Skip to main content

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
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.
参数字段 参数类型 是否必填 默认值 参数说明
branchstringNO空字符串模板仓库分支,配合 --remote 使用
homestringNO~/.goctl模板仓库本地路径,优先级低于 --remote
ostringNO空字符串输出 api 文件
remotestringNO空字符串模板仓库远程路径

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
参数字段 参数类型 是否必填 默认值 参数说明
apistringYES空字符串api 文件
dirstringYES空字符串生成代码输出目录
hostnamestringNOgo-zero.devhost 值
legacybooleanNOfalse是否旧版本

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
参数字段 参数类型 是否必填 默认值 参数说明
dirstringYES空字符串api 文件所在目录
ostringNO当前 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
参数字段 参数类型 是否必填 默认值 参数说明
declarebooleanNOfalse是否检测上下文
dirstringYES空字符串api 所在目录
iu---未使用字段,待移出
stdinbooleanNOfalse是否格式化终端输入的 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")
参数字段 参数类型 是否必填 默认值 参数说明
apistringYES空字符串api 文件路径
branchstringNO空字符串远程模板所在 git 分支名称,仅当 remote 有值时使用
dirstringNO当前工作目录代码输出目录
homestringNO${HOME}/.goctl本地模板文件目录
remotestringNO空字符串远程模板所在 git 仓库地址,当此字段传值时,优先级高于 home 字段值
stylestringNOgozero输出文件和目录的命名风格格式化符号,详情见 文件风格

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")
参数字段 参数类型 是否必填 默认值 参数说明
branchstringNO空字符串远程模板所在 git 分支名称,仅当 remote 有值时使用
homestringNO${HOME}/.goctl本地模板文件目录
remotestringNO空字符串远程模板所在 git 仓库地址,当此字段传值时,优先级高于 home 字段值
stylestringNOgozero输出文件和目录的命名风格格式化符号,详情见 文件风格
温馨提示

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]
参数字段 参数类型 是否必填 默认值 参数说明
apistringYES空字符串api 文件路径
dirstringNO当前工作目录api 文件路径
pluginstringYES空字符串插件可执行文件所在路径,支持本地和 http 文件
stylestringNOgozero输出文件和目录的命名风格格式化符号,详情见 文件风格

插件资源请参考 goctl 插件资源

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
参数字段 参数类型 是否必填 默认值 参数说明
apistringYES空字符串api 文件路径
dirstringNO当前工作目录api 文件路径
callerstringNOwebapiweb caller,
pluginstringYES空字符串插件可执行文件所在路径,支持本地和 http 文件
stylestringNOgozero输出文件和目录的命名风格格式化符号,详情见 文件风格

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
参数字段 参数类型 是否必填 默认值 参数说明
apistringYES空字符串api 文件路径