react-component-hook-guidelines-cnlisted

# React Component Hook Guidelines ## Overview 提供 React 组件、页面组件、自定义 Hook 的拆分、重构与评审判断。重点处理职责混杂、props 过宽、大状态下传、分支过多、页面编排过重、展示与逻辑耦合。 ## 何时使用 当用户提出以下需求时使用本技能： - 拆组件 - 拆 Hook - 组件太大、Hook 太重 - 帮忙梳理页面或 React 分层 - 重构 React 组件、页面逻辑或组件设计 - 减少 props、收敛职责、拆分 God Component 或 God Hook - 处理页面状态混乱、逻辑和 UI 耦合、分支太多等问题 ## 不要使用 以下场景不应使用本技能： - 与 React 组件、Hook 或页面编排无关的任务 - 纯后端逻辑或非前端任务 - 与职责边界、状态流转、props 设计无关的简单样式修改 ## 使用说明 1. 先识别任务类型：代码评审、重构、实现新功能，或梳理目录/分层。 2. 定位核心单位：页面组件、业务组件、展示组件、自定义 Hook、工具函数。 3. 判断变化原因是否单一，再检查 props、状态、副作用、路由、缓存、弹窗、埋点是否被错误耦合。 4. 优先通过拆分边界解决复杂度，不用机械压行数代替设计判断。 ## 快速决策 - 需要判断组件或 Hook 是否拆分时，读取 [references/react-component-hook-rules.md](references/react-component-hook-rules.md)。 - 需要评审现有 React 代码时，按“职责边界 → props 设计 → 复杂度 → 分支扩展”的顺序检查。 - 需要落地重构时，优先抽业务 Hook、展示组件、纯函数，不要先做样式层面的无效搬运。 - 需要实现新组件时，先决定它属于页面编排、业务容器、展示组件还是通用 UI 组件。 ## 执行规则 ### 评审 至少检查以下问题： - 是否只导出一个主组件或主 Hook。 - 是否把页面级大 state 或整包 actions 直接下发给子组件。 - 是否同时耦合 UI、请求、路由、副作用、缓存、弹窗或埋点。 - 是否存在超过 3 个模式分支且更适合改成映射/策略。 - 是否有应当提取为 Hook 或 `lib/utils` 的逻辑。 ### 重构 优先使用这条拆分路径： 1. 从页面组件中拿掉业务状态与副作用。 2. 把可复用或可测试的状态流转抽成业务 Hook。 3. 把重 JSX 区块拆成最小展示组件。 4. 把纯数据转换、校验、映射提到 `lib/` 或 `utils/`。 5. 收缩 props，只保留子组件真正需要的字段和回调。 ### 新实现 实现前先做三个判断： 1. 这是编排层还是展示层？ 2. 状态逻辑是否应该进 Hook？ 3. 这段逻辑是否脱离 React 生命周期后仍成立？如果成立，放到 `lib/utils`。 补充强约束： - 代码注释必须使用中文。 - 函数需要在定义前补充功能注释，说明其职责与处理场景。 - Hook 需要在定义前补充功能注释，说明其封装的业务职责、状态范围或副作用边界。 - 注释只说明职责、边界和意图，不写低信息量的逐行翻译式注释。 ## 输出要求 - 如果是评审，先给“发现的问题”，再给修改建议。 - 如果是重构，明确列出新边界：哪些留在页面，哪些进入 Hook，哪些进入展示组件，哪些进入工具函数。 - 如果