clean-code-ts-react

Robert C. Martin（Uncle Bob）的 TypeScript 5.x + React 19 最佳实践

将 Robert C. Martin 的《Clean Code》（2008）中的工艺原则，重新阐释为适用于现代 TypeScript 和 React 的实践。包含 11 个类别中的 61 条规则，按代码变更整个生命周期中的认知成本排序。示例使用 TS 5.x 和 React 19 的惯用写法——但这些规则关乎永恒的原则，而非特定 API。

这项技能有何不同

有三点让它有别于一般的整洁代码指南：

1. 以现代惯用写法为载体。 示例使用 TS 5.x（satisfies、品牌类型、可辨识联合、const 类型参数）和 React 19（函数组件、hooks、use()，以及适用时的 Server Components）。但规则始终讲的是原则，而非语法。
2. “何时不适用”是重点。 每条规则都包含 2–3 个具体场景，说明原则应当有所变通——不是泛泛的免责声明，而是真实情况。循环计数器可以叫 i。只用一次的代码不必遵循 DRY。某些 HOC 无法避免。
3. 设有原则冲突的元类别。 第 11 类明确列出最常见的冲突——DRY 与单一职责、小函数与深模块（Ousterhout）、类型精确性与 API 易用性、测试作为规范与文档。资深与否，体现在知道该在哪些地方变通。

何时应用

遇到以下情况时，可参考这些指南：

• 编写新的 TypeScript 或 React 代码，并希望获得工艺方面的反馈
• 审查拉取请求中的清晰度、命名或抽象
• 重构现有代码以提升可读性或可维护性
• 设计函数、hook 或组件 API
• 决定要提取、抽象还是复制代码
• 解决两条整洁代码规则之间的冲突（参见第 11 类）

以下情况请跳过这项技能，改用：

• react，了解 React 19 API 模式（并发渲染、Server Components、ref-as-prop、useActionState、<Context>-as-provider）
• typescript，了解编译器性能、tsconfig 调优、类型系统性能
• refactor，了解机械式重构工作流
• tdd，了解 TDD 工作流本身

按优先级划分的规则类别

排序反映变更整个生命周期中的认知成本（阅读 → 理解 → 修改 → 验证 → 发布 → 维护）。越早的阶段影响越大——糟糕的命名会影响每一次阅读。

优先级	类别	影响	前缀	规则数
1	有意义的名称	严重	name-	8
2	函数、组件与 Hooks	严重	func-	8
3	自文档化（类型与注释）	高	doc-	5
4	格式（超越 Prettier）	高	fmt-	4
5	错误处理	高	err-	7
6	数据形状与不可变性	中高	data-	6
7	边界	中高	bound-	4
8	组合优于继承	中高	comp-	6
9	测试	中	test-	5
10	涌现与简单设计	中	emerge-	4
11	元原则：原则冲突时	中	meta-	4

总计：61 条规则。

快速参考

1. 有意义的名称（严重）

• name-intention-revealing — 使用能揭示意图的名称
• name-avoid-disinformation — 避免使用误导性名称
• name-meaningful-distinctions — 做出有意义的区分
• name-component-pascal-case — 组件使用 PascalCase 名词短语
• name-hook-use-prefix — Hooks 使用 useX 动词短语
• name-handler-convention — 事件处理器使用 onX / handleX
• name-boolean-predicate — 布尔变量使用 is/has/can
• name-types-pascal-case — 类型和接口使用 PascalCase

2. 函数、组件与 Hook（CRITICAL）

• func-small — 保持函数、组件与 Hook 简短
• func-one-thing — 一次只做一件事
• func-abstraction-level — 每个函数只使用一个抽象层级
• func-minimize-arguments — 优先使用对象参数，而非冗长的参数列表
• func-no-side-effects — 避免隐藏的副作用（尤其是在渲染过程中）
• func-command-query-separation — 将命令与查询分开
• func-dry — 遵循 DRY，直到概念出现分歧
• func-custom-hook-extract — 将可复用的有状态逻辑提取为自定义 Hook

3. 自我说明：类型与注释（HIGH）

• doc-types-over-comments — 优先使用类型，而非注释
• doc-satisfies-narrows-with-check — 使用 satisfies 检查推断出的值
• doc-jsdoc-public-api — 为公共 API 和不明显的副作用编写 JSDoc
• doc-avoid-redundant-comments — 避免冗余注释
• doc-delete-commented-out-code — 删除注释掉的代码

4. Prettier 之外的格式规范（HIGH）

• fmt-vertical-density — 让相关代码紧凑排列，让无关代码保持距离
• fmt-newspaper-order — 按照报纸的编排方式从上到下组织文件
• fmt-team-rules-over-preference — 遵循团队规范，而非个人偏好
• fmt-imports-grouped — 按来源对导入进行分组

5. 错误处理（HIGH）

• err-early-return — 使用提前返回来简化错误处理路径
• err-result-vs-throw — 审慎选择使用 throw 还是 Result
• err-narrow-unknown — 始终在 catch 块中缩小 unknown 的类型范围
• err-error-boundaries — 使用错误边界处理渲染时的失败
• err-suspense-for-loading — 使用 Suspense 处理加载状态
• err-no-swallow — 绝不静默吞掉错误
• err-null-vs-undefined — 根据领域选择 null 或 undefined

6. 数据形状与不可变性（MEDIUM-HIGH）

• data-discriminated-unions-over-flags — 优先使用判别联合类型，而非布尔标志
• data-readonly-by-default — 将只读数据标记为 readonly
• data-branded-types — 使用品牌类型表示领域不变量
• data-dto-vs-domain — 将 DTO 与领域类型分开
• data-demeter-prop-drilling — Prop drilling 往往意味着违反 Demeter 法则
• data-structural-typing-pitfalls — 谨防结构化类型导致的别名问题

7. 边界（MEDIUM-HIGH）

• bound-wrap-third-party-hooks — 使用自定义 Hook 封装第三方 Hook
• bound-learning-tests — 为第三方行为编写学习测试
• bound-isolate-framework — 在边界处隔离特定于框架的代码
• bound-type-assertions-at-edges — 类型断言只能出现在边界处

8. 组合优于继承（中高优先级）

• comp-children-over-props — 优先使用 children 进行组合，而非配置属性
• comp-small-components — 保持组件小巧且内聚
• comp-avoid-hoc-stacks — 避免堆叠高阶组件
• comp-context-only-when-needed — Context 用于依赖注入（DI），而非避免传递属性
• comp-render-props-vs-hooks — 复用逻辑时优先使用 hooks，而非 render props
• comp-separate-construction-from-use — 将设置与渲染分离

9. 测试（中优先级）

• test-behavior-not-implementation — 测试行为，而非实现
• test-mock-at-boundaries — 只在真正的边界处使用 mock
• test-first-principles — 遵循 FIRST 原则
• test-one-concept — 每个测试关注一个概念，而非一个断言
• test-clean-as-production — 测试代码也应获得生产级别的维护

10. 涌现与简单设计（中优先级）

• emerge-four-rules — 按顺序应用简单设计的四项规则
• emerge-yagni-types — 避免过早引入类型泛型
• emerge-premature-abstraction — 抵制过早抽象
• emerge-reveal-intent — 最大化表达力，让代码成为沟通方式

11. 元原则：原则冲突时如何处理（中优先级）

这是本类别的标志性内容——明确说明一种整洁代码原则何时应让位于另一种原则。

• meta-dry-vs-srp — 概念逐渐分离时，灵活运用 DRY
• meta-small-vs-deep — 当间接层级 > 理解能力时，深层模块优于小函数
• meta-types-vs-ergonomics — 在稳定边界处，易用性优先于类型安全
• meta-tests-as-spec-vs-doc — 针对每个文件，选择将测试作为规范还是文档

使用方法

对于临时问题（“这样的命名可以吗？”、“我应该提取这部分吗？”），请通过上方的快速参考直接跳转到相关规则文件。

对于代码审查或重构，请按优先级顺序浏览各类别——先检查名称和函数形态（影响范围最大），再检查错误和数据形态，最后检查组合和测试。按类别而非按文件逐项检查会更高效。

当两项原则看似冲突时，请阅读相应的元原则（第 11 类）。选出优先适用的原则，并记录决策。

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	添加新规则的模板
metadata.json	版本和参考信息

相关技能

• .experimental/clean-code — 原始的、与语言无关的整洁代码指南（Java 示例）。此技能是其 TS+React 版本。
• .curated/react — React 19 专属模式（Server Components、并发渲染、ref-as-prop）。
• .curated/typescript — TS 编译器性能和 tsconfig 调优。
• .curated/refactor — 机械式重构工作流。
• .curated/tdd — TDD 工作流本身。