TypeScript中泛型约束的高级用法与实战

在 TypeScript 开发中，泛型是构建可复用组件的核心工具，但如果不加以限制，泛型往往会过于宽泛，导致代码内部无法安全访问属性或方法。泛型约束正是为了解决这一问题，它允许我们规定泛型参数必须满足特定的条件。本文将手把手带你掌握从基础属性约束到高级条件类型约束的实战用法。

一、 基础属性约束：确保属性存在

最基础的约束场景是确保传入的泛型对象包含特定的属性。没有约束时，TypeScript 会报错提示无法访问潜在不存在的属性。

1. 定义 一个包含 length 属性的接口 HasLength。
2. 编写 一个泛型函数 logLength，使用 extends 关键字强制参数 T 必须符合 HasLength 接口。
3. 尝试 在函数体内访问 arg.length，此时类型系统已确认该属性必然存在。

interface HasLength {
  length: number;
}

function logLength<T extends HasLength>(arg: T): number {
  return arg.length;
}

// 正确使用
logLength("hello world"); // 字符串有 length 属性
logLength([1, 2, 3]);     // 数组有 length 属性
logLength({ length: 10, value: "hi" }); // 对象包含 length 属性

// 错误使用（编译时报错）
// logLength(100); // 数字类型没有 length 属性

二、 键值约束：限制操作对象键名

当我们编写一个获取对象属性的函数时，不仅需要限制对象的类型，还需要限制“键名”必须存在于该对象中。这需要结合 keyof 操作符与泛型约束。

1. 声明 一个泛型函数 getProperty。
2. 设置 第一个泛型参数 T 为对象类型。
3. 设置 第二个泛型参数 K，并约束它必须是 T 的键名之一（即 K extends keyof T）。
4. 返回 对象中对应键的值。

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

const user = {
  name: "Alice",
  age: 30,
  isAdmin: true
};

// 正确：智能提示 "name" | "age" | "isAdmin"
const userName = getProperty(user, "name");

// 错误：编译器报错，"gender" 不是 "user" 的键
// const userGender = getProperty(user, "gender");

为了更清晰地展示键值约束与普通访问的区别，请参考下表：

三、 条件类型约束：根据类型动态选择

TypeScript 的条件类型类似于 JavaScript 的三元表达式，允许根据类型关系进行逻辑判断。其核心语法为 T extends U ? X : Y。

以下流程描述了条件类型约束的判定逻辑：

1. 定义 一个工具类型 NonNullable。
2. 判断 泛型 T 是否继承自 null 或 undefined。
3. 返回 如果是，则返回 never（表示不可能出现）；否则返回 T 本身。

type MyNonNullable = T extends null | undefined ? never : T;

// 测试类型
type TypeA = MyNonNullable<string>;       // string
type TypeB = MyNonNullable<number | null>; // number
type TypeC = MyNonNullable<null>;          // never

四、 实战演练：构建类型安全的 API 请求函数

结合上述知识，我们构建一个真实的 API 请求函数。该函数需要接收配置对象，并根据配置中的 method 字段，动态约束 data 和 response 的类型。

1. 定义 基础的 HTTP 方法类型 Method。
2. 创建 接口 GetConfig 和 PostConfig，分别区分 GET 和 POST 的参数结构（GET 无 body，POST 有 body）。
3. 编写 核心请求函数 request，泛型 T 代表具体的配置类型。
4. 使用 条件约束 T extends { method: 'POST' } 来决定是否需要 data 参数。

type Method = 'GET' | 'POST' | 'DELETE';

interface GetConfig {
  method: 'GET';
  url: string;
  params?: Record<string, any>;
}

interface PostConfig {
  method: 'POST';
  url: string;
  data: Record<string, any>;
}

// 联合类型作为泛型的可选范围
type ApiConfig = GetConfig | PostConfig;

function request<T extends ApiConfig>(config: T): Promise<void> {
  // 逻辑实现省略...
  console.log(`Sending ${config.method} request to ${config.url}`);

  // 泛型约束确保了类型安全访问
  if (config.method === 'POST') {
    // 在此分支中，TypeScript 知道 config 必定有 data 属性
    console.log('Payload:', config.data);
  } else {
    // 在此分支中，config 不会有 data 属性，而是可能有 params
    console.log('Query:', config.params);
  }

  return Promise.resolve();
}

// 使用案例
request({
  method: 'GET',
  url: '/user',
  params: { id: 1 }
});

request({
  method: 'POST',
  url: '/user',
  data: { name: 'Bob' }
});

// 错误案例：POST 请求缺少 data
// request({ method: 'POST', url: '/user' });

五、 高 infer 模式约束：提取函数返回值

在某些高级场景下，我们需要约束一个类型必须是函数，并提取其返回值类型。这需要配合 infer 关键字使用。

1. 定义 一个泛型工具类型 ReturnType。
2. 设置 约束 T 必须是一个函数类型（即 (...args: any[]) => any）。
3. 使用 infer R 推断函数的返回值类型，并将其返回。

type MyReturnType<T extends (...args: any) => any> = T extends (...args: any) => infer R ? R : any;

function getUser() {
  return { name: "TypeScript", age: 10 };
}

type User = MyReturnType<typeof getUser>; 
// User 类型被推断为 { name: string; age: number; }

通过掌握这些约束技巧，你可以编写出既灵活又严谨的 TypeScript 代码，将大部分类型错误拦截在编译阶段。