AI 原生开放教材

外观

Coze Loop 源码研读源码研读·中英混排原文 ↗仓库 ↗

IDL 变更与代码生成流程 ​

本文档描述修改 Thrift IDL 后，前后端代码如何同步更新。

IDL 目录结构 ​

idl/thrift/
├── base.thrift                    # 公共基础类型
├── extra.thrift                   # 扩展类型
├── trajectory.thrift              # 轨迹类型
└── coze/loop/
    ├── apis/                      # API 接口定义
    ├── data/                      # 数据模块类型
    ├── evaluation/                # 评测模块类型
    ├── foundation/                # 基础能力类型
    ├── llm/                       # LLM 模块类型
    ├── observability/             # 可观测性类型
    └── prompt/                    # Prompt 模块类型

变更流程 ​

1. 修改 IDL 文件 ​

在 idl/thrift/ 下修改对应的 .thrift 文件。

2. 后端代码生成 ​

bash
cd backend

# Kitex (RPC) 代码生成
bash script/cloudwego/kitex_tool.sh

# Hertz (HTTP) 代码生成
bash script/cloudwego/hertz_tool.sh

# 通用代码生成
bash script/cloudwego/code_gen.sh

生成产物:

  • backend/kitex_gen/ — Kitex/Thrift 生成的 Go 代码（勿手动修改）
  • backend/loop_gen/ — 其他生成代码（勿手动修改）
  • backend/api/router_gen.go — 路由生成代码（勿手动修改）

3. 前端类型生成 ​

前端通过 frontend/infra/idl/ 工具将 Thrift IDL 转换为 TypeScript 类型定义。

生成产物进入 frontend/packages/loop-base/api-schema/。

4. Wire 依赖注入（如需） ​

如果 IDL 变更导致新增了服务接口，需更新对应模块的 Wire 定义:

bash
cd backend/modules/<domain>/application
wire

生成产物: wire_gen.go（勿手动修改）

5. GORM 模型生成（如需） ​

如果涉及数据库 schema 变更:

bash
cd backend
# 使用 gorm_gen 脚本

6. 错误码生成（如需） ​

bash
cd backend
# 使用 errorx 脚本

CI 检查 ​

  • IDL 变更会触发 .github/workflows/idl.yaml CI 工作流
  • 数据库 schema 变更触发 .github/workflows/mysql-schema-check.yaml

注意事项 ​

  • 所有 *_gen.go、kitex_gen/、loop_gen/ 文件均为自动生成，禁止手动修改
  • IDL 变更后必须同时更新前后端生成代码，保持契约一致
  • 生成结果需要提交到仓库（不在 .gitignore 中）