typescript-best-practices

TypeScript 最佳实践

在 Muse 上，遵循此技能前，请阅读平台映射，包括其中针对各项技能的说明。

请先应用 type-system-discipline 原则技能。

规则	摘要
可辨识联合	使用 kind 字面量判别字段为不同变体建模，确保无法表示不可能的状态。不要使用可选字段集合。
品牌类型	使用 & { readonly __brand: "X" } 为原始类型添加品牌，以免混淆。只需在边界处验证一次。品牌必须来自验证型类型守卫（input is AgentId），绝不能来自 as。
构造式建模	设计类型结构，使非法值无法构造。非空列表使用 [T, ...T[]]，偶数长度列表使用 [T, T][]，范围使用 start 加 duration。这不是运行时守卫，也不是对细化类型的期望。
最简单的全函数类型	只要对 T[] 的所有操作都保持全定义，就继续使用 T[]。只有在宽泛类型迫使你使用 !、类型断言或“理论上不应发生”的抛错时，才强化为 NonEmpty<T>。
优先使用 unknown，而非 any	外部数据的类型为 unknown。
先用 Schema，再写守卫	手写逐属性类型守卫之前，先使用仓库的运行时 Schema 库，并从 Schema 推导类型，例如使用 z.infer。
不使用 as 类型断言	每个 as 都可能导致运行时崩溃。只在验证之后才使用类型断言。
缩窄层级	判别字段 switch > in 运算符 > typeof/instanceof > 用户定义的类型守卫 > as。
类型守卫	必须验证其声明。说谎的守卫比 as 更糟，因为 Bug 会藏在一个声称安全的名称背后。将其命名为 isX 或 hasX。
穷尽性检查	在 default 分支中内联 const _exhaustive: never = x;，这样新增变体时编译器会报错。
优先使用 satisfies，而非 as	验证值，同时不扩大字面量类型。
边界验证	在数据进入系统时进行解析，并转换为具名领域类型。Record<string, unknown>（无论具体写法如何）都应止于该解析步骤。内部代码信任类型。参见 boundary-discipline 原则技能。
从 Schema 推导类型	声明新接口之前，优先考虑 Pick/Omit/Parameters/ReturnType/Awaited/typeof。
对象参数	传递对象而非位置参数，让参数顺序一目了然。热路径（逐帧渲染、分词器、解析器）除外。
真实测试	能实际运行的就不要模拟。优先使用框架真实的测试原语，并检查泄漏和可释放资源；在运行中的构建里验证 UI。只模拟无法在本地运行的内容。
结构化遥测	优先使用上下文充足、可根据 ID 调试的结构化日志诊断。已发布代码中不要使用 console.log。

示例：references/patterns.md。