类型安全的API客户端

第一章 概述

1.1 为什么需要类型安全的 API 客户端

现代前端应用通过 HTTP/HTTPS 协议与后端进行数据交换，API 调用是应用的核心逻辑之一。然而，传统的 JavaScript API 客户端存在严重的类型缺陷：

// 传统方案：无类型约束
async function fetchUser(id: string): Promise<any> {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
}

const user = await fetchUser('123');
user.name;        // OK，但无法验证 name 属性存在
user.naem;        // 拼写错误，编译通过
user.email.address; // 无法验证嵌套属性

这种方案存在三大问题：

1. 请求参数无类型约束：URL 路径、查询参数、请求体都使用宽泛的 string 或 any，拼写错误与类型错误只能在运行时暴露。
2. 响应数据无类型保证：response.json() 返回 any，开发者基于”假设”访问响应字段，导致 undefined 访问错误。
3. 路由与方法不匹配：调用 DELETE /users 时无法在编译时发现该路由只支持 GET 与 POST。

类型安全的 API 客户端通过 TypeScript 的泛型（Generics）、条件类型（Conditional Types）、模板字面量类型（Template Literal Types）和映射类型（Mapped Types）实现端到端类型安全：从请求构造到响应处理，每一步都有编译时保证。

// 类型安全方案
const user = await api['/users/:id'].get({ params: { id: '123' } });
user.name;       // OK，类型为 string
user.naem;       // 编译错误：'naem' 不存在
user.email;      // 编译错误：'email' 不在 User 类型中

await api['/users/:id'].delete({ params: { id: '123' } }); // OK
await api['/users/:id'].put({ params: { id: '123' } });     // 编译错误：缺少 body

1.2 学习目标

完成本教程后，读者将能够：

1. 设计 API 路由类型映射（Route Type Map），描述路由路径、HTTP 方法、参数、查询、请求体、响应体的完整契约。
2. 使用模板字面量类型从路径中提取参数名，实现路径参数的类型安全。
3. 使用条件类型与可变元组实现条件参数（method 决定是否需要 body）。
4. 构建泛型请求函数，根据路由与方法自动推断所有参数与返回类型。
5. 实现类型安全的链式请求构建器与自动生成的 API 客户端。
6. 处理错误类型化、结果类型（Result Type）、重试策略与超时控制。
7. 集成 OpenAPI/Swagger 自动生成 API 类型定义。
8. 实现类型安全的请求/响应拦截器与认证管理。
9. 在 React、Vue 等框架中集成类型安全的 API Hook。
10. 分析类型安全 API 客户端对编译时与运行时性能的影响。

1.3 本教程的定位

本教程是 TypeScript “类型安全应用”系列的第五篇，与《类型安全的国际化》、《类型安全的表单验证》、《类型安全的状态管理》、《类型安全的事件系统》形成互补。前者侧重特定领域的类型设计模式，本教程侧重”如何用类型系统约束 HTTP 通信的端到端契约”。

参考 MIT 6.5810《Web Performance Engineering》与 Stanford CS142《Web Applications》课程对 API 设计的讲解：API 客户端的核心是”契约的精确表达”。本教程将这一思想用 TypeScript 的类型系统加以实现，使 API 调用的每一步都有编译时保证。

1.4 API 客户端的核心维度

完整的类型安全 API 客户端涉及多个维度：

1.5 核心问题导引

阅读本教程时请带着以下问题：

1. 路由路径如何类型化：/users/:id 中的 :id 是动态的，如何在类型层面提取 id 并约束其类型？
2. 方法与参数的条件关系：GET 请求不需要 body，POST 请求需要 body，如何让类型系统根据方法自动决定是否需要 body？
3. 响应类型如何推断：调用 api['/users'].get() 如何自动推断返回类型为 User[]？
4. 路径参数替换如何类型安全：将 :id 替换为实际值时，如何保证替换后的路径仍然是合法的？
5. 错误如何类型化：HTTP 错误（404、500）与业务错误（code: ‘NOT_FOUND’）如何在类型层面区分？
6. 类型安全与开发体验如何平衡：复杂的类型约束会增加编译时间，如何在两者间取得平衡？

1.6 端到端类型安全的形式化定义

端到端类型安全可以形式化定义为：

即对于每个路由 $r$ 和该路由支持的每个方法 $m$，请求参数的类型决定了响应数据的类型。这一契约在编译时验证，运行时无需额外检查。

第二章 基础概念

2.1 API 路由类型映射

API 路由类型映射是类型安全 API 客户端的核心数据结构，它将每个路由路径映射到其支持的 HTTP 方法及对应的参数与响应类型：

// API 路由类型映射
interface APIClient {
  '/users': {
    GET: { response: User[]; query?: { page?: number; limit?: number } };
    POST: { response: User; body: Omit<User, 'id'> };
  };
  '/users/:id': {
    GET: { response: User; params: { id: string } };
    PUT: { response: User; params: { id: string }; body: Partial<User> };
    DELETE: { response: void; params: { id: string } };
  };
  '/posts/:postId/comments': {
    GET: { response: Comment[]; params: { postId: string }; query?: { sort?: 'asc' | 'desc' } };
    POST: { response: Comment; params: { postId: string }; body: { content: string } };
  };
}

结构说明：

• 顶层键是路由路径，使用字面量字符串类型（如 '/users/:id'）。
• 每个路由对应的值是一个映射，键是 HTTP 方法（GET、POST、PUT、DELETE、PATCH），值是该方法的请求/响应契约。
• 每个方法的契约包含四个可选字段：
  • response：响应数据类型（必填）。
  • params：路径参数类型（可选，仅当路径包含 :param 时）。
  • query：查询参数类型（可选）。
  • body：请求体类型（可选，仅当方法是 POST/PUT/PATCH 时）。

2.2 路径参数提取

路径参数（Path Parameters）是 URL 路径中以 : 开头的动态片段。TypeScript 的模板字面量类型可以从路径中提取参数名：

// 提取路径中的所有参数名
type ExtractPathParams<Path> = Path extends `${infer _}:${infer Param}/${infer Rest}`
  ? Param | ExtractPathParams<`/${Rest}`>
  : Path extends `${infer _}:${infer Param}`
  ? Param
  : never;

// 使用
type UserParams = ExtractPathParams<'/users/:id'>;
// 'id'

type CommentParams = ExtractPathParams<'/posts/:postId/comments/:commentId'>;
// 'postId' | 'commentId'

type NoParams = ExtractPathParams<'/users'>;
// never

递归解析：该类型递归地分割路径，每次提取 : 后的参数名，直到路径中不再包含 :。

2.3 路径参数替换

路径参数替换（Path Parameter Substitution）将路径中的 :param 替换为实际值。在类型层面，可以用模板字面量类型描述替换后的路径：

// 替换路径中的参数
type ReplaceParams<Path, Params extends Record<string, string>> =
  Path extends `${infer Before}:${infer Param}/${infer Rest}`
    ? `${Before}${Params[Param]}${ReplaceParams<`/${Rest}`, Params>}`
    : Path extends `${infer Before}:${infer Param}`
    ? `${Before}${Params[Param]}`
    : Path;

// 使用
type ReplacedPath = ReplaceParams<'/users/:id', { id: '123' }>;
// '/users/123'

type ReplacedComplex = ReplaceParams<'/posts/:postId/comments/:commentId', { postId: 'p1'; commentId: 'c1' }>;
// '/posts/p1/comments/c1'

2.4 HTTP 方法的语义

不同 HTTP 方法有不同的语义与参数要求：

类型安全的 API 客户端应反映这些语义：GET 与 DELETE 通常不需要 body，POST/PUT/PATCH 通常需要 body。

2.5 条件参数

不同方法对参数的要求不同，这通过条件类型与可变元组实现：

// 根据方法决定是否需要 body
type RequestOptions<M extends HttpMethod, Route> = {
  method?: M;
  params?: Route extends { params: infer P } ? P : never;
  query?: Route extends { query: infer Q } ? Q : never;
} & (M extends 'POST' | 'PUT' | 'PATCH'
  ? Route extends { body: infer B } ? { body: B } : {}
  : {});

这一类型根据方法 $M$ 决定 body 字段是否必填：POST/PUT/PATCH 时必填，GET/DELETE 时不存在。

2.6 泛型请求函数

基于路由类型映射，构建泛型请求函数：

async function request<
  Path extends keyof APIClient,
  Method extends keyof APIClient[Path] = 'GET',
>(
  path: Path,
  options: RequestOptions<Method, APIClient[Path][Method]>
): Promise<APIClient[Path][Method] extends { response: infer R } ? R : never> {
  // 实现省略
  return undefined as any;
}

// 使用
const users = await request('/users', { method: 'GET', query: { page: 1 } });
// 推断为 User[]

const user = await request('/users/:id', { method: 'GET', params: { id: '1' } });
// 推断为 User

await request('/users', { method: 'POST', body: { name: '张三' } });
// OK

await request('/users', { method: 'GET', body: { name: '张三' } });
// 编译错误：GET 请求不接受 body

2.7 infer 关键字

infer 关键字在条件类型中”推断”类型变量，是类型安全 API 客户端的核心工具：

// 从 Route 类型中提取 response 类型
type GetResponse<Route> = Route extends { response: infer R } ? R : never;

// 从 Route 类型中提取 params 类型
type GetParams<Route> = Route extends { params: infer P } ? P : never;

// 从 Route 类型中提取 query 类型
type GetQuery<Route> = Route extends { query: infer Q } ? Q : never;

// 从 Route 类型中提取 body 类型
type GetBody<Route> = Route extends { body: infer B } ? B : never;

// 使用
type UserResponse = GetResponse<{ response: User; params: { id: string } }>;
// User

type UserParams = GetParams<{ response: User; params: { id: string } }>;
// { id: string }

第三章 历史演变

3.1 早期：原生 fetch 与 XMLHttpRequest（2005-2014）

早期的 Web API 调用使用 XMLHttpRequest 或 fetch，无任何类型约束：

// XMLHttpRequest 时代
var xhr = new XMLHttpRequest();
xhr.open('GET', '/api/users/123', true);
xhr.onreadystatechange = function() {
  if (xhr.readyState === 4 && xhr.status === 200) {
    var user = JSON.parse(xhr.responseText);
    console.log(user.name); // 无类型保证
  }
};
xhr.send();

这一方案的问题：无类型约束、回调地狱、错误处理繁琐。

3.2 jQuery.ajax 与 Promise（2010-2015）

jQuery.ajax 引入了 Promise 风格的 API，简化了错误处理：

// jQuery.ajax
$.ajax({
  url: '/api/users/123',
  method: 'GET',
})
  .done((user: any) => {
    console.log(user.name);
  })
  .fail((xhr: any) => {
    console.error(xhr.responseText);
  });

仍然是 any 类型，无类型保证。

3.3 Axios 与 TypeScript 兴起（2015-2018）

Axios 是当时最流行的 HTTP 客户端，支持 Promise 与拦截器。TypeScript 兴起后，Axios 提供了基础类型：

import axios from 'axios';

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

// 显式指定响应类型
const response = await axios.get<User>('/api/users/123');
const user = response.data; // 类型为 User

问题：响应类型是显式指定的，与后端实际返回的类型可能不一致。如果后端修改了 API 但前端未更新类型，类型安全失效。

3.4 类型安全路由映射（2018-2020）

TypeScript 2.8 引入条件类型后，开发者开始构建类型安全的路由映射：

interface APIClient {
  '/users': {
    GET: { response: User[] };
  };
}

async function request<Path extends keyof APIClient>(
  path: Path
): Promise<APIClient[Path]['GET']['response']> {
  // ...
  return undefined as any;
}

const users = await request('/users'); // 推断为 User[]

这一方案实现了路由到响应的自动推断，但还不支持方法选择与参数约束。

3.5 模板字面量类型与完整类型安全（2020 至今）

TypeScript 4.1 引入模板字面量类型后，API 客户端实现了完整的类型安全：

// 路径参数自动提取
type ExtractParams<Path> = Path extends `${infer _}:${infer Param}/${infer Rest}`
  ? Param | ExtractParams<`/${Rest}`>
  : Path extends `${infer _}:${infer Param}`
  ? Param
  : never;

// 完整的类型安全请求函数
async function request<
  Path extends keyof APIClient,
  Method extends keyof APIClient[Path] = 'GET',
>(
  path: Path,
  options: RequestOptions<Method, APIClient[Path][Method]>
): Promise<GetResponse<APIClient[Path][Method]>> {
  // ...
}

这一方案实现了路径参数提取、方法选择、参数约束、响应推断的完整类型安全。

3.6 现代 API 客户端工具的时间线

3.7 tRPC：端到端类型安全的革命

tRPC（TypeScript Remote Procedure Call）是端到端类型安全的革命性方案，它不需要 OpenAPI 规范，直接共享 TypeScript 类型：

// 服务端定义
const appRouter = t.router({
  getUser: t.procedure.input(z.string()).query(({ input }) => {
    return getUserById(input);
  }),
});

// 客户端调用
const user = await trpc.getUser.query('123');
// 自动推断为 User 类型

tRPC 的局限：仅适用于 TypeScript 全栈应用，无法与非 TypeScript 后端集成。

第四章 设计哲学

4.1 类型驱动开发

类型安全 API 客户端的核心哲学是”类型驱动开发”：先定义 API 类型映射，再实现请求函数。类型定义是”契约”，实现是”履约”。

// 1. 先定义类型契约
interface APIClient {
  '/users': {
    GET: { response: User[] };
  };
}

// 2. 再实现请求函数（自动获得类型安全）
const api = createClient<APIClient>({ baseUrl: '/api' });

// 3. 调用时自动获得类型推断
const users = await api['/users'].get();
// User[]

这一哲学源自 Idris、Agda 等依赖类型语言的传统：类型先于实现，类型即规约。

4.2 单一真相源

类型安全的 API 客户端中，API 路由类型映射是”单一真相源”：

• 请求函数的签名由类型映射派生。
• 响应数据的类型由类型映射派生。
• IDE 自动补全基于类型映射。
• 错误提示基于类型映射。

避免在多处定义 API 契约（如后端文档、前端类型、测试 mock），导致不一致。

4.3 渐进式类型增强

API 客户端的类型安全是渐进式的：

// Level 0：无类型约束
async function fetchUser(id: string): Promise<any> { /* ... */ }

// Level 1：显式响应类型
async function fetchUser(id: string): Promise<User> { /* ... */ }

// Level 2：路由到响应的映射
interface APIClient {
  '/users/:id': { GET: { response: User; params: { id: string } } };
}
async function request<P extends keyof APIClient>(path: P): Promise<...> { /* ... */ }

// Level 3：完整的方法与参数约束
async function request<
  P extends keyof APIClient,
  M extends keyof APIClient[P] = 'GET',
>(path: P, options: RequestOptions<M, APIClient[P][M]>): Promise<...> { /* ... */ }

// Level 4：自动生成（从 OpenAPI）
// APIClient 类型由 openapi-typescript 自动生成

4.4 编译时与运行时分离

类型安全的类型约束在编译时完全消除，运行时只保留必要的数据与逻辑：

• 编译时：路由路径检查、方法检查、参数类型检查、响应类型推断。
• 运行时：HTTP 请求、参数序列化、响应解析、错误处理。

这一分离确保类型安全不带来运行时开销。数学上：

4.5 类型安全与开发体验平衡

完整的类型安全有时会增加编译时间。设计 API 客户端时需要在类型安全与开发体验间平衡：

• 严格模式：所有路由与方法显式约束，禁止 any。
• 宽松模式：允许部分路由使用 any，便于快速开发。
• 混合模式：核心路由严格约束，非核心路由宽松。

// 严格模式
type StrictClient = {
  [P in keyof APIClient]: {
    [M in keyof APIClient[P]]: (
      options: RequestOptions<M, APIClient[P][M]>
    ) => Promise<GetResponse<APIClient[P][M]>>;
  };
};

// 宽松模式
type LooseClient = {
  [P in keyof APIClient]: {
    get: (options?: any) => Promise<any>;
    post: (options?: any) => Promise<any>;
  };
};

4.6 契约优先设计

API 客户端的设计应遵循”契约优先”原则：先定义契约（类型映射），再实现客户端与服务器。这一原则与 OpenAPI/Swagger 的设计哲学一致：

// 1. 定义契约
interface APIClient { /* ... */ }

// 2. 生成 OpenAPI 规范
const openapiSpec = generateOpenAPI<APIClient>();

// 3. 后端根据规范实现
// 4. 前端根据规范生成客户端

这一设计确保前后端契约一致，避免不一致导致的运行时错误。

第五章 语法与语义

5.1 路由类型映射的完整语法

interface APIClient {
  [path: string]: {
    [method in HttpMethod]: RouteContract;
  };
}

interface RouteContract {
  response: unknown;          // 响应类型（必填）
  params?: Record<string, string | number>;  // 路径参数（可选）
  query?: Record<string, unknown>;           // 查询参数（可选）
  body?: unknown;             // 请求体（可选）
  headers?: Record<string, string>;          // 自定义请求头（可选）
}

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';

语法元素：

• [path: string]：路由路径，使用字面量字符串类型（如 '/users/:id'）。
• [method in HttpMethod]：HTTP 方法，使用联合类型。
• RouteContract：路由契约，包含 response、params、query、body、headers 等字段。

5.2 路径参数提取的完整语法

// 基础版：仅支持单一参数
type ExtractParam<Path> = Path extends `${infer _}:${infer Param}`
  ? Param
  : never;

// 进阶版：支持多参数与嵌套路径
type ExtractPathParams<Path> = Path extends `${infer _}:${infer Param}/${infer Rest}`
  ? Param | ExtractPathParams<`/${Rest}`>
  : Path extends `${infer _}:${infer Param}`
  ? Param
  : never;

// 完整版：处理参数名中的特殊字符
type ExtractPathParamsStrict<Path extends string> =
  Path extends `${infer _}:${infer Param}/${infer Rest}`
    ? Param extends `${infer Name}`
      ? Name | ExtractPathParamsStrict<`/${Rest}`>
      : never
    : Path extends `${infer _}:${infer Param}`
    ? Param
    : never;

语义：

• ${infer _}：匹配 : 前的任意字符串，赋值给 _（忽略）。
• ${infer Param}：匹配 : 后到 / 前的字符串，赋值给 Param。
• ${infer Rest}：匹配剩余路径，递归处理。

5.3 路径参数替换的完整语法

// 基础版：替换单一参数
type ReplaceParam<Path, Value extends string> =
  Path extends `${infer Before}:${infer _}`
    ? `${Before}${Value}`
    : Path;

// 进阶版：替换多个参数
type ReplaceParams<Path, Params extends Record<string, string>> =
  Path extends `${infer Before}:${infer Param}/${infer Rest}`
    ? `${Before}${Params[Param & keyof Params]}${ReplaceParams<`/${Rest}`, Params>}`
    : Path extends `${infer Before}:${infer Param}`
    ? `${Before}${Params[Param & keyof Params]}`
    : Path;

5.4 条件类型的分布性

条件类型在裸类型参数上自动分发，对处理 HTTP 方法联合类型有用：

// 联合类型分发
type GetMethods<Routes> = Routes extends { [M in HttpMethod]: any }
  ? keyof Routes
  : never;

type Methods = GetMethods<{ GET: any; POST: any }>;
// 'GET' | 'POST'

5.5 映射类型与键重映射

映射类型用于遍历路由与方法，生成 API 客户端类型：

// 自动生成 API 客户端
type APIMethods = {
  [Path in keyof APIClient]: {
    [Method in keyof APIClient[Path] as Lowercase<string & Method>]: (
      options: RequestOptions<Method, APIClient[Path][Method]>
    ) => Promise<GetResponse<APIClient[Path][Method]>>;
  };
};

键重映射（as Lowercase<string & Method>）：将 GET 转换为 get，符合 JavaScript 命名习惯。

5.6 infer 的多重使用

infer 可以在一次条件类型中多次使用，提取多个类型变量：

// 一次性提取所有字段
type ExtractRouteFields<Route> = Route extends {
  response: infer R;
  params?: infer P;
  query?: infer Q;
  body?: infer B;
}
  ? { response: R; params: P; query: Q; body: B }
  : never;

5.7 约束泛型参数

泛型参数可以使用 extends 约束，确保类型安全：

// Path 必须是 APIClient 的键
async function request<Path extends keyof APIClient>(path: Path): Promise<...> { /* ... */ }

// Method 必须是 APIClient[Path] 的键
async function request<
  Path extends keyof APIClient,
  Method extends keyof APIClient[Path],
>(path: Path, method: Method): Promise<...> { /* ... */ }

5.8 默认泛型参数

泛型参数可以有默认值，简化调用：

async function request<
  Path extends keyof APIClient,
  Method extends keyof APIClient[Path] = 'GET',  // 默认 GET
>(path: Path, options?: RequestOptions<Method, APIClient[Path][Method]>): Promise<...> { /* ... */ }

// 调用时不指定 Method，默认为 GET
const users = await request('/users');

第六章 实战示例

6.1 基础类型安全请求函数

实现一个基础的类型安全请求函数，支持路径参数、查询参数、请求体和响应推断：

// ============== 类型定义 ==============

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

interface Post {
  id: string;
  title: string;
  content: string;
  authorId: string;
  createdAt: string;
}

interface Comment {
  id: string;
  postId: string;
  content: string;
  authorId: string;
}

// API 路由类型映射
interface APIClient {
  '/users': {
    GET: {
      response: User[];
      query?: { page?: number; limit?: number; search?: string };
    };
    POST: {
      response: User;
      body: Omit<User, 'id'>;
    };
  };
  '/users/:id': {
    GET: { response: User; params: { id: string } };
    PUT: { response: User; params: { id: string }; body: Partial<Omit<User, 'id'>> };
    DELETE: { response: void; params: { id: string } };
  };
  '/posts': {
    GET: {
      response: Post[];
      query?: { authorId?: string; page?: number; limit?: number };
    };
    POST: {
      response: Post;
      body: Omit<Post, 'id' | 'createdAt'>;
    };
  };
  '/posts/:postId/comments': {
    GET: {
      response: Comment[];
      params: { postId: string };
      query?: { sort?: 'asc' | 'desc' };
    };
    POST: {
      response: Comment;
      params: { postId: string };
      body: { content: string };
    };
  };
}

// ============== 工具类型 ==============

type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

// 提取路径参数名
type ExtractPathParams<Path> = Path extends `${infer _}:${infer Param}/${infer Rest}`
  ? Param | ExtractPathParams<`/${Rest}`>
  : Path extends `${infer _}:${infer Param}`
  ? Param
  : never;

// 获取路由的响应类型
type GetResponse<Route> = Route extends { response: infer R } ? R : never;

// 获取路由的路径参数类型
type GetParams<Route> = Route extends { params: infer P } ? P : never;

// 获取路由的查询参数类型
type GetQuery<Route> = Route extends { query: infer Q } ? Q : never;

// 获取路由的请求体类型
type GetBody<Route> = Route extends { body: infer B } ? B : never;

// 提取支持指定方法的所有路径
type PathsWithMethod<M extends HttpMethod> = {
  [P in keyof APIClient]: M extends keyof APIClient[P] ? P : never;
}[keyof APIClient];

// 请求选项类型
type RequestOptions<Route> = {
  params?: GetParams<Route>;
  query?: GetQuery<Route>;
  body?: GetBody<Route>;
  headers?: Record<string, string>;
  signal?: AbortSignal;
};

// ============== 请求函数实现 ==============

async function request<
  Path extends keyof APIClient,
  Method extends keyof APIClient[Path] = 'GET',
>(
  path: Path,
  options: RequestOptions<APIClient[Path][Method]> = {}
): Promise<GetResponse<APIClient[Path][Method]>> {
  const { params, query, body, headers, signal } = options;

  // 替换路径参数
  let url: string = path;
  if (params) {
    for (const [key, value] of Object.entries(params)) {
      url = url.replace(`:${key}`, encodeURIComponent(String(value)));
    }
  }

  // 添加查询参数
  if (query) {
    const searchParams = new URLSearchParams();
    for (const [key, value] of Object.entries(query)) {
      if (value !== undefined && value !== null) {
        searchParams.append(key, String(value));
      }
    }
    const queryString = searchParams.toString();
    if (queryString) {
      url += `?${queryString}`;
    }
  }

  // 构造请求头
  const requestHeaders: Record<string, string> = {
    ...(body ? { 'Content-Type': 'application/json' } : {}),
    ...headers,
  };

  // 发送请求
  const response = await fetch(url, {
    method: options.method as string || 'GET',
    headers: requestHeaders,
    body: body ? JSON.stringify(body) : undefined,
    signal,
  });

  // 处理错误
  if (!response.ok) {
    const errorBody = await response.json().catch(() => ({}));
    throw new APIError(
      errorBody.code || 'UNKNOWN_ERROR',
      errorBody.message || `请求失败: ${response.status}`,
      response.status,
      errorBody.details
    );
  }

  // 解析响应
  const contentType = response.headers.get('Content-Type') || '';
  if (contentType.includes('application/json')) {
    return response.json();
  }
  return undefined as GetResponse<APIClient[Path][Method]>;
}

// ============== 使用示例 ==============

// GET /users
const users = await request('/users', {
  query: { page: 1, limit: 10 },
});
// 推断为 User[]

// GET /users/:id
const user = await request('/users/:id', {
  params: { id: '123' },
});
// 推断为 User

// POST /users
const newUser = await request('/users', {
  method: 'POST',
  body: { name: '张三', email: 'zhangsan@example.com', age: 25 },
});
// 推断为 User

// PUT /users/:id
const updatedUser = await request('/users/:id', {
  method: 'PUT',
  params: { id: '123' },
  body: { name: '李四' },
});
// 推断为 User

// DELETE /users/:id
await request('/users/:id', {
  method: 'DELETE',
  params: { id: '123' },
});
// 推断为 void

6.2 类型安全的链式请求构建器

实现一个链式请求构建器，提供更流畅的 API：

// ============== 请求构建器 ==============

class RequestBuilder<
  Path extends keyof APIClient,
  Method extends keyof APIClient[Path] = 'GET',
> {
  private path: Path;
  private method: Method = 'GET' as Method;
  private paramsObj?: GetParams<APIClient[Path][Method]>;
  private queryObj?: GetQuery<APIClient[Path][Method]>;
  private bodyObj?: GetBody<APIClient[Path][Method]>;
  private headersObj: Record<string, string> = {};
  private signalObj?: AbortSignal;

  constructor(path: Path) {
    this.path = path;
  }

  method<M extends keyof APIClient[Path]>(method: M): RequestBuilder<Path, M> {
    const builder = new RequestBuilder<Path, M>(this.path);
    builder.method = method;
    builder.paramsObj = this.paramsObj as any;
    builder.queryObj = this.queryObj as any;
    builder.bodyObj = this.bodyObj as any;
    builder.headersObj = this.headersObj;
    builder.signalObj = this.signalObj;
    return builder;
  }

  params(p: GetParams<APIClient[Path][Method]>): this {
    this.paramsObj = p;
    return this;
  }

  query(q: GetQuery<APIClient[Path][Method]>): this {
    this.queryObj = q;
    return this;
  }

  body(b: GetBody<APIClient[Path][Method]>): this {
    this.bodyObj = b;
    return this;
  }

  headers(h: Record<string, string>): this {
    this.headersObj = { ...this.headersObj, ...h };
    return this;
  }

  signal(s: AbortSignal): this {
    this.signalObj = s;
    return this;
  }

  async execute(): Promise<GetResponse<APIClient[Path][Method]>> {
    return request<Path, Method>(this.path, {
      method: this.method,
      params: this.paramsObj,
      query: this.queryObj,
      body: this.bodyObj,
      headers: this.headersObj,
      signal: this.signalObj,
    } as any);
  }
}

// ============== 使用示例 ==============

// 链式调用
const users = await new RequestBuilder('/users')
  .method('GET')
  .query({ page: 1, limit: 10 })
  .execute();
// User[]

const newUser = await new RequestBuilder('/users')
  .method('POST')
  .body({ name: '张三', email: 'zhangsan@example.com', age: 25 })
  .execute();
// User

const updatedUser = await new RequestBuilder('/users/:id')
  .method('PUT')
  .params({ id: '123' })
  .body({ name: '李四' })
  .execute();
// User

6.3 自动生成的 API 客户端

自动生成所有路由与方法的 API 客户端：

// ============== 自动生成 API 客户端 ==============

type APIMethods = {
  [Path in keyof APIClient]: {
    [Method in keyof APIClient[Path] as Lowercase<string & Method>]: (
      options: Omit<RequestOptions<APIClient[Path][Method]>, 'method'>
    ) => Promise<GetResponse<APIClient[Path][Method]>>;
  };
};

// 创建 API 客户端
function createAPIClient(): APIMethods {
  const handler: ProxyHandler<APIMethods> = {
    get(target, path: string) {
      return new Proxy({} as APIMethods[string], {
        get(target, method: string) {
          return (options: RequestOptions<any>) => {
            return request(path as keyof APIClient, {
              ...options,
              method: method.toUpperCase() as HttpMethod,
            } as any);
          };
        },
      });
    },
  };

  return new Proxy({} as APIMethods, handler);
}

const api = createAPIClient();

// ============== 使用示例 ==============

// 类型安全的调用
const users = await api['/users'].get({ query: { page: 1 } });
// User[]

const user = await api['/users/:id'].get({ params: { id: '123' } });
// User

const newUser = await api['/users'].post({
  body: { name: '张三', email: 'zhangsan@example.com', age: 25 },
});
// User

await api['/users/:id'].delete({ params: { id: '123' } });
// void

// 编译错误示例
// await api['/users'].delete({}); // 错误：/users 不支持 DELETE
// await api['/users/:id'].get({}); // 错误：缺少 params.id
// await api['/users'].post({}); // 错误：缺少 body

6.4 错误类型化与结果类型

实现类型化的错误处理与 Result 类型：

// ============== 错误类型定义 ==============

// API 错误码枚举
type APIErrorCode =
  | 'NOT_FOUND'
  | 'UNAUTHORIZED'
  | 'FORBIDDEN'
  | 'VALIDATION_ERROR'
  | 'CONFLICT'
  | 'INTERNAL_ERROR'
  | 'RATE_LIMIT_EXCEEDED'
  | 'UNKNOWN_ERROR';

// API 错误类
class APIError extends Error {
  constructor(
    public code: APIErrorCode,
    message: string,
    public statusCode: number,
    public details?: Record<string, string[]>
  ) {
    super(message);
    this.name = 'APIError';
  }

  isNotFound(): this is APIError & { code: 'NOT_FOUND' } {
    return this.code === 'NOT_FOUND';
  }

  isUnauthorized(): this is APIError & { code: 'UNAUTHORIZED' } {
    return this.code === 'UNAUTHORIZED';
  }

  isValidationError(): this is APIError & { code: 'VALIDATION_ERROR'; details: Record<string, string[]> } {
    return this.code === 'VALIDATION_ERROR';
  }
}

// Result 类型
type APIResult<T> =
  | { success: true; data: T }
  | { success: false; error: APIError };

// ============== 安全请求函数 ==============

async function safeRequest<
  Path extends keyof APIClient,
  Method extends keyof APIClient[Path] = 'GET',
>(
  path: Path,
  options: RequestOptions<APIClient[Path][Method]> = {}
): Promise<APIResult<GetResponse<APIClient[Path][Method]>>> {
  try {
    const data = await request<Path, Method>(path, options as any);
    return { success: true, data };
  } catch (error) {
    if (error instanceof APIError) {
      return { success: false, error };
    }
    return {
      success: false,
      error: new APIError(
        'UNKNOWN_ERROR',
        error instanceof Error ? error.message : '未知错误',
        0
      ),
    };
  }
}

// ============== 使用示例 ==============

const result = await safeRequest('/users/:id', {
  params: { id: '123' },
});

if (result.success) {
  console.log(result.data.name); // User
} else {
  if (result.error.isNotFound()) {
    console.log('用户不存在');
  } else if (result.error.isValidationError()) {
    console.log('验证错误:', result.error.details);
  } else {
    console.log('错误:', result.error.message);
  }
}

6.5 请求/响应拦截器

实现类型安全的请求/响应拦截器：

// ============== 拦截器类型定义 ==============

interface RequestConfig {
  url: string;
  method: HttpMethod;
  headers: Record<string, string>;
  params?: Record<string, string>;
  query?: Record<string, string>;
  body?: unknown;
  signal?: AbortSignal;
}

interface ResponseConfig<T> {
  data: T;
  status: number;
  headers: Record<string, string>;
}

interface RequestInterceptor {
  onRequest(config: RequestConfig): RequestConfig | Promise<RequestConfig>;
  onError?(error: Error): Error | Promise<Error>;
}

interface ResponseInterceptor {
  onResponse<T>(response: ResponseConfig<T>): ResponseConfig<T> | Promise<ResponseConfig<T>>;
  onError?(error: APIError): APIError | Promise<APIError>;
}

// ============== HTTP 客户端类 ==============

class HTTPClient {
  private requestInterceptors: RequestInterceptor[] = [];
  private responseInterceptors: ResponseInterceptor[] = [];
  private baseUrl: string;

  constructor(baseUrl: string = '') {
    this.baseUrl = baseUrl;
  }

  // 添加请求拦截器
  addRequestInterceptor(interceptor: RequestInterceptor): void {
    this.requestInterceptors.push(interceptor);
  }

  // 添加响应拦截器
  addResponseInterceptor(interceptor: ResponseInterceptor): void {
    this.responseInterceptors.push(interceptor);
  }

  // 添加认证拦截器
  addAuthToken(getToken: () => string | null): void {
    this.addRequestInterceptor({
      onRequest(config) {
        const token = getToken();
        if (token) {
          config.headers = { ...config.headers, Authorization: `Bearer ${token}` };
        }
        return config;
      },
    });
  }

  // 添加日志拦截器
  addLogger(): void {
    this.addRequestInterceptor({
      onRequest(config) {
        console.log(`[Request] ${config.method} ${config.url}`);
        return config;
      },
    });
    this.addResponseInterceptor({
      onResponse(response) {
        console.log(`[Response] ${response.status}`);
        return response;
      },
      onError(error) {
        console.error(`[Error] ${error.code}: ${error.message}`);
        return error;
      },
    });
  }

  // 添加重试拦截器
  addRetry(maxRetries: number = 3, retryDelay: number = 1000): void {
    let retryCount = 0;
    this.addRequestInterceptor({
      async onError(error) {
        if (retryCount < maxRetries && error instanceof APIError && error.statusCode >= 500) {
          retryCount++;
          await new Promise(resolve => setTimeout(resolve, retryDelay * retryCount));
          throw error; // 重新抛出以触发重试
        }
        return error;
      },
    });
  }

  // 执行请求
  async execute<T>(
    config: Omit<RequestConfig, 'url'> & { path: string }
  ): Promise<T> {
    let finalConfig: RequestConfig = {
      ...config,
      url: `${this.baseUrl}${config.path}`,
    };

    // 应用请求拦截器
    for (const interceptor of this.requestInterceptors) {
      try {
        finalConfig = await interceptor.onRequest(finalConfig);
      } catch (error) {
        if (interceptor.onError) {
          throw await interceptor.onError(error as Error);
        }
        throw error;
      }
    }

    // 发送请求
    let response: Response;
    try {
      response = await fetch(finalConfig.url, {
        method: finalConfig.method,
        headers: finalConfig.headers,
        body: finalConfig.body ? JSON.stringify(finalConfig.body) : undefined,
        signal: finalConfig.signal,
      });
    } catch (error) {
      const apiError = new APIError(
        'UNKNOWN_ERROR',
        error instanceof Error ? error.message : '网络错误',
        0
      );
      for (const interceptor of this.responseInterceptors) {
        if (interceptor.onError) {
          throw await interceptor.onError(apiError);
        }
      }
      throw apiError;
    }

    // 处理响应
    if (!response.ok) {
      const errorBody = await response.json().catch(() => ({}));
      const apiError = new APIError(
        errorBody.code || 'UNKNOWN_ERROR',
        errorBody.message || `请求失败: ${response.status}`,
        response.status,
        errorBody.details
      );
      for (const interceptor of this.responseInterceptors) {
        if (interceptor.onError) {
          throw await interceptor.onError(apiError);
        }
      }
      throw apiError;
    }

    const data = await response.json().catch(() => undefined);
    let responseConfig: ResponseConfig<T> = {
      data: data as T,
      status: response.status,
      headers: Object.fromEntries(response.headers.entries()),
    };

    // 应用响应拦截器
    for (const interceptor of this.responseInterceptors) {
      responseConfig = await interceptor.onResponse(responseConfig);
    }

    return responseConfig.data;
  }
}

// ============== 使用示例 ==============

const httpClient = new HTTPClient('/api');
httpClient.addAuthToken(() => localStorage.getItem('token'));
httpClient.addLogger();
httpClient.addRetry(3, 1000);

const user = await httpClient.execute<User>({
  path: '/users/123',
  method: 'GET',
  headers: {},
});

6.6 React Hook 集成

实现类型安全的 React Hook：

// ============== React Hook ==============

import { useState, useEffect, useCallback } from 'react';

// useFetch Hook
interface UseFetchOptions {
  enabled?: boolean;       // 是否立即执行
  retry?: number;          // 重试次数
  retryDelay?: number;     // 重试延迟
}

interface UseFetchResult<T> {
  data: T | undefined;
  loading: boolean;
  error: APIError | undefined;
  refetch: () => Promise<void>;
}

function useFetch<
  Path extends keyof APIClient,
  Method extends keyof APIClient[Path] = 'GET',
>(
  path: Path,
  options: RequestOptions<APIClient[Path][Method]> = {},
  useFetchOptions: UseFetchOptions = {}
): UseFetchResult<GetResponse<APIClient[Path][Method]>> {
  type ResponseType = GetResponse<APIClient[Path][Method]>;

  const [data, setData] = useState<ResponseType>();
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<APIError>();
  const { enabled = true, retry = 0, retryDelay = 1000 } = useFetchOptions;

  const fetchData = useCallback(async () => {
    setLoading(true);
    setError(undefined);

    let lastError: APIError | undefined;
    let attempt = 0;

    while (attempt <= retry) {
      try {
        const result = await request<Path, Method>(path, options as any);
        setData(result);
        setError(undefined);
        return;
      } catch (err) {
        if (err instanceof APIError) {
          lastError = err;
        } else {
          lastError = new APIError(
            'UNKNOWN_ERROR',
            err instanceof Error ? err.message : '未知错误',
            0
          );
        }
        attempt++;
        if (attempt <= retry) {
          await new Promise(resolve => setTimeout(resolve, retryDelay));
        }
      }
    }

    setError(lastError);
  }, [JSON.stringify(path), JSON.stringify(options), retry, retryDelay]);

  useEffect(() => {
    if (enabled) {
      fetchData();
    }
  }, [enabled, fetchData]);

  const refetch = useCallback(async () => {
    await fetchData();
  }, [fetchData]);

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

// useMutation Hook
interface UseMutationResult<T, V> {
  data: T | undefined;
  loading: boolean;
  error: APIError | undefined;
  mutate: (variables: V) => Promise<T>;
}

function useMutation<
  Path extends keyof APIClient,
  Method extends 'POST' | 'PUT' | 'PATCH' | 'DELETE',
>(
  path: Path,
  method: Method
): UseMutationResult<
  GetResponse<APIClient[Path][Method]>,
  GetBody<APIClient[Path][Method]>
> {
  type ResponseType = GetResponse<APIClient[Path][Method]>;
  type BodyType = GetBody<APIClient[Path][Method]>;

  const [data, setData] = useState<ResponseType>();
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<APIError>();

  const mutate = useCallback(async (variables: BodyType): Promise<ResponseType> => {
    setLoading(true);
    setError(undefined);

    try {
      const result = await request<Path, Method>(path, {
        method: method as any,
        body: variables,
      } as any);
      setData(result);
      return result;
    } catch (err) {
      if (err instanceof APIError) {
        setError(err);
        throw err;
      }
      const apiError = new APIError(
        'UNKNOWN_ERROR',
        err instanceof Error ? err.message : '未知错误',
        0
      );
      setError(apiError);
      throw apiError;
    } finally {
      setLoading(false);
    }
  }, [path, method]);

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

// ============== 使用示例 ==============

// 在组件中使用
function UserList() {
  const { data: users, loading, error, refetch } = useFetch('/users', {
    query: { page: 1, limit: 10 },
  });

  if (loading) return <div>加载中...</div>;
  if (error) return <div>错误: {error.message}</div>;

  return (
    <div>
      {users?.map(user => (
        <div key={user.id}>{user.name}</div>
      ))}
      <button onClick={refetch}>刷新</button>
    </div>
  );
}

function CreateUser() {
  const { mutate, loading, error } = useMutation('/users', 'POST');

  const handleSubmit = async () => {
    try {
      await mutate({
        name: '张三',
        email: 'zhangsan@example.com',
        age: 25,
      });
    } catch (err) {
      console.error('创建失败:', err);
    }
  };

  return (
    <div>
      <button onClick={handleSubmit} disabled={loading}>
        {loading ? '创建中...' : '创建用户'}
      </button>
      {error && <div>错误: {error.message}</div>}
    </div>
  );
}

6.7 Vue Composable 集成

实现类型安全的 Vue 3 Composable：

// ============== Vue Composable ==============

import { ref, watchEffect, type Ref } from 'vue';

// useFetch Composable
interface UseFetchOptions {
  enabled?: Ref<boolean>;
  retry?: number;
  retryDelay?: number;
}

interface UseFetchResult<T> {
  data: Ref<T | undefined>;
  loading: Ref<boolean>;
  error: Ref<APIError | undefined>;
  refetch: () => Promise<void>;
}

function useFetch<
  Path extends keyof APIClient,
  Method extends keyof APIClient[Path] = 'GET',
>(
  path: Path | Ref<Path>,
  options: RequestOptions<APIClient[Path][Method]> | Ref<RequestOptions<APIClient[Path][Method]>> = {},
  useFetchOptions: UseFetchOptions = {}
): UseFetchResult<GetResponse<APIClient[Path][Method]>> {
  type ResponseType = GetResponse<APIClient[Path][Method]>;

  const data = ref<ResponseType>() as Ref<ResponseType | undefined>;
  const loading = ref(false);
  const error = ref<APIError>();
  const { enabled = ref(true), retry = 0, retryDelay = 1000 } = useFetchOptions;

  const fetchData = async () => {
    if (!enabled.value) return;

    loading.value = true;
    error.value = undefined;

    const currentPath = typeof path === 'object' && 'value' in path ? path.value : path;
    const currentOptions =
      typeof options === 'object' && 'value' in options ? options.value : options;

    let lastError: APIError | undefined;
    let attempt = 0;

    while (attempt <= retry) {
      try {
        const result = await request(currentPath, currentOptions as any);
        data.value = result;
        error.value = undefined;
        return;
      } catch (err) {
        if (err instanceof APIError) {
          lastError = err;
        } else {
          lastError = new APIError(
            'UNKNOWN_ERROR',
            err instanceof Error ? err.message : '未知错误',
            0
          );
        }
        attempt++;
        if (attempt <= retry) {
          await new Promise(resolve => setTimeout(resolve, retryDelay));
        }
      }
    }

    error.value = lastError;
    loading.value = false;
  };

  watchEffect(() => {
    fetchData();
  });

  const refetch = async () => {
    await fetchData();
  };

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

// useMutation Composable
interface UseMutationResult<T, V> {
  data: Ref<T | undefined>;
  loading: Ref<boolean>;
  error: Ref<APIError | undefined>;
  mutate: (variables: V) => Promise<T>;
}

function useMutation<
  Path extends keyof APIClient,
  Method extends 'POST' | 'PUT' | 'PATCH' | 'DELETE',
>(
  path: Path,
  method: Method
): UseMutationResult<
  GetResponse<APIClient[Path][Method]>,
  GetBody<APIClient[Path][Method]>
> {
  type ResponseType = GetResponse<APIClient[Path][Method]>;
  type BodyType = GetBody<APIClient[Path][Method]>;

  const data = ref<ResponseType>() as Ref<ResponseType | undefined>;
  const loading = ref(false);
  const error = ref<APIError>();

  const mutate = async (variables: BodyType): Promise<ResponseType> => {
    loading.value = true;
    error.value = undefined;

    try {
      const result = await request<Path, Method>(path, {
        method: method as any,
        body: variables,
      } as any);
      data.value = result;
      return result;
    } catch (err) {
      if (err instanceof APIError) {
        error.value = err;
        throw err;
      }
      const apiError = new APIError(
        'UNKNOWN_ERROR',
        err instanceof Error ? err.message : '未知错误',
        0
      );
      error.value = apiError;
      throw apiError;
    } finally {
      loading.value = false;
    }
  };

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

// ============== 使用示例 ==============

// 在组件中使用
import { defineComponent } from 'vue';

export default defineComponent({
  setup() {
    const { data: users, loading, error, refetch } = useFetch('/users', {
      query: { page: 1, limit: 10 },
    });

    const { mutate: createUser, loading: creating } = useMutation('/users', 'POST');

    const handleCreate = async () => {
      try {
        await createUser({
          name: '张三',
          email: 'zhangsan@example.com',
          age: 25,
        });
        await refetch();
      } catch (err) {
        console.error('创建失败:', err);
      }
    };

    return { users, loading, error, creating, handleCreate };
  },
});

6.8 请求取消与超时

实现请求取消与超时控制：

// ============== 请求取消 ==============

class CancellationToken {
  private controller: AbortController;

  constructor() {
    this.controller = new AbortController();
  }

  get signal(): AbortSignal {
    return this.controller.signal;
  }

  abort(): void {
    this.controller.abort();
  }
}

// 带超时的请求
async function requestWithTimeout(
  url: string,
  options: RequestInit & { timeout?: number } = {}
): Promise<Response> {
  const { timeout = 10000, ...fetchOptions } = options;
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeout);

  try {
    const response = await fetch(url, {
      ...fetchOptions,
      signal: controller.signal,
    });
    return response;
  } finally {
    clearTimeout(timeoutId);
  }
}

// 使用示例
const token = new CancellationToken();

// 在某处取消
setTimeout(() => token.abort(), 5000);

try {
  const user = await request('/users/:id', {
    params: { id: '123' },
    signal: token.signal,
  });
} catch (error) {
  if (error instanceof DOMException && error.name === 'AbortError') {
    console.log('请求已取消');
  }
}

6.9 文件上传

实现类型安全的文件上传：

// ============== 文件上传类型定义 ==============

interface FileUploadOptions {
  file: File;
  fieldName?: string;
  additionalFields?: Record<string, string>;
  onProgress?: (loaded: number, total: number) => void;
}

// 文件上传函数
function uploadFile(
  url: string,
  options: FileUploadOptions,
  signal?: AbortSignal
): Promise<{ url: string }> {
  return new Promise((resolve, reject) => {
    const formData = new FormData();
    formData.append(options.fieldName || 'file', options.file);

    if (options.additionalFields) {
      for (const [key, value] of Object.entries(options.additionalFields)) {
        formData.append(key, value);
      }
    }

    const xhr = new XMLHttpRequest();
    xhr.open('POST', url);

    if (options.onProgress) {
      xhr.upload.onprogress = (event) => {
        if (event.lengthComputable) {
          options.onProgress!(event.loaded, event.total);
        }
      };
    }

    xhr.onload = () => {
      if (xhr.status >= 200 && xhr.status < 300) {
        try {
          const response = JSON.parse(xhr.responseText);
          resolve(response);
        } catch (error) {
          reject(new APIError('UNKNOWN_ERROR', '响应解析失败', xhr.status));
        }
      } else {
        reject(new APIError('UNKNOWN_ERROR', `上传失败: ${xhr.status}`, xhr.status));
      }
    };

    xhr.onerror = () => {
      reject(new APIError('UNKNOWN_ERROR', '网络错误', 0));
    };

    if (signal) {
      signal.addEventListener('abort', () => {
        xhr.abort();
        reject(new APIError('UNKNOWN_ERROR', '上传已取消', 0));
      });
    }

    xhr.send(formData);
  });
}

// 使用示例
const fileInput = document.querySelector<HTMLInputElement>('#file')!;
const file = fileInput.files?.[0];

if (file) {
  const result = await uploadFile('/api/upload', {
    file,
    fieldName: 'avatar',
    additionalFields: {
      userId: '123',
    },
    onProgress: (loaded, total) => {
      console.log(`上传进度: ${(loaded / total * 100).toFixed(2)}%`);
    },
  });
  console.log('上传成功:', result.url);
}