Kitex命令行工具

学习目标

类比（先建立直觉）：kitex 命令行工具就像"代码生成器工厂的订货单"——你给它一份 IDL（接口说明书）和几个参数（模块名、服务名…），它就吐出一套能直接编译运行的 RPC 桩代码和服务端骨架。读懂这张"参数清单"，你就能按需定制生成结果，而不是每次都照抄别人的命令。

学完本章你应该能够：

1. 说出 kitex 的基本语法与安装方式（含 thriftgo / protoc 前置依赖）。
2. 讲清 -module、-service、-use、-I、-type 等核心参数的作用与典型用法。
3. 根据"多服务共享桩代码"“多 IDL 批量生成"等真实场景，选对 -use / -record 等进阶参数。
4. 看懂生成产物目录结构，知道 handler.go / client.go / server.go 各自该填什么。
5. 把"定义 IDL → 生成 → 填业务 → 启动 → 调用"串成一条可复用的标准工作流。

前置知识：

• Go module 基本机制（go.mod、import path）
• Thrift / Protobuf IDL 基本语法
• Kitex 框架的服务端 / 客户端基本用法

本章你会动手做的事：

1. 安装 kitex 与 thriftgo，对一份示例 echo.thrift 跑出完整服务端骨架。
2. 用 -use 让两个服务共享同一份 kitex_gen，体会"复用桩代码"的场景。
3. 用 -record 记录多条命令，之后用一条 sh kitex-all.sh 重新生成全部代码。

一、概述

基本语法：

kitex [options] xxx.thrift/xxx.proto

二、安装

# 先安装 IDL 编译器（二选一或都装）
go install github.com/cloudwego/thriftgo@latest    # thrift 编译器
# protoc 需从 GitHub Release 下载放到 $PATH

# 安装 kitex 工具本身
go install github.com/cloudwego/kitex/tool/cmd/kitex@latest

# 验证
kitex --version

三、全量参数一览

四、核心参数详解

4.1 -module — Go Module 名

决定生成的 go.mod 和所有代码中的 import path。

• 在 $GOPATH/src 下可不指定，自动推算
• 在 $GOPATH/src 外必须指定
• 会向上搜索 go.mod：不存在则自动 go mod init；存在则校验一致性，不一致报错退出

kitex -module github.com/my/demo echo.thrift

4.2 -service — 生成服务端脚手架

加上此参数后，除 kitex_gen/ 外，还会生成可直接运行的 Server 骨架：

├── build.sh # 快速构建脚本
├── handler.go # 业务逻辑填充入口
├── kitex_info.yaml # 元信息（集成 cwgo 用）
├── main.go # Server 启动入口
├── script/
│   └── bootstrap.sh
└── kitex_gen/
    └── ...

kitex -module github.com/my/demo -service mydemoservice demo.thrift

4.3 -use — 复用 kitex_gen

场景：多个服务共享同一个 IDL 生成的桩代码。第一次生成 kitex_gen，后续服务通过 -use 指向它，不再重复生成。

# 第一步：生成公共桩代码
kitex -module example_shop idl/item.thrift
# 生成到 kitex_gen/

# 第二步：item 服务复用
cd rpc/item
kitex -module example_shop -service example.shop.item -use example_shop/kitex_gen ../../idl/item.thrift

4.4 -I — IDL 搜索路径

支持本地路径和远程 Git 仓库：

# 本地路径（可多次指定）
kitex -module demo -I ./idl -I ./common idl/user.thrift

# 远程 Git 仓库 + 指定分支
kitex -module xx -I git@github.com/org/repo.git@develop abc/xxx.thrift

4.5 -type — IDL 类型

# thrift（默认）
kitex -module demo -service myservice echo.thrift

# protobuf（必须显式指定）
kitex -module demo -type protobuf -service myservice myservice.proto

protobuf 注意事项:

• 仅支持 proto3
• go_package 必须定义，且路径必须匹配 kitex_gen 后缀
• 可通过 –protobuf Msome.proto=your/package/kitex_gen/xxx 覆盖单个文件的 go_package

4.6 -combine-service — 合并多 Service

thrift IDL 中定义了多个 service 时，kitex 默认只对最后一个生成代码。加此参数后合并所有 service 为一个 CombineService。

kitex -module demo -service mysvc -combine-service api.thrift

要求所有 service 的方法名不冲突。

4.7 -thrift / -protobuf — 透传编译器参数

# 传给 thriftgo 的参数
kitex -module demo -thrift "no_default_serdes" echo.thrift

# 传给 protoc 的参数
kitex -module demo -type protobuf -protobuf "Mproto/user.proto=github.com/my/demo/kitex_gen/proto/user" user.proto

kitex 对 thrift 默认传递了：naming_style=golint,ignore_initialisms,gen_setter,gen_deep_equal，可通过此参数覆盖。

4.8 -record — 批量命令记录

多次执行带 -record 的命令后生成 kitex-all.sh，之后一条脚本即可重新生成所有代码：

kitex -module demo -service mysvc -record api.thrift
kitex -module demo -record user.thrift
kitex -module demo -record order.thrift

# 之后只需执行
sh kitex-all.sh

记录规则：只保留一条 -service 命令，同 IDL 路径覆盖，新 IDL 路径追加。

4.9 -no-fast-api — 关闭高性能优化

kitex 默认对 thrift binary 协议和 protobuf 生成 FastAPI 编解码优化。若需关闭：

kitex -module demo -no-fast-api echo.thrift

4.10 -protobuf-plugin — 接入 protoc 插件

格式：plugin_name:options:out_dir

# 接入 protoc-gen-validator 插件
kitex -type protobuf \
  -protobuf-plugin "validator:module=toutiao/middleware/kitex,recurse=true:." \
  myservice.proto

五、生成产物结构

# 无 -service（仅桩代码）

kitex_gen/
├── {package}/
│   ├── {idl_name}.go       # thriftgo/protoc 生成的类型定义
│   ├── k-{idl_name}.go     # kitex 序列化优化
│   └── k-consts.go
└── {service_name}/
    ├── client.go           # NewClient API
    ├── server.go           # NewServer API
    ├── invoker.go          # Server SDK 化 API
    └── {service_name}.go   # 共用定义

# 有 -service（含脚手架）

├── build.sh
├── handler.go              # 在这里实现业务逻辑
├── kitex_info.yaml
├── main.go                 # 直接 go run 启动
├── script/
│   └── bootstrap.sh
└── kitex_gen/              # 桩代码（同上）

六、典型工作流

# 1. 定义 IDL：echo.thrift
# 2. 生成代码
kitex -module github.com/my/echo -service echo echo.thrift

# 3. 在 handler.go 中填充业务逻辑
# 4. 启动服务
go run main.go
# 默认监听 8888

# 5. 其他服务调用
# 使用 kitex_gen 下的 NewClient 发起 RPC

对于多个 IDL 文件的项目：

kitex -module example_shop -service example.shop.item -record idl/item.thrift
kitex -module example_shop -service example.shop.stock -record idl/stock.thrift
# 更新时执行 sh kitex-all.sh 即可

本章小结

• 基本形态：kitex [options] xxx.thrift/xxx.proto，核心是把 IDL 翻译成 Go 桩代码与服务端脚手架。
• 核心参数：-module 决定 import path、-service 决定是否生成可运行骨架、-use 复用已有 kitex_gen、-I 指定 IDL 搜索路径、-type 切换 thrift / protobuf。
• 进阶技巧：-combine-service 合并多 service、-record 沉淀批量生成脚本、-no-fast-api 关闭高性能编解码、-protobuf-plugin 接入 protoc 插件生态。
• 产物结构：无 -service 只生成 kitex_gen/ 桩代码；带 -service 额外生成 handler.go / main.go 等可直接 go run 的骨架。
• 标准工作流：定义 IDL → kitex 生成 → 在 handler.go 填业务 → go run main.go 启动 → 用 kitex_gen 的 NewClient 调用。

掌握命令行只是第一步，下一章我们会把这些生成出来的代码真正接进服务治理与可观测性体系。