如何用 Codex 优化组件复用结构

一、为什么组件复用结构会越来越乱？

很多前端项目的问题不是“没有组件”，而是组件太多、太散、太像。一个按钮在登录页写了一版，在后台页写了一版，在移动端弹窗里又写了一版；一个 Card 组件在列表页、详情页、推荐区各自复制了一套；表单字段、空状态、加载状态、弹窗、筛选栏也不断重复。短期看，这样写最快。长期看，每次改视觉、改交互、改字段、改响应式，都要在多个文件里重复修改。

组件复用结构优化，不是简单地把重复代码抽成一个 Button 或 Card。真正要优化的是组件之间的边界：哪些属于基础 UI，哪些属于业务模块，哪些只是布局组合，哪些逻辑应该放到 hook 或 utility，哪些差异不应该硬塞进一个巨大的 props 对象。

Codex 适合介入这类任务，因为它可以先读完整代码库，再根据现有目录、命名、样式和依赖关系提出重构方案。OpenAI 官方文档也把 Codex 定义为面向软件开发的 coding agent，可用于理解代码库、写代码、代码审查、调试和自动化重构等开发任务。

二、什么叫“组件复用结构优化”？

不要把组件复用理解成“哪里重复就抽哪里”。在真实项目里，组件复用至少包含五层问题：

• 基础 UI 复用：Button、Input、Select、Modal、Tabs、Badge、Avatar、EmptyState、Loading 等是否有统一入口。

• 业务组件复用：UserCard、ProductCard、ArticleList、OrderStatus、PricingPlan 等是否在同一业务域内复用，而不是跨域乱用。

• 布局组件复用：PageContainer、Section、Grid、SidebarLayout、DetailHeader 等是否减少了页面级重复结构。

• 逻辑复用：数据获取、分页、筛选、表单校验、状态转换、权限判断，是否被拆到 hook、service 或 util。

• 样式复用：Tailwind class、CSS module、theme token、variant 规则是否统一，而不是每个组件独立拼 class。

好的组件复用结构不是组件越少越好，而是修改成本更低、复用边界更清楚、业务变化更容易承接。

三、什么时候应该让 Codex 做组件复用体检？

当项目出现下面这些现象时，就可以让 Codex 先做一次组件复用结构检查：

四、先别让 Codex 直接重构，要先让它做组件地图

最容易出问题的用法，是直接对 Codex 说“帮我优化组件复用结构”。这句话太大，Codex 可能会一次性移动大量文件、改 import、改 props、删重复组件，最后你很难判断哪些改动是必要的。正确流程应该是：先检查，不改代码；再出方案，不动文件；最后选择一个低风险模块试点重构。

第一步可以让 Codex 生成组件地图，找出当前项目有哪些组件、在哪些地方被使用、是否存在重复实现、是否适合抽象。

请你先不要修改任何代码，只做组件复用结构体检。

请扫描当前前端项目，重点检查：

1. src/components、src/features、src/app、src/pages、src/modules 等目录下的组件分布；

2. 是否存在功能相似、视觉相似、props 相似的重复组件；

3. 页面级文件里是否包含过多可抽离的 UI 片段；

4. 是否有重复的 loading、empty、error、card、modal、form field、filter、list item 结构；

5. 是否有业务逻辑和展示组件混在一起的情况；

6. 是否有 import 路径混乱、命名不统一、组件层级不清的问题。

请输出一份组件复用体检报告，不要改代码。报告格式：

• 当前组件目录概览

• 重复组件候选列表

• 可以抽离的页面片段

• 不建议抽象的部分

• 优先级排序

• 建议的第一轮低风险重构范围

五、让 Codex 判断哪些重复值得抽象，哪些不值得

重复并不一定都应该抽象。两个组件代码相似，但业务语义完全不同，强行抽成一个共享组件，后面可能会变成“一个组件管所有场景”的泥潭。Codex 做组件复用时，要明确让它区分四类重复：

• 结构重复：DOM 层级、布局、状态展示一致，通常适合抽象。

• 样式重复：className、间距、字号、圆角、颜色重复，通常适合通过 token、variant 或基础组件统一。

• 逻辑重复：分页、筛选、权限、状态映射、格式化逻辑重复，通常适合抽成 hook 或 util。

• 语义相似但业务不同：表面很像，但未来变化方向不同，通常不建议强行合并。

请基于刚才的组件体检结果，进一步判断每个重复候选是否真的值得抽象。

请按以下标准分析：

1. 重复代码是否超过 3 处；

2. 组件未来变化方向是否一致；

3. 是否可以用清晰 props 表达差异，而不是堆很多布尔值；

4. 抽象后是否会降低调用方理解成本；

5. 是否会影响现有 UI、交互、响应式或测试；

6. 是否更适合抽成 hook / util，而不是 UI 组件。

请输出表格：

• 重复候选

• 出现位置

• 重复类型

• 是否建议抽象

• 推荐抽象方式

• 风险等级

• 理由

六、推荐的前端组件分层方式

如果项目没有稳定结构，可以让 Codex 按“基础 UI、通用业务组件、业务域组件、页面组件、逻辑层”来重排。但注意：目录结构不是越复杂越好。小项目不需要一上来搞完整设计系统，大项目也不能把所有东西都塞进 common。

Codex 在执行重构时，应该优先保持现有项目习惯。如果当前项目已经有 src/shared、src/widgets、src/modules 等结构，不要强行改成另一套流派。更合理的做法是先统一命名和边界，再逐步迁移。

七、让 Codex 先出重构计划，不要马上改文件

组件复用结构优化属于架构型重构，不适合一次性“全自动”。应该先让 Codex 输出计划，包括要动哪些文件、保留哪些 API、如何验证、是否需要兼容旧 import。

请根据组件复用体检报告，制定一份分阶段重构计划。

要求：

1. 不要立即修改代码；

2. 优先选择低风险、高重复的组件作为第一轮；

3. 每一轮改动必须控制在可 review 的范围内；

4. 保持现有 UI、交互、路由、数据逻辑不变；

5. 保留或兼容原有组件导出，避免一次性大面积断 import；

6. 明确每一步需要运行的检查命令，例如 typecheck、lint、test、build；

7. 如果项目没有测试，请说明人工验收页面和关键路径。

请输出：

• 第一轮重构目标

• 涉及文件列表

• 新目录结构建议

• 组件 API 设计

• 兼容策略

• 风险点

• 验收方式

八、第一轮只重构一个低风险模块

推荐从“重复明显、业务风险低、页面影响范围可控”的组件开始，比如 EmptyState、Loading、Badge、StatusTag、Card Header、Filter Bar，而不是一上来重构核心表单、支付流程、权限逻辑或订单详情页。

第一轮目标不是把所有重复都解决，而是验证 Codex 的判断是否可靠、项目结构是否适合这样拆、团队是否能接受新的组件 API。

请执行第一轮低风险组件复用重构。

重构范围：只处理你在计划中列出的第一轮目标，不要扩展到其他模块。

要求：

1. 保持现有 UI 视觉表现不变，包括间距、字号、颜色、圆角、hover、disabled、loading、响应式；

2. 保持现有业务逻辑不变；

3. 新组件命名要清晰，props 不要过度抽象；

4. 如果需要兼容旧组件，请保留旧导出或添加轻量 wrapper；

5. 不要进行无关格式化；

6. 修改完成后运行项目现有的 lint、typecheck、test 或 build 命令；

7. 最后输出变更摘要、影响文件、验证结果、仍需人工检查的页面。

如果发现风险超出第一轮范围，请暂停并说明，不要继续扩大改动。

九、组件 API 设计：不要把复用做成 props 垃圾桶

组件复用失败，很多时候不是目录错了，而是组件 API 设计错了。一个被复用的组件如果塞满 isHome、isDetail、isAdmin、showExtra、compact、simple、hasBorder、useNewStyle 这类参数，后续会非常难维护。

更稳的做法是使用清晰的 variant、slot、children composition、局部 wrapper。比如基础 Button 可以有 variant、size、disabled、loading；业务里的 SubmitOrderButton 可以基于 Button 再封装，而不是让 Button 知道“订单提交”是什么。

请检查本次新抽象组件的 props 设计是否合理。

重点检查：

1. 是否存在过多布尔 props；

2. 是否把业务语义塞进基础 UI 组件；

3. 是否可以用 variant / size / children / render slot 简化；

4. 是否有不必要的 optional props；

5. 是否需要拆成基础组件 + 业务 wrapper；

6. 是否有清晰的 TypeScript 类型和默认值；

7. 调用方是否比重构前更容易理解。

请给出 props API 审查意见，并在必要时修改为更稳定的组件 API。

十、让 Codex 把重复逻辑抽到 hook 或 util，而不是全抽成组件

有些重复并不是 UI 重复，而是逻辑重复。比如多个列表页都有搜索、分页、排序、筛选、URL query 同步；多个表单都有提交状态、错误提示、字段格式化；多个状态标签都有状态码到文案和颜色的映射。

这类问题如果都抽成 UI 组件，反而会把逻辑和展示绑死。更好的方式是让 Codex 判断：应该抽成 usePagination、useFilters、formatPrice、getStatusMeta，还是抽成 DataTable、StatusBadge。

请检查当前项目是否有适合抽成 hook 或 util 的重复逻辑，而不是只抽 UI 组件。

重点查找：

1. 重复的数据格式化逻辑；

2. 重复的状态码映射；

3. 重复的分页、筛选、搜索、排序逻辑；

4. 重复的表单提交和错误处理逻辑；

5. 重复的权限判断或展示条件判断；

6. 重复的 API 响应适配逻辑。

请输出：

• 重复逻辑位置

• 推荐抽象为 hook / util / service / component 的哪一种

• 理由

• 第一轮可安全处理的候选

未经确认不要修改代码。

十一、把组件规范写进 AGENTS.md，让 Codex 以后持续遵守

组件复用结构不是一次重构就结束。后面每次新增页面、修 bug、加功能，Codex 都可能继续产生新的重复组件。解决方法是把组件目录、命名、抽象原则、测试命令写进 AGENTS.md。OpenAI 官方文档说明，Codex 会在开始工作前读取 AGENTS.md，用这些项目规则形成一致的执行预期。

下面是一段可以放进项目 AGENTS.md 的组件规范示例：

Component reuse rules

• Keep low-level reusable UI components in src/components/ui.

• Keep cross-page shared components in src/components/common.

• Keep domain-specific components inside src/features/<domain>/components.

• Do not put business-specific logic into base UI components.

• Prefer composition over adding many boolean props.

• Do not create a new Button, Modal, EmptyState, Loading, Badge, Input, Select, Card, or Table component before checking existing shared components.

• If two implementations look similar, first report whether they should be abstracted. Do not force abstraction when future business changes are likely to diverge.

• Preserve existing visual behavior unless the task explicitly asks for design changes.

• After component refactors, run typecheck, lint, tests, and build when available.

• Summarize changed files, removed duplication, compatibility decisions, and pages that need manual visual QA.

十二、一条完整的 Codex 一键执行指令

下面这条指令适合直接发给 Codex，用于“先检查、再计划、经确认后再重构”的工作流。如果你希望一次性执行，可以删除“不要改代码”的限制，但不建议在复杂项目里这么做。

你现在是一个资深前端架构工程师，请帮我优化当前项目的组件复用结构。

项目目标：

让组件目录更清晰，减少重复 UI 和重复逻辑，提高后续新增页面和维护的效率。

重要限制：

1. 先检查并输出方案，不要直接修改代码；

2. 不允许改变现有 UI 视觉、交互、路由、数据请求和业务逻辑；

3. 不要做无关格式化，不要重写整页；

4. 不要为了复用而过度抽象；

5. 优先处理低风险、高重复、容易验收的组件；

6. 所有建议必须结合当前项目已有目录和代码习惯，不要强行套用新架构。

请完成以下任务：

1. 扫描当前项目的组件目录、页面目录、业务模块目录；

2. 找出重复组件、重复 UI 片段、重复逻辑和样式重复；

3. 判断哪些值得抽象，哪些不建议抽象；

4. 设计推荐的组件分层结构；

5. 输出第一轮可执行重构计划，包括涉及文件、新组件 API、兼容策略、风险点和验收方式；

6. 列出建议写入 AGENTS.md 的组件规范；

7. 最后给出一条后续执行重构的 Codex 指令。

输出格式：

• 当前问题概览

• 重复候选表格

• 推荐组件分层

• 第一轮重构计划

• 风险与不建议处理项

• 验收清单

• 后续执行提示词

十三、重构完成后，必须让 Codex 做回归检查

组件复用重构最大的风险，是“代码更干净了，但页面坏了”。因此重构完成后，不要只看 build 是否通过，还要检查页面表现、交互状态、响应式、空数据、错误状态、加载状态和边界数据。

请对刚才的组件复用重构做回归检查。

请检查：

1. TypeScript 类型是否通过；

2. lint 是否通过；

3. build 是否通过；

4. 被重构组件的所有调用方是否仍然正常；

5. 是否存在 import 路径错误或循环依赖；

6. 是否有 UI 状态丢失，例如 loading、disabled、empty、error、hover、active；

7. 是否影响移动端布局；

8. 是否删除了仍被使用的旧组件；

9. 是否有 props 兼容问题；

10. 是否需要补充测试或文档。

请输出：

• 已运行的命令和结果

• 发现的问题

• 已修复的问题

• 仍需人工验收的页面

• 是否建议继续下一轮重构

十四、设计师或产品经理怎么参与这类优化？

组件复用结构不是纯技术问题。设计师和产品经理也应该参与，因为组件是否应该复用，取决于产品语义和未来变化方向。比如两个卡片视觉上很像，但一个用于营销推荐，一个用于订单状态，它们未来变化方向可能完全不同，强行合并会让后续设计扩展变难。

如果你是设计师，可以让 Codex 输出“组件复用影响清单”：哪些 UI 被合并，哪些状态被统一，哪些页面需要视觉复核。然后你只需要重点检查这些页面，而不是通读代码。

请把本次组件复用重构转换成设计验收清单。

我不需要看代码细节，请输出：

1. 哪些页面的 UI 可能受到影响；

2. 哪些组件被合并或替换；

3. 每个组件需要检查的状态，例如默认、hover、active、disabled、loading、empty、error；

4. 需要重点检查的移动端断点；

5. 与设计稿可能不一致的风险点；

6. 建议截图对比的页面路径。

十五、常见错误：这些情况不要让 Codex 硬抽象

• 不要把未来变化方向不同的业务组件强行合并。现在代码相似，不代表三个月后仍然相似。

• 不要为了减少文件数量而牺牲可读性。组件拆分的目标是降低维护成本，不是减少行数。

• 不要让一个基础组件知道具体业务，例如订单状态、会员等级、文章分类、支付状态。

• 不要一次性移动大量目录。大面积改 import 会让 review、回滚和排查问题变得困难。

• 不要忽略视觉回归。组件复用重构很容易在边距、宽度、换行、暗色模式、移动端上出问题。

• 不要把 components/common 变成垃圾桶。凡是不知道放哪的组件都放 common，最后 common 会变成新的混乱中心。

十六、组件复用优化验收清单

十七、FAQ：关于用 Codex 优化组件复用结构

1. Codex 可以直接自动重构整个组件库吗？

技术上可以，但不建议一开始这么做。组件复用结构优化涉及架构、设计语义和业务边界，一次性全量重构风险很高。更稳的方式是先体检、再计划、先做一个低风险模块，确认无问题后再分批推进。

2. 没有单元测试的项目还能让 Codex 做吗？

可以，但要降低重构范围，并增加人工验收清单。没有测试时，Codex 至少应该运行 typecheck、lint、build，并列出需要人工检查的页面和状态。

3. 组件复用是不是越多越好？

不是。过度复用会导致组件 API 膨胀，业务差异被硬塞进 props。真正好的复用，是让稳定部分复用，让变化部分保持独立。

4. React、Next.js、Vue 项目都适用吗？

适用。原则是一致的：先识别重复，再判断抽象价值，再做分层和低风险迁移。区别只在于目录约定、组件写法、路由结构和测试命令。

5. 设计师能不能用这套方法？

能。设计师不需要关心所有代码细节，可以让 Codex 输出组件影响清单、页面验收清单和状态检查清单，用来判断重构后视觉和体验有没有偏移。

十八、总结

用 Codex 优化组件复用结构，关键不是让它“自动重构”，而是让它按工程流程工作：先读代码库，找重复；再判断哪些值得抽象；再设计组件分层；再选择低风险模块试点；最后通过类型、构建、测试和视觉验收确认结果。

组件复用优化做得好，项目会更容易扩展；做得差，只是把重复代码变成更难懂的抽象。给 Codex 的指令越清楚，它越容易保持边界、减少误改，并把重构变成一次可 review、可回滚、可持续的工程改进。

参考来源

• OpenAI Developers：Codex 官方开发者文档，用于确认 Codex 的代码理解、代码生成、审查、调试和自动化开发任务能力。

• OpenAI：Codex 产品页，用于确认 Codex 可用于复杂重构、测试和代码审查等工程工作。

• OpenAI：Introducing Codex，用于确认 Codex 可读写文件，并运行测试、linter、type checker 等命令，同时仍需要人工审查。

• OpenAI Developers：AGENTS.md 与 Codex Best Practices，用于确认项目规则、测试命令和工程约定可以写入 AGENTS.md。