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