泛型

是什么，为什么存在

泛型（generic） 是一种用占位类型来写声明的机制。 这个占位类型叫作 类型参数（type parameter） ，常写成 T、TKey 或 TValue。 调用函数、实例化类或引用类型别名时，具体类型会代入这些参数。 它记录的是同一个未知类型在多个位置之间必须保持怎样的关系，而不只是接受任意值。

例如，(value: T) => T 表示返回值与输入值属于同一类型。 (items: T[]) => T | undefined 表示结果若存在，就来自该数组的元素类型。 如果把这些位置都换成 any，代码仍可能运行，但调用者无法再从签名得知输出与输入的关系。 分别为 string、number 和每个领域对象复制一份实现，又会让相同逻辑分叉。

你会在数组方法、Promise、集合、React 组件属性、API 客户端和库函数中遇到泛型。 标准库中的 Array<T>、Map<TKey, TValue> 与 Promise<T> 都用类型参数记录容器和所含值的关系。 业务代码中的分页响应、仓储接口和事件映射也常需要同一种表达能力。

泛型是一项静态机制。 它能让检查器拒绝不一致的调用，并让编辑器保留准确的补全信息，却不会自动检查网络响应或在 JavaScript 中创建类型对象。 如果运行时值来自 JSON、数据库驱动或无类型依赖，仍要先验证它。

工作原理

声明 function identity<T>(value: T): T 时，T 的作用域覆盖参数类型、返回类型和函数体中的类型位置。 调用 identity("ready") 时，检查器从实参收集候选类型，并通过 类型推断（type inference） 选择本次调用的 T。 这里通常不必写 identity<string>("ready")；显式类型实参适合推断信息不足或你有意固定公共契约的场合。

一次泛型调用可以有多个类型参数。 Map<TKey, TValue> 分开记录键和值，因为两者没有必须相同的理由。 名称应反映角色：很短、局部且关系明显时，T 与 U 足够；公开 API 涉及多个角色时，TInput 和 TResult 更容易读懂诊断。

泛型约束（generic constraint） 使用 extends 限制可代入的类型。 在 TKey extends keyof TObject 中，TKey 只能取 TObject 的已知键。 于是参数 key 与返回类型 TObject[TKey] 保持对应：传入 "id" 得到 id 属性的类型，而不是所有属性类型的宽泛联合。

约束按照 TypeScript 的结构类型规则检查能力。 T extends { length: number } 表示值必须有数值型 length 属性，并不要求它来自某个特定类。 约束还让函数体可以安全访问所声明的成员，但不能访问约束中没有出现的成员。

类型参数也可以有默认值，例如 Result<TValue, TError = Error>。 默认值减少常见调用中的标注，却不会覆盖已经推断出的候选类型。 公共 API 若把默认值写成 any，调用者在省略参数后会失去检查，因此 unknown、领域默认类型或不设默认值通常更诚实。

检查器大致沿着下面的路径处理泛型调用。 这张图描述静态阶段；最后生成的 JavaScript 不携带 T。

泛型函数、接口、类型别名和类都能声明类型参数，但参数的归属不同。 interface Box<T> 把 T 固定在整个实例契约上；interface Converter { convert<T>(value: T): T } 则允许每次方法调用选择自己的 T。 把类型参数放错层级，常会让本应独立的调用意外共享一个过宽的类型选择。

示例

让推断贯穿输入与输出

firstMatch 只需要知道元素类型，并把同一个 T 放在数组、谓词参数和返回值中。 调用者传入 Product[] 后，谓词里的 product 与返回值都会保留 Product 类型。

readonly T[] 表明函数只读取集合。 因此它既接受普通数组，也接受只读数组，并且函数体不能误改调用者的数据。 返回类型保留 undefined，因为类型关系不能证明一定存在匹配项。

这个例子不需要显式传入 <Product>。 如果调用者把类型实参写成更宽的结构，反而可能掩盖本可由推断暴露的输入问题。 先让编译器推断，只有在错误信息或 API 边界确实需要时才固定类型实参。

用键约束建立合法访问

下面的两个类型参数不是独立占位符。 TKey 受 keyof TObject 约束，而索引访问类型 TObject[TKey] 计算对应属性的值类型。

function getProperty<TObject, TKey extends keyof TObject>(
  object: TObject,
  key: TKey,
): TObject[TKey] {
  return object[key];
}

const shipment = {
  id: "S-204",
  attempts: 2,
  delivered: false,
};

const shipmentId = getProperty(shipment, "id");
const attempts = getProperty(shipment, "attempts");

console.log(shipmentId.toLowerCase());
console.log(attempts + 1);

s-204
3

shipmentId 是 string，attempts 是 number。 如果第二个参数改成 "owner"，检查会在调用点失败，因为这个字面量不属于 keyof typeof shipment。 这比返回 string | number | boolean 更准确，也比把结果断言成目标类型更可靠。

keyof 只描述静态类型已知的键。 它不证明运行时对象没有额外属性，也不把 Object.keys() 的结果自动变成 (keyof T)[]。 编写遍历所有键的通用工具时，要单独处理这个差异。

泛型类保存同一关系

函数的类型参数通常只服务于一次调用。 类的类型参数则属于实例；创建 Registry<number, Job> 后，该实例的所有 set 与 get 都遵守相同的键值关系。

class Registry<TKey, TValue> {
  readonly #entries = new Map<TKey, TValue>();

  set(key: TKey, value: TValue): void {
    this.#entries.set(key, value);
  }

  get(key: TKey): TValue | undefined {
    return this.#entries.get(key);
  }
}

type Job = {
  owner: string;
  state: "queued" | "running";
};

const jobs = new Registry<number, Job>();
jobs.set(17, { owner: "Lin", state: "queued" });

console.log(jobs.get(17));
console.log(jobs.get(99));

{ owner: 'Lin', state: 'queued' }
undefined

这个类包装了 Map，但没有假装 get 一定成功。 键缺失时，真实运行时结果就是 undefined，所以签名也保留它。 生成代码常用非空断言把这一分支抹掉；那只会静音检查器，不会创建缺失的值。

类的静态成员不能直接使用实例类型参数。 静态成员属于构造函数本身，不属于某个 Registry<number, Job> 实例。 如果静态工厂需要泛型，它应声明自己的类型参数，并返回相应的实例类型。

把运行时证据传给泛型函数

类型参数会被擦除，所以 parseJson<T> 无法只凭 T 判断 JSON 是否有效。 下面的版本同时接收一个类型谓词；该函数是运行时证据，也是从 unknown 到 T 的唯一入口。

type Validator<T> = (value: unknown) => value is T;

function parseJson<T>(text: string, isValid: Validator<T>): T {
  const value: unknown = JSON.parse(text);
  if (!isValid(value)) {
    throw new Error("invalid payload");
  }
  return value;
}

type FeatureFlag = { name: string; enabled: boolean };

const isFeatureFlag: Validator<FeatureFlag> = (
  value,
): value is FeatureFlag =>
  typeof value === "object" &&
  value !== null &&
  "name" in value &&
  typeof value.name === "string" &&
  "enabled" in value &&
  typeof value.enabled === "boolean";

const flag = parseJson(
  '{"name":"new-checkout","enabled":true}',
  isFeatureFlag,
);
console.log(`${flag.name}: ${flag.enabled}`);

new-checkout: true

泛型保证验证器接受的类型与函数返回的类型一致。 但类型谓词本身仍是人工编写的证明，检查器不会验证其逻辑是否完整。 要用错误字段类型、null、缺失字段和额外领域约束测试验证器，而不是因为签名漂亮就信任它。

同一种“传入证据”模式也适用于构造对象。 若函数需要创建 T，可以接收 new (...args) => T 形式的构造签名；若要解析 T，可以接收验证器或模式对象。 泛型负责保持关系，传入的值负责运行时行为。

陷阱

用 any 假装保留关系

修复方法： 如果实现确实原样返回输入，写成 <T>(value: T) => T。 如果输入可以是任何值，但使用前必须检查，参数应为 unknown。 先写清哪些位置必须一致，再决定需要几个类型参数。

用 as T 凭空制造结果

这种函数通常长得像通用解析器，实际契约却是“相信我”。 调用者写 <Account> 后会得到完整补全，但运行时可能连 id 都不存在。 错误因此从边界移动到更远的业务代码中。

修复方法： 从 unknown 开始，并要求调用者提供验证器、模式或构造器。 断言只能放在已经由其他机制证明过的窄边界，并要说明那个证明是什么。 无法证明时，返回 unknown 比返回虚假的 T 更准确。

把 extends 约束当作运行时验证

约束回答的是“函数体可以依赖哪些静态成员”。 它不回答“这个运行时值是否真的满足业务规则”。 即使结构正确，空字符串、格式错误或无权访问的 ID 仍可能不合法。

修复方法： 在外部边界验证形状和领域约束，然后再把值交给泛型核心。 让约束描述核心算法所需的最小能力。 不要为了方便访问额外字段而把约束扩大成一个庞大的业务接口。

让类型参数只出现一次

function logValue<T>(value: T): void 通常不比 function logValue(value: unknown): void 提供更多信息。 相反，T 同时出现在输入和返回位置，或连接集合元素与回调参数时，才向调用者传递有用事实。

修复方法： 检查每个类型参数至少连接两个有意义的位置，或者受到另一个参数约束。 如果参数只需接受一类固定值，就使用具体类型。 如果值确实未知且函数不依赖其结构，就使用 unknown。

显式类型实参掩盖推断结果

同一个 T 也不表示两个实参必须具有完全相同的字面量类型。 检查器会根据所有推断位置寻找可接受的候选类型，结果可能是公共上界、宽化类型或联合。 需要严格相等关系时，应直接为领域状态建模并写类型测试，不要从字母相同推导出额外保证。

修复方法： 默认让调用实参驱动推断，并检查编辑器显示的实际结果类型。 只有推断缺少信息、需要固定返回契约或调用空集合 API 时才显式传入类型实参。 用 @ts-expect-error 为必须拒绝的调用写负向类型测试。

忽略只读输入与 TSX 语法

这两个问题都常见于模型把普通函数机械改写成泛型箭头函数时。 类型关系也许正确，调用面和解析环境却变差。

修复方法： 只读输入写成 readonly T[] 或 ReadonlyArray<T>。 在 TSX 中把单个类型参数写成 <T,>，或使用 function 声明消除歧义。 修改后要在项目真实的 .tsx 配置下运行检查，而不是只在孤立的 .ts 文件中查看代码。

延伸阅读

• TypeScript 手册：泛型
• TypeScript 手册：keyof 类型运算符
• TypeScript 手册：索引访问类型
• TypeScript 手册：函数
• TypeScript 6.0 发布说明