TypeScript best practices 是一个面向 TypeScript 编码与审查场景的技能,适用于编写、阅读或审查 TypeScript 代码,以及在类型安全与校验模式之间做选择时。它的总体原则是“先应用类型系统纪律”,即尽量用类型结构表达约束,而不是依赖运行时检查或断言。
主要能力与规则要点:
- 可辨识联合:用一个 kind 字面量判别字段对变体建模,使不可能的状态无法被表示,避免用一堆可选字段拼凑对象。
- 品牌类型:给原始类型加上只读品牌标记(如 & { readonly __brand: "X" })防止混用;在边界处校验一次,品牌只能来自经过验证的类型守卫,不能来自 as。
- 构造式建模:从结构上让非法值无法构造,例如用 [T, ...T[]] 表示非空数组、[T, T] 表示偶数长度、用起点加时长表示区间;这属于结构约束,不依赖运行时守卫或改进类型。
- 最简单的全类型:只要所有操作都能保持全函数,就保留 T[];仅当松散类型迫使使用 !、类型断言或“不应发生”的抛错时,才收紧为 NonEmpty<T> 之类的类型。
- unknown 优先于 any:外部数据一律视为 unknown。
- schema 先于手写守卫:在逐属性手写类型守卫之前,优先使用仓库已有的运行时 schema 库,并从 schema 推断类型,例如 z.infer。
- 禁止 as 断言:每个 as 都可能埋下运行时崩溃隐患,只有在校验之后才允许断言。
- 收窄层次:判别字段 switch 优先于 in 运算符,in 优先于 typeof/instanceof,再优先于用户自定义类型守卫,as 排在最后。
- 类型守卫必须真正验证声明:说谎的守卫比 as 更糟,因为 bug 藏在声称安全的名字后面;命名采用 isX 或 hasX。
- 穷尽性检查:在 default 分支内联 const _exhaustive: never = x;,让新增变体时编译器报错。
- 用 satisfies 代替 as:在不拓宽字面量类型的前提下校验值。
- 边界校验:数据进入系统处解析为具名领域类型,Record<string, unknown> 之类的松散类型止步于该解析点,内部信任类型。
- schema 派生类型:在声明新接口前,先考虑 Pick/Omit/Parameters/ReturnType/Awaited/typeof。
- 对象参数:用对象而非位置参数传参,使参数顺序自解释;热路径(逐帧渲染、分词器、解析器)可例外。
- 真实测试:能真实运行的就不要 mock,优先使用框架的真实测试原语并做泄漏/可释放检查,在运行中的构建里验证 UI;只 mock 本地无法运行的部分。
- 结构化遥测:优先使用带足以上下文、可凭 id 排查问题的结构化日志诊断;发布代码中不使用 console.log。
使用方式:该技能作为编码助手或审查流程中的指导规则集使用,在写、读、审查 TypeScript 代码时按上述规则约束类型设计与校验方式。资料另提供 references/patterns.md 作为示例参考。
适用场景:TypeScript 项目中的类型建模、外部数据边界解析、守卫与断言审查、联合类型变体扩展、测试与日志规范等。
限制:资料未提供具体安装命令、代码生成能力、收费信息或平台要求,暂未提供;具体规则落地需结合所在仓库的 schema 库与测试框架。