gojsj2025/backend/docs/gozero/goctl.md

文件风格 概述 ​ goctl 生成代码支持对文件和文件夹的命名风格进行格式化，可以满足不同开发者平时的阅读习惯，不过在 Golang 中，文件夹和文件命名规范推荐使用全小写风格，详情可参考 Go Style。

格式化符号 ​ 在 goctl 代码生成中，可以通过 go 和 zero 组成格式化符号来格式化文件和文件夹的命名风格，如常见的风格格式化符号如下：

lowercase: gozero camelcase: goZero snakecase: go_zero 格式化符号表参考 ​ 假设我们有一个源字符串 welcome_to_go_zero，其参考格式化符号表如下：

格式化符号 格式化后的字符串 说明 gozero welcometogozero lower case goZero welcomeToGoZero camel case gozero welcome_to_go_zero snake case Go#zero Welcome#to#go#zero 自定义分隔符，如分割符 # GOZERO WELCOMETOGOZERO upper case _go#zero welcome#to#go#zero 前缀、后缀及自定义分割符，这里使用 _ 作为前缀和后缀，使用 # 作为分割符 非法格式化符号 go gOZero zero goZEro goZERo goZeRo foo 使用 ​ 格式化符号是在 goctl 代码生成时使用的，由 style 参数来对格式化符进行控制，如：

生成 lower case 文件和目录示例

$ goctl api new demo --style gozero

生成 snake case 文件和目录示例

$ goctl api new demo --style go_zero

生成 camel case 文件和目录示例

$ goctl api new demo --style goZero

goctl api 概述 ​ goctl api 是 goctl 中的核心模块之一，其可以通过 .api 文件一键快速生成一个 api 服务，如果仅仅是启动一个 go-zero 的 api 演示项目， 你甚至都不用编码，就可以完成一个 api 服务开发及正常运行。在传统的 api 项目中，我们要创建各级目录，编写结构体， 定义路由，添加 logic 文件，这一系列操作，如果按照一条协议的业务需求计算，整个编码下来大概需要 5 ～ 6 分钟才能真正进入业务逻辑的编写， 这还不考虑编写过程中可能产生的各种错误，而随着服务的增多，随着协议的增多，这部分准备工作的时间将成正比上升， 而 goctl api 则可以完全替代你去做这一部分工作，不管你的协议要定多少个，最终来说，只需要花费 10 秒不到即可完成。

goctl api 指令 ​ $ goctl api --help Generate api related files

Usage: goctl api [flags] goctl api [command]

Available Commands: dart Generate dart files for provided api in api file doc Generate doc files format Format api files go Generate go files for provided api in api file kt Generate kotlin code for provided api file new Fast create api service plugin Custom file generator swagger Generate swagger file from api ts Generate ts files for provided api in api file validate Validate api file

Flags: --branch string The branch of the remote repo, it does work with --remote -h, --help help for api --home string The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority --o string Output a sample api file --remote string The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure

Use "goctl api [command] --help" for more information about a command. 参数字段 参数类型 是否必填 默认值 参数说明 branch string NO 空字符串 模板仓库分支，配合 --remote 使用 home string NO ~/.goctl 模板仓库本地路径，优先级低于 --remote o string NO 空字符串 输出 api 文件 remote string NO 空字符串 模板仓库远程路径 dart​ 根据 api 文件生成 dart 代码。

$ goctl api dart --help Generate dart files for provided api in api file

Usage: goctl api dart [flags]

Flags: --api string The api file --dir string The target dir -h, --help help for dart --hostname string hostname of the server --legacy Legacy generator for flutter v1 参数字段 参数类型 是否必填 默认值 参数说明 api string YES 空字符串 api 文件 dir string YES 空字符串 生成代码输出目录 hostname string NO go-zero.dev host 值 legacy boolean NO false 是否旧版本 doc​ 根据 api 文件生成 markdown 文档。

$ goctl api doc --help Generate doc files

Usage: goctl api doc [flags]

Flags: --dir string The target dir -h, --help help for doc --o string The output markdown directory 参数字段 参数类型 是否必填 默认值 参数说明 dir string YES 空字符串 api 文件所在目录 o string NO 当前 work dir 文档输出目录 format​ 递归格式化目录下的 api 文件。

$ goctl api format --help Format api files

Usage: goctl api format [flags]

Flags: --declare Use to skip check api types already declare --dir string The format target dir -h, --help help for format --iu Ignore update --stdin Use stdin to input api doc content, press "ctrl + d" to send EOF 参数字段 参数类型 是否必填 默认值 参数说明 declare boolean NO false 是否检测上下文 dir string YES 空字符串 api 所在目录 iu - - - 未使用字段，待移出 stdin boolean NO false 是否格式化终端输入的 api 内容 go​ 根据 api 文件生成 Go HTTP 代码。

$ goctl api go --help Generate go files for provided api in api file

Usage: goctl api go [flags]

Flags: --api string The api file --branch string The branch of the remote repo, it does work with --remote --dir string The target dir -h, --help help for go --home string The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority --remote string The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure --style string The file naming format, see [https://github.com/zeromicro/go-zero/blob/master/tools/goctl/config/readme.md] (default "gozero") 参数字段 参数类型 是否必填 默认值 参数说明 api string YES 空字符串 api 文件路径 branch string NO 空字符串 远程模板所在 git 分支名称，仅当 remote 有值时使用 dir string NO 当前工作目录 代码输出目录 home string NO ${HOME}/.goctl 本地模板文件目录 remote string NO 空字符串 远程模板所在 git 仓库地址，当此字段传值时，优先级高于 home 字段值 style string NO gozero 输出文件和目录的命名风格格式化符号，详情见 文件风格 new​ 快速生成 Go HTTP 服务，开发者需要在终端指定服务名称参数，输出目录为当前工作目录。

$ goctl api new --help Fast create api service

Usage: goctl api new [flags]

Examples: goctl api new [options] service-name

Flags: --branch string The branch of the remote repo, it does work with --remote -h, --help help for new --home string The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority --remote string The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure --style string The file naming format, see [https://github.com/zeromicro/go-zero/blob/master/tools/goctl/config/readme.md] (default "gozero") 参数字段 参数类型 是否必填 默认值 参数说明 branch string NO 空字符串 远程模板所在 git 分支名称，仅当 remote 有值时使用 home string NO ${HOME}/.goctl 本地模板文件目录 remote string NO 空字符串 远程模板所在 git 仓库地址，当此字段传值时，优先级高于 home 字段值 style string NO gozero 输出文件和目录的命名风格格式化符号，详情见 文件风格 温馨提示 goctl api new 需要一个终端参数来指定需要生成的服务名称，输出目录为当前工作目录，如 demo 服务生成的指令示例如下：

$ goctl api new demo plugin​ goctl api plugin 命令用于引用插件生成代码，开发者需要在终端指定插件名称、参数等信息。

$ goctl api plugin --help Custom file generator

Usage: goctl api plugin [flags]

Flags: --api string The api file --dir string The target dir -h, --help help for plugin -p, --plugin string The plugin file --style string The file naming format, see [https://github.com/zeromicro/go-zero/tree/master/tools/goctl/config/readme.md] 参数字段 参数类型 是否必填 默认值 参数说明 api string YES 空字符串 api 文件路径 dir string NO 当前工作目录 api 文件路径 plugin string YES 空字符串 插件可执行文件所在路径，支持本地和 http 文件 style string NO gozero 输出文件和目录的命名风格格式化符号，详情见 文件风格 插件资源请参考 goctl 插件资源

swagger​ 根据 api 文件生成 swagger 文档，详情可参考 swagger 生成

温馨提示 要求 goctl 版本大等于 1.8.3

goctl api swagger -h Generate swagger file from api

Usage: goctl api swagger [flags]

Flags: --api string The api file --dir string The target dir -h, --help help for swagger --yaml Generate swagger yaml file, default to json 参数字段 参数类型 是否必填 默认值 参数说明 api string YES 空字符串 api 文件路径 dir string NO 当前工作目录 输出目录 yaml bool NO false 输出 swagger 为 yaml 格式 ts​ 根据 api 文件生成 TypeScript 代码。

$ goctl api ts --help Generate ts files for provided api in api file

Usage: goctl api ts [flags]

Flags: --api string The api file --caller string The web api caller --dir string The target dir -h, --help help for ts --unwrap Unwrap the webapi caller for import --webapi string The web api file path 参数字段 参数类型 是否必填 默认值 参数说明 api string YES 空字符串 api 文件路径 dir string NO 当前工作目录 api 文件路径 caller string NO webapi web caller， plugin string YES 空字符串 插件可执行文件所在路径，支持本地和 http 文件 style string NO gozero 输出文件和目录的命名风格格式化符号，详情见 文件风格 validate​ 校验 api 文件是否符合规范。

goctl api validate --help Validate api file

Usage: goctl api validate [flags]

Flags: --api string Validate target api file -h, --help help for validate 参数字段 参数类型 是否必填 默认值 参数说明 api string YES 空字符串 api 文件路径

goctl rpc 概述 ​ goctl rpc 是 goctl 中的核心模块之一，其可以通过 .proto 文件一键快速生成一个 rpc 服务，如果仅仅是启动一个 go-zero 的 rpc 演示项目， 你甚至都不用编码，就可以完成一个 rpc 服务开发及正常运行。在传统的 rpc 项目中，我们要创建各级目录，编写结构体， 定义路由，添加 logic 文件，这一系列操作，如果按照一条协议的业务需求计算，整个编码下来大概需要 5 ～ 6 分钟才能真正进入业务逻辑的编写， 这还不考虑编写过程中可能产生的各种错误，而随着服务的增多，随着协议的增多，这部分准备工作的时间将成正比上升， 而 goctl rpc 则可以完全替代你去做这一部分工作，不管你的协议要定多少个，最终来说，只需要花费 10 秒不到即可完成。

goctl rpc 指令 ​ $ goctl rpc --help Generate rpc code

Usage: goctl rpc [flags] goctl rpc [command]

Available Commands: new Generate rpc demo service protoc Generate grpc code template Generate proto template

Flags: --branch string The branch of the remote repo, it does work with --remote -h, --help help for rpc --home string The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority --o string Output a sample proto file --remote string The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure

Use "goctl rpc [command] --help" for more information about a command. 参数字段 参数类型 是否必填 默认值 参数说明 branch string NO 空字符串 模板仓库分支，配合 --remote 使用 home string NO ~/.goctl 模板仓库本地路径，优先级低于 --remote o string NO 空字符串 输出 api 文件 remote string NO 空字符串 模板仓库远程路径 示例：生成 proto 文件

$ goctl rpc --o greet.proto goctl rpc new​ 快速生成一个 rpc 服务，其接收一个终端参数来指定服务名称。

$ goctl rpc new --help Generate rpc demo service

Usage: goctl rpc new [flags]

Flags: --branch string The branch of the remote repo, it does work with --remote -h, --help help for new --home string The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority --idea Whether the command execution environment is from idea plugin. --remote string The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure --style string The file naming format, see [https://github.com/zeromicro/go-zero/tree/master/tools/goctl/config/readme.md] (default "gozero") -v, --verbose Enable log output 参数字段 参数类型 是否必填 默认值 参数说明 branch string NO 空字符串 模板仓库分支，配合 --remote 使用 home string NO ~/.goctl 模板仓库本地路径，优先级低于 --remote idea bool NO false 仅 idea 插件用，终端请忽略此字段 remote string NO 空字符串 模板仓库远程路径 style string NO gozero 文件命名风格，详情可参考 文件风格 示例：

$ goctl rpc new greet goctl rpc protoc​ 根据 protobufer 文件生成 rpc 服务。

$ goctl rpc protoc --help Generate grpc code

Usage: goctl rpc protoc [flags]

  --branch string     The branch of the remote repo, it does work with --remote

-c, --client Whether to generate rpc client (default true) -h, --help help for protoc --home string The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority -m, --multiple Generated in multiple rpc service mode --remote string The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
--style string The file naming format, see [https://github.com/zeromicro/go-zero/blob/master/tools/goctl/config/readme.md] -v, --verbose Enable log output --zrpc_out string The zrpc output directory 参数字段 参数类型 是否必填 默认值 参数说明 branch string NO 空字符串 模板仓库分支，配合 --remote 使用 home string NO ~/.goctl 模板仓库本地路径，优先级低于 --remote client bool NO true 是否生成客户端代码 multiple bool NO false 是否生成多个 rpc 服务 remote string NO 空字符串 模板仓库远程路径 style string NO gozero 文件命名风格，详情可参考 文件风格 zrpc_out string NO 空字符串 输出目录 除了上述参数外，还有支持 protoc 指令的原生参数，详情可参考 Go Generated Code Guide。

示例：

单个 rpc 服务生成示例指令

$ goctl rpc protoc greet.proto --go_out=./pb --go-grpc_out=./pb --zrpc_out=. --client=true

多个 rpc 服务生成示例指令

$ goctl rpc protoc greet.proto --go_out=./pb --go-grpc_out=./pb --zrpc_out=. --client=true -m tip 多个 rpc 服务生成示例（rpc 分组）生成效果可参考 服务分组

小技能 goctl rpc protoc 指令比较长，参数很多，其实在理解 protoc 用法的前提下，你可以将指令理解成是如下的形式：

goctl rpc ${protoc 用法} --zrpc_out=${output directory}，比如指令 goctl rpc protoc greet.proto --go_out=./pb --go-grpc_out=./pb --zrpc_out=.，其中 protoc greet.proto --go_out=./pb --go-grpc_out=./pb 完全是 protoc 指令的用法，而 --zrpc_out=. 则是 goctl rpc protoc 指令的的参数。

注意 goctl rpc protoc 指令生成 rpc 服务对 proto 有一些事项须知：

proto 文件中如果有 import 语句，goctl 不会对 import 的 proto 文件进行处理，需要自行手动处理。 rpc service 中的请求体和响应体必须是当前 proto 文件中的 message，不能是 import 的 proto 文件中的 message。 goctl rpc template​ 快速生成一个 proto 模板文件，其接收一个 proto 文件名称参数。

注意 该指令已经废弃，推荐使用 goctl rpc -o 指令。

$ goctl rpc template --help Generate proto template

Usage: goctl rpc template [flags]

Flags: --branch string The branch of the remote repo, it does work with --remote -h, --help help for template --home string The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority --o string Output a sample proto file --remote string The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure 参数字段 参数类型 是否必填 默认值 参数说明 branch string NO 空字符串 模板仓库分支，配合 --remote 使用 home string NO ~/.goctl 模板仓库本地路径，优先级低于 --remote o string NO 空字符串 输出文件路径 remote string NO 空字符串 模板仓库远程路径 示例：

$ goctl rpc template -o greet.proto

goctl template 概述 ​ 模板（Template）是数据驱动生成的基础，所有的代码（rest api、rpc、model、docker、kube）生成都会依赖模板， 默认情况下，模板生成器会选择内存中的模板进行生成，而对于有模板修改需求的开发者来讲，则需要将模板进行落盘， 从而进行模板修改，在下次代码生成时会加载指定路径下的模板进行生成。

goctl template 指令 ​ $ goctl template --help Template operation

Usage: goctl template [command]

Available Commands: clean Clean the all cache templates init Initialize the all templates(force update) revert Revert the target template to the latest update Update template of the target category to the latest

Flags: -h, --help help for template

Use "goctl template [command] --help" for more information about a command. goctl template clean 指令 ​ goctl template clean 用于删除持久化在本地的模板文件。

$ goctl template clean --help Clean the all cache templates

Usage: goctl template clean [flags]

Flags: -h, --help help for clean --home string The goctl home path of the template goctl template init 指令 ​ goctl template init 用于初始化模板，会将模板文件存储到本地。

$ goctl template init --help Initialize the all templates(force update)

Usage: goctl template init [flags]

Flags: -h, --help help for init --home string The goctl home path of the template goctl template revert 指令 ​ goctl template revert 用于回滚某个分类下的指定的模板文件。

$ goctl template revert --help Revert the target template to the latest

Usage: goctl template revert [flags]

Flags: -c, --category string The category of template, enum [api,rpc,model,docker,kube] -h, --help help for revert --home string The goctl home path of the template -n, --name string The target file name of template 参数字段 参数类型 是否必填 默认值 参数说明 category string YES 空字符串 模板分类，api|rpc|model|docker|kube home string YES ${HOME}/.goctl 模板存储的文件位置 name string YES 空字符串 模板文件名称 goctl template update 指令 ​ goctl template update 用于更新某个分类下的所有模板文件。

$ goctl template update --help Update template of the target category to the latest

Usage: goctl template update [flags]

Flags: -c, --category string The category of template, enum [api,rpc,model,docker,kube] -h, --help help for update --home string The goctl home path of the template 参数字段 参数类型 是否必填 默认值 参数说明 category string YES 空字符串 模板分类，api|rpc|model|docker|kube home string YES ${HOME}/.goctl 模板存储的文件位置

goctl upgrade 概述 ​ goctl upgrade 用于升级 goctl 工具。

goctl upgrade 指令 ​ goctl upgrade 会将当前 goctl 工具升级到最新版本。

$ goctl upgrade --help Upgrade goctl to latest version

Usage: goctl upgrade [flags]

Flags: -h, --help help for upgrade