review-react

技能：审查 React

目的

仅审查 React 代码是否遵循框架惯例。不要界定审查范围（差异内容还是整个代码库），也不要进行安全或架构分析；这些由范围技能和认知技能负责。按标准格式输出发现列表，供汇总使用。重点关注函数组件设计、Hooks 正确性、状态管理（本地和外部）、渲染性能、副作用和数据获取、路由与代码分割，以及无障碍性。

---

核心目标

主要目标：针对给定代码范围，输出 React 框架发现列表，涵盖组件设计、Hooks 正确性、状态管理、渲染性能、副作用、路由与代码分割，以及无障碍性。

成功标准（必须全部满足）：

1. ✅ 仅限 React 框架范围：只审查 React 框架惯例；不进行范围选择、安全分析或架构分析
2. ✅ 涵盖 React 的七个维度：在相关情况下评估组件设计、Hooks 正确性、状态管理、渲染性能、副作用／数据获取、路由／代码分割，以及无障碍性
3. ✅ 符合发现列表格式：每项发现都包含 findings-list §5.1 要求的所有要素，且类别为 framework-react
4. ✅ 引用组件／文件：每项发现都注明具体的文件和行号或组件名称
5. ✅ 排除非 React 代码：除非明确属于审查范围，否则不按 React 专属规则分析非 React 文件

验收测试：输出是否包含一份以 React 为中心的发现列表，涵盖所有相关的框架维度并注明组件／文件，同时不进行安全、架构或范围分析？

---

范围边界

本技能负责：

• 函数组件设计（单一职责、组合模式、属性类型／默认值、children 模式）
• Hooks 正确性（依赖数组、过期闭包、自定义 Hook 提取、Hooks 规则、useEffect 中的清理）
• 状态管理（本地状态与全局状态、Context 用法、reducer 模式、Zustand／Redux 等外部状态库，以及通过 TanStack Query／SWR 管理服务端状态）
• 渲染性能（memo／useMemo／useCallback 的使用、列表中的 key 稳定性、避免不必要的重新渲染、大型列表的虚拟化）
• 副作用和数据获取（useEffect 模式、竞态条件、中止控制器、加载／错误状态、数据获取库）
• 路由与代码分割（React.lazy、Suspense 边界、基于路由的代码分割、错误边界）
• 无障碍性（ARIA 属性、语义化 HTML、键盘导航、焦点管理、屏幕阅读器支持）

本技能不负责：

• 范围选择——范围由调用方提供
• 安全分析（XSS、注入风险）——使用 review-security
• 架构分析——使用 review-architecture
• 语言／运行时（JavaScript／TypeScript）惯例——使用 review-typescript 或通用 JS／TS 分析
• 完整的编排式审查——使用 orchestrate-code-review

交接点：输出所有 React 相关发现后，将其交给 orchestrate-code-review 汇总。对于 XSS 风险（误用 dangerouslySetInnerHTML、未清理的内容），请注明该问题并指向 review-security。

---

使用场景

• 编排式审查：当 orchestrate-code-review 对 React 项目按范围 → 语言 → 框架 → 库 → 认知的流程运行时，本技能作为框架审查步骤。
• 仅审查 React：当用户只想检查 React／前端框架惯例时使用。
• PR 前 React 检查清单：确认 Hook 用法、组件设计和状态管理模式正确。

何时使用：待审查代码使用 React，且任务包含框架质量检查时使用。审查范围由调用方或用户设定。

---

行为

此技能涵盖的内容

• 分析：给定代码范围（调用方提供的文件或差异）中的 React 框架约定。不负责确定范围；以代码范围作为输入。
• 不做：选择代码范围、安全审查或架构审查；除非非 React 文件属于审查范围（例如混合仓库），否则不针对这些文件检查 React 规则。

审查清单（仅限 React 框架）

1. 组件设计：优先使用函数组件；每个组件只承担一项职责；优先组合而非深层嵌套；明确声明属性类型并设置合理默认值（TypeScript 接口或 PropTypes）；恰当使用 children 和渲染属性。
2. Hooks 正确性：为 useEffect/useMemo/useCallback 设置正确的依赖数组；避免闭包过期；将可复用逻辑提取到自定义 Hook 中；遵循 Hook 规则（仅在顶层调用，仅在 React 函数中调用）；在 useEffect 中为订阅和计时器设置清理函数。
3. 状态管理：恰当选择本地状态（useState）或全局状态；使用 Context 处理横切关注点，但避免过度使用；复杂状态转换优先使用 useReducer；正确集成外部存储（Zustand、Redux Toolkit）；将服务端状态（TanStack Query、SWR）与客户端状态分开。
4. 渲染性能：仅在能明确证明有益时使用 React.memo、useMemo、useCallback；确保列表使用稳定的 key（动态列表不要使用索引作为 key）；避免在 JSX 中内联创建对象或函数，以免导致重新渲染；对大型列表进行虚拟化（react-window、react-virtuoso）。
5. 副作用与数据获取：遵循正确的 useEffect 模式（每个 effect 只负责一项任务，并妥善清理）；使用中止控制器或标志处理竞态条件；明确表示加载、错误和成功状态；优先使用数据获取库（TanStack Query、SWR），而不是直接使用 useEffect + fetch。
6. 路由与代码拆分：使用 React.lazy 和 Suspense 按路由拆分代码；在延迟加载的路由周围定义错误边界；以声明式方式定义路由；适合延迟加载时，避免急切加载整个模块。
7. 无障碍：使用语义化 HTML 元素；正确应用 ARIA 属性（角色、标签、实时区域）；确保键盘导航和焦点管理；支持屏幕阅读器；测试交互组件是否符合无障碍要求。

语气与参考资料

• 专业且技术性强：注明确切位置（文件:行号或组件名称）。输出的每条发现都必须包含 findings-list §5.1 要求的所有要素。

---

输入与输出

输入

• 代码范围：包含 React 代码的文件或目录（或差异），例如使用 React API 的 .tsx、.jsx、.ts、.js 文件。由用户或范围技能提供。

输出

• 按照 specs/findings-list.md 中定义的格式输出零条或多条发现，Category 为 framework-react。
• 此技能的类别为 framework-react。

---

限制

严格边界

• 不要选择代码范围，也不要进行安全或架构审查。仅审查 React 框架约定。
• 不要在没有具体位置或可执行建议的情况下提出发现。
• 不要针对范围之外的非 React 代码应用 React 专属规则进行审查。

技能边界

不要执行以下工作（由其他技能负责）：

• 不要选择或定义代码范围——范围由调用方或 orchestrate-code-review 确定
• 不要进行安全分析（XSS、注入）——请使用 review-security
• 不要进行架构分析——请使用 review-architecture

停止并移交的时机：

• 输出所有 React 相关发现后，将其交给 orchestrate-code-review 汇总
• 发现 XSS 风险时（例如不安全地使用 dangerouslySetInnerHTML），请注明并指向 review-security
• 用户需要完整审查（范围 + 语言 + 认知）时，请转交 orchestrate-code-review

---

自检

核心成功标准

• 仅限 React 框架范围：仅审查 React 框架约定；不进行范围选择、安全或架构分析
• 涵盖全部七个 React 维度：在相关情况下评估组件设计、Hook 正确性、状态管理、渲染性能、副作用/数据获取、路由/代码拆分和无障碍性
• 符合问题发现格式：每条问题发现都包含 findings-list §5.1 要求的所有要素，类别为 framework-react
• 组件/文件引用：每条问题发现都引用具体的文件:行号或组件名称
• 排除非 React 代码：除非明确属于审查范围，否则不使用 React 专属规则分析非 React 文件

流程质量检查

• 是否仅审查了 React 框架维度（未涉及范围/安全/架构）？
• 是否在相关情况下涵盖了组件设计、Hook、状态、性能、副作用、路由和无障碍性？
• 每条问题发现是否都包含 findings-list §5.1 要求的所有要素，且类别 = framework-react？
• 每个问题是否都关联到文件:行号或组件？

验收测试

输出是否包含以 React 为中心的问题发现列表，附有组件/文件引用并涵盖所有相关框架维度，且未进行安全、架构或范围分析？

---

示例

示例 1：useEffect 中缺少清理逻辑

• 输入：一个在 useEffect 中打开 WebSocket 连接、但没有清理逻辑的组件。
• 预期：针对缺少清理逻辑提出一条问题发现（严重）；建议返回一个关闭连接的清理函数。类别 = framework-react。

示例 2：动态列表将索引用作 key

• 输入：一个使用数组索引作为 key 来渲染可排序/可筛选列表的组件。
• 预期：针对 key 不稳定及其可能导致的状态错误提出一条问题发现；建议使用稳定且唯一的标识符作为 key。类别 = framework-react。

边缘情况：现代代码库中的类组件

• 输入：一个代码库中存在旧式类组件，但其他部分使用函数组件和 Hook。
• 预期：在可行时建议迁移到使用 Hook 的函数组件；检查类组件的生命周期是否正确（componentDidMount、componentWillUnmount 清理）。请注意，对于稳定且经过充分测试的组件，建议迁移，但并非始终必须迁移。