TypeScript泛型全面指南：从类型参数到工程化应用

1. 从"写死类型"到"类型参数化"：泛型到底解决了什么问题

先从一个我实际写代码时遇到的场景说起。当时我在维护一个数据转换模块，里面有个函数，作用是把后端返回的列表数据做一层清洗和标准化。一开始我用 any 写得飞快，函数签名大概是这样的：

typescript复制function normalizeList(rawList: any[]): any[] {
  return rawList.map(item => {
    // 清洗逻辑，去掉多余字段、格式化时间等
    return processedItem;
  });
}

代码能跑，但问题随之而来。调用方拿到的返回值是 any[]，这意味着编辑器里没有任何字段提示，字段名拼错了也不会报错，改个数据结构还得全局搜调用点。后来我改成用接口定义返回类型，但发现一个更尴尬的问题——normalizeList 接收的原始数据结构在不同业务线里长得不一样，有的带 id，有的带 orderId，有的时间字段叫 createTime，有的叫 created_at。如果针对每种结构都写一个函数，代码重复得离谱；如果写成联合类型，每加一种结构就得改函数签名，维护成本直线上升。

这正是泛型登场的时刻。泛型的核心思路其实很朴素：把类型也当作函数的参数来处理。普通函数接收的是"值"参数，泛型函数额外接收的是"类型"参数。调用方传入什么类型，函数内部和返回值就按什么类型来做类型检查。

用泛型改写上面的函数：

typescript复制function normalizeList<T>(rawList: T[]): T[] {
  return rawList.map(item => {
    // 清洗逻辑，这里 item 的类型是 T，编辑器能给出 T 上已知属性的提示
    return item;
  });
}

// 调用时显式传入类型
const result = normalizeList<OrderItem>(orderList);
// result 的类型是 OrderItem[]，拿 result[0].xxx 有完整的类型提示

这一改，函数逻辑没有任何变化，但调用方的体验完全不一样了：类型信息不再丢失，编辑器提示回来了，编译期就能发现字段拼写错误。这就是泛型最核心的价值——在保证逻辑复用的同时，把类型约束也一并保留下来。

很多初学者会把泛型和 any 搞混，觉得"反正都是不限定类型，用 any 不就行了"。这是理解泛型最大的误区。any 是放弃类型检查，把类型责任推给运行时；泛型是在编译期建立类型约束，把类型责任明确给调用方。一个是"不管了"，一个是"你来定"，性质完全不同。

泛型在 TypeScript 里不是一个孤立的功能点，它贯穿了函数、接口、类、工具类型，甚至和条件类型、映射类型这些高级特性深度绑定。学泛型不能只停留在"会写 <T>"这个层面，得理解它在整个类型系统里的位置。这篇内容我按自己学习时的理解路径来拆解，从最基础的用法逐步讲到进阶场景，过程中会穿插一些我踩过的坑和总结的判断标准。

2. 泛型基础语法拆解：函数、接口、类的写法与推断机制

2.1 泛型函数：从单参数到多类型参数

最基础的泛型函数写法就是在函数名后面加上一对尖括号，里面放类型参数。类型参数的名字理论上可以随便起，但社区约定俗成的规则是：单个参数用 T（Type 的缩写），后续参数按字母序用 U、V；语义明确时用描述性的名字，比如 TKey、TValue、TItem。

typescript复制// 单个类型参数
function identity<T>(value: T): T {
  return value;
}

// 多个类型参数
function mapPair<T, U>(first: T, second: U): [T, U] {
  return [first, second];
}

// 数组泛型的两种写法等价
function firstElement<T>(arr: T[]): T | undefined {
  return arr[0];
}
function firstElementAlt<T>(arr: Array<T>): T | undefined {
  return arr[0];
}

这里值得注意的一个细节是类型参数和值参数的区别。普通函数的参数列表在圆括号里，类型参数列表在尖括号里。调用时可以先指定类型再传值，也可以完全不指定类型，让 TypeScript 根据实参自动推断。比如 identity("hello") 不显式写类型参数，编译器会自动推断出 T = string。

实际开发中，我见到不少人习惯每次调用都手动写类型参数，其实绝大多数场景下类型推断够用，不需要显式指定。需要显式指定的典型场景是这样：函数接收的参数类型是泛型参数的约束类型，但调用方想强制确定泛型参数的具体类型。

typescript复制function toArray<T>(value: T): T[] {
  return [value];
}

// 正常推断
const arr1 = toArray("hello");  // string[]

// 显式指定：当期望的类型和推断结果不一致，或者 T 被约束时使用
const arr2 = toArray<string | number>("hello");  // (string | number)[]

2.2 泛型接口：将类型参数化从函数扩展到数据结构

泛型不只能用在函数上，接口同样支持类型参数。这在定义通用的数据结构时特别有用。最典型的场景是 API 响应包装：

typescript复制interface ApiResponse<T> {
  code: number;
  message: string;
  data: T;
}

interface UserInfo {
  id: number;
  name: string;
  email: string;
}

interface OrderInfo {
  orderId: string;
  totalAmount: number;
  status: "pending" | "paid" | "shipped";
}

// 复用同一个接口描述不同的响应体
type UserResponse = ApiResponse<UserInfo>;
type OrderResponse = ApiResponse<OrderInfo>;

function fetchUser(): Promise<ApiResponse<UserInfo>> {
  // 请求逻辑...
  return Promise.resolve({
    code: 200,
    message: "success",
    data: { id: 1, name: "张三", email: "zhangsan@example.com" }
  });
}

这种写法在真实项目中几乎是刚需。后端接口的响应结构通常是一个统一的包裹格式（code + message + data），而 data 里的内容千差万别。没有泛型的话，要么为每个接口写一个独立的响应接口，要么把 data 定义成 any。泛型接口让"外层结构复用 + 内层类型自由指定"这两件事同时成立。

泛型接口还可以和泛型函数配合使用，比如定义通用的列表分页结构：

typescript复制interface PageResult<T> {
  list: T[];
  total: number;
  page: number;
  pageSize: number;
  hasMore: boolean;
}

function fetchOrderPage(page: number): Promise<PageResult<OrderInfo>> {
  // ...
  return Promise.resolve({
    list: [],
    total: 0,
    page,
    pageSize: 20,
    hasMore: false
  });
}

2.3 泛型类：让实例方法共享类型参数

泛型类的写法和泛型接口类似，把类型参数放在类名后面。常见的使用场景是数据结构的封装，比如缓存、队列、栈。

typescript复制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[this.items.length - 1];
  }

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

// Number 类型的栈
const numberStack = new Stack<number>();
numberStack.push(10);
numberStack.push(20);
const top = numberStack.pop();  // top 的类型是 number | undefined

// 错误：推入字符串会被编译拦截
// numberStack.push("hello");  // 报错：类型 "string" 的参数不能赋给类型 "number" 的参数

泛型类的一个关键特性是，类实例化时指定的类型参数在整个实例生命周期内都保持约束。这保证了数据结构的一致性——你创建了一个数字栈，就别想往里塞字符串，编译器会在编译期拦截。

这里有个容易踩的坑：静态成员不能引用类的类型参数。TypeScript 编译器会直接报错 "Static members cannot reference class type parameters"，这是因为静态成员属于类本身而非实例，类的类型参数在静态上下文中没有定义。

typescript复制class Repository<T> {
  // 错误写法：静态成员不能引用 T
  // static defaultItem: T;

  // 正确做法：静态成员使用具体类型或自己的泛型参数
  static version: string = "1.0";
}

2.4 类型推断的边界：什么时候 TypeScript 会"猜不出来"

理解了基本写法之后，有必要弄清楚类型推断的规则边界。TypeScript 会尽量从实参推断类型参数，但有以下几种情况它无能为力：

第一种，返回值类型无法推断。 如果函数的返回值是一个新构造的类型（类型参数只出现在返回值中，不出现在参数中），编译器无法凭空推断出 T 是什么。

typescript复制// 错误示例：T 只出现在返回位置，调用时无法推断
function createInstance<T>(): T {
  return {} as T;
}
// 必须显式指定类型参数
const instance = createInstance<UserInfo>();

第二种，部分推断。 假设函数有多个类型参数，调用时想只指定其中一个，另一个靠推断。TypeScript 不支持这种"部分显式指定"的语法，要么全都指定，要么全都推断。遇到这种情况，常规做法是调整参数顺序，把需要推断的类型参数放在前面，需要显式指定的放在后面，或者用函数柯里化的方式拆成两层调用。

typescript复制// 不优雅的写法：必须先全部指定
function merge<A, B>(a: A, b: B): A & B {
  return { ...a, ...b };
}
const merged = merge<UserInfo, OrderInfo>(userInfo, orderInfo);

// 更好的方式：借助柯里化让第一个类型参数可以推断
function mergeCurried<A>(a: A) {
  return function <B>(b: B): A & B {
    return { ...a, ...b };
  };
}
const merged2 = mergeCurried(userInfo)(orderInfo);

第三种，空数组字面量。 当调用 foo<T>([]) 这样的表达式时，编译器从 [] 推断不出任何线索，类型参数会被推断为 unknown。这时就需要显式指定类型参数，或者给数组加上类型标注。

理解这些边界不是为了追求理论完备，而是为了在实际报错时能快速定位问题。我在同事的代码里见过不少"为什么这里泛型推断不出来"的困惑，大部分都能归到上面三类里。

3. 泛型约束：从"什么类型都行"到"满足条件的类型才行"

3.1 为什么需要约束：用 extends 限制类型参数的边界

泛型如果完全不设限制，能做的事非常有限。比如你写一个 logLength 函数，想打印任意类型的长度，但 number 类型没有 length 属性，T 上做 .length 操作编译器会直接报错。

typescript复制// 错误：类型 T 上不存在属性 "length"
function logLength<T>(arg: T): T {
  console.log(arg.length);
  return arg;
}

泛型约束解决的就是这个问题。用 extends 关键字指定类型参数的边界，告诉编译器"这个泛型可以有很多种具体类型，但无论如何都必须满足某个条件"。最常见的约束是要求类型具有某个属性，或者必须继承自某个接口。

typescript复制interface HasLength {
  length: number;
}

// T 被约束为必须具有 length 属性
function logLength<T extends HasLength>(arg: T): T {
  console.log(arg.length);
  return arg;
}

logLength("hello");           // 合法：string 有 length
logLength([1, 2, 3]);         // 合法：数组有 length
logLength({ length: 10 });    // 合法：对象字面量有 length
// logLength(123);            // 错误：number 没有 length 属性

3.2 约束的本质是"最小要求"

理解泛型约束，关键要抓住一个点：约束定义的是"最小要求"，而不是"具体类型"。T extends HasLength 的含义是"T 必须是 HasLength 的子类型"，所有满足这一要求的类型都可以用。这个设计非常像面向对象里的接口编程——你不需要关心具体传入的是什么对象，只需要保证它具备你所依赖的能力。

看一个实际项目里更复杂的例子。假设要写一个通用的排序函数，要求传入的对象都具备一个可比较的字段：

typescript复制interface Sortable {
  id: number;
}

function sortById<T extends Sortable>(list: T[]): T[] {
  return [...list].sort((a, b) => a.id - b.id);
}

const users: UserInfo[] = [{ id: 3, name: "张三" }, { id: 1, name: "李四" }];
const sortedUsers = sortById(users);  // 返回类型是 UserInfo[]

注意这里有个非常微妙但重要的类型推断成果：sortById(users) 的返回类型是 UserInfo[]，而不是 Sortable[]。因为编译器在约束范围内保留了具体的泛型参数类型。如果你不写泛型而是直接参数写成 Sortable[]，那么传入 UserInfo[] 虽然合法，但返回类型会被放宽为 Sortable[]，你再想访问 name 属性就得先做类型断言。泛型约束加上类型保留，让"传入什么类型就返回什么类型"这个特性得以成立，这在函数库设计中极其关键。

3.3 约束 + 条件类型的组合：keyof 与泛型的经典搭配

提到约束，keyof 操作符和泛型的组合是绕不开的经典用法。keyof 的作用是获取一个类型的所有键名组成联合类型。配合泛型约束，可以写出非常强大的类型安全函数，比如通用的对象取值函数：

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

const user: UserInfo = { id: 1, name: "张三", email: "zhangsan@example.com" };

// 合法且类型精确
const idVal = getValue(user, "id");        // number
const nameVal = getValue(user, "name");    // string
const emailVal = getValue(user, "email");  // string

// 错误：user 对象上没有 "age" 这个键，编译期报错
// const ageVal = getValue(user, "age");

这个函数的签名拆解一下含义：T 是对象的类型，K 被约束为 keyof T 的联合类型（也就是 T 所有键名中的某一个），返回值是 T[K]（通过索引访问类型获取对应键的值类型）。这三者配合起来，实现的效果是——key 参数只能传对象实际存在的键，返回值的类型自动跟随传入的键变化。

这种写法的意义在于把"魔法字符串"从代码中赶走。你调用 getValue(user, "name") 时，"name" 字面量是在编译期被校验的，如果拼写成 "nmae"，编译器会直接报错。相比 obj[key as keyof UserInfo] 这种到处断言的写法，泛型约束提供的检查是全局和自动的。

keyof 的另一个常见用法是配合映射类型实现"键名筛选"。比如从一个类型里挑出某些键组成新类型：

typescript复制type PickKeys<T, K extends keyof T> = {
  [P in K]: T[P];
};

type UserNameAndEmail = PickKeys<UserInfo, "name" | "email">;
// 等价于 { name: string; email: string; }

这里 [P in K] 是映射类型的语法，遍历联合类型 K 中的每个键，生成新的对象类型。熟悉之后你会发现，很多工具类型（Pick、Omit、Partial、Required）的背后都是这套组合拳。

3.4 约束的常见误区和实际项目里的设计原则

在使用泛型约束时，有几个经验值得分享。

第一，约束不能多余。如果你的函数根本不会访问 .length，就不要定义 extends HasLength。多余的约束会限制函数的适用范围，让本来可以支持的类型变得不可用。泛型约束应该只描述函数真正依赖的最小接口集合。

第二，避免把约束当成判断条件。有时候你会想写"T 如果是某个类型就怎么做，否则怎么做"，这其实不是泛型约束的职责，应该用条件类型（conditional types）来处理。约束负责"准入",条件类型负责"分派"，两者层次不同。

第三，约束和默认类型可以配合。给类型参数设置默认值可以让调用方可选地省略类型参数。这在封装复杂类型时特别有用，能显著提升使用体验：

typescript复制interface TableColumn<T = any> {
  title: string;
  key: keyof T;
  width?: number;
}

// 使用时不指定泛型，默认 any
const columns: TableColumn[] = [{ title: "ID", key: "id" }];

// 使用时指定泛型，key 自动校验
const userColumns: TableColumn<UserInfo>[] = [
  { title: "姓名", key: "name" },
  { title: "邮箱", key: "email" }
];

4. 泛型在真实项目中的进阶应用：工具类型、场景化封装与性能取舍

4. 泛型在真实项目中的进阶应用：工具类型、场景化封装与性能取舍

4.1 内置工具类型背后的泛型逻辑

TypeScript 内置了几个非常常用的工具类型，这些工具类型的定义本身就是泛型的教科书级示范。我把它们拆开看一遍，远比死记 API 有效得多。

先看 Partial，它把所有属性变成可选：

typescript复制type Partial<T> = {
  [P in keyof T]?: T[P];
};

再看 Readonly，它把所有属性变成只读：

typescript复制type Readonly<T> = {
  readonly [P in keyof T]: T[P];
};

然后是 Pick，它从 T 中挑选一组属性：

typescript复制type Pick<T, K extends keyof T> = {
  [P in K]: T[P];
};

注意到没有，这三个工具类型的写法高度一致：先用 keyof 取出键集合，然后用映射类型遍历，再对每个属性做修饰（可选、只读、过滤）。理解了泛型约束和映射类型之后，内置工具类型不再是黑盒，你甚至可以根据项目需求组装自己的工具类型。

我之前在项目里写过一个 Nullable 工具类型，把所有属性变成可空版本，还支持深度处理嵌套对象：

typescript复制type Nullable<T> = {
  [P in keyof T]: T[P] | null;
};

type DeepNullable<T> = {
  [P in keyof T]: T[P] extends object ? DeepNullable<T[P]> : T[P] | null;
};

这种自造工具类型的能力，是泛型真正发挥威力的地方。当你发现项目里有大量重复的类型变换时可以抽象出来。

4.2 一个完整场景：封装可复用的请求函数

实操层面，泛型最常见的落地场景就是网络请求封装。以一个 fetch 请求函数为例，展示泛型从设计到使用的完整链路。

需求分析：项目里所有接口调用都有相似的流程（拼接 URL、设置请求头、处理错误码、解析数据）。用泛型封装后，调用方必须能指定响应类型，并且拿到完整类型安全的返回值。

typescript复制interface RequestOptions<TData = unknown> {
  url: string;
  method?: "GET" | "POST" | "PUT" | "DELETE";
  data?: TData;
  headers?: Record<string, string>;
}

interface ApiResult<T> {
  code: number;
  message: string;
  data: T;
}

async function request<TResponse, TBody = unknown>(
  options: RequestOptions<TBody>
): Promise<TResponse> {
  const { url, method = "GET", data, headers = {} } = options;

  const response = await fetch(url, {
    method,
    headers: {
      "Content-Type": "application/json",
      ...headers
    },
    body: data ? JSON.stringify(data) : undefined
  });

  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }

  const result = (await response.json()) as ApiResult<TResponse>;

  if (result.code !== 200) {
    throw new Error(result.message);
  }

  return result.data;
}

// 调用时的类型体验
interface LoginPayload {
  username: string;
  password: string;
}

interface LoginResult {
  token: string;
  userInfo: UserInfo;
}

const loginResult = await request<LoginResult, LoginPayload>({
  url: "/api/login",
  method: "POST",
  data: { username: "admin", password: "123456" }
});
// loginResult 的类型是 LoginResult，有完整的类型提示

设计这个封装时有几个决策点值得展开：

第一个决策是两个类型参数的设计。TResponse 和 TBody 分别描述响应数据和请求体，各自独立。调用 request<LoginResult, LoginPayload> 时，两个类型都被明确指定，函数内部的 fetch 请求体也有了类型约束，data 字段不能随便传一个不满足 LoginPayload 的对象。

第二个决策是返回值的类型安全。response.json() 返回的是 any，通过 as ApiResult<TResponse> 断言后再解包返回 result.data。调用方不需要知道 ApiResult 这个包裹结构的存在，拿到的是干净的 TResponse。

第三个决策是错误处理的取舍。这里选择在 HTTP 层抛错，在网络层也检查错误码。类型设计和错误处理是两回事，类型保证的是"一旦返回，数据一定符合 TResponse"，错误路径上类型帮不了太多，需要靠运行时防御。

4.3 泛型在 React/Vue 等框架中的典型使用模式

如果你在前端项目里用了 React 或者 Vue，泛型几乎是无处不在的。

React 里最常见的场景是自定义 Hook。用泛型可以让 Hook 接收不同类型的状态返回不同类型的值，同时保持类型推导：

typescript复制import { useCallback, useState } from "react";

function useApi<TResponse>(fetcher: () => Promise<TResponse>) {
  const [data, setData] = useState<TResponse | null>(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error | null>(null);

  const execute = useCallback(async () => {
    setLoading(true);
    setError(null);
    try {
      const result = await fetcher();
      setData(result);
    } catch (err) {
      setError(err as Error);
    } finally {
      setLoading(false);
    }
  }, [fetcher]);

  return { data, loading, error, execute };
}

// 使用时传入泛型参数
const { data, loading, execute } = useApi<UserInfo>(() => fetchUser());

另一个常见套路是泛型组件的 props 类型。很多表格或列表组件需要接收一个数据源，数据源的类型由使用方决定，此时组件泛型就显得尤为重要：

typescript复制interface ListViewProps<T> {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
  keyExtractor: (item: T) => string;
}

function ListView<T>({ items, renderItem, keyExtractor }: ListViewProps<T>) {
  return (
    <div>
      {items.map(item => (
        <div key={keyExtractor(item)}>{renderItem(item)}</div>
      ))}
    </div>
  );
}

// 使用时自动推导 T 为 UserInfo
<ListView items={users} renderItem={user => <span>{user.name}</span>} keyExtractor={user => String(user.id)} />

这里有个实践细节：在 .tsx 文件里写泛型箭头函数时，<T> 会被 JSX 解析器误认为是标签开头，导致语法报错。解决办法有两个：一是用 function 声明函数，二是给泛型参数加上 extends 约束（哪怕约束是 extends unknown 或 extends object），让解析器能区分 JSX 和类型参数。

typescript复制// 在 .tsx 文件里，箭头函数泛型会报错
// const ListView = <T,>({ items }: { items: T[] }) => { ... };  // 老写法，需要逗号

// 推荐写法：加约束
const ListView = <T extends unknown>({ items }: { items: T[] }) => {
  return <div>{items.length}</div>;
};

Vue 3 里同样大量使用泛型，特别是组合式 API 和 defineProps 的类型声明。ref<T>()、reactive<T>() 这些都是泛型函数，在使用时如果显式传入类型参数，可以避免类型被推断得过宽或过窄。

4.4 泛型与性能：类型代码的编译期成本

有一个经常被问到的问题："泛型会影响运行时性能吗？"答案是：不会。TypeScript 的类型系统只存在于编译期，运行时根本没有类型。所有泛型相关的代码在编译成 JavaScript 后都会被擦除或者转换成普通的函数和类。

比如上面那个 identity 函数，编译后的 JS 代码就是：

javascript复制function identity(value) {
  return value;
}

没有尖括号，没有任何类型信息。泛型是纯粹的编译期特性，它的成本全部发生在编译阶段，而且这个成本通常可以忽略不计。真正的性能风险不在泛型本身，而在错误使用泛型导致的类型复杂度过高，让编译器在多文件增量编译时变慢。如果项目的类型体操特别复杂，编译时间确实会上升，但这是另一个层面的话题（类型设计是否合理），和运行时性能无关。

4.5 进阶：泛型与条件类型的组合，解决真实分支场景

泛型的价值在单独使用时可能感觉有限，一旦和条件类型组合起来，就能实现非常灵活的类型运算。条件类型的语法是三目运算符的形式，在类型层面做分支判断：

typescript复制type IsArray<T> = T extends any[] ? true : false;

type A = IsArray<string[]>;   // true
type B = IsArray<number>;     // false

这个能力的意义在于，可以在类型系统中表达"如果输入类型满足某个条件，则输出某个类型，否则输出另一个类型"。它和泛型约束的区别是：约束是硬性的准入检查，条件类型是软性的分支逻辑。

一个经典的实战场景是"从函数参数里提取类型"。比如有一个事件处理函数，它的参数类型由某张配置表决定。需求是写一个工具类型，能从函数的返回类型或参数中提取出类型信息：

typescript复制type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;

type Result = UnwrapPromise<Promise<UserInfo>>;  // UserInfo
type Result2 = UnwrapPromise<UserInfo>;          // UserInfo（不是 Promise，原样返回）

// 更实际的应用：从 API 响应里取出 data 字段的类型
type ApiResultData<T> = T extends { data: infer U } ? U : never;

type LoginApiResult = ApiResult<LoginResult>;
type LoginData = ApiResultData<LoginApiResult>;  // LoginResult

infer 关键字用于在条件类型中声明一个类型变量，让 TypeScript 去推断某个位置的类型。这个特性非常强大，很多高级工具类型（比如 Parameters<T>、ReturnType<T>、Awaited<T>）都是基于它实现的。实际项目里如果你的封装层做得比较深，经常需要把"深层类型"提取出来，infer 配合条件类型是标准解法。

不过要提醒一句：条件类型 + infer + 递归映射这些高级特性组合起来，很容易写出"类型代码黑客"。代码能编译通过不代表类型设计是合理的。我的建议是，类型层面的复杂度和业务层面的复杂度要对等——简单业务用简单类型，层级深、复用广的库代码才值得投入高级泛型技巧。

5. 实践中容易翻车的细节：TSX 陷阱、类型推断失败和通用排错方法

5.1 翻车现场一：JSX 文件里泛型箭头函数报错

在 React 项目里初次使用泛型箭头函数时，几乎所有人都会遇到这个报错：

typescript复制// .tsx 文件内
const getValue = <T,>(obj: T, key: keyof T) => {
  return obj[key];
};

这里的 <T,> 多出来一个逗号，是早起 TypeScript 兼容 JSX 解析的解决方案。如果不写逗号，<T> 会被当作 JSX 标签的开始，编译器直接报语法错误。现在新版本的 TypeScript（4.7+）已经有了优化，但为了兼容性和团队统一，我建议团队里约定：

• 简单的泛型辅助函数优先用 function 声明，不涉及 JSX 时用箭头函数没影响。
• 必须用箭头函数 + 泛型时，要么加逗号，要么加 extends unknown 约束，二选一。

typescript复制// 方案 A：函数声明
function getValue<T extends object>(obj: T, key: keyof T) {
  return obj[key];
}

// 方案 B：extends 约束
const getValue = <T extends object>(obj: T, key: keyof T) => {
  return obj[key];
};

5.2 翻车现场二：类型参数在返回值位置但调用时被推断为 unknown

这个翻车现场在封装第三方库或编写通用型函数时经常出现。比如从 localStorage 里读取数据并期望自动转换类型：

typescript复制function readFromStorage<T>(key: string): T {
  const raw = localStorage.getItem(key);
  return raw ? JSON.parse(raw) as T : null as T;
}

// 调用时忘记写泛型参数
const userData = readFromStorage("user");
// userData 的类型是 unknown，因为没有任何实参数信息可以推导出 T

这种"纯返回位置泛型"的坑，只有显式调用才能解决。更好的设计是把泛型放在"输入"或"输入 + 输出"的位置，让编译器有推断的素材。如果确实没有输入位置的数据，那就必须接受"调用时显式指定类型参数"这个前提。

另一个相关的坑是泛型参数的默认值并不能解决推断失败的问题。function readFromStorage<T = UserInfo>(key: string): T 这样写，在没有推断时会使用默认类型 UserInfo，但如果你期望的是"自动推断"，这个默认值也是一种隐式的选择，可能隐藏错误。只有在你明确知道"当调用方不指定时应该用默认类型"的场景，才建议使用默认值。

5.3 翻车现场三：过度泛型导致类型不相关

有一种倾向很常见：喜欢把所有函数都写成泛型，觉得"这样更通用"。但泛型是有代价的，它增加了类型签名的复杂度，也让编辑器提示变慢，更重要的是，它可能掩盖类型之间的联系。

哪种情况不需要泛型？如果函数接收的所有参数类型都是固定的、无关的，直接写具体类型就好。比如：

typescript复制// 不需要泛型的例子
function formatDate(date: Date, format: string): string {
  // ...
  return "";
}

// 强行泛型的例子（不推荐）
function formatDate<T extends Date>(date: T, format: string): string {
  // ...
  return "";
}

第二个版本比第一个多了约束，但没有带来任何额外价值。泛型应该服务于"参数类型与返回值类型之间有推导或约束关系"的场景。比如"参数是 T，返回值是 T[]"、"参数是 K，约束为 keyof T"、"返回值从参数里推导出来"。如果没有这种关联，泛型就变成了装饰。

5.4 排查泛型报错的通用策略

遇到泛型相关的报错，我一般按这个顺序排查：

第一步，先定位是类型约束不满足，还是推断结果不符合预期。TypeScript 的报错信息通常会明确指出"类型 X 不满足约束 Y"或"参数类型不能赋给类型 Z"，这是两条完全不同的解决路径。

第二步，如果是"不满足约束"，检查传入类型是否真的具备所需的属性和能力。常见情况是接口定义漏了字段，或者实际数据结构和接口声明不一致。可以用鼠标悬停在传入值上，看编辑器能推断出的具体类型，逐字段比对。

第三步，如果是"推断结果不符合预期"，检查类型参数是否只出现在返回值位置，或者是否有类型参数从未被使用。用 // @ts-expect-error 或其他手段缩小范围，把临时调试的类型标注拿出来看编译器推断的具体类型是什么。

第四步，涉及 infer 和条件类型的复杂场景，可以把复杂的类型拆成多个中间类型，分别检查每个中间类型的结果。类型代码和业务代码一样，需要分步调试，不能指望一步到位。

5.5 泛型 + 重载：何时选择重载而不是泛型

最后补充一个容易混淆的点：重载（overload）和泛型的适用边界。二者的目标类似，都是让函数在不同输入下表现不同的类型行为，但实现方式和使用体验有区分。

重载适合"参数数量或参数类型差异较大、且各分支逻辑差异明显"的函数。泛型适合"类型参数之间有推导关系、函数的逻辑结构保持一致"的场景。

typescript复制// 重载示例：参数类型差异大
function handle(input: string): string;
function handle(input: number): number;
function handle(input: string | number): string | number {
  if (typeof input === "string") {
    return input.trim();
  }
  return input * 2;
}

// 泛型示例：类型参数之间有推导关系
function wrap<T>(value: T): { value: T } {
  return { value };
}

判断标准很简单：如果函数内部逻辑对参数类型做了显著分支（比如 typeof 判断后才走不同逻辑），用重载更清晰；如果函数只是把类型参数在参数、中间变量、返回值之间做传递，用泛型更自然。混用当然也常见，但核心原则是别让泛型成为重载的替代品，也别让重载掩盖了泛型能表达的约束关系。

在我自己带的项目里，我给新成员的代码审查有一条不成文的规定：写了泛型必须问一句"这个泛型参数提供了哪些类型收益？"如果答不上来，说明这个泛型大概率是装饰，该删就删。反过来也成立——如果某个公共功能重复写了三遍类似的类型定义，可以用泛型来抽象的场景就别硬扛着复制粘贴。TypeScript 的泛型不是炫技工具，它是一种让类型逻辑跟随业务逻辑自然复用的手段，用对了地方会非常顺手，用错了地方就成了维护负担。