Go-Zero 可以自动生成 Swagger 文档，然后你可以用工具根据文档自动生成前端的 API 请求代码

作者
254 次阅读

本文最后更新于 2026年5月19日。

Go-Zero 可以自动生成 Swagger 文档，然后你可以用工具根据文档自动生成前端的 API 请求代码。这样 AI 连接口请求都不用写，直接调用生成的函数即可 这个是认真的吗，这么智能？怎么自动生成前端api请求代码

这是非常认真的，也是目前工业级开发（尤其是 2026 年 AI 辅助编程时代）最推荐的**“契约优先”**模式。

这种方式的智能之处在于：它把“接口文档”变成了“可执行代码”。你不再需要手动在前端写 axios.post('/api/user/login', ...)，所有的请求函数、入参类型、返回类型都是全自动生成的。

以下是实现这一过程的三个具体步骤：

第一步：后端生成“契约” (OpenAPI/Swagger)

在 Go-Zero 中，你编写的是 .api 定义文件（DSL）。这个文件描述了所有的接口路径、请求参数和响应结构。

  1. 编写 .api 文件：

    Go

    // translation.api
type TranslateReq {
    FileID string `json:"fileId"`
    Target string `json:"target"`
}
service translation-api {
    @handler TranslateHandler
    post /v1/translate (TranslateReq) returns (TranslateResp)
}

  2. 一键导出 Swagger：使用 goctl 工具，一行命令直接把这个定义转成标准的 swagger.json 或 openapi.yaml 文件。

    Bash

    goctl api plugin -plugin goctl-swagger="swagger -filename translation.json" -api translation.api -dir .

第二步：前端“捡现成” (自动生成请求代码)

拿到 translation.json 后，前端不需要手动写代码，而是使用工具（如 openapi-generator 或 hey-api）直接生成 TypeScript 客户端代码。

  • 如果你用 Vue/React：你可以使用 openapi-typescript-codegen 或针对特定框架的工具。

  • 生成效果：工具会为你生成一个 TranslationService.ts 文件，里面长这样：

    TypeScript

    // 这是自动生成的，AI 和你都不用写！
export class TranslationService {
  static postV1Translate(requestBody: TranslateReq): CancelablePromise<TranslateResp> {
    return __request(OpenAPI, {
      method: 'POST',
      url: '/v1/translate',
      body: requestBody,
    });
  }
}

第三步：AI 的角色（真正的魔法）

当你完成了前两步，AI 的工作方式就变了：

  1. 上下文对齐：你把生成的 TranslationService.ts 喂给 AI（或者它在你的项目上下文中已经读到了）。

  2. 指令进化：

    • 以前：“帮我写个翻译按钮，点击后发请求给 /api/v1/translate，参数是文件 ID…” (AI 可能会写错 URL，或者参数名拼错)。

    • 现在：“帮我写个翻译按钮，调用 TranslationService.postV1Translate 函数。”

  3. 智能感应：由于生成的代码带完整的 TypeScript 类型定义，AI 在写代码时会自动补全 fileId 和 target，如果参数传错了，编辑器会直接飘红报错。

为什么这能防止“功能污染”？

  1. 类型安全隔离：每个功能模块都有自己独立生成的 API 类（如 UserService、FileService）。AI 在写翻译功能时，它调用的函数是强类型绑定的，它无法随意捏造不存在的接口。

  2. 物理隔离：所有的请求逻辑都在 generated/ 文件夹下。如果你修改了后端的 .api 文件并重新生成，只会更新这个文件夹，不会动到你手写的 UI 业务逻辑代码。

  3. 单向流动：

    • 修改后端定义 -> 重新生成前端 API -> AI 根据新函数改 UI。

    • 这种流程下，API 永远是最新且准确的。

总结工具链推荐：

  • 后端生成器：goctl (Go-Zero 官方工具)

  • 前端代码生成：

    • 轻量级：openapi-typescript (生成类型定义)

    • 功能全：@hey-api/openapi-ts (2026 年最流行的前端 Client 生成工具)

    • React/Vue 深度集成：@tanstack/query-codegen (连请求后的缓存逻辑 useQuery 都帮你写好了)

这种开发模式在目前被戏称为**“程序员只负责定义，AI 负责填肉”**。你准备好尝试这种“契约驱动”的开发流程了吗？