5.4 类型体操方法论

5.4 类型体操方法论

这节在地图里是高级类型的"刹车片"。5.1–5.3 给了你很强的能力，但能力用错地方就是负担。我们讲清"什么时候该写复杂类型、什么时候该停"，并给出几条实战纪律，帮你避开"炫技型代码"的坑。

类型体操的收益边界

类型编程不是越复杂越好。它的收益来自"把运行期才能保证的事提前到编译期"，当这个收益明显大于阅读成本时才值得。

// 收益明显：用类型强制 API 路径与参数匹配
type Route = "/users" | "/users/:id" | "/posts";
type ParamOf<R extends Route> =
  R extends "/users/:id" ? { id: string } : never;
function go<R extends Route>(r: R, p: ParamOf<R>) {}
go("/users/:id", { id: "1" }); // OK
// go("/users/:id", {});       // 报错：缺 id，契约生效
​

输入输出：路径与参数被类型绑死，拼错或少传编译期拦下。这种"约束业务正确性"的体操值得写。

何时该停手：三类信号

// 信号一：类型写出来自己都要试三次才对
// 信号二：为了一个只出现一次的场景写 30 行条件类型
// 信号三：同事读不懂，只能你一人维护
// 出现任意一条，重新考虑是否用普通联合/重载/运行时校验替代
​

背景：有人用递归条件类型解析 URL query string，结果类型展开巨长、报错信息天书。操作：退回用 Record<string, string> + 运行时校验。结果：代码可读性回升，正确性没丢。解读：类型不是唯一防线，运行时 schema 校验常常更直白。

复杂度控制：把聪明封进工具库

// utils/types.ts —— 复杂类型集中此处，配注释与测试
/** 提取 Promise 内部类型，支持嵌套 */
export type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
/** 把对象指定键变可空，用于部分更新 */
export type NullableKeys<T, K extends keyof T> = Omit<T, K> & { [P in K]: T[P] | null };
// 业务文件只调用，不重造
import type { NullableKeys } from "@/utils/types";
​

业务侧永远调用现成工具，复杂实现只在工具库出现一次。新人看业务代码不被类型吓退，工具库有注释兜底。

错误信息可读性原则

类型越复杂，报错越难懂。用"可辨识的中间类型"拆步骤，让报错指向中间产物而非整个巨型表达式。

// 不好：一整条巨型条件类型，报错指向它整体
// 较好：分步命名
type Step1 = Extract<Keys, "a" | "b">;
type Step2 = { [K in Step1]: ... };
// 报错会指明是 Step1 还是 Step2 出问题
​

这张图给出"类型复杂度 vs 收益"的决策区间：

实战：用重载替代复杂联合分发

有时函数重载比一个巨型条件返回类型更清楚：

// 重载：调用处类型清晰，实现处内部用 any 兜底
function parse(input: string): number;
function parse(input: number): string;
function parse(input: string | number): string | number {
  return typeof input === "string" ? Number(input) : String(input);
}
const a = parse("1"); // number
const b = parse(1);   // string
​

背景：返回类型依赖入参类型。操作：用重载签名分别描述。结果：调用侧类型精确，实现侧简单。解读：当"不同入参→不同出参"且组合不多，重载比条件类型更可读。

给类型工具写单测

复杂类型值得像函数一样被测。用类型断言测试锁定它的行为，变更时立刻暴露。

import { expectTypeOf } from "vitest";
import type { NullableKeys } from "@/utils/types";

interface Article { id: number; title: string; body: string; }
type Patch = NullableKeys<Article, "title" | "body">;

expectTypeOf<Patch>().toEqualTypeOf<{
  id: number;
  title: string | null;
  body: string | null;
}>();

// 若有人改了 NullableKeys 语义，这条断言失败，契约被守护
​

背景：类型工具一旦被多处复用，改错影响面大。操作：给关键工具写类型断言测试。结果：重构类型工具时不会悄悄改变下游契约。解读：和 4.4 的"单测类型断言"同一思路——类型也是契约，契约也要被测试守护。

用品牌类型替代复杂体操

有些"语义约束"用运行时校验 + 品牌类型更省心，不必写长条件类型。

// 目标：确保"邮箱字符串"不会和普通 string 混用
type Email = string & { __brand: "email" };
function asEmail(s: string): Email {
  if (!s.includes("@")) throw new Error("不是邮箱");
  return s as Email;
}
function send(to: Email) { /* 只接邮箱，普通 string 进不来 */ }
const e = asEmail("a@b.com"); // OK
// send("a@b.com"); // 报错：普通 string 不是 Email

// 等价于用条件类型给 string 加约束，但品牌类型维护成本更低
​

背景：想区分"语义不同的同形类型"。操作：品牌类型 + 一个校验工厂。结果：编译期隔离、运行期兜底。解读：这比"用条件类型在字符串里抠格式"实在得多——格式校验本来就是运行时的活，类型只负责"贴标签"。

渐进复杂度：从联合到工具再到体操

新手别一上来写深层递归。按这条阶梯递进，能写清楚就别升级：

第一级：普通联合 / 接口 —— 绝大多数场景够用
第二级：内置工具（Pick/Omit/Record/Parameters）—— 派生变体
第三级：简单映射 / 条件 —— 需要"按规则生成"时
第四级：递归 + infer 组合 —— 仅类型库、确有复用价值时
​

背景：很多团队一学类型编程就到处用递归，结果业务代码难以维护。操作：先问"前一级能不能解决"。结果：复杂度只在必要处出现。解读：这条阶梯本身就是"刹车"的可操作化——把"克制"落到"先易后难"的判断顺序上。

工程取舍：团队类型素养匹配

类型体操的适度程度取决于团队平均水平。新人多的团队，把复杂类型严格收在工具库并配单测;高手聚集的库项目，可在类型层做更多。无论如何，类型的最终目的是"帮人少出错"，不是为了展示语言特性。

实战：用可辨识联合约束状态机

状态机是类型体操"收益明显"的典型场景——把"非法状态转移"挡在编译期，比运行时 if 判断更省心。

type Machine =
  | { state: "idle" }
  | { state: "loading"; url: string }
  | { state: "done"; data: string }
  | { state: "error"; message: string };

function render(m: Machine): string {
  switch (m.state) {
    case "idle": return "等待";
    case "loading": return `加载 ${m.url}`;   // m.url 精确可用
    case "done": return `完成 ${m.data}`;
    case "error": return `出错 ${m.message}`;
  }
}
​

输入输出：在 loading 分支里 m.url 自动可用，不会和 done 的 data 混。漏处理某个状态，加 never 兜底（见 1.1）会让编译失败，强迫你覆盖全部状态。这正是"类型即契约"在流程控制上的体现。

实战：类型测试工具守住体操不退化

复杂类型一旦写好，最怕后人"顺手改坏"。给它配类型级测试，退化即红。

import { expectTypeOf } from "vitest";
type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
expectTypeOf<Awaited<Promise<number>>>().toEqualTypeOf<number>();
// 若有人把递归去掉变成只拆一层，这条测试立刻失败
​

背景：类型工具库被多处依赖，改一处可能影响全局。操作：每个公开工具类型配一条类型断言。结果：破坏性改动在单测阶段暴露。解读：这把"方法论的刹车"落到了自动化——不是靠纪律提醒，而是靠测试拦截，契合第四章质量保障思路。

本节要点回顾

• 类型体操收益 = 把运行期保证提前到编译期，需大于阅读成本
• 三类停手信号：难写对、只一次用、没人懂
• 复杂类型封进工具库加注释，业务侧只调用
• 可读性差时用重载/联合/运行时校验替代

⚠️ 别把类型错误信息的可读性当小事。一个三层条件类型出错，编译器报的行号指向整条表达式，排查可能比运行期 bug 还久;分步命名能缓解。

💡 写复杂类型前先问"这事运行时校验是不是更直白"。很多场景 zod 这类 schema 一行顶十行类型体操，还顺带管了运行时，别硬用类型逞强。