# TypeScript 重构最佳实践专为 AI 代理和法学硕士设计的综合 TypeScript 重构和现代化指南。包含 8 个类别的 43 条规则，按影响进行优先级排序，以指导自动重构、代码审查和代码生成。 ## 何时申请在以下情况下请参考这些指南： * 重构 TypeScript 代码以确保类型安全性和可维护性 * 设计类型架构（可区分联合、品牌类型、泛型） * 缩小类型以消除不安全的“as”强制转换 * 采用现代 TypeScript 4.x-5.x 功能（`satisfies`、`using`、const 类型参数） * 优化大型代码库中的编译器性能 * 实现类型安全的错误处理模式 * 审查代码中的 TypeScript 怪癖和陷阱 ## 按优先级规则类别优先|类别 |影响 |前缀 ---|---|---|--- 1 |类型架构 |关键 | `拱门-` 2 |类型缩小和防护 |关键 | `窄-` 3 |现代打字稿 |高| ‘现代-’ 4 |通用模式|高| `通用-` 5 |编译器性能 |中高| `编译-` 6 |错误安全 |中 | `错误-` 7 |运行时模式 |中 | `性能-` 8 |怪癖和陷阱|低-中| `怪癖-` ## 快速参考 ### 1\.类型架构（关键） * [`arch-discrimulated-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` ### 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`]() — 对自动生成的 getter 和 setter 使用 `accessor` * [`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`]() — 使用项目引用进行 monorepo 构建 * [`compile-base-types-over-unions`]() — 使用基本类型而不是大联合类型 ### 6\.错误安全性（中） * [`error-result-type`]() — 使用结果类型而不是抛出异常 * [`error-exhaustive-error-handling`]() — 对类型错误变体进行详尽检查 * [`error-typed-catch`]() — 将 catch 子句变量输入为 `unknown` * [`error-never-for-unreachable`]() — 使用 `never` 标记无法访问的代码路径 * [`error-discrimulated-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]() |版本和参考信息

打字稿重构

包含技能