TypeScript 最佳实践是一份面向 TypeScript 代码阅读与编辑的规则集,适用于任何 .ts 或 .tsx 文件。使用前应先应用“类型系统纪律”(type-system-discipline)原则技能。
主要规则按用途可分为以下几类:
类型建模:用带 kind 字面量判别字段的判别联合(discriminated unions)表达变体,使不可能状态无法被表示,避免可选字段堆叠;用 & { readonly __brand: "X" } 品牌原始类型,防止混用,并在边界处校验一次;采用构造性建模(constructive modeling),让非法值无法被构造,例如用 [T, ...T[]] 表示非空、[T, T][] 表示偶数长度、用起点加时长表示区间,而非依赖运行时守卫或精化类型;在操作保持全函数性时保留 T[],仅当松散类型迫使使用 !、类型断言或“不应发生”抛错时才强化为 NonEmpty<T>。
类型安全与收窄:外部数据一律视为 unknown,优先于 any;在收窄层级上,判别字段 switch 优于 in 运算符,优于 typeof/instanceof,优于用户定义类型守卫,优于 as;每个 as 都被视为潜在运行时崩溃,仅在验证后使用;类型守卫必须真正验证其声明,命名以 isX 或 hasX 开头;在 default 分支内联 const _exhaustive: never = x; 以便新增变体时编译器报错;用 satisfies 而非 as,以在不拓宽字面量类型的前提下校验值。
边界与派生:在数据进入处解析为具名领域类型,Record<string, unknown> 止于该解析点,内部信任类型;声明新接口前优先使用 Pick/Omit/Parameters/ReturnType/Awaited/typeof 派生类型;优先使用仓库已有的运行时 schema 库并从 schema 推导类型(如 z.infer),而非手写逐属性类型守卫。
工程实践:传对象而非位置参数以使参数顺序自解释,但在热路径(逐帧渲染、分词器、解析器)上跳过;不 mock 能真实运行的部分,优先使用框架真实测试原语并检查泄漏/可释放性,在运行构建中验证 UI,仅 mock 本地无法运行的部分;优先使用带足够上下文、可凭 id 调试的结构化日志,发布代码中不使用 console.log。
更多示例见 references/patterns.md。