React应用架构重构指南Skill：用40条规则把混乱的React代码库重新梳理清楚
- 一句话定位：这不是一个"帮你写新代码"的技能，而是一份可被AI随时调用的React架构重构手册——7大类别、40条规则，按影响从"关键"到"增量"排序。
- 核心覆盖范围：组件架构、状态架构、钩子模式、组件分解、耦合与内聚、数据与副作用、重构安全性，基本对齐一次中大型React重构的全部决策点。
- 最好用的时机：接手遗留项目、审查PR里的架构异味、拆分超大组件、把逻辑抽成自定义钩子、降低模块间耦合。
- 边界很明确：不覆盖React 19 API用法（交给
react技能）、不覆盖性能优化（交给react-optimise技能）、不覆盖客户端表单处理（交给react-hook-form技能）。 - 最大的价值：把"重构要靠老师傅的经验"变成"可以按编号逐条对照的检查清单"，让AI给出的建议有理有据，而不是泛泛而谈的"建议拆分组件"。
该技能叫什么？如何一键安装 AI 技能提升开发效率？
基本信息
| 项目 | 内容 |
|---|---|
| 技能中文名 | React应用架构重构指南Skill |
| 技能英文名 | react-refactor |
| 技能ID | 11464 |
| 技能类型 | 架构方法论 / 代码审查类技能 |
| 规则规模 | 7个类别、40条规则 |
它到底解决什么问题
写React的人大多遇到过这几个场景：一个组件写到八百行还在加if；状态被一路提升到App里，改一个开关导致整页重渲染；自定义钩子既取数据又做转换又管缓存，谁也不敢动；两个人同时改同一个文件必然冲突；重构完不敢合并，因为不知道有没有改坏。
这些问题都不是"API用错了"，而是架构问题。普通AI助手面对这类问题，通常会给出"可以把组件拆小一点""建议使用自定义钩子"这类正确的废话——因为它手里没有一套成体系的判断标准。
react-refactor技能做的事情，就是把一套成体系的架构判断标准（40条规则、按影响分级、每条都带具体模式与反模式）作为技能上下文喂给AI，让它在回答重构问题时，能落到"这属于组件架构类别第5条：优先组合而非属性爆炸"这种颗粒度上。
一键安装的思路与步骤
"一键安装"的价值在于：你不需要每次对话都把这份几十页的重构手册粘贴一遍，也不需要团队成员各自背规则。安装一次，技能常驻，任何时候提问都会自动带上这套标准。
安装前提：需要一个支持 Skill（技能）机制的AI编程助手或客户端（IDE插件、命令行助手、对话式编程工具等，具体形态以官方说明为准）。
安装步骤（通用流程，具体入口与命令以官方说明为准）：
- 打开技能管理入口：在你的AI助手/IDE中找到「技能」「Skills」「技能市场」或「扩展」面板（不同产品叫法不同，以官方说明为准）。
- 按名称或ID检索：搜索英文名
react-refactor，或直接搜索技能ID11464，一般可精确定位。 - 执行安装并启用：点击安装/启用按钮，确认该技能处于"已启用"状态。若你的工具支持按项目级配置，建议把它加进前端项目的技能清单，随项目一起生效。
- 验证是否生效：新建一段对话，贴入一个有明显问题的组件（例如十几个props、状态又被提升到父级），提问"这个组件的架构有什么问题，怎么改？“。如果回答开始出现"组件架构”“状态架构”“属性爆炸”"状态共置"等分类化表述，并能给出规则层面的判断和改造顺序，说明技能已生效。
- 配套技能一起装：
react（React 19 API最佳实践）、react-optimise（性能优化）、react-hook-form（表单处理）。这三个与react-refactor是明确分工关系，重构时经常需要串联使用。
该技能的主要功能和特点
1. 40条规则按"影响等级"排序，先做最重要的事
技能把规则分成七个类别，并标注了影响级别，避免重构时"抓小放大"：
| 类别 | 影响 | 规则数 | 关键主题 |
|---|---|---|---|
| 组件架构 | 关键 | 8 | 复合组件、无头模式、组合优于属性、客户端边界 |
| 状态架构 | 关键 | 7 | 状态共置、状态机、URL状态、衍生值 |
| 钩子模式 | 高 | 6 | 单一职责、命名、依赖稳定性、组合 |
| 组件分解 | 高 | 6 | 滚动测试、按变更原因提取、视图/逻辑分离 |
| 耦合与内聚 | 中等 | 4 | 依赖注入、循环依赖、稳定导入、无桶文件 |
| 数据与副作用 | 中等 | 4 | 服务器优先获取、TanStack查询、错误边界 |
| 重构安全性 | 低-中等 | 5 | 特征化测试、行为测试、集成测试 |
2. 每条规则都配"模式 + 反模式"，可直接对照代码
比如状态架构里明确写了"常见错误"：只有一个组件读取时却把状态提升到App、给快速变化的值用上下文、造一个"获取+转换+缓存"三合一的钩子、测试实现细节而非行为。这类反模式清单特别适合PR审查时逐条扫。
3. 提供可量化的改造预期
技能中为不少规则标注了参考性收益数值，例如：接口隔离可减少30-50%的不必要重渲染；按功能而非类型共置文件可减少约70%的跨目录导航；组合优于属性爆炸可减少50-70%的props数量；状态机可把复杂工作流的有效状态从2的n次方降到N；在数据获取粒度放置错误边界可把错误隔离在受影响区域。这些数字来自技能自身的经验总结，可作为说服团队排期的参考依据。
4. 重构优先，安全性兜底
"重构安全性"类别虽然影响等级标为低-中等，但内容非常实用：重构前先写特征化测试（技能给出可捕获约90%非预期变更的参考值）、避免对重构中的组件做快照测试、优先集成测试、测试行为而非实现细节、把纯函数抽出来以便快速单测。
5. 与普通AI助手的差异
普通助手给的是"通用最佳实践"，react-refactor给的是分级、分场景、可编号引用的架构决策依据，并且明确划出了自己的边界（不管React 19 API、不管性能优化），从而避免给出"看着都对但落不了地"的建议。
如何使用该技能？
步骤一：明确你要的是"审查"还是"改造"
技能详情里列出了典型触发场景，提问时直接对号入座即可：
- 重构现有React代码库，或计划大规模重组
- 审查PR的架构问题和代码异味
- 把过大的组件分解为聚焦单元
- 从组件逻辑中提取可重用钩子
- 提高React代码的可测试性
- 减少功能模块之间的耦合
步骤二：用自然语言给出上下文
不需要记任何命令，直接把代码和诉求说清楚即可。示例：
请用 react-refactor 技能审查这个组件。它现在有600多行、18个props，内部有5个useState和一个useEffect做数据转换。我想知道按影响优先级，应该先改哪几处，以及每一步改完怎么验证没改坏。
步骤三：按类别要求逐条检查（推荐用于PR审查）
如果只是想系统地扫一遍，可以点名类别：
按"状态架构"这一类别的全部规则检查下面这个文件，逐条告诉我：这条规则我违反了没有、违反了会有什么后果、最小改法是什么。
步骤四：要求输出可执行的改造计划
重构最怕"一步到位"。可以这样要求：
请把这些改造按影响等级从关键到低-中等排序，切成可以独立提交的小步，每一步说明改哪几个文件、需要先补什么测试。
合理的输出通常会呈现这样的形态：先给出组件架构与状态架构层面的关键改造（如把状态从父级下沉到使用它的组件、把属性爆炸改为组合或复合组件、把复杂工作流改为状态机），再给钩子与组件分解层面的高影响改造，最后给耦合与重构安全性层面的收尾动作。
步骤五：用测试兜底再动手
在真正改代码前，按"重构安全性"类别先补特征化测试和集成测试，确认现有行为被锁定，再开始结构调整。改完后跑同一套测试，验证行为未变。
输入输出小贴士
- 输入越具体，建议越具体：给出组件实际代码、props清单、状态流转路径，比只说"我的组件太大了"效果好得多。
- 主动说明技术栈细节：是否使用服务端渲染、是否已引入TanStack Query、路由方案是什么，会直接影响"数据与副作用"类建议的准确性。
- 注意技能边界：如果问题其实是React 19新API用法或渲染性能调优，应转向
react或react-optimise技能，react-refactor不负责这部分。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| react-refactor（本技能） | React架构重构方法论技能 | 7类40条分级规则，覆盖组件/状态/钩子/分解/耦合/数据/重构安全 | 低：在AI助手中一键安装，用自然语言提问即可 | 遗留项目重构、PR架构审查、大组件拆分 | 优势：有分级、有反模式、有量化参考，边界清晰；不足：只覆盖架构层面，不含React 19 API与性能调优 |
| 通用AI编程助手（未装技能） | 通用代码问答 | 能读懂代码、给出通用建议 | 极低 | 日常写代码、解释报错 | 优势：开箱即用；不足：架构建议偏泛，缺少统一标准，容易"每个回答一套说法"，难以在团队内形成共识 |
| ESLint + 架构类lint规则（如依赖方向检查工具） | 静态检查 | 自动发现依赖环、越界导入、命名等问题 | 中：需要配置规则集与CI集成 | 持续集成中拦截架构违规 | 优势：自动化、可强制；不足：只能检查"可模式化"的问题，判断不了"状态该放在哪里""这个组件该不该拆"这类设计决策 |
| 人工Code Review + 团队架构清单 | 人工评审 | 依赖资深工程师经验 | 高：依赖人员水平和时间 | 关键模块评审 | 优势：理解业务上下文；不足：不可规模化、结论因人而异、难以覆盖全部40条规则 |
| 官方文档与社区架构资料（react.dev、patterns.dev等） | 学习资料 | 系统性知识 | 中：需要阅读与消化 | 个人学习、架构选型 | 优势：权威、体系完整；不足：需要自己提炼成检查清单，落地时缺少"按优先级排序"的指引 |
怎么选：如果你已经有ESLint把关"机器能判断的规则"，缺的是"人才能判断的设计决策"，那react-refactor正好补位；如果团队有稳定的资深Reviewer，它能把这个人的判断标准固化下来，让整个团队都能用同一套语言讨论架构。
该技能的典型应用场景与实际体验情况
场景一：接手遗留项目的前端负责人
角色与痛点：接手一个两年前的项目，首页组件1200行，状态被提升到根组件，改一个筛选条件整页闪烁。想重构又不敢动，因为没有任何测试。
使用方式：先用"组件分解"类别里的滚动测试识别哪些组件确实过大，再按"按独立变更原因提取"的思路切分，同时用"重构安全性"类别要求在动手前补特征化测试与集成测试。
实际体验：上手几乎零成本，因为它不要求你先学一套新工具，直接描述现状即可。效果上最明显的是改造顺序变清晰了——不再纠结"先拆组件还是先整状态"，而是按关键→高的影响等级推进。注意事项：必须先补测试，否则技能给出的激进拆分建议执行起来风险很高。
场景二：日常PR审查的Tech Lead
角色与痛点：每天要审十几个PR，架构类问题（属性爆炸、状态乱提升、钩子职责不清）靠肉眼扫，容易漏，且每次都要重复解释同样的道理。
使用方式：把PR里的组件代码贴进去，要求"按组件架构和状态架构两个类别检查架构异味"，让AI输出问题清单和引用规则条目。Review时直接附上规则说明链接给作者。
实际体验：审查速度提升明显，因为反模式清单是现成的（比如"当只有一个组件读取时，将状态提升到App"这条几乎每周都能用上）。注意：AI给出的判断仍需要人工确认业务上下文，比如某个状态提升其实是跨页面共享需求，不能机械照搬规则。
场景三：设计系统/组件库维护者
角色与痛点：组件越做props越多，一个<Select>有二十多个props，用户还在提新需求；逻辑和视图混在一起，无法复用。
使用方式：围绕"组件架构"类别工作——用复合组件减少API表面、用无头组件把逻辑与渲染分离、用组合替代属性爆炸、用接口隔离收敛props。
实际体验：这类场景收益最直接，因为组件架构是本技能标注为"关键"的类别，规则密度最高（8条）。技能中给出的参考收益（如减少API表面约60%、属性数量减少50-70%）在组件库场景下体感比较接近。注意事项：改造组件API是破坏性变更，需要配套版本策略。
场景四：状态管理混乱的中型SaaS团队
角色与痛点：一个多步骤表单/审批流用了七八个布尔状态，出现"既加载又报错又弹窗"的不可能组合，测试写不出来。
使用方式：用"状态架构"类别里的状态机规则梳理工作流，用useReducer处理多字段状态转换，用URL参数承载可分享的视图状态（筛选条件、当前页签），用衍生值替代同步状态。
实际体验：这是最容易"见效于无形"的部分——状态从指数级组合收敛为有限几个状态后，测试用例数量直接下降。注意：URL作为状态会影响路由设计，需与路由方案一起考虑。
该技能能为用户带来的价值
1. 把隐性经验变成显性清单
一套40条、7类、分级的架构规则，本身就是一份团队可以直接引用的重构规范。新人不用再靠"跟着老同事改几次"来悟，直接对照规则编号讨论即可，沟通成本显著下降。
2. 让重构有优先级，不做无用功
技能明确按影响等级排序：组件架构与状态架构是"关键"，钩子与组件分解是"高"，耦合、数据副作用是"中等"，重构安全性是"低-中等"。这直接回答了团队最纠结的问题——这个季度先改哪里。
3. 提高重构的安全性预期
通过"重构前写特征化测试、避免快照测试、优先集成测试、测试行为而非实现细节"这条链路，把"重构=赌博"变成"重构=有护栏的工程动作"。技能给出的参考值（特征化测试可捕获约90%非预期变更、集成测试比单元测试多捕获约40%错误）可用于推动团队接受"先补测试再重构"的流程。
4. 降低工具门槛与人员门槛
不需要引入新的构建工具、不需要改CI、不需要团队成员都读过架构书。安装一次技能，任何人在任何时刻提问，都能得到同一套标准的回答。
5. 长期价值：可测试性与可维护性的复利
按"按变更原因提取组件"“按功能共置文件”“无桶文件的功能模块”"稳定导入"这些规则整理过的代码库，后续每次需求变更触及的文件更少、构建更快、冲突更少。这类收益不会在一次迭代里爆发，但会在半年、一年后持续兑现。
常见问题 FAQ
Q1：这个技能怎么安装？需要付费吗？
在支持技能机制的AI助手中，打开技能管理入口，搜索英文名 react-refactor 或技能ID 11464，点击安装并启用即可，具体入口位置和命令以你所用工具的官方说明为准。是否收费取决于承载它的平台策略，本技能自身未提供价格信息，请以官方说明为准。
Q2：它能自动帮我把代码改好吗？
它的定位是架构重构指南——给出问题诊断、规则依据、改造顺序和验证方式，而不是无脑批量改文件。实践中最稳的用法是：让技能输出改造计划和最小改动步骤，由你或你的AI助手按步骤执行，每步用测试验证。直接让它大范围重写代码，风险不可控。
Q3：适合谁用？前端新人用得上吗？
最适合三类人：负责遗留项目重构的前端负责人、需要审PR的Tech Lead、维护设计系统/组件库的工程师。有一定React经验的新人同样适合——它能告诉你"为什么这样写是反模式"，比抽象的"最佳实践"更好理解。纯初学者建议先补React基础，再看这些规则。
Q4：它和react、react-optimise这些技能是什么关系？
明确分工、互补不重叠：react-refactor只管架构与结构（组件怎么组织、状态放哪、钩子怎么切、耦合怎么降）；react技能管React 19 API用法；react-optimise技能管性能优化；react-hook-form技能管客户端表单处理。遇到渲染卡顿先看性能技能，遇到API写法问题先看react技能，遇到"结构该怎么改"才轮到本技能。
Q5：和ESLint、人工Review相比，该怎么选？
它们不是替代关系。ESLint负责机器可判定的规则（依赖环、越界导入、命名），能进CI强制拦截；人工Review负责业务上下文；react-refactor补齐的是"设计决策层的标准"——比如状态该共置还是提升、组件该按什么维度拆、什么时候该用状态机。三者叠加，才是完整的架构防线。