typescript-advanced-types

TypeScript 高级类型

目标

使用高级类型提升安全性，同时避免代码难以阅读。 在复杂度带来的收益足够大之前，优先使用简单类型。

规则

• 对于不可信输入，使用 unknown 而不是 any。
• 让 TypeScript 推断简单类型。
• 仅当某个类型必须关联多个位置时，才添加泛型。
• 对于不同变体，优先使用联合类型和可辨识联合类型。
• 对象结构优先使用 interface。
• 联合类型、条件类型、映射类型和别名使用 type。
• 避免深度嵌套的条件类型或递归类型。
• 如果项目支持，请为可复用工具添加类型测试。

核心工具

• 泛型：在相关类型间复用逻辑。
• 条件类型：根据类型条件选择类型。
• 映射类型：转换对象属性。
• 模板字面量类型：约束字符串模式。
• 工具类型：使用 Pick、Omit、Partial、Required、Readonly、Record。
• infer：从数组、Promise、函数或对象中提取内部类型。
• 类型守卫：在运行时收窄 unknown。
• 断言函数：在运行时验证失败时抛出异常。
• 品牌类型：区分经过验证的字符串或 ID。

泛型规则

如果某个类型参数只出现一次，它很可能是不必要的。

实用模式

type StrictOmit<T, K extends keyof T> = Omit<T, K>;

type ElementType<T> = T extends (infer U)[] ? U : never;

type UserId = string & { readonly __brand: "UserId" };

type User = z.infer<typeof userSchema>;

避免

• 把 any 当作捷径。
• 在可以使用守卫时使用类型断言。
• 使用过于巧妙、掩盖意图的类型。
• 使用无边界的泛型参数。
• 重复定义架构或 API 定义中已有的类型。
• 使用会拖慢编译器的递归类型。

渐进式披露

此技能通过上下文文件提供详细示例。需要时加载：

上下文文件	加载时机
context/core-examples.md	需要泛型、条件类型、映射类型示例时
context/patterns.md	实现 EventEmitter、API 客户端或 Builder 等真实场景模式时
context/techniques.md	需要类型推断、守卫、断言和测试相关内容时

参考资料

• TypeScript 手册
• Type Challenges
• TypeScript Deep Dive
• Effective TypeScript

输出

• 类型方案。
• 最简单的类型结构。
• 必要时说明泛型约束。
• 输入为 unknown 时的运行时验证边界。