goctl api

概述

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

goctl api 指令

  1. $ goctl api --help
  2. Generate api related files
  3. Usage:
  4. goctl api [flags]
  5. goctl api [command]
  6. Available Commands:
  7. dart Generate dart files for provided api in api file
  8. doc Generate doc files
  9. format Format api files
  10. go Generate go files for provided api in api file
  11. kt Generate kotlin code for provided api file
  12. new Fast create api service
  13. plugin Custom file generator
  14. ts Generate ts files for provided api in api file
  15. validate Validate api file
  16. Flags:
  17. --branch string The branch of the remote repo, it does work with --remote
  18. -h, --help help for api
  19. --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
  20. --o string Output a sample api file
  21. --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
  22. The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
  23. Use "goctl api [command] --help" for more information about a command.
goctl api - 图1 参数字段goctl api - 图2 参数类型goctl api - 图3 是否必填goctl api - 图4 默认值goctl api - 图5 参数说明
branchstringNO空字符串模板仓库分支,配合 —remote 使用
homestringNO~/.goctl模板仓库本地路径,优先级高于 —remote
ostringNO空字符串输出 api 文件
remotestringNO空字符串模板仓库远程路径

dart

根据 api 文件生成 dart 代码。

  1. $ goctl api dart --help
  2. Generate dart files for provided api in api file
  3. Usage:
  4. goctl api dart [flags]
  5. Flags:
  6. --api string The api file
  7. --dir string The target dir
  8. -h, --help help for dart
  9. --hostname string hostname of the server
  10. --legacy Legacy generator for flutter v1
goctl api - 图6 参数字段goctl api - 图7 参数类型goctl api - 图8 是否必填goctl api - 图9 默认值goctl api - 图10 参数说明
apistringYES空字符串api 文件
dirstringYES空字符串生成代码输出目录
hostnamestringNOgo-zero.devhost 值
legacybooleanNOfalse是否旧版本

doc

根据 api 文件生成 markdown 文档。

  1. $ goctl api doc --help
  2. Generate doc files
  3. Usage:
  4. goctl api doc [flags]
  5. Flags:
  6. --dir string The target dir
  7. -h, --help help for doc
  8. --o string The output markdown directory
goctl api - 图11 参数字段goctl api - 图12 参数类型goctl api - 图13 是否必填goctl api - 图14 默认值goctl api - 图15 参数说明
dirstringYES空字符串api 文件所在目录
ostringNO当前 work dir文档输出目录

format

递归格式化目录下的 api 文件。

  1. $ goctl api format --help
  2. Format api files
  3. Usage:
  4. goctl api format [flags]
  5. Flags:
  6. --declare Use to skip check api types already declare
  7. --dir string The format target dir
  8. -h, --help help for format
  9. --iu Ignore update
  10. --stdin Use stdin to input api doc content, press "ctrl + d" to send EOF
goctl api - 图16 参数字段goctl api - 图17 参数类型goctl api - 图18 是否必填goctl api - 图19 默认值goctl api - 图20 参数说明
declarebooleanNOfalse是否检测上下文
dirstringYES空字符串api 所在目录
iu---未使用字段,待移出
stdinbooleanNOfalse是否格式化终端输入的 api 内容

go

根据 api 文件生成 Go HTTP 代码。

  1. $ goctl api go --help
  2. Generate go files for provided api in api file
  3. Usage:
  4. goctl api go [flags]
  5. Flags:
  6. --api string The api file
  7. --branch string The branch of the remote repo, it does work with --remote
  8. --dir string The target dir
  9. -h, --help help for go
  10. --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
  11. --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
  12. The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
  13. --style string The file naming format, see [https://github.com/zeromicro/go-zero/blob/master/tools/goctl/config/readme.md] (default "gozero")
goctl api - 图21 参数字段goctl api - 图22 参数类型goctl api - 图23 是否必填goctl api - 图24 默认值goctl api - 图25 参数说明
apistringYES空字符串api 文件路径
branchstringNO空字符串远程模板所在 git 分支名称,仅当 remote 有值时使用
dirstringNO当前工作目录代码输出目录
homestringNO${HOME}/.goctl本地模板文件目录
remotestringNO空字符串远程模板所在 git 仓库地址,当此字段传值时,优先级高于 home 字段值
stylestringNOgozero输出文件和目录的命名风格格式化符号,详情见文件风格

new

快速生成 Go HTTP 服务,开发者需要在终端指定服务名称参数,输出目录为当前工作目录。

  1. $ goctl api new --help
  2. Fast create api service
  3. Usage:
  4. goctl api new [flags]
  5. Examples:
  6. goctl api new [options] service-name
  7. Flags:
  8. --branch string The branch of the remote repo, it does work with --remote
  9. -h, --help help for new
  10. --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
  11. --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
  12. The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
  13. --style string The file naming format, see [https://github.com/zeromicro/go-zero/blob/master/tools/goctl/config/readme.md] (default "gozero")
goctl api - 图26 参数字段goctl api - 图27 参数类型goctl api - 图28 是否必填goctl api - 图29 默认值goctl api - 图30 参数说明
branchstringNO空字符串远程模板所在 git 分支名称,仅当 remote 有值时使用
homestringNO${HOME}/.goctl本地模板文件目录
remotestringNO空字符串远程模板所在 git 仓库地址,当此字段传值时,优先级高于 home 字段值
stylestringNOgozero输出文件和目录的命名风格格式化符号,详情见文件风格
goctl api - 图31温馨提示

goctl api new 需要一个终端参数来指定需要生成的服务名称,输出目录为当前工作目录,如 demo 服务生成的指令示例如下:

  1. $ goctl api new demo

plugin

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

  1. $ goctl api plugin --help
  2. Custom file generator
  3. Usage:
  4. goctl api plugin [flags]
  5. Flags:
  6. --api string The api file
  7. --dir string The target dir
  8. -h, --help help for plugin
  9. -p, --plugin string The plugin file
  10. --style string The file naming format, see [https://github.com/zeromicro/go-zero/tree/master/tools/goctl/config/readme.md]
goctl api - 图32 参数字段goctl api - 图33 参数类型goctl api - 图34 是否必填goctl api - 图35 默认值goctl api - 图36 参数说明
apistringYES空字符串api 文件路径
dirstringNO当前工作目录api 文件路径
pluginstringYES空字符串插件可执行文件所在路径,支持本地和 http 文件
stylestringNOgozero输出文件和目录的命名风格格式化符号,详情见文件风格

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

ts

根据 api 文件生成 TypeScript 代码。

  1. $ goctl api ts --help
  2. Generate ts files for provided api in api file
  3. Usage:
  4. goctl api ts [flags]
  5. Flags:
  6. --api string The api file
  7. --caller string The web api caller
  8. --dir string The target dir
  9. -h, --help help for ts
  10. --unwrap Unwrap the webapi caller for import
  11. --webapi string The web api file path
goctl api - 图37 参数字段goctl api - 图38 参数类型goctl api - 图39 是否必填goctl api - 图40 默认值goctl api - 图41 参数说明
apistringYES空字符串api 文件路径
dirstringNO当前工作目录api 文件路径
callerstringNOwebapiweb caller,
pluginstringYES空字符串插件可执行文件所在路径,支持本地和 http 文件
stylestringNOgozero输出文件和目录的命名风格格式化符号,详情见文件风格

validate

校验 api 文件是否符合规范。

  1. goctl api validate --help
  2. Validate api file
  3. Usage:
  4. goctl api validate [flags]
  5. Flags:
  6. --api string Validate target api file
  7. -h, --help help for validate
goctl api - 图42 参数字段goctl api - 图43 参数类型goctl api - 图44 是否必填goctl api - 图45 默认值goctl api - 图46 参数说明
apistringYES空字符串api 文件路径