使用 TypeScript 构建类型安全的 API 客户端：从 OpenAPI 到自动生成类型

在现代前后端分离的开发模式中，API 客户端是连接前端应用与后端服务的桥梁。然而，手动维护 API 请求代码和对应的 TypeScript 类型定义，往往是一件既繁琐又容易出错的事情。后端接口一旦调整，前端若未能同步更新，轻则出现运行时错误，重则导致线上故障。本文将介绍如何利用 OpenAPI 规范，自动生成类型安全的 TypeScript API 客户端，从而彻底解决这一痛点。

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

在没有类型约束的情况下，我们通常这样调用接口：

const res = await fetch('/api/users/1');
const data = await res.json();
console.log(data.nmae); // 拼写错误，但编译不会报错

这种代码存在几个明显问题：

• 字段拼写错误无法在编译期发现，只能等到运行时才暴露。
• 接口返回结构变更时，前端没有任何提示，容易产生隐性 bug。
• 请求参数缺乏约束，传错类型或漏传字段都难以察觉。

而类型安全的 API 客户端可以在编写代码时提供自动补全、参数校验和错误提示，把问题扼杀在编译阶段，极大提升开发效率和代码可靠性。

OpenAPI：类型生成的基石

OpenAPI 规范（原 Swagger 规范）是目前最流行的 RESTful API 描述格式。它使用 JSON 或 YAML 描述接口的路径、请求方法、参数、请求体和响应结构。只要后端维护一份准确的 OpenAPI 文档，前端就可以据此自动生成类型和请求代码。

一个简化的 OpenAPI 片段如下：

paths:
  /users/{id}:
    get:
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string

这份文档清晰地定义了接口的输入与输出，为自动生成提供了完整信息。

主流代码生成工具对比

社区中有多款成熟的工具可以将 OpenAPI 转换为 TypeScript 代码，常见的有：

• openapi-typescript：只生成类型定义，不生成请求逻辑，轻量灵活，适合搭配 fetch 或 axios 使用。
• openapi-generator：功能全面，支持多种语言和客户端模板，可生成完整的 API 类。
• orval：专为 TypeScript 设计，能生成类型、请求函数以及 React Query、SWR 等 hooks。
• swagger-typescript-api：生成简洁的 API 类，支持 axios 和 fetch。

对于大多数前端项目，openapi-typescript + fetch 封装或 orval 是最推荐的组合。前者轻量可控，后者开箱即用。

实战：使用 openapi-typescript 生成类型

首先安装依赖：

npm install -D openapi-typescript

假设后端提供的 OpenAPI 文档位于 http://localhost:3000/openapi.json，执行以下命令生成类型文件：

npx openapi-typescript http://localhost:3000/openapi.json -o src/api/schema.d.ts

生成的 schema.d.ts 包含所有接口的路径、参数和响应类型。例如：

export interface paths {
  '/users/{id}': {
    get: operations['getUser'];
  };
}

export interface operations {
  getUser: {
    parameters: {
      path: { id: number };
    };
    responses: {
      200: {
        content: {
          'application/json': components['schemas']['User'];
        };
      };
    };
  };
}

有了这些类型，我们就可以封装一个类型安全的请求函数：

import createClient from 'openapi-fetch';
import type { paths } from './schema';

const client = createClient<paths>({ baseUrl: 'http://localhost:3000' });

async function fetchUser(id: number) {
  const { data, error } = await client.GET('/users/{id}', {
    params: { path: { id } },
  });
  if (error) throw new Error('请求失败');
  return data; // data 的类型自动推断为 User
}

可以看到，id 参数必须是数字，返回的 data 自动获得 User 类型。如果传入字符串或访问不存在的字段，TypeScript 会立即报错。

集成到构建流程

为了确保类型始终与后端同步，建议将生成命令加入 package.json 脚本：

{
  "scripts": {
    "api:generate": "openapi-typescript http://localhost:3000/openapi.json -o src/api/schema.d.ts",
    "prebuild": "npm run api:generate"
  }
}

这样每次构建前都会重新生成类型。在 CI 环境中，还可以加入校验步骤，若生成的类型与仓库中的不一致则直接失败，强制开发者更新。

进阶：使用 orval 生成完整客户端

如果希望连请求函数和 React Query hooks 一起生成，orval 是更好的选择。配置 orval.config.ts：

export default {
  api: {
    input: 'http://localhost:3000/openapi.json',
    output: {
      target: 'src/api/endpoints.ts',
      client: 'react-query',
      mode: 'tags-split',
    },
  },
};

运行 npx orval 后，你会得到按标签拆分的请求函数和 hooks，例如 useGetUser，直接具备缓存、重试等能力，进一步提升开发体验。

注意事项与最佳实践

1. 保持 OpenAPI 文档准确：类型生成的源头是文档，文档失真则一切白费。建议后端将文档生成纳入 CI，确保与代码一致。
2. 版本管理：将生成的类型文件提交到仓库，便于 code review 时发现接口变更。
3. 避免过度生成：只生成项目实际用到的接口，可通过过滤减少体积。
4. 错误处理统一化：在封装的客户端中集中处理 401、500 等状态码，避免每个调用点重复判断。

总结

从 OpenAPI 到自动生成 TypeScript 类型，这条链路让 API 客户端从“手工作坊”走向“工业化生产”。它不仅消除了字段拼写错误、参数类型不匹配等常见问题，还让接口变更的影响在编译期就暴露出来。借助 openapi-typescript、orval 等工具，我们只需几行配置，就能获得完整的类型安全和自动补全体验。如果你还在手动维护 API 类型，不妨从今天开始，让代码生成接管这项工作。

未经允许不得转载：任鹏个人博客 » 使用 TypeScript 构建类型安全的 API 客户端：从 OpenAPI 到自动生成类型