TypeScript 严格模式（深度工作流）

严格性是一种渐进式特性，而非单一开关。目标是在不阻碍交付的前提下，通过渐进式迁移与在 IO 边界处设置清晰的类型边界，显著减少运行时意外行为。

何时提供该工作流

触发条件：

• 启用 strict、strictNullChecks、noImplicitAny 或 noUncheckedIndexedAccess
• 遗留代码库中充斥着 any 和 @ts-ignore
• 存在本可通过类型系统捕获的运行时错误（如访问 undefined、数据结构不匹配等）
• 开发库时需提供准确的 .d.ts 导出声明

初始建议：

采用六个阶段：（1）基线与目标设定，（2）编译器标志路线图，（3）边界类型定义（IO 边界），（4）类型收窄与穷尽性检查，（5）泛型与模式设计，（6）验证与防护机制。确认当前使用的TS 版本、构建工具（如 tsc、esbuild 等）以及monorepo 的目录结构。

阶段 1：基线与目标设定

目标：明确当前痛点与期望达成的严格程度，并以可度量指标为依据。

操作项

• 执行 tsc --noEmit，统计总错误数及按错误数量排序的问题最集中的文件
• 识别核心依赖包与末端应用，用于确定迁移优先级顺序
• 明确定义非目标事项（例如：“本季度不对未经类型的第三方 JSON 数据追求完美类型覆盖”）

退出条件：基线错误数 + 明确的高优先级目录列表。

阶段 2：编译器标志路线图

目标：以渐进方式启用各项编译器标志——集中修复错误簇，而非一次性处理整个仓库。

典型启用顺序（需依实际情况调整）

1. strictNullChecks（通常收益最高）
2. noImplicitAny：对新文件强制启用，并逐步收紧旧文件
3. strictFunctionTypes、strictBindCallApply
4. noUncheckedIndexedAccess（影响广泛，需提前规划 undefined 联合类型处理）
5. exactOptionalPropertyTypes（边界情况较多，建议延后启用）

实践技巧

• 使用 // @ts-expect-error 并附带对应 issue 编号，替代无注释的 @ts-ignore
• 对要求更严格的部分包，采用路径专属的 tsconfig 配置，通过 extends 继承基础配置
• CI 门禁：禁止在变更行中引入新的 any 类型（借助 eslint 规则 @typescript-eslint/no-explicit-any）

退出条件：一份明确的标志启用时间表，并为每个包指定责任人（owners）。

阶段 3：边界类型定义（IO 边界）

目标：对外部输入数据仅做一次校验；内部逻辑则完全信任已收窄的类型。

常用模式

• 在 API 边界使用 zod / io-ts / valibot 进行运行时解析与校验
• 对配置对象使用 satisfies 操作符——保留字面量类型信息
• 避免未经校验直接将 unknown 类型强制转换为其他类型

接口定义

• 尽可能使用 OpenAPI 或 graphql-codegen 等工具自动生成类型定义
• 为 ID 等关键标识符采用品牌化类型（Branded types）（例如：type UserId = string & { __brand: 'UserId' }），防止类型混淆

退出条件：所有新增的 IO 相关代码均已实现并文档化“解析 → 类型化”的完整流程。

阶段 4：类型收窄与穷尽性检查

目标：让控制流分析真正为你服务——善用可辨识联合类型（discriminated unions）与never 类型校验。

实践规范

• 对状态机建模使用可辨识联合类型：如 { status: 'loading' } | { status: 'ok', data: T }
• 在 switch 语句中配合 assertNever(x) 实现编译期穷尽性检查
• 统一模块内对可选链式调用（optional chaining）与显式 undefined 处理的选择，保持一致性

空值处理

• 在代码库各模块中，统一采用 undefined 或 null 中的一种约定，避免混用

退出条件：若干代表性模块已完成重构，其中易引发错误的可选类型使用明显减少。

阶段 5：泛型与模式设计

目标：在保障可复用性的同时，避免落入 any 类型泛滥的陷阱——合理运用约束（constraints）与默认类型（defaults）。

指导原则

• 优先使用 extends 设置泛型约束；除非确实需要完全通用，否则避免无约束泛型
• 谨慎使用条件类型——在应用代码中，应以可读性为先，避免过度追求技巧性
• 利用 ReturnType / Parameters 等内置类型辅助类型推导
• 避免因数组可变性导致的类型推导异常——必要时显式声明元素类型

性能考量

• 庞大的映射类型（mapped types）可能显著拖慢 tsc 编译速度——考虑拆分或简化此类类型

退出条件：在共享库的风格指南中，已包含明确的泛型使用规范章节。

阶段 6：验证与防护机制

目标：确保严格性可持续维持——任何退化均能在 CI 中被及时捕获。

CI 集成

• 受影响项目必须通过 tsc --noEmit 检查，且结果为绿色（无错误）
• 启用感知类型的 ESLint 规则；pre-commit 检查为可选
• 当开发库时，使用 dtslint 或 tsd 对 library 的类型定义进行专项测试

重构安全性

• 按模块提交小粒度 PR；仍需配套完整的运行时测试——类型检查无法替代测试

最终审查清单

• 已建立基线指标与编译器标志启用路线图
• IO 边界已通过 Schema 校验或代码生成完成类型验证
• 关键状态机已采用可辨识联合类型与穷尽性检查机制
• 共享代码中泛型使用规范已在风格指南中明确记录
• CI 已在合并前强制执行类型检查

高效指导建议

• 优先使用 unknown 而非 any——强制在使用点执行类型收窄。
• 当用户抵触 noUncheckedIndexedAccess 时，提供辅助 getter 方法或基于 Record 的模式示例。
• Monorepo 场景下：确保所有包使用统一版本的TypeScript——版本错位（version skew）将引发难以排查的“幽灵错误”。

应对偏差情形

• AllowJS 混合代码库：优先为关键路径编写强类型封装层。
• 第三方 未提供类型定义的库：创建本地 d.ts 声明文件，或构建一个封装模块（wrapper module），仅暴露经收窄后的类型接口。