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
  4. Usage:
  5.   goctl api [flags]
  6.   goctl api [command]
  8. Available Commands:
  9.   dart        Generate dart files for provided api in api file
  10.   doc         Generate doc files
  11.   format      Format api files
  12.   go          Generate go files for provided api in api file
  13.   kt          Generate kotlin code for provided api file
  14.   new         Fast create api service
  15.   plugin      Custom file generator
  16.   ts          Generate ts files for provided api in api file
  17.   validate    Validate api file
  19. Flags:
  20.       --branch string   The branch of the remote repo, it does work with --remote
  21.   -h, --help            help for api
  22.       --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
  23.       --o string        Output a sample api file
  24.       --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
  25.                         The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
  28. 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
  4. Usage:
  5.   goctl api dart [flags]
  7. Flags:
  8.       --api string        The api file
  9.       --dir string        The target dir
  10.   -h, --help              help for dart
  11.       --hostname string   hostname of the server
  12.       --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
  4. Usage:
  5.   goctl api doc [flags]
  7. Flags:
  8.       --dir string   The target dir
  9.   -h, --help         help for doc
  10.       --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
  4. Usage:
  5.   goctl api format [flags]
  7. Flags:
  8.       --declare      Use to skip check api types already declare
  9.       --dir string   The format target dir
  10.   -h, --help         help for format
  11.       --iu           Ignore update
  12.       --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
  4. Usage:
  5.   goctl api go [flags]
  7. Flags:
  8.       --api string      The api file
  9.       --branch string   The branch of the remote repo, it does work with --remote
  10.       --dir string      The target dir
  11.   -h, --help            help for go
  12.       --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
  13.       --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
  14.                         The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
  15.       --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
  4. Usage:
  5.   goctl api new [flags]
  7. Examples:
  8. goctl api new [options] service-name
  10. Flags:
  11.       --branch string   The branch of the remote repo, it does work with --remote
  12.   -h, --help            help for new
  13.       --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
  14.       --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
  15.                             The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
  16.       --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
  4. Usage:
  5.   goctl api plugin [flags]
  7. Flags:
  8.       --api string      The api file
  9.       --dir string      The target dir
  10.   -h, --help            help for plugin
  11.   -p, --plugin string   The plugin file
  12.       --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
  4. Usage:
  5.   goctl api ts [flags]
  7. Flags:
  8.       --api string      The api file
  9.       --caller string   The web api caller
  10.       --dir string      The target dir
  11.   -h, --help            help for ts
  12.       --unwrap          Unwrap the webapi caller for import
  13.       --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
  4. Usage:
  5.   goctl api validate [flags]
  7. Flags:
  8.       --api string   Validate target api file
  9.   -h, --help         help for validate
goctl api - 图42 参数字段goctl api - 图43 参数类型goctl api - 图44 是否必填goctl api - 图45 默认值goctl api - 图46 参数说明
apistringYES空字符串api 文件路径