name: typescript-refactor description: 从首席专家视角的TypeScript重构和现代化指南。此技能应用于重构、审查或现代化TypeScript代码，以确保类型安全、编译器性能和惯用模式。触发任务涉及TypeScript类型架构、缩小、泛型、错误处理或迁移到现代TypeScript功能。
TypeScript重构最佳实践
全面的TypeScript重构和现代化指南，专为AI代理和LLM设计。包含8个类别中的43条规则，按影响优先级排序，以指导自动化重构、代码审查和代码生成。
何时应用
参考这些指南时：
- 重构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 constarch-readonly-by-default— 默认使用只读类型处理函数参数和返回值arch-avoid-partial-abuse— 避免滥用Partial<T>用于构建器模式
2. 类型缩小和守卫（关键）
narrow-custom-type-guards— 编写自定义类型守卫而不是类型断言narrow-assertion-functions— 使用断言函数进行前提条件检查narrow-exhaustive-switch— 使用never强制执行穷举开关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和settermodern-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— 为monorepo构建使用项目引用compile-base-types-over-unions— 使用基类型而不是大型联合类型
6. 错误安全（中）
error-result-type— 使用结果类型而不是抛出异常error-exhaustive-error-handling— 使用穷举检查处理类型化错误变体error-typed-catch— 将catch子句变量类型化为unknownerror-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— 避免{}类型 — 它表示非空值quirk-type-widening-let— 使用let声明防止类型扩大quirk-variance-annotations— 对泛型接口使用方差注释quirk-structural-typing-escapes— 防范结构类型逃逸门
如何使用
阅读单个参考文件以获取详细解释和代码示例：
参考文件
| 文件 | 描述 |
|---|---|
| references/_sections.md | 类别定义和排序 |
| assets/templates/_template.md | 新规则的模板 |
| metadata.json | 版本和参考信息 |