同事接手一个「类型写得很完整」的表格组件,打开源码,第一行是:

type Column<T> = {
  key: string;
  title: string;
  render?: (row: T) => string;
};

泛型参数 T 用上了,但 key: string 把列名彻底放开,render 里的 row 虽然类型正确,访问哪个字段却没人管。结果是:列名写错编译不报,运行时读到 undefined;排序字段传了个不存在的名字,表格静默不动。类型看着有,实际一点忙没帮上。

另一种极端是反过来。一个只有四个字段的配置对象,被写成三层条件类型加递归映射,编辑器悬停显示二十行,新人改一个字段查了半小时。类型体操做过头,维护成本比没类型还高。

这篇讲什么:泛型到底解决什么问题、约束和推断怎么配合、keyof 与映射类型怎么从已有类型算出新类型、条件类型和 infer 能做什么、satisfies 补了什么缺口。读完你能做到:写出能自动补全字段名的组件类型;看懂常见开源库的类型声明;判断一段类型该简化还是该保留。

版本说明:本文按 TypeScript 6 写,示例不依赖 7.0 的新特性。文中出现的工具类型都是标准库自带或就地实现,不需要额外依赖。

泛型:让类型跟着参数走

泛型的本质是「类型层面的函数参数」。没有它,你要么写死类型,要么用 any 放弃检查。最简单的例子:

function first<T>(list: T[]): T | undefined {
  return list[0];
}

const a = first([1, 2, 3]);        // a: number | undefined
const b = first(["x", "y"]);       // b: string | undefined

T 不是随便起的名字,它是从实参推断出来的。调用时传 number[],T 就是 number,返回值跟着变。这就是泛型的价值:一次实现,类型随输入流动。

但 T 不能随便用。函数体里想访问 item.id,直接写会报错,因为编译器不知道 T 有没有 id。这时要加约束:

function idsOf<T extends { id: string }>(list: T[]): string[] {
  return list.map((item) => item.id);
}

extends 在这里不是继承,是「至少满足这个形状」。它限制了调用方能传什么,也给了函数体访问字段的权力。约束要尽量窄:写成 T extends object 几乎等于没约束,写成 T extends { id: string; name: string; createdAt: Date } 又会把调用方卡死。按函数体真正用到的字段来写。

有时候类型推断不出来,需要显式指定。比如 T 只出现在返回值里:

function createEmpty<T>(): T[] {
  return [];
}

const list = createEmpty<string>();   // 不写 <string> 会推断成 unknown[]

这是泛型最常见的「失效」场景:类型参数没有推断来源。解决方式要么加一个参数让它参与推断,要么调用时显式写类型实参。不要在函数体里用 as T 硬压,那等于把检查关掉。

泛型也可以有默认值,适合「绝大多数情况用某个类型,少数情况要定制」:

interface ApiResult<T = unknown> {
  ok: boolean;
  data: T;
  message?: string;
}

keyof、索引访问和 typeof:把类型当数据查

三个操作符经常一起出现,作用是「从已有类型里取信息」:

写法得到什么典型用途
keyof TT 所有属性名组成的联合类型限制字段名只能是已有字段
T[K]属性 K 对应的值类型让值的类型跟着字段走
typeof value一个值对应的类型从常量对象推导配置类型
interface Order {
  id: string;
  amount: number;
  status: "pending" | "paid";
}

type OrderKey = keyof Order;          // "id" | "amount" | "status"
type Amount = Order["amount"];        // number

const defaults = { pageSize: 20, sort: "id" as const };
type Defaults = typeof defaults;      // { pageSize: number; sort: "id" }

把三者拼起来,能写出「字段名必须存在、值类型必须匹配」的函数:

function getField<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

const order: Order = { id: "A1", amount: 99, status: "paid" };
const amount = getField(order, "amount");   // number
// getField(order, "amountt");              // 编译报错,字段名拼错

这是泛型最实用的形态:不是炫技,而是把「拼错字段名」这类错误从运行时提前到编辑时。K extends keyof T 是关键,少了它,obj[key] 直接报错。

工具类型:标准库已经写好了一大半

TypeScript 自带一批工具类型,日常够用。先把它们的作用记住,别重复造轮子:

工具类型作用常见场景
Partial<T>所有字段变可选更新接口的请求体、表单草稿
Required<T>所有字段变必填配置校验后的最终结构
Readonly<T>所有字段只读常量、对外暴露的状态
Pick<T, K>只保留指定字段列表页只需要几个字段
Omit<T, K>去掉指定字段创建时去掉服务端生成的 id
Record<K, V>键值映射字典、错误信息表
Exclude<T, U>从联合类型里去掉某些成员过滤状态、事件名
ReturnType<F>取函数返回值类型复用已有函数的返回结构

它们不是魔法,底层就是映射类型和条件类型。自己实现一遍,理解会深很多:

type MyPartial<T> = {
  [K in keyof T]?: T[K];
};

type MyPick<T, K extends keyof T> = {
  [P in K]: T[P];
};

type MyReadonly<T> = {
  readonly [K in keyof T]: T[K];
};

映射类型里的 [K in keyof T] 是在「遍历」类型的所有键。它可以配合 as 做键名重映射,比如给每个字段加前缀:

type Prefixed<T> = {
  [K in keyof T as `form_${string & K}`]: T[K];
};

模板字面量类型让「字符串也有结构」成为可能。事件名、CSS 变量名、路由参数都适合用它约束,但别写得太复杂,否则错误信息会变成一长串模板展开。

工具类型用在公共 API 上要克制。Omit<A, B> 看起来简单,一旦 A 是联合类型,Omit 不会按成员分别处理,而是把所有成员共有的键取出来,结果可能不是你想要的。遇到联合类型,先用 Distribute 思路拆开,再合并。

条件类型与 infer:从类型里「猜」出类型

条件类型的写法像三元表达式,判断的是类型关系:

type IsString<T> = T extends string ? true : false;

type A = IsString<"x">;    // true
type B = IsString<1>;      // false

真正有用的是 infer:在条件里声明一个待推断的类型变量,从结构里把它提出来。标准库的 ReturnType 就是这么实现的:

type MyReturnType<F> =
  F extends (...args: never[]) => infer R ? R : never;

type Fn = (id: string) => { name: string };
type R = MyReturnType<Fn>;   // { name: string }

还可以从数组、Promise、元组里提类型:

type ElementOf<T> = T extends (infer U)[] ? U : never;
type Unwrapped<T> = T extends Promise<infer U> ? U : never;
type FirstArg<F> = F extends (first: infer A, ...rest: never[]) => unknown ? A : never;

有一个反直觉行为叫「分布式条件类型」:当条件类型作用于一个裸的类型参数,而实参是联合类型时,它会自动对每个成员分别判断,再把结果合并。

type Boxed<T> = T extends unknown ? { value: T } : never;

type R = Boxed<"a" | "b">;
// { value: "a" } | { value: "b" },不是 { value: "a" | "b" }

想关掉分布,用方括号把两边包起来:

type BoxedTogether<T> = [T] extends [unknown] ? { value: T } : never;

这个细节在写工具类型时经常决定结果对不对。遇到「联合类型被拆散了」的怪现象,先检查是不是裸类型参数在条件左边。

判别联合与穷尽检查:业务类型的主力

进阶篇里最值得养成的习惯,是用可辨识联合表达「有几种确定的状态」,而不是一堆可选字段。订单状态、请求结果、表单校验都适合:

type RequestState<T> =
  | { status: "idle" }
  | { status: "loading" }
  | { status: "success"; data: T }
  | { status: "error"; error: Error };

function view<T>(state: RequestState<T>) {
  switch (state.status) {
    case "idle": return "等待";
    case "loading": return "加载中";
    case "success": return state.data;
    case "error": return state.error.message;
    default: return assertNever(state);
  }
}

function assertNever(value: never): never {
  throw new Error(`未处理的状态: ${JSON.stringify(value)}`);
}

assertNever 的参数是 never,意味着「所有分支都处理完了,这里不该有值」。以后有人给状态加一个 "timeout",default 分支立刻编译报错。这比写注释「记得处理新状态」可靠得多。

类型收窄不只靠 switch。自定义类型守卫能让判断逻辑复用:

function isOrder(value: unknown): value is Order {
  return (
    typeof value === "object" &&
    value !== null &&
    typeof (value as Order).id === "string"
  );
}

function assertOrder(value: unknown): asserts value is Order {
  if (!isOrder(value)) throw new Error("不是合法订单");
}

asserts 是断言签名:函数正常返回后,调用方后面的代码就把参数当成 Order。它适合「校验失败就抛错」的边界解析,不适合做业务分支判断。

satisfies:既要检查,又要保留字面量

标注类型和保留字面量,过去只能二选一:

type Routes = Record<string, { title: string; public: boolean }>;

const routes: Routes = {
  home: { title: "首页", public: true }
};

routes.home.title;   // 可以
// Object.keys(routes) 是 string[],丢了具体的键名

标注成 Routes 后,编译器只记得「这是个字符串键的字典」,具体有哪些键、键名是什么字面量,全丢了。satisfies 解决这个问题:检查形状,但保留推断出来的精确类型。

const routes = {
  home: { title: "首页", public: true },
  order: { title: "订单", public: false }
} satisfies Routes;

type RouteKey = keyof typeof routes;   // "home" | "order"

配置对象、常量表、主题令牌都适合用它。注意 satisfies 不是断言,它真的会检查;写错字段会报错,而不是像 as 那样放行。

as const 解决的是另一个问题:让推断结果变成字面量而不是宽泛的 string、number。两者经常搭配:

const statusMap = {
  pending: "待支付",
  paid: "已支付"
} as const satisfies Record<string, string>;

type Status = keyof typeof statusMap;   // "pending" | "paid"

完整场景走查:给表格组件补上真正的类型

需求是一个通用表格:列可以配置标题、字段名、自定义渲染;不同页面传入不同的行数据类型。第一版就是开头那个 Column<T>,key 是 string,等于没有约束。

第一步,把字段名收窄到 keyof T:

interface Column<T> {
  key: keyof T;
  title: string;
  render?: (row: T) => string;
}

改完,调用方写错列名会报错。但 render 里的 row 是整行,想渲染某个字段还得自己取,而且取的类型是联合类型,不精确。

第二步,用映射类型生成「每个字段一列」的联合类型,让 key 和 render 的值类型绑定:

type Column<T> = {
  [K in keyof T]: {
    key: K;
    title: string;
    render?: (value: T[K], row: T) => string;
  };
}[keyof T];

这段类型的意思是:先为每个字段生成一个列定义,再取所有列定义的联合。效果是,当 key 写 "amount" 时,render 的第一个参数自动是 number;写 "status" 时是状态联合。编辑器补全也能列出准确字段。

第三步,处理表单错误。表单字段和值类型一一对应,错误信息按字段存:

type FormErrors<T> = {
  [K in keyof T]?: string;
};

function validate<T>(values: T, errors: FormErrors<T>) {
  // errors.amount 只接受 string,写错字段名会报错
}

第四步,接口边界。写一个通用的 JSON 解析函数,把校验函数传进去:

function parseJson<T>(raw: string, guard: (value: unknown) => value is T): T {
  const data: unknown = JSON.parse(raw);
  if (!guard(data)) throw new Error("数据结构不符合预期");
  return data;
}

const order = parseJson(text, isOrder);   // order: Order

这一步把「类型」和「运行时」接上了:泛型负责让调用方拿到正确类型,守卫负责让这个类型在运行时成立。少了任何一半,都只是自我安慰。

第五步,给配置加 satisfies。表格的默认配置、列宽映射、状态文案,都用它约束形状,同时保留键名。上线前跑一次 tsc --noEmit,再检查类型检查耗时。这个组件库不大,检查时间从三秒涨到四秒,可以接受;如果涨到三十秒,就要回头看是不是类型写得过深。

错误现象对照

现象真实原因第一步查什么
泛型被推断成 unknown 或 {}类型参数没有推断来源,只出现在返回值看调用处能否从参数推断;不能就显式写类型实参
Property 'x' does not exist on type 'T'泛型没有约束,函数体却访问了具体字段给 T 加 extends,只约束真正用到的字段
Type instantiation is excessively deep递归条件类型层级过深,或联合类型爆炸简化类型,限制递归深度,拆成多个小类型
联合类型被意外拆散条件类型作用于裸类型参数,触发分布式行为用 [T] extends [U] 关掉分布
配置对象丢了字面量键名用了类型标注,推断被拓宽改用 satisfies,必要时配合 as const
新增状态后没有报错联合类型被拓宽成 string,或没有穷尽检查检查联合定义,补 assertNever
导出的函数类型在别的项目里不可用返回值靠推断,引用了未导出的私有类型给公开 API 显式标注返回类型,导出必要类型

边界与代价

类型体操的收益有明确上限。业务代码里,keyof、映射类型、判别联合、satisfies 这四样能解决八成问题;条件类型和 infer 更多出现在库和工具函数里。一个业务组件为了「类型绝对精确」写两百行条件类型,后人改字段要读半小时,这笔账通常不划算。

判断标准可以很具体:这段类型是否会被三个以上地方复用?出错时是否能给出可读的报错?新人能否在十分钟内看懂?三个里有两个否,就退回简单写法。类型是给人看的,不是给编译器炫技的。

类型检查有性能成本。深层递归、超大联合、复杂条件类型都会拖慢编辑器和 CI。项目变大后,用 tsc --extendedDiagnostics 看检查耗时和类型实例数量;某个类型突然让耗时翻倍,通常是它。skipLibCheck 能挡掉第三方声明的问题,但挡不住自己写的深递归。

公共库和业务项目的标准不同。库的类型是给外部用户看的契约,值得多花时间做精确、做兼容、写测试(类型测试可以用 expectTypeOf 一类工具);业务项目的类型是内部工具,可读和够用优先。别把库的做法照搬到业务里,也别让业务的 any 漏进公共库。

最后一条边界:类型不能替代运行时校验。再精确的泛型,套在 JSON.parse 的 any 上都不成立。边界处永远要有一个「把 unknown 变成可信类型」的函数,类型守卫、schema 校验、手写解析都行,关键是它真的运行了。

小结

泛型是类型参数让类型跟着实参走;能推断就别显式指定,推断不出来就加参数或写类型实参。
keyof 加索引访问是字段级约束K extends keyof T 让字段名和值类型绑定,拼错列名在编辑时就报错。
工具类型和映射类型是算出来的标准库够用就别重写;理解 [K in keyof T] 才能看懂别人的类型。
条件类型要小心分布infer 用来提取类型;裸类型参数会拆散联合,必要时用方括号包住。
satisfies 兼顾检查和字面量配置对象用它;再加 as const 保留键名,别用 as 代替检查。

可以当天动手的练习:

  1. 手写 MyPick、MyReadonly、MyPartial,再和标准库的实现对比行为。
  2. 用映射类型写出「每个字段都可选、且值多一个 null」的类型,观察数组字段的处理差异。
  3. 给一个列表组件写 Column<T> 的联合版本,验证写错字段名和传错值类型都会报错。
  4. 用 satisfies 约束一份配置,再用 keyof typeof 取键名,对比直接标注的结果。
  5. 写一个 parseJson<T> 加类型守卫,故意传错结构,确认运行时抛错而不是返回脏数据。

下一篇讲代码规范。类型能管住「数据长什么样」,但管不住命名、未使用变量、危险的写法、团队风格。这些要靠 Lint 和格式化工具,而它们最容易变成「所有人都在关规则」的摆设。下一篇就讲怎么让规范真正落地,而不是变成提交前的一道噪音。