TypeScript 泛型约束：extends 与 keyof

TypeScript 的泛型系统允许你编写可复用、类型安全的代码。但泛型本身是“未知”的，直接使用会受限。要让泛型真正发挥作用，必须通过约束（constraints）来限定它的能力。其中，extends 和 keyof 是两个核心工具，它们组合起来能实现强大的类型操作。

理解泛型约束的基本形式

泛型约束通过 T extends U 语法实现，意思是“泛型 T 必须兼容类型 U”。这不仅限制了传入的类型，还让 TypeScript 能在函数体内将 T 当作 U 来使用。

定义一个带约束的泛型函数：

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

这个函数有两层约束：

1. T extends object：确保 T 是一个对象类型（不能是 string、number 等原始类型）。
2. K extends keyof T：确保 K 是 T 对象上实际存在的属性名。

掌握 keyof 操作符

keyof 是 TypeScript 的索引类型查询操作符。给定一个类型 T，keyof T 返回一个联合类型，包含 T 所有公共属性的字面量名称。

例如：

interface Person {
  name: string;
  age: number;
}

type PersonKeys = keyof Person; // 等价于 "name" | "age"

关键点：keyof 的结果是字符串字面量类型的联合，不是 string。这意味着你可以精确控制哪些属性名被允许。

组合 extends 与 keyof 实现安全取值

现在，把两者结合起来，解决一个常见问题：从对象中安全地读取属性值。

1. 创建一个泛型函数，接收任意对象和一个键名。
2. 约束键名类型为该对象的合法属性名。
3. 返回值类型自动推导为对应属性的类型。

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

// 使用示例
const user = { id: 1, name: "Alice", active: true };
const userName = getValue(user, "name");     // 类型为 string
const userId = getValue(user, "id");         // 类型为 number
// getValue(user, "email"); // ❌ 编译错误！"email" 不在 keyof user 中

这里，T[K] 是索引访问类型（indexed access type），表示“从类型 T 中按 K 索引出的类型”。

常见错误与正确实践

初学者常犯两类错误：过度约束或约束不足。

错误 1：忘记约束泛型

// 危险写法
function badGet<T>(obj: T, key: string) {
  return obj[key]; // ❌ error: Element implicitly has 'any' type
}

因为 T 可能是任何类型（包括非对象），且 key 是任意字符串，TypeScript 无法保证安全性。

错误 2：错误地使用 keyof

// 错误写法
function wrongGet<T>(obj: T, key: keyof T) { // ✅ 看似正确...
  return obj[key]; // ❌ 仍报错！
}

问题在于：如果 T 是 string 或 number，keyof T 会变成内置属性（如 "toString"），但 obj[key] 的类型无法确定。必须先确保 T 是对象。

正确做法：始终先用 extends object 或更具体的接口约束 T。

function safeGet<T extends Record<string, any>, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

这里 Record<string, any> 表示“任意字符串键、任意值的对象”，比 object 更实用。

高级技巧：约束到特定属性子集

有时你不想允许所有属性，只想允许某些特定类型的属性。例如，只允许获取 string 类型的属性。

1. 定义一个工具类型，筛选出值为 string 的键：

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

这个类型遍历 T 的所有键，如果 T[K] 是 string，就保留 K，否则变成 never。最后通过 [keyof T] 提取所有非 never 的键。

2. 在函数中使用该约束：

function getStringValue<T extends Record<string, any>, K extends StringKeys<T>>(
  obj: T,
  key: K
): T[K] {
  return obj[key];
}

// 使用
const config = { host: "localhost", port: 8080, env: "dev" };
const host = getStringValue(config, "host"); // ✅ OK, 类型 string
// const port = getStringValue(config, "port"); // ❌ Error! "port" 不在 StringKeys<config> 中

实战：构建类型安全的配置读取器

假设你要读取一个嵌套配置对象，并希望路径表达式也能获得类型检查。

1. 定义递归泛型约束，支持点分路径：

type Path<T, K extends keyof T = keyof T> = K extends string
  ? T[K] extends Record<string, any>
    ? `${K}` | `${K}.${Path<T[K]>}`
    : `${K}`
  : never;

2. 实现 get 函数（简化版，仅支持一层）：

function getConfigValue<T extends Record<string, any>, K extends keyof T>(
  config: T,
  key: K
): T[K] {
  return config[key];
}

3. 扩展支持嵌套（进阶）需结合模板字面量类型，但核心思想不变：用 extends keyof 保证每一步都合法。

约束组合的常用模式总结

下表列出常见泛型约束组合及其用途：

避免过度约束

虽然约束能提高安全性，但太严格的约束会降低函数通用性。

反例：

function tooStrict<T extends { id: number }>(obj: T) {
  console.log(obj.id);
}

这个函数只能用于有 id: number 的对象，无法用于 { id: string } 或没有 id 的对象。

改进：只在真正需要时约束。

function flexibleLogId<T>(obj: T & { id: unknown }) {
  console.log(obj.id); // 只要求有 id 属性，类型不限
}

或者使用可选属性约束：

function logOptionalId<T extends { id?: any }>(obj: T) {
  if ("id" in obj) console.log(obj.id);
}

在类和接口中使用泛型约束

泛型约束不仅用于函数，也适用于类和接口。

定义一个带约束的泛型类：

class Repository<T extends { id: string }> {
  private items: T[] = [];

  findById(id: string): T | undefined {
    return this.items.find(item => item.id === id);
  }

  add(item: T): void {
    this.items.push(item);
  }
}

// 使用
interface User {
  id: string;
  name: string;
}

const userRepo = new Repository<User>(); // ✅ OK
// const numRepo = new Repository<number>(); // ❌ Error! number 没有 id 属性

这里，T extends { id: string } 确保所有存储的项都有 id 字段，使 findById 方法安全可用。

调试泛型约束的技巧

当泛型行为不符合预期时：

1. 显式指定类型参数，看是否报错：

getValue<User, "name">(user, "name"); // 如果这里报错，说明约束有问题

2. 用鼠标悬停查看推导类型（在 VS Code 中）：

   • 将光标放在 getValue 上，查看 T 和 K 的实际推导结果。
   • 如果 T 被推导为 any，说明缺少必要约束。

3. 逐步放宽约束，定位问题点：

   • 先移除 K extends keyof T，看是否能编译。
   • 再加回，确认是键约束的问题。

性能与编译时影响

泛型约束完全在编译时生效，不影响运行时性能。TypeScript 会在编译阶段检查所有约束，并在生成的 JavaScript 中完全擦除类型信息。

这意味着：

• 你可以放心使用复杂约束，不会增加包体积。
• 所有类型安全都在开发阶段保证，用户不会收到类型错误。

最佳实践清单

1. 始终为泛型添加必要约束，避免 any 或隐式 any。
2. 优先使用 keyof T 而不是 string 作为对象键的类型。
3. 组合 extends 与接口/类型字面量，精确描述所需结构。
4. 避免在约束中使用 any，改用 unknown 或具体类型。
5. 测试边界情况：传入空对象、原始类型、数组等，确保约束能正确拦截非法输入。

// 好的约束示例
function processItem<T extends { name: string; value: number }>(item: T) {
  console.log(`${item.name}: ${item.value}`);
}