TypeScript 泛型：泛型函数、泛型类型和泛型类

泛型就是类型参数。泛型函数声明一个占位类型，通常叫 T，每次调用时都会把它填上，所以输入的类型决定了输出的类型。这样一个函数就能同时处理数字、字符串和你自己的对象，而且每次调用依然有完整的类型。

function first<T>(items: T[]): T | undefined {
  return items[0];
}

const n = first([10, 20, 30]);        // T = number, n: number | undefined
const s = first(["ada", "grace"]);    // T = string, s: string | undefined
const u = first([{ id: 1 }]);         // T = { id: number }

console.log(n?.toFixed(1));           // 10.0
console.log(s?.toUpperCase());        // ADA
console.log(u?.id);                   // 1

函数名后面的 <T> 声明了类型参数。items: T[] 把它用在输入上，T | undefined 把它用在输出上，从而把两者关联起来。你从来没写过 number 或 string：TypeScript 根据实参推断出了 T。

为什么不用 any 或 unknown？

没有泛型的话，你会把参数类型写成 any 或 unknown。两者都能接受任何数组，但都丢掉了输入和输出之间的关联：

function firstAny(items: any[]): any {
  return items[0];
}

function firstUnknown(items: unknown[]): unknown {
  return items[0];
}

function firstGeneric<T>(items: T[]): T | undefined {
  return items[0];
}

const a = firstAny(["x"]);
console.log(typeof a.toFixed);         // undefined: a.toFixed(2) would compile, then throw

const b = firstUnknown(["x"]);
// b.toUpperCase();                    // error TS18046: 'b' is of type 'unknown'.
console.log(typeof b === "string" ? b.toUpperCase() : "?"); // X (after narrowing)

const c = firstGeneric(["x"]);
console.log(c?.toUpperCase());         // X, with no narrowing needed

类型参数推断

通常 TypeScript 会根据你传入的值推断类型实参。你也可以在调用时用尖括号显式写出来；当实参中没有任何东西涉及 T，或者推断的结果不是你想要的时候，就需要这样做。

function pair<T>(a: T, b: T): [T, T] {
  return [a, b];
}

function emptyList<T>(): T[] {
  return [];
}

const p1 = pair(1, 2);                      // T inferred as number
const p2 = pair<string | number>(1, "one"); // explicit: mixing allowed
const names = emptyList<string>();          // nothing to infer from, so pass it
names.push("Ada");

console.log(p1, p2, names); // [ 1, 2 ] [ 1, 'one' ] [ 'Ada' ]

有两个推断结果值得了解。不显式写类型实参的 pair(1, "one") 会报错：TypeScript 根据第一个实参推断出 T = number，然后报告 Argument of type 'string' is not assignable to parameter of type 'number'.（TS2345）。而完全没有实参的 emptyList() 会得到 T = unknown，也就是 unknown[]，这很少是你想要的。

多个类型参数

一个函数可以按需声明任意多个类型参数，用逗号分隔。每个参数都会被独立推断。

function zip<A, B>(left: A[], right: B[]): [A, B][] {
  const length = Math.min(left.length, right.length);
  const out: [A, B][] = [];
  for (let i = 0; i < length; i++) out.push([left[i], right[i]]);
  return out;
}

function mapValues<K extends string, V, R>(obj: Record<K, V>, fn: (value: V) => R): Record<K, R> {
  const out = {} as Record<K, R>;
  for (const key of Object.keys(obj) as K[]) out[key] = fn(obj[key]);
  return out;
}

console.log(zip(["a", "b", "c"], [1, 2]));        // [ [ 'a', 1 ], [ 'b', 2 ] ]
const prices = mapValues({ tea: 2.5, cake: 4 }, (v) => `$${v.toFixed(2)}`);
console.log(prices);                               // { tea: '$2.50', cake: '$4.00' }

mapValues 一次推断出三样东西：K 是 "tea" | "cake"，V 是 number，R 根据回调的返回值推断为 string。K extends string 是一个约束，下一页会讲到。

泛型接口和类型别名

类型也可以带参数。使用这个类型时要写上实参：Box<number>、ApiResponse<User>。大多数内置的集合类型都是这样的：Array<T>、Map<K, V>、Promise<T>、Record<K, V>。

interface ApiResponse<T> {
  status: number;
  data: T;
}

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

interface User {
  id: number;
  name: string;
}

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0 ? { ok: true, value: n } : { ok: false, error: `bad age: ${text}` };
}

const res: ApiResponse<User[]> = { status: 200, data: [{ id: 1, name: "Ada" }] };
console.log(res.data[0].name);   // Ada

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? r.value + 1 : r.error); // 37, then bad age: abc
}

Result<T, E = string> 还展示了默认类型参数：Result<number> 表示 Result<number, string>。和函数的可选参数一样，带默认值的参数必须放在必需的参数后面。

泛型类

类在名称后面接收类型参数，每个实例都会确定这些参数。字段、方法和构造函数的参数都可以使用它们。

class Stack<T> {
  private items: T[] = [];

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

  pop(): T | undefined {
    return this.items.pop();
  }

  peek(): T | undefined {
    return this.items.at(-1);
  }

  get size(): number {
    return this.items.length;
  }
}

const visited = new Stack<string>();
visited.push("/home");
visited.push("/docs");
console.log(visited.pop(), visited.size); // /docs 1

const numbers = new Stack<number>();
numbers.push(42);
// numbers.push("42"); // error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
console.log(numbers.peek()); // 42

如果构造函数接收一个 T，你就可以省略显式的类型实参：new Box(5) 会推断为 Box<number>。静态成员属于类本身而不是实例，所以不能使用类的类型参数（Static members cannot reference class type parameters.，TS2302）。

泛型箭头函数和函数类型

类型参数列表写在参数列表前面。同样的语法也用来描述泛型函数类型。

const last = <T>(items: T[]): T | undefined => items[items.length - 1];

type Mapper = <T, R>(items: T[], fn: (item: T) => R) => R[];
const mapAll: Mapper = (items, fn) => items.map(fn);

// In a .tsx file, <T> looks like a JSX tag. Add a trailing comma:
const lastTsx = <T,>(items: T[]) => items[items.length - 1];

用 const 类型参数推断字面量类型

默认情况下，泛型推断出的是放宽后的类型：pair("a", "b") 得到 [string, string]。当确切的值很重要时（路由名、事件名、列名列表），把参数标记为 const（TypeScript 5.0 及以上），它就会像实参写了 as const 一样进行推断：

function defineColumns<const T extends readonly string[]>(columns: T): T {
  return columns;
}

const loose = ["id", "name"];                  // string[]
const columns = defineColumns(["id", "name"]); // readonly ["id", "name"]

type Column = (typeof columns)[number];        // "id" | "name"
const sortBy: Column = "name";
console.log(columns, sortBy, loose.length);    // [ 'id', 'name' ] name 2

调用者写的是普通数组，函数却保留了字面量类型。

什么时候不该用泛型

类型参数只有在关联两样东西时才有存在的价值：一个参数和返回类型、两个参数，或者一个参数和一个回调。如果 T 只出现一次，它就什么也没增加，直接写普通类型更清楚。

// Pointless: T is used once, so it is just a longer way to write unknown
function logValue<T>(value: T): void {
  console.log(value);
}

// Clearer
function logValueSimple(value: unknown): void {
  console.log(value);
}

// Also pointless: returns T but nothing connects T to an argument,
// so the caller is really just asserting a type
function parseJson<T>(text: string): T {
  return JSON.parse(text);
}

最后一种写法很常见，也很有误导性：parseJson<User>(text) 看起来类型安全，实际上什么都没检查，和 JSON.parse(text) as User 完全一样。应该返回 unknown 再进行校验。其他滥用的迹象还有：一个类型参数总是被传入同一个实参，或者它可以用两个已知类型的联合来代替。

如果泛型需要知道 T 的某些信息（比如它有 length，或者 K 是 T 的键），下一步就是用 extends 添加约束。