Agent Skills
返回列表
💻

TypeScript 重构最佳实践

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/shipshitdev-skills-typescript-refactor。

技能介绍

要解决什么问题

TypeScript 项目做大以后,常见痛点不是「有没有类型」,而是类型架构松散、到处 as 断言、联合类型无法穷尽检查,以及为了省事滥用 Partial、大联合类型拖慢编译。团队在做重构、评审或让 AI 生成补丁时,往往缺少一套按影响排序的共识,容易在低优先级琐事上争论,却漏掉 discriminated union、自定义 type guard 这类关键改动。

技能如何工作

本技能把实践整理成 43 条规则、8 个类别,并在资料中标注优先级(CRITICAL → LOW-MEDIUM)与前缀(如 arch-、narrow-、modern-),便于按场景检索:

  • Type Architecture(arch-):discriminated unions 替代 string enum、branded types 防混用 ID、satisfies 保留字面量、接口扩展优于交叉类型等。
  • Type Narrowing(narrow-):自定义 type guard、assertion function、switch 穷尽到 never、用 in 缩窄接口联合、消除不必要的 as。
  • Modern TypeScript(modern-):using 资源清理、const 类型参数、template literal types、NoInfer、verbatimModuleSyntax 等 4.x–5.x 能力。
  • 其余类别覆盖泛型约束与分配律、compile- 导出函数显式返回类型与 project references、error- Result 与 discriminated error、perf- 字面量联合替代 enum、quirk- 多余属性检查与 {} 语义等。

使用方式是按类别或规则 ID 查阅对应 reference 说明与示例;新增规则可参照 assets/templates/_template.md,分类与排序见 references/_sections.md。

适用边界与注意点

这是重构与类型设计清单,不是替代 tsc 配置或 ESLint 的规则全集;条目侧重类型安全、可维护性与编译表现,不会替你决定业务领域模型该怎么命名。自动化重构前应结合项目 tsconfig 与测试;LOW-MEDIUM 的 quirk 类规则更适合 code review 时点名,而非一次性大规模改写。

使用场景

  • 旧代码里大量 `as` 断言,要在不改行为的前提下改成 type guard 与穷尽 `switch`
  • 设计 API 错误与状态联合类型,需要 discriminated union 与 Result 模式的条目对照
  • Monorepo 编译变慢,想按 compile- 规则给导出函数补返回类型并收紧大联合类型
  • 评审 PR 时逐条核对 modern- 规则,确认能否用 `satisfies` 与 const 类型参数替代宽注解

适合人员

  • 维护上千文件 TypeScript monorepo、需要把类型改动和编译耗时纳入评审标准的平台工程师
  • 负责每周合并多条特性分支、要在 review 里统一收窄与泛型写法的一线 Tech Lead
  • 正在把库从 TS 4.x 升到 5.x、要逐项核对 `using` 与 `verbatimModuleSyntax` 的模块维护者
  • 用 AI 生成重构补丁前、希望按 arch-/narrow- 优先级自检补丁内容的应用开发者