Kitex命令行工具

2024-01-16T14:21:02+08:00 | 4分钟阅读 | 更新于 2024-01-16T14:21:02+08:00

@ MoonlightMaze

一、概述

基本语法：

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

三、全量参数一览

参数	类型	默认值	说明
`-module`	string	(自动探测)	Go module 名，决定生成代码的 import path
`-service`	string	`""`	服务名；指定后生成带脚手架的完整服务端项目
`-use`	string	`""`	复用已有的 `kitex_gen` 包路径，不再重新生成该目录
`-type`	string	`"thrift"`	IDL 类型：`thrift` 或 `protobuf`
`-I`	repeated	`[]`	IDL 搜索路径（支持多次指定，支持 git 仓库拉取）
`-gen-path`	string	`"kitex_gen"`	生成代码的输出目录
`-thrift`	repeated	`[]`	透传给 thriftgo 的参数，拼在 `-g go:` 后
`-protobuf`	repeated	`[]`	透传给 protoc 的参数，拼在 `--go_out` 后
`-combine-service`	bool	false	合并 IDL 中所有 service 为一个 CombineService
`-copy-idl`	bool	false	将 IDL 文件拷贝到输出目录
`-no-fast-api`	bool	false	关闭 FastAPI/Thrift 高性能编解码优化
`-invoker`	bool	false	生成 Invoker 端代码（Server SDK 化）
`-record`	bool	false	记录本次命令到 `kitex-all.sh`，方便批量重新执行
`-no-recurse`	bool	false	不递归生成 include 的文件
`-template-dir`	string	`""`	自定义模板目录
`-compiler-path`	string	`""`	自定义 thriftgo/protoc 编译器路径
`-verbose` / `-v`	bool	false	详细日志输出
`-gen-frugal`	bool	false	配合 IDL 注解为指定结构体启用 Frugal 编解码
`-frugal_struct`	repeated	`[]`	直接指定启用 Frugal 编解码的结构体名
`-protobuf-plugin`	string	`""`	接入 protoc 插件生态（如 validator）

四、核心参数详解

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服务注册与发现

下一页 Kitex配置