Kubb：OpenAPI一键生成类型安全的前端代码

Kubb 是一个基于插件架构的元框架，能把 OpenAPI/Swagger 规范自动转换为类型安全的 TypeScript 类型、axios/fetch 客户端、TanStack Query 与 SWR hooks、Zod 校验器、Faker 模拟数据和 MSW 处理器。它支持 OpenAPI 2.0/3.0/3.1，可自由组合插件、按标签分组输出，并提供 MCP 服务器让 AI 工具直接驱动代码生成，是前后端协作提效的利器。

适用人群：1. 使用 OpenAPI/Swagger 规范的前后端团队，尤其是需要频繁同步接口类型的前端开发者；2. 采用 React、Vue、Svelte、Solid 等框架并搭配 TanStack Query、SWR、Zod 的技术团队；3. 希望构建自定义代码生成插件或探索 AI 辅助开发（MCP）的高级工程师与工具链维护者。

适用场景：1. 前端项目根据后端 OpenAPI 文档自动生成类型定义、请求客户端和数据校验逻辑，避免手写接口类型；2. 在 React/Vue 项目中一键生成 TanStack Query 或 SWR 的 hooks，并配合 MSW/Faker 生成测试与模拟数据，加速开发与联调；3. 通过 MCP 服务器让 Claude 等 AI 工具直接调用 Kubb 生成代码，实现 AI 驱动的接口对接与脚手架搭建。

推荐理由：Kubb 用插件化引擎把 OpenAPI 到前端代码的链路彻底标准化，覆盖类型、客户端、hooks、校验、Mock 全流程，且支持多框架与 AI 工具集成。相比手写或单一用途的生成器，它更灵活、可扩展，能显著减少重复劳动和类型错误，是前端工程化值得投入的基础设施。

项目定位与背景

在前后端分离的开发模式中，OpenAPI/Swagger 规范已成为接口描述的事实标准。然而，从规范到前端可用的类型、请求客户端、数据校验和 Mock 数据，往往需要大量手工转换或依赖多个零散工具。Kubb 正是为解决这一痛点而生，它把自己定位为代码生成的元框架，核心思路是：指向一份 schema，就能产出类型、客户端、hooks、校验器、Mock 等全套前端资产。项目由 kubb-labs 维护，采用 TypeScript 编写，目前在 GitHub 上已获得近 1800 颗星，拥有活跃的插件生态和文档站点。

核心功能与技术架构

Kubb 的架构围绕插件化引擎展开。它首先通过适配器读取 OpenAPI 2.0、3.0 和 3.1 规范，官方提供 @kubb/adapter-oas 适配器，并支持 Node.js 与 Bun 运行时。解析后的中间模型交由一系列插件处理，每个插件负责一种输出：plugin-ts 生成 TypeScript 类型，plugin-axios 和 plugin-fetch 生成类型安全的请求客户端，plugin-react-query、plugin-vue-query、plugin-swr 生成对应框架的数据请求 hooks，plugin-zod 生成校验器，plugin-faker 生成模拟数据，plugin-msw 生成 Mock Service Worker 处理器，此外还有 plugin-cypress、plugin-redoc、plugin-mcp 等。用户只需在 kubb.config.ts 中声明所需插件，即可组合出完全定制化的生成流水线。客户端生成支持状态码分键结果、鉴权、校验、文件上传、服务器推送事件、拦截器以及可替换的传输层，输出可以按标签分组文件、按操作包含或排除，并能写入磁盘、内存或自定义存储后端。

创新点与亮点

Kubb 最大的创新在于其元框架与插件作者工具包 kubb/kit 的设计。开发者不仅能使用官方插件，还能基于 kit 构建自己的插件、生成器、适配器和渲染器，甚至提供了 JSX 渲染器用于组件化输出，这大幅降低了扩展门槛。另一个亮点是与构建工具的深度集成：unplugin-kubb 让生成过程可以直接跑在 Vite、Nuxt、Astro、webpack 等打包流程中，实现开发时的实时生成。最引人注目的是内置的 MCP 服务器，它允许 Claude 等 AI 工具通过 Model Context Protocol 直接驱动 Kubb 进行代码生成，把 AI 辅助开发从对话延伸到了实际的工程产出。此外，项目还提供 npx kubb init 向导，自动创建配置文件、引导插件选择并安装依赖，上手体验相当顺滑。

与同类项目对比

市面上常见的方案如 openapi-typescript 专注于生成类型，orval 能生成客户端和 hooks，但它们通常是单一工具、配置相对固定，扩展性有限。Kubb 的差异在于把生成能力拆解为可插拔的插件，用户按需组合，避免了引入不需要的代码。同时它覆盖的框架和输出类型更广，从 React、Vue、Svelte、Solid 到 SWR、Zod、Faker、MSW，几乎覆盖了前端数据层的全部环节。与纯 AI 代码生成工具相比，Kubb 基于确定性的 schema 解析，产出稳定可复现，而 MCP 集成又让它能融入 AI 工作流，兼顾了确定性与智能化。

上手指南或快速开始

使用 Kubb 非常简单。首先通过 bun add kubb、pnpm add kubb 或 npm install kubb 安装核心包，然后运行 npx kubb init 启动向导，它会按需创建 package.json、引导选择插件、安装依赖并生成 kubb.config.ts。配置完成后，执行 npx kubb generate 即可生成代码。官方文档站点 kubb.dev 提供了详细的插件说明和高级用法，建议从 plugin-ts 和 plugin-axios 开始，逐步加入 react-query、zod、msw 等插件，体验按需组合的灵活性。

总结与展望

Kubb 以插件化元框架的定位，把 OpenAPI 到前端代码的转换做成了一个可扩展、可组合、可集成 AI 的工程化平台。它的优势在于覆盖面广、扩展性强、上手友好，尤其适合接口频繁变动、追求类型安全的前端团队。需要注意的是，插件组合的灵活性也带来一定的学习成本，初次配置可能需要理解各插件职责；同时生成代码的质量高度依赖 schema 的规范性。总体而言，Kubb 是当前代码生成领域极具潜力的项目，随着 MCP 与 AI 工作流的普及，它有望成为前端数据层自动化的关键基础设施。

查看 GitHub 项目 →