同事接手一个「类型写得很完整」的表格组件,打开源码,第一行是:
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 T | T 所有属性名组成的联合类型 | 限制字段名只能是已有字段 |
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 校验、手写解析都行,关键是它真的运行了。
小结
K extends keyof T 让字段名和值类型绑定,拼错列名在编辑时就报错。[K in keyof T] 才能看懂别人的类型。infer 用来提取类型;裸类型参数会拆散联合,必要时用方括号包住。as const 保留键名,别用 as 代替检查。可以当天动手的练习:
- 手写
MyPick、MyReadonly、MyPartial,再和标准库的实现对比行为。 - 用映射类型写出「每个字段都可选、且值多一个
null」的类型,观察数组字段的处理差异。 - 给一个列表组件写
Column<T>的联合版本,验证写错字段名和传错值类型都会报错。 - 用
satisfies约束一份配置,再用keyof typeof取键名,对比直接标注的结果。 - 写一个
parseJson<T>加类型守卫,故意传错结构,确认运行时抛错而不是返回脏数据。
下一篇讲代码规范。类型能管住「数据长什么样」,但管不住命名、未使用变量、危险的写法、团队风格。这些要靠 Lint 和格式化工具,而它们最容易变成「所有人都在关规则」的摆设。下一篇就讲怎么让规范真正落地,而不是变成提交前的一道噪音。