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](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 补充功能注释。

## 例外处理

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

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

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