泛型

泛型（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发布说明