react-component-hook-guidelines-cn

name	react-component-hook-guidelines-cn
description	React 组件、页面组件、自定义 Hook 的拆分、重构与评审技能。用户提到“拆组件”“拆 Hook”“这个组件太大了”“这个 Hook 太重了”“帮我理一下这个页面”“这段 React 怎么拆比较合理”“重构 React 组件”“重构页面逻辑”“优化组件设计”“评审组件设计”“评审 Hook 设计”“减少 props”“收敛职责”“拆分 God Component”“拆分 God Hook”“调整页面编排”“整理前端分层”“组件职责不清”“逻辑和 UI 耦合”“页面状态太乱”“大 state 下传”“props 太多”“分支太多”时触发。重点处理职责混杂、props 过宽、大状态下传、分支过多、页面编排过重、展示与逻辑耦合。

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。
• 需要评审现有 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，哪些进入展示组件，哪些进入工具函数。
• 如果是实现，产出代码时遵守引用规范，不要重新引入“大对象 props”或“万能 Hook”，并为新增或修改的函数、Hook 补充功能注释。

例外处理

允许合理例外，但必须说明理由。常见可接受例外：

• 纯展示组件略长，但视觉结构集中且职责稳定。
• 同文件存在少量只服务当前主组件的辅助子组件。
• 页面入口文件稍长，但业务逻辑已经拆出。

如果无法给出明确理由，默认按规范收紧边界。