命令行管理痛点

前面我们介绍的命令行管理,都是通过回调函数的parser对象获取解析的参数及选项数据,在使用的时候存在以下痛点:

  • 需要手动传入硬编码的参数索引或者选项名称信息来获取数据
  • 难以定义参数/选项的说明介绍
  • 难以定义参数/选项的数据类型
  • 难以对参数/选项进行通用性的数据校验
  • 对于需要管理大量命令行的项目是个灾难

对象化管理命令

我们来一个最简单的结构化管理参数示例。我们将前面介绍过的Command示例改造为结构化管理:

  1. package main
  2. import (
  3. "context"
  4. "fmt"
  5. "github.com/gogf/gf/v2/frame/g"
  6. "github.com/gogf/gf/v2/os/gcmd"
  7. "github.com/gogf/gf/v2/os/gctx"
  8. )
  9. type cMain struct {
  10. g.Meta `name:"main"`
  11. }
  12. type cMainHttpInput struct {
  13. g.Meta `name:"http" brief:"start http server"`
  14. }
  15. type cMainHttpOutput struct{}
  16. type cMainGrpcInput struct {
  17. g.Meta `name:"grpc" brief:"start grpc server"`
  18. }
  19. type cMainGrpcOutput struct{}
  20. func (c *cMain) Http(ctx context.Context, in cMainHttpInput) (out *cMainHttpOutput, err error) {
  21. fmt.Println("start http server")
  22. return
  23. }
  24. func (c *cMain) Grpc(ctx context.Context, in cMainGrpcInput) (out *cMainGrpcOutput, err error) {
  25. fmt.Println("start grpc server")
  26. return
  27. }
  28. func main() {
  29. cmd, err := gcmd.NewFromObject(cMain{})
  30. if err != nil {
  31. panic(err)
  32. }
  33. cmd.Run(gctx.New())
  34. }

可以看到,我们通过对象的形式来管理父级命令,通过方法的形式来管理其下一层级的子级命令,并通过规范化的Input输入参数对象来定义子级命令的描述/参数/选项。大部分场景下,大家可以忽略Output返回对象的使用,但为规范化及扩展性需要保留,如果未用到,该返回参数直接返回nil即可。关于其中的结构体标签,后续会有介绍。

我们将示例代码编译后,执行查看效果:

  1. $ main
  2. USAGE
  3. main COMMAND [OPTION]
  4. COMMAND
  5. http start http server
  6. grpc start grpc server
  7. DESCRIPTION
  8. this is the command entry for starting your process

使用http命令:

  1. $ main http
  2. start http server

使用grpc命令:

  1. $ main grpc
  2. start grpc server

效果和前面介绍的示例一致。

结构化管理入参

既然命令行通过对象化管理,我们仔细看看参数/选项是如何通过结构化管理。

我们将上面的实例简化一下,来个简单的例子,实现通过http命令开启http服务:

  1. package main
  2. import (
  3. "context"
  4. "github.com/gogf/gf/v2/frame/g"
  5. "github.com/gogf/gf/v2/net/ghttp"
  6. "github.com/gogf/gf/v2/os/gcmd"
  7. "github.com/gogf/gf/v2/os/gctx"
  8. )
  9. type cMain struct {
  10. g.Meta `name:"main" brief:"start http server"`
  11. }
  12. type cMainHttpInput struct {
  13. g.Meta `name:"http" brief:"start http server"`
  14. Name string `v:"required" name:"NAME" arg:"true" brief:"server name"`
  15. Port int `v:"required" short:"p" name:"port" brief:"port of http server"`
  16. }
  17. type cMainHttpOutput struct{}
  18. func (c *cMain) Http(ctx context.Context, in cMainHttpInput) (out *cMainHttpOutput, err error) {
  19. s := g.Server(in.Name)
  20. s.BindHandler("/", func(r *ghttp.Request) {
  21. r.Response.Write("Hello world")
  22. })
  23. s.SetPort(in.Port)
  24. s.Run()
  25. return
  26. }
  27. func main() {
  28. cmd, err := gcmd.NewFromObject(cMain{})
  29. if err != nil {
  30. panic(err)
  31. }
  32. cmd.Run(gctx.New())
  33. }

我们为http命令定义了两个输入参数:

  • NAME 服务的名称,通过参数输入。这里使用了大写形式,方便展示在自动生成的帮助信息中
  • port 服务的端口,通过p/port选项输入

并且我们通过v:"required"校验标签为这两个参数都绑定的必需的校验规则。是的,在GoFrame框架中,只要涉及到校验的地方都使用了统一的校验组件,具体请参考章节:数据校验

我们编译后执行看看效果:

  1. $ main http
  2. arguments validation failed for command "http": The Name field is required
  3. 1. arguments validation failed for command "http"
  4. 1). github.com/gogf/gf/v2/os/gcmd.newCommandFromMethod.func1
  5. /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/os/gcmd/gcmd_command_object.go:290
  6. 2). github.com/gogf/gf/v2/os/gcmd.(*Command).doRun
  7. /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/os/gcmd/gcmd_command_run.go:120
  8. 3). github.com/gogf/gf/v2/os/gcmd.(*Command).RunWithValueError
  9. /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/os/gcmd/gcmd_command_run.go:77
  10. 4). github.com/gogf/gf/v2/os/gcmd.(*Command).RunWithValue
  11. /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/os/gcmd/gcmd_command_run.go:32
  12. 5). github.com/gogf/gf/v2/os/gcmd.(*Command).Run
  13. /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/v2/os/gcmd/gcmd_command_run.go:26
  14. 6). main.main
  15. /Users/john/Workspace/Go/GOPATH/src/github.com/gogf/gf/.test/test.go:38
  16. 2. The Name field is required

执行后,报错了,这个错误来自于数据校验,表示必须参数(Name/Port)必须传递。

这里的报错打印了堆栈信息,因为GoFrame框架采用了全错误堆栈设计,所有组件错误都会带有自底向上的错误堆栈,以方便错误快速定位。当然我们可以通过RunWithError方法获取返回的错误对象关闭堆栈信息。

我增加参数输入再试试:

  1. $ main http my-http-server -p 8199
  2. 2022-01-19 22:52:45.808 [DEBU] openapi specification is disabled
  3. SERVER | DOMAIN | ADDRESS | METHOD | ROUTE | HANDLER | MIDDLEWARE
  4. -----------------|---------|---------|--------|-------|-----------------------------------------------------------------|--------------------
  5. my-http-server | default | :8199 | ALL | / | main.(*cMain).Http.func1 |
  6. -----------------|---------|---------|--------|-------|-----------------------------------------------------------------|--------------------
  7. my-http-server | default | :8199 | ALL | /* | github.com/gogf/gf/v2/net/ghttp.internalMiddlewareServerTracing | GLOBAL MIDDLEWARE
  8. -----------------|---------|---------|--------|-------|-----------------------------------------------------------------|--------------------
  9. 2022-01-19 22:52:45.810 66292: http server started listening on [:8199]

是的,这就对了。

完整使用案例

GoFrame框架的开发工具普通使用了对象化、结构化的命令行管理,大家感兴趣可以更进一步查看源码了解:https://github.com/gogf/gf/tree/master/cmd/gf

命令管理-结构化参数 - 图1

预定义的标签

在结构化设计中,我们使用了一些结构体标签,大部分来源于Command命令的属性,这里我们来介绍一下:

标签缩写说明注意事项
name-命名名称如果是输入参数结构体,在未指定name时将会自动读取方法名称作为name
short-命令缩写
usage-命令使用
brief-命令描述
arg-表示该输入参数来源于参数而不是选项仅用于属性标签
orphan-表示该选项不带参数属性通常为bool类型
descriptiondc命令的详细介绍
additionalad命令的额外描述信息
exampleseg命令的使用示例
root-指定子级命令名称是父级命令,其他方法是它的子级命令仅用于主命令对象结构体Meta标签
strict-表示该命令严格解析参数/选项,当输入不支持的参数/选项时,返回错误仅用于对象结构体Meta标签
config-表示该命令的选项数据支持从指定的配置读取,配置来源于默认的全局单例配置对象仅用于方法输入结构体Meta标签

高级特性

自动数据转换

结构化的参数输入支持自动的数据类型转换,您只需要定义好数据类型,其他的事情交给框架组件即可。自动数据类型转换出现在框架的很多组件中,特别是HTTP/GRPC服务的参数输入中。底层数据转换组件使用的是:类型转换

命令行参数的数据转换采用不区分大小写、且忽略特殊字符的规则来匹配属性字段。例如,如果入参结构体中存在Name字段属性,无论命令行输入name还是NAME的命名参数,都将能被Name字段属性接收。

自动数据校验

同样的,数据校验组件也是使用的统一的组件,具体请参考章节:数据校验

从配置读取数据

当命令行中没有传递对应的数据时,输入参数的结构体数据支持从配置组件中自动获取,只需要在Meta中设置config标签即可,配置来源于默认的全局单例配置对象。具体示例可以参考GoFrame框架开发工具源码:https://github.com/gogf/gf/tree/master/cmd/gf