typescript-refactor

TypeScript 重构最佳实践

面向 AI Agent 和大模型的全面 TypeScript 与 TSX 重构和现代化指南。包含 9 个类别中的 47 条规则，并按影响程度排序，用于指导自动化重构、代码审查和代码生成。内容适用于 TypeScript 6.0 和 React 19。

适用场景

以下情况请参考这些指南：

• 为提升类型安全性和可维护性而重构 TypeScript 或 React/TSX 代码
• 设计类型架构（判别联合、品牌类型、泛型）
• 收窄类型，消除不安全的 as 类型断言
• 为 .tsx 文件中的 React 组件和 Hook（props、refs、事件、状态）添加类型
• 采用现代 TypeScript 5.x–6.0 特性（satisfies、using、const 类型参数、推断的类型谓词、可擦除语法、with 导入属性）
• 优化大型代码库的编译器性能（isolatedDeclarations、项目引用）
• 实现类型安全的错误处理模式
• 审查代码中的 TypeScript 特性和陷阱

按优先级划分的规则类别

优先级	类别	影响	前缀
1	类型架构	关键	arch-
2	类型收窄与守卫	关键	narrow-
3	现代 TypeScript	高	modern-
4	React 与 TSX	高	tsx-
5	泛型模式	高	generic-
6	编译器性能	中高	compile-
7	错误安全	中	error-
8	运行时模式	中	perf-
9	特性与陷阱	低中	quirk-

快速参考

1. 类型架构（关键）

• arch-discriminated-unions — 使用判别联合代替字符串枚举，以实现穷尽式模式匹配
• arch-branded-types — 对领域标识符使用品牌类型，防止值混淆
• arch-satisfies-over-annotation — 对配置对象使用 satisfies，以保留字面量类型
• arch-interfaces-over-intersections — 扩展接口而非交叉组合类型，以获得更清晰的错误消息
• arch-const-assertion — 使用 as const 推断不可变字面量
• arch-readonly-by-default — 默认将函数参数和返回值设为只读类型
• arch-avoid-partial-abuse — 避免在构建器模式中过度使用 Partial<T>

2. 类型收窄与守卫（关键）

• narrow-custom-type-guards — 用经过运行时检查的守卫替代 as；TypeScript 5.5+ 会推断类型谓词
• narrow-assertion-functions — 使用断言函数检查前置条件
• narrow-exhaustive-switch — 使用 never 强制实现穷尽式 switch
• narrow-in-operator — 使用 in 运算符收窄接口联合类型
• narrow-eliminate-as-casts — 通过恰当的收窄链消除 as 类型断言

3. 现代 TypeScript（高）

• modern-using-keyword — 使用 using 关键字清理资源
• modern-const-type-parameters — 使用 const 类型参数推断字面量类型
• modern-template-literal-types — 使用模板字面量类型表示字符串模式
• modern-noinfer-utility — 使用 NoInfer 控制类型参数推断
• modern-verbatim-module-syntax — 启用 verbatimModuleSyntax，显式声明导入类型
• modern-erasable-syntax — 优先使用可擦除语法，而非枚举和命名空间，以便剥离类型
• modern-import-attributes — 使用 with 导入属性代替已弃用的 assert

4. React 与 TSX（高）

• tsx-avoid-react-fc — 直接为 props 指定类型，而非使用 React.FC
• tsx-ref-as-prop — 将 ref 作为 prop 传递，而非使用 forwardRef（React 19）
• tsx-extend-native-props — 使用 ComponentPropsWithRef 扩展原生元素 props，而非重新声明
• tsx-discriminated-props — 将互斥 props 建模为可辨识联合类型
• tsx-event-handler-types — 使用 React 合成事件类型为事件处理函数指定类型
• tsx-hook-typing — 为可空和可变状态的 useState/useRef 指定类型

5. 泛型模式（高）

• generic-constrain-dont-overconstrain — 尽可能少地约束泛型
• generic-avoid-distributive-surprises — 控制分布式条件类型
• generic-mapped-type-utilities — 为重复转换构建自定义映射类型
• generic-return-type-inference — 保留泛型函数的返回类型推断

6. 编译器性能（中高）

• compile-explicit-return-types — 为导出的函数添加显式返回类型
• compile-avoid-deep-recursion — 避免定义深度递归类型
• compile-project-references — 在单体仓库构建中使用项目引用
• compile-base-types-over-unions — 使用基础类型代替大型联合类型
• compile-isolated-declarations — 启用 isolatedDeclarations，以并行生成声明文件

7. 错误安全（中）

• error-result-type — 使用 Result 类型代替抛出异常
• error-exhaustive-error-handling — 对带类型的错误变体进行穷尽检查
• error-typed-catch — 将 catch 子句变量的类型指定为 unknown
• error-discriminated-error-unions — 将领域错误建模为可辨识联合类型

8. 运行时模式（中）

• perf-union-literals-over-enums — 使用联合字面量而非枚举——枚举无法被擦除
• perf-avoid-delete-operator — 避免对对象使用 delete 运算符
• perf-object-freeze-const — 使用 Object.freeze 和 as const 实现真正的不可变性
• perf-object-keys-narrowing — 避免 Object.keys 扩大类型范围
• perf-map-set-over-object — 动态集合优先使用 Map 和 Set，而非普通对象

9. 特性与陷阱（低至中）

• quirk-excess-property-checks — 了解对象字面量的多余属性检查
• quirk-empty-object-type — 避免使用 {} 类型——它表示非 nullish 值
• quirk-structural-typing-escapes — 防范结构化类型逃逸口
• quirk-variance-annotations — 使用变体注解说明泛型意图（而非用于提升速度）

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则的模板

参考文件

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