TypeScript泛型约束完整指南：extends、keyof与T[K]索引访问类型实战

TypeScript 泛型约束的作用，是让类型参数保留复用能力，同时限定它必须具备的结构。遇到“类型 T 上不存在某属性”时，不要改成 any；用 extends 描述函数需要的最低能力，再用 keyof 绑定对象与键，用 T[K] 保留属性对应的返回类型，错误就能在编译期暴露。

本文按 TypeScript strict 模式讲解，从无约束泛型的真实报错开始，逐步实现安全取属性、配置更新和接口字段选择。示例可保存为 generic.ts 后执行 npx tsc --strict --noEmit generic.ts，并通过一组故意失败的调用确认约束确实生效。

一、先看结论：三种泛型约束怎么选

一句话：extends 描述能力，keyof 绑定键，T[K] 保留返回类型；先写最小约束，再验证。

二、为什么无约束的 T 不能随便访问属性

基础概念不熟时，可先看 TypeScript 教程。先保留下面的错误版本并运行 tsc，得到编译器证据后再修复，不要一看到红线就用类型断言压掉。

// 错误版本：T 可能是 number，编译器不能假定它有 length
function printLength<T>(value: T): number {
  return value.length;
}

这段代码会报错，因为 T 可能是数字，编译器不能假定它有 length。正确做法是描述最小结构：

// 定义最小结构：只要拥有 number 类型的 length 即可
interface HasLength {
  length: number;
}

// T 必须满足 HasLength，函数内部才能安全访问 value.length
function printLength<T extends HasLength>(value: T): number {
  return value.length;
}

console.log(printLength('w3cschool')); // 字符串有 length
console.log(printLength([1, 2, 3]));   // 数组也有 length

预期结果（未在本机执行）为 9 和 3。传入数字时，tsc 会在编译阶段拒绝。

extends 在这里不是类继承，而是“传入类型至少满足这个结构”。结构类型系统只关心是否拥有所需成员，字符串、数组和自定义对象都可以满足 HasLength。更系统的例子可参考 TypeScript 深入教程。

约束只应包含函数内部真正访问的成员。若把 HasLength 扩成同时要求 name、id 和 createdAt，字符串与数组就会被无端排除，复用性反而下降。

三、keyof 把键限制在对象真实属性内

// T 是对象类型，K 必须是 T 的键之一
function getProperty<T extends object, K extends keyof T>(
  object: T,
  key: K
): T[K] {
  // 返回类型 T[K] 表示“传入哪个键，就返回哪个属性类型”
  return object[key];
}

const course = { title: 'TypeScript', lessons: 12 };

// 正确：title 是 course 的键，返回 string
const title = getProperty(course, 'title');

// 错误：price 不是 course 的键，编译失败
// getProperty(course, 'price');

K extends keyof T 建立了两个类型参数的关系：先确定对象 T，再把 K 限制为 T 的键。这个 keyof 用法不是简单生成字符串联合，而是在调用时让键跟随对象变化。

返回值 T[K] 是索引访问类型，能够保留具体属性类型：

// lessons 推导为 number
const lessons = getProperty(course, 'lessons');
lessons.toFixed(0);   // 可以：推导为 number

// title 推导为 string，不能调用 toFixed
// title.toFixed(0);  // 编译错误：title 是 string

如果把返回类型粗暴写成 T[keyof T]，结果会变成对象所有属性类型的联合，调用者还得重新缩小类型。单独引入 K，正是为了保存“传入哪个键，就返回哪个属性类型”的关系。

四、约束配置合并，而不是用 any 放弃检查

// 定义最小结构：必须有字符串 id
type Identified = { id: string };

// T 必须满足 Identified，patch 是 T 的部分属性
function mergeById<T extends Identified>(base: T, patch: Partial<T>): T {
  // 展开 base 和 patch，最后用原 id 覆盖，避免主键被改
  return { ...base, ...patch, id: base.id };
}

const user = mergeById(
  { id: 'u-1', name: '编程狮', active: true },
  { active: false }
);

console.log(user);

这个约束保证对象必须有字符串 id，并避免补丁覆盖主键。把 T 换成 any 虽然不报错，却会让拼错的字段和错误值一路流到运行时。JavaScript 教程 可以帮助理解对象展开的运行时行为。

不过这段实现仍有边界：Partial<T> 允许 patch 中出现 id，只是函数最终用原值覆盖它。若希望调用端也不能传 id，可改成 Omit<Partial<T>, 'id'>：

function updateById<T extends Identified>(
  base: T,
  patch: Omit<Partial<T>, 'id'> // 禁止 patch 中出现 id
): T {
  return { ...base, ...patch };
}

// 错误：patch 中不能传 id
// updateById(user, { id: 'u-2' });

// 正确：只更新 active
updateById(user, { active: true });

此时 updateById(user, { id: 'u-2' }) 会直接编译失败，而 { active: true } 仍然合法。这是类型系统为 API 使用者提供的决策信息。

五、条件类型适合映射，不适合掩盖复杂设计

// 根据 T 是否为 Error 选择不同输出形状
type ApiResult<T> = T extends Error
  ? { ok: false; error: T }
  : { ok: true; data: T };

条件类型根据输入类型选择输出形状。它适合类型转换和库接口，但不应把十几条业务规则塞进一个别名。推导变得难读时，拆成命名类型和普通函数更容易维护。

泛型默认值也不能代替约束。T = string 只是调用者未提供类型时的默认值；T extends string 才限制允许的范围。运行部分可以在 JavaScript 环境观察，但类型检查必须交给项目实际使用的 tsc 与 tsconfig。

六、泛型约束的常见失败

排查推导异常时，一次只改变一项：先显式写出 T 和 K，确认约束关系；再去掉显式参数，观察推导结果；最后检查对象是否因提前赋值而发生字面量拓宽。不要同时加入条件类型、重载和断言，否则很难知道是哪一层改变了结果。

七、用编译成功与编译失败两组样例验收

类型工具不能只验证“正确代码能通过”，还要验证错误调用会被拒绝。可以保留一个不进入生产构建的类型测试文件：

// 应通过：name 是对象的键
getProperty({ id: 1, name: 'A' }, 'name');

// @ts-expect-error 对象中不存在 missing
getProperty({ id: 1, name: 'A' }, 'missing');

// @ts-expect-error number 不满足 HasLength
printLength(42);

@ts-expect-error 的价值是：如果未来修改让错误意外消失，编译器反而会提示这条指令不再需要。它比普通 @ts-ignore 更适合类型回归。

最后分别运行 npx tsc --strict --noEmit generic.ts 和项目自己的构建命令；前者验证最小示例，后者确认真实 tsconfig、库版本和生成目标没有带来差异。

发布公共类型声明时，还要在最低支持的 TypeScript 版本上编译。较新的类型语法可能在本机通过，却让下游旧编译器无法解析；这属于版本兼容问题，不是泛型约束本身错误。把最低版本写进包说明，并在持续集成中保留对应编译任务。

类型检查也不能替代运行时验证。来自 JSON、接口或 localStorage 的数据在运行时没有 T 的保证，必须先用校验函数或 schema 判断真实结构，再交给泛型函数。泛型约束保护的是已进入 TypeScript 类型系统的调用关系，不能自动清洗未知外部数据。

总结

TypeScript 泛型约束的核心不是语法炫技，而是表达“这个函数最低需要什么能力”。extends 描述结构，keyof 用法负责绑定真实键，T[K] 索引访问类型保留精确返回值，条件类型只用于必要映射。先写最小约束，再用一组应通过和一组应失败的调用验证，只有真实需求出现时才增加复杂度。

延伸学习

1. TypeScript 泛型字母含义 适合补充命名习惯；
2. TypeScript 泛型基础 可复习类型参数的基本概念。

3. TypeScript快速入门（通俗易懂）

常见问题

Q：extends 在泛型里等于类继承吗？

A：不等于。它表示类型参数必须可赋值给某个类型，常用于结构约束，并不要求存在类的继承关系。

Q：什么时候只用 keyof 就够了？

A：当任务只是限制属性名时，用 K extends keyof T 即可。还要限制对象具备特定成员时，再给 T 增加 extends 约束。

Q：泛型约束越多越安全吗？

A：不是。过度约束会降低复用性并让推导恶化。约束应只覆盖函数内部实际访问的成员和必须保持的关系。

Q：泛型约束能替代运行时校验吗？

A：不能。来自 JSON、接口或 localStorage 的数据在运行时没有类型保证，必须先用校验函数或 schema 判断真实结构，再交给泛型函数。