openapi-ts-client

openapi-ts-client — SKILL.md

变体： standard · 适用场景： 使用 @hey-api/openapi-ts 从 OpenAPI 3.1 契约生成类型化 TS 客户端/SDK。

概览

@hey-api/openapi-ts 是维护中的 OpenAPI TypeScript 代码生成器，也是 FastAPI 官方文档推荐用于 TS 客户端的工具。将 OpenAPI 3.1 文档（实时的 /openapi.json URL 或已保存的文件）传入，它便会生成类型化模型、类型化 SDK（每个操作对应一个异步函数），以及通过插件生成的 TanStack Query hooks 和 Zod schemas。生成的客户端属于构建产物：OpenAPI 契约是唯一事实来源，应重新生成，而不是手动编辑。本技能介绍如何配置它、选择客户端传输方式、启用 TanStack Query + Zod 插件、执行重新生成与偏差检查工作流，以及修复 FastAPI 特有的 operationId 命名问题。已针对 @hey-api/openapi-ts v0.98.2（0.x 系列）进行验证；设置时请确认当前版本。

何时启用

• ✅ 从 FastAPI（或任何 OpenAPI 3.1）/openapi.json 生成类型化 TS 客户端/SDK。
• ✅ 根据规范添加生成的 TanStack Query hooks 或 Zod 请求/响应 schemas。
• ✅ 将手写或手动维护的 API 客户端替换为生成的客户端。
• ✅ 设置契约变更时重新生成的工作流，以及 CI 偏差检查。

不要在以下情况下启用：

• 你需要 TanStack Query 的使用模式（缓存、失效处理、查询键）——请与 tanstack-query 技能搭配使用；本技能只负责生成 hooks。
• 你正在编写后端、OpenAPI 规范或 Pydantic 模型——请使用 fastapi / pydantic-v2 技能。
• 契约仅使用 OpenAPI 3.0，且你需要专门针对 3.0 的工具——hey-api 面向 3.1（FastAPI ≥ 0.99 生成的版本）；它可以读取 3.0，但最适合的场景是 3.1。

工作流

第 1 步：安装

安装生成器。从 v0.73.0 起，客户端已内置于生成器中，无需单独安装客户端包：

npm install @hey-api/openapi-ts -D -E      # generator (pnpm/yarn/bun analogous)

第 2 步：编写 openapi-ts.config.ts

import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  input: 'http://localhost:8000/openapi.json', // URL, file path, or a spec object
  output: 'src/client',                        // dir; or { path, format, lint }
  plugins: [
    '@hey-api/client-fetch',      // transport (fetch default; -axios / -next)
    '@tanstack/react-query',      // generated query/mutation hooks
    'zod',                        // generated request/response schemas
  ],
});

@hey-api/typescript（类型）、@hey-api/sdk 和 @hey-api/schemas 是默认包含的核心插件。完整配置架构和所有选项请见：references/configuration.md。客户端传输方式详解请见：references/clients.md。

第 3 步：生成

通过 package.json 脚本运行（不要临时直接运行），以确保可重复：

// package.json
"scripts": { "gen:api": "openapi-ts" }

npm run gen:api 会读取 openapi-ts.config.ts。一次性 CLI 命令格式为 npx @hey-api/openapi-ts -i <input> -o <output> -c @hey-api/client-fetch。

第 4 步：使用 SDK

每个操作都会生成一个类型化异步函数；默认情况下，函数会解析为 { data, error } 结果（不会抛出异常）。参数放在一个选项对象中（path / query / body / headers）：

const { data, error } = await getItem({ path: { id: 1 } });
if (error) { /* typed error */ } else { /* typed data */ }

设置 throwOnError: true（可按调用设置，也可在客户端配置中设置），即可让函数改为抛出异常。通过客户端配置设置一次基础 URL，详见 references/clients.md。

第 5 步：使用生成的 TanStack Query hooks + Zod schemas

@tanstack/react-query 插件会生成 <op>Options()、<op>QueryKey()、<op>InfiniteOptions() 和 <op>Mutation() 辅助函数，供你展开传入 TanStack Query——详见 references/plugins-query-zod.md。查询、变更和缓存模式本身请参考 tanstack-query 技能。zod 插件会生成用于边界验证的 schemas（位于同一文件中）。

第 6 步：FastAPI operationId 与重新生成/偏差检查工作流

FastAPI 默认的 operationId 会生成不美观的方法名（createItemItemsPost）。使用 generate_unique_id_function 从源头修复——详见 references/fastapi-regen.md，其中还介绍了变更时重新生成脚本、CI 偏差检查，以及提交生成文件还是加入 gitignore 的取舍。

规则

硬性规则（绝不违反）：

• 绝不手动编辑生成文件。 每次重新生成时都会覆盖这些文件。请通过配置／插件进行自定义，或封装 SDK，切勿修改 src/client。
• OpenAPI 契约是唯一依据。 契约变更时应重新生成；不要让生成的客户端偏离规范（通过 CI 偏差检查确保这一点）。
• 固定生成器版本（在 package.json 中使用 -E／精确版本）。hey-api 尚未达到 1.0（目前为 0.x），迭代很快；不固定版本可能导致输出发生变化。设置时请确认当前版本。
• 生成代码，不要手写。 如果你正根据规范手动编写 API 类型或 fetch 封装，请停下来并改用生成方式。

偏好（可覆盖）：

• 默认使用 fetch 客户端，除非项目统一使用 axios，或这是一个 Next.js 应用。
• 保留 { data, error } 结果风格（显式处理错误），除非某一层需要 throwOnError。
• 在 package.json 脚本和 CI 中运行代码生成，而不是让每台机器临时运行。

注意事项

• 客户端已随生成器打包提供（v0.73.0+）——无需单独安装。 只需将客户端添加到 plugins 中（fetch 是默认选项，因此这一步也可以省略）。如果你接手的是 0.73 之前的配置，且安装了 @hey-api/client-*，可以移除这些依赖后重新生成。（这是不同的概念：客户端可以将其代码内联到生成的输出中——这是一个输出选项，与安装无关。）
• FastAPI 的 operationId 冗长。 如果没有设置 generate_unique_id_function，名称会类似 createItemItemsPost。请在 FastAPI 端修复，这样每次重新生成的结果都会干净整洁（references/fastapi-regen.md）。
• SDK 函数默认不会抛出异常。 它们会解析为 { data, error }；如果代码使用 try/catch，却从不检查 error，就会悄无声息地忽略失败。若需要抛出异常，请使用 throwOnError: true。
• OpenAPI 3.0 与 3.1。 hey-api 面向 3.1（FastAPI ≥ 0.99）。仅支持 3.0 的文档，或过时的代码生成思路（openapi-typescript-codegen 是 hey-api 能胜任的旧工具），都会导致错误假设——请使用当前工具处理 3.1 规范。
• 从运行中的服务生成，还是从保存的规范生成。 使用 URL 作为输入时，生成期间服务必须处于运行状态，且 API 变更时会静默重新生成；提交规范文件可确保结果可复现，但必须主动更新。请根据 references/fastapi-regen.md 中的偏差策略进行选择。

反模式

• “我只改一下生成的类型。” 不行——下次重新生成时会被覆盖。请修改规范或封装生成结果。
• “我手写客户端会更快。” 它会立即偏离契约；生成正是为了解决这个问题。
• “提交生成的客户端，然后就不管了。” 如果没有 CI 偏差检查，客户端会在不知不觉中与 API 脱节。请添加重新生成并执行 git diff --exit-code 的门禁。
• “我也在这里记录一下查询缓存／失效的内容。” 这是 tanstack-query 技能的职责；本技能只负责生成钩子。

输出

在配置的 output 目录下生成类型化客户端——包括模型、类型化 SDK，以及（根据插件配置）TanStack Query 钩子和 Zod 模式——此外还有 openapi-ts.config.ts、gen:api 脚本，以及（推荐添加的）CI 偏差检查。使用方是前端代码（及其测试／CI），它们通过生成的 SDK 和钩子调用 API。

相关内容

• tanstack-query——查询／变更／缓存的使用；本技能负责生成它所使用的钩子。
• fastapi / pydantic-v2——提供本技能读取的 OpenAPI 契约的后端。
• vite——生成的客户端通常随之发布的 SPA 构建工具。

渐进式披露

• references/configuration.md — 编写 openapi-ts.config.ts 时加载：完整的 input/output/plugins 架构、选项、CLI 标志、package.json 接线方式。
• references/clients.md — 选择或配置传输方式时加载：深入介绍 fetch/axios/next（及其他方式）、运行时配置（setConfig、createClientConfig、单次调用配置）、基础 URL，以及客户端代码的 bundle 选项。
• references/plugins-query-zod.md — 接入生成的 TanStack Query 钩子或 Zod 架构时加载：生成的导出项命名与用法，以及如何衔接 tanstack-query 技能。
• references/fastapi-regen.md — 与 FastAPI 集成或设置再生成流程时加载：operationId 修复、再生成脚本、CI 漂移检查，以及提交还是加入 gitignore。
• references/sources.md — 研究来源与事实核查备注。

正文篇幅限制

• description ≤ 1,024 个字符；正文 ≤ 约 500 行 / 5,000 个 token；较长内容放在 references/ 中。