typescript-refactor

TypeScript 重构最佳实践

涵盖 8 个类别的 43 条 TypeScript 重构与现代化规则，按影响程度排序，帮助指导自动化重构、代码审查和代码生成。

适用场景

• 重构 TypeScript 代码，以提升类型安全性和可维护性
• 设计类型架构（可辨识联合、品牌类型、泛型）
• 收窄类型，消除不安全的 as 类型断言
• 采用现代 TypeScript 4.x-5.x 特性（satisfies、using、const 类型参数）
• 优化大型代码库中的编译器性能
• 实现类型安全的错误处理模式
• 审查代码，排查 TypeScript 的特性和陷阱

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	类型架构	关键	arch-
2	类型收窄与守卫	关键	narrow-
3	现代 TypeScript	高	modern-
4	泛型模式	高	generic-
5	编译器性能	中高	compile-
6	错误安全	中	error-
7	运行时模式	中	perf-
8	特性与陷阱	中低	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 — 函数参数和返回值默认使用 readonly 类型
• arch-avoid-partial-abuse — 避免在构建器模式中过度使用 Partial<T>

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

• narrow-custom-type-guards — 编写自定义类型守卫，而不是使用类型断言
• narrow-assertion-functions — 使用断言函数检查前置条件
• narrow-exhaustive-switch — 使用 never 强制实现穷尽式 switch
• narrow-in-operator — 使用 in 运算符收窄接口联合类型
• narrow-eliminate-as-casts — 通过适当的收窄链消除 as 类型断言
• narrow-typeof-chains — 在访问属性前使用 typeof 收窄类型

3. 现代 TypeScript（高）

• modern-using-keyword — 使用 using 关键字清理资源
• modern-const-type-parameters — 使用 const 类型参数推断字面量
• modern-template-literal-types — 使用模板字面量类型表示字符串模式
• modern-noinfer-utility — 使用 NoInfer 控制类型参数推断
• modern-accessor-keyword — 使用 accessor 自动生成 getter 和 setter
• modern-verbatim-module-syntax — 启用 verbatimModuleSyntax，显式声明导入类型

4. 泛型模式（高）

• generic-infer-over-annotate — 让 TypeScript 推断，而不是显式标注
• generic-constrain-dont-overconstrain — 尽可能少地约束泛型
• generic-avoid-distributive-surprises — 控制分布式条件类型
• generic-mapped-type-utilities — 为重复转换构建自定义映射类型
• generic-return-type-inference — 在泛型函数中保留返回类型推断

5. 编译器性能（中高）

• compile-explicit-return-types — 为导出的函数添加显式返回类型
• compile-avoid-deep-recursion — 避免深度递归的类型定义
• compile-project-references — 在单体仓库构建中使用项目引用
• compile-base-types-over-unions — 使用基类型，而不是大型联合类型

6. 错误安全（中）

• error-result-type — 使用 Result 类型，而不是抛出异常
• error-exhaustive-error-handling — 对类型化的错误变体进行穷尽检查
• error-typed-catch — 将 catch 子句变量的类型标注为 unknown
• error-never-for-unreachable — 使用 never 标记不可达的代码路径
• error-discriminated-error-unions — 将领域错误建模为可辨识联合

7. 运行时模式（中）

• 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，而不是普通对象

8. 特性与陷阱（低中）

• quirk-excess-property-checks — 了解对象字面量的多余属性检查
• quirk-empty-object-type — 避免 {} 类型——它表示非 nullish 值
• quirk-type-widening-let — 避免 let 声明导致类型拓宽
• quirk-variance-annotations — 为泛型接口使用变异注解
• quirk-structural-typing-escapes — 防范结构类型的逃逸机制

使用方法

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

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

参考文件

文件	描述
references/_sections.md	分类定义和排序
assets/templates/_template.md	新规则模板