kubb

一行命令，告别手写 API 类型：Kubb 代码生成工具

痛点场景

想象你正在开发一个前后端分离的项目。后端工程师刚刚更新了 API，新增了 UserProfile 字段并改了 orderId 的类型。前端开发者面对这个变更，需要手动搜索接口文档、逐字敲入 TypeScript 类型定义、调整请求函数——一个字段改动可能牵动十几个文件，还极易漏改、错改。

更糟糕的是，你可能同时需要：

• TypeScript 前端调用的类型定义
• Zod 运行时验证 schema
• React Query / SWR 数据获取 hooks
• Faker.js Mock 数据用于本地调试
• MSW（Mock Service Worker）在测试环境拦截请求

这些工具各自独立，维护多套 schema 是噩梦，维护同步更是噩梦中的噩梦。Kubb 正是为了终结这场混乱而生。

背景与起源

Kubb（瑞典语"积木"之意）是一个由 stijnvanhulle 主导开发的开源 TypeScript 代码生成框架，托管于 kubb-labs/kubb 仓库，目前在 GitHub 获得约 1738 颗星、297 个 fork，收到了来自全球 TypeScript 开发者的积极反馈。

项目诞生于作者在实际项目中深受 API 类型不同步之苦。传统的 OpenAPI→SDK 流水线要么过于笨重，要么只能生成单一目标语言的代码，难以满足现代前端复杂的技术栈需求。 Kubb 从一开始就定位为插件化、可扩展的元框架，让任何人都可以基于其核心引擎编写新的生成器插件。

核心功能解析

1. OpenAPI 驱动的类型安全

Kubb 的数据源是 OpenAPI 规范（支持 OpenAPI 3.x 和 Swagger 2.0）。只需一条命令：

npx @kubb/cli generate

Kubb 会根据配置的插件，自动生成以下产物：

插件	生成内容
@kubb/plugin-ts	TypeScript 类型定义（请求/响应/模型）
@kubb/plugin-zod	Zod 运行时验证 schema
@kubb/plugin-client	Axios/Fetch 原生请求客户端
@kubb/plugin-react-query	TanStack Query（React Query）hooks
@kubb/plugin-swr	SWR hooks
@kubb/plugin-faker	Faker.js Mock 数据
@kubb/plugin-msw	MSW 请求拦截处理器
@kubb/plugin-zodios	Zodios 类型安全 HTTP 客户端

生成的代码与 OpenAPI 规范保持实时同步——API 改动后，重新运行命令即可更新所有类型和 mock 数据，彻底消除"文档和代码不一致"的问题。

2. 插件化架构与 AST 层

Kubb 背后是一套精心设计的插件驱动引擎，核心位于 @kubb/core。其工作流如下：

OpenAPI 规范文件 (YAML/JSON)
        ↓
@kubb/adapter-oas  (将 OpenAPI 转换为统一 AST)
        ↓
@kubb/core 核心引擎 (遍历 AST 节点，调度各插件)
        ↓
各插件 Renderer (将 AST 节点渲染为目标代码)
        ↓
输出 TypeScript/Zod/React Query... 文件

这种架构的优势在于：插件之间互不干扰，新语言/框架的支持只需要实现一个新的插件，无需改动核心引擎。官方维护的插件生态涵盖前端主流框架（React、Vue、Solid、Svelte）和工具链（MSW、Faker、Zod）。

3. MCP 服务器：AI 时代的代码生成

Kubb 包含 @kubb/mcp 包，通过 Model Context Protocol（MCP）暴露代码生成能力。这意味着 Claude、Cursor、Windsurf 等支持 MCP 的 AI 助手可以直接调用 Kubb，在对话中实时生成或更新 API 类型，无需切换到终端。开发者可以在 AI 辅助编程环境中直接享受 Kubb 的类型安全红利。

技术架构一览

Kubb 采用 monorepo + pnpm workspaces + Turborepo 架构，仓库包含 11 个核心包：

packages/
  core/          # 插件驱动引擎、文件管理、build 编排
  ast/           # AST 定义层（与 parser 解耦）
  parser-md/     # Markdown parser（支持 mdx 文件解析）
  parser-ts/     # TypeScript parser
  adapter-oas/   # OpenAPI 规范 → AST 适配器
  cli/           # 命令行入口
  kubb/          # 主包（整合所有插件的默认集）
  mcp/           # Model Context Protocol 服务器
  renderer-jsx/   # JSX 文件渲染器（React/Vue/Solid/Svelte）
  plugin-barrel/ # Barrel 文件（index.ts 导出聚合）
  unplugin-kubb/ # Vite/Rspack Rollup 插件集成

开发工具链：Node.js >= 22、Vitest（测试）、tsdown（打包）、oxlint（代码检查）、Changesets（版本发布）、GitHub Actions（CI/CD）。

上手门槛与安装

Kubb 定位为开发者工具，上手门槛适中。以下是三种典型使用方式：

方式一：快速试用（无需安装）

npx @kubb/cli init my-api-types
cd my-api-types
npx @kubb/cli generate

方式二：项目集成（推荐）

pnpm add @kubb/cli @kubb/plugin-ts @kubb/plugin-zod @kubb/plugin-client

然后在项目根目录创建 kubb.config.ts 配置文件即可。

方式三：AI 助手集成（MCP）

在 Claude Desktop 或 Cursor 中配置 MCP 服务器，AI 即可在对话中直接调用 Kubb 生成代码，无需切换到终端。

硬件需求：Kubb 是纯 Node.js CLI 工具，不需要 GPU，内存占用极低（512MB 足够），磁盘约 200MB。

局限与争议

1. 严重依赖 OpenAPI 规范质量：如果上游 OpenAPI 文档不规范（缺少响应类型、参数描述缺失），生成代码质量会大打折扣，维护规范的团队成本不低。

2. TypeScript 强绑定：尽管 Kubb 面向多种前端框架，但生成目标均是 TypeScript，不支持 Flow 或原生 JavaScript 项目。

3. 无官方 Docker 支持：Kubb 官方未提供 Dockerfile 或 docker-compose.yml，对于需要在容器化环境中运行的用户，需要自行编写构建步骤。

4. monorepo 复杂度：11 个内部包的依赖关系对外部贡献者有一定学习成本。

行业意义

在 AI 辅助编程时代，类型安全已经从"加分项"变成"基础设施"。Kubb 将这一基础设施的维护成本降到最低——一次规范定义，全链路代码生成。它代表了一种趋势：让机器处理重复性代码，让开发者聚焦业务逻辑。

结合 MCP 协议的支持，Kubb 正在成为 AI 时代 API 开发流水线的关键节点——AI 读取 OpenAPI 规范，调用 Kubb 生成类型，开发者确认后直接使用，整个流程无需人工干预。

项目地址：https://github.com/kubb-labs/kubb 官网：https://kubb.dev 维护者：stijnvanhulle（活跃维护中，open issues 仅 4 个）