console

README

OpenMix 出品：https://openmix.org

Mix Console

命令行控制台程序开发框架

Command line console program development framework

该库还有 php 版本：https://github.com/mix-php/console

Contents

• Overview
• Installation
• Quick start
• Flag
• Event
• Daemon
• Catch panic
• Application
• Bean
• Logger

Overview

Mix Console 不仅仅只是一个命令行骨架，它还包括命令行参数获取、依赖注入、事件驱动、全局 panic 捕获，错误信息接入日志或者第三方、程序后台执行等各种命令行开发常用功能，是一个完整的命令行程序开发框架。

Installation

• 安装

go get -u github.com/mix-go/console

Quick start

下面这些复杂的配置，在 mix 生成的骨架中都已经配置好了，并且做了合理的目录规划。

package main

import (
    "github.com/mix-go/bean"
    "github.com/mix-go/console"
    "github.com/mix-go/event"
    "github.com/mix-go/logrus"
)

type HelloCommand struct {
}

func (t *HelloCommand) Main() {
    // do something
}

func main() {
    definition := console.ApplicationDefinition{
        Name:    "app",
        Version: "0.0.0-alpha",
        Debug:   true,
        // 该字段为程序依赖配置，内部的 eventDispatcher, error 是两个核心依赖，是必须配置的
        Beans: []bean.BeanDefinition{
            bean.BeanDefinition{
                Name:            "eventDispatcher",
                Reflect:         bean.NewReflect(event.NewDispatcher),
                Scope:           bean.SINGLETON,
                ConstructorArgs: bean.ConstructorArgs{},
            },
            bean.BeanDefinition{
                Name:            "error",
                Reflect:         bean.NewReflect(console.NewError),
                Scope:           bean.SINGLETON,
                ConstructorArgs: bean.ConstructorArgs{bean.NewReference("logger")},
                Fields: bean.Fields{
                    "Dispatcher": bean.NewReference("eventDispatcher"),
                },
            },
            bean.BeanDefinition{
                Name:    "logger",
                Reflect: bean.NewReflect(logrus.NewLogger),
                Scope:   bean.SINGLETON,
            },
        },
        // 该字段配置了程序有多少个命令，并且包含的参数，所有在程序中需要使用的参数都必须在这里定义
        Commands: []console.CommandDefinition{
            console.CommandDefinition{
                Name:  "hello",
                Usage: "\tEcho demo",
                Options: []console.OptionDefinition{
                    {
                        Names: []string{"n", "name"},
                        Usage: "Your name",
                    },
                    {
                        Names: []string{"say"},
                        Usage: "\tSay ...",
                    },
                },
                Command: &HelloCommand{},
                /* Singleton: true, // 如果这个程序只有一个命令，就开启这个配置 */
            },
        },
    }
    // 后面两个参数指定了必须配置的两个核心依赖的名称
    console.NewApplication(definition, "eventDispatcher", "error").Run()
}

编译后，查看整个命令行程序的帮助

$ ./go_build_main_go 
Usage: ./go_build_main_go [OPTIONS] COMMAND [opt...]

Global Options:
  -h, --help    Print usage
  -v, --version Print version information

Commands:
  hello         Echo demo


Run './go_build_main_go COMMAND --help' for more information on a command.

Developed with Mix Go framework. (openmix.org/mix-go)

查看命令行程序的版本信息

$ ./go_build_main_go -v
app 0.0.0-alpha, framework 1.0.9

查看 hello 命令的帮助

$ ./go_build_main_go hello --help
Usage: ./go_build_main_go hello [opt...]

Command Options:
  -n, --name    Your name
  --say         Say ...

Developed with Mix Go framework. (openmix.org/mix-go)

执行 hello 命令

$ ./go_build_main_go hello 

Flag

该 flag 比 golang 自带的更加好用，不需要 Parse 操作

获取命令行参数，可以获取 String、Bool、Int64、Float64 多种类型，也可以指定默认值。

name := flag.Match("n", "name").String("Xiao Ming")

参数规则 (部分UNIX风格+GNU风格)

• 单字母参数只支持一个中杠，如 -p，多字母参数只支持二个中杠，如：--option
• 参数可以有值、也可以没有值，如：
  • 无值：-p、 --option
  • 有值(空格)：-p value、--option value
  • 有值(等号)：-p=value、--option=value

Event

控制台基于 Mix Event 管理本身的核心事件调度，让用户可以自定义处理

• console.CommandBeforeExecuteEvent 当命令执行前会调度该事件，用户可监听该事件在命令执行前处理前置逻辑，比如：将程序后台执行
• console.HandleErrorEvent 当程序捕获到全局 panic 或者代码中手动捕获的错误信息时调度该事件，用户可监听该事件将错误信息打印到日志或者发送到 Sentry 等平台。

Daemon

将命令行程序变为后台执行，该方法只可在 Main 协程中使用。

process.Daemon()

我们可以通过配合 console.CommandBeforeExecuteEvent 和 flag 获取参数，实现通过某几个参数控制程序后台执行。

package listeners

import (
    "github.com/mix-go/console"
    "github.com/mix-go/console/flag"
    "github.com/mix-go/console/process"
    "github.com/mix-go/event"
)

type CommandListener struct {
}

func (t *CommandListener) Events() []event.Event {
    return []event.Event{
        &console.CommandBeforeExecuteEvent{},
    }
}

func (t *CommandListener) Process(e event.Event) {
    switch e.(type) {
    case *console.CommandBeforeExecuteEvent:
        // 设置守护
        if flag.Match("d", "daemon").Bool() {
            process.Daemon()
        }
        break
    }
}

创建的监听器需要注册到 eventDispatcher 组件的构造参数中

ConstructorArgs: bean.ConstructorArgs{listeners.CommandListener{}},

上面就实现了一个当命令行参数中带有 -d/--daemon 参数时，程序就在后台执行，注意：这两个参数需要在 console.CommandDefinition 中配置才可使用。

Catch panic

go 程序的 err 返回设计虽然用户手动处理了大部分的错误，但是总是会有一些运行时 panic 是忘记处理的，但是这个错误信息是默认直接输出在 os.Stdout 中，日志中无法看到，非常容易忽略并且 debug 困难，我们解决了这个问题，可以将全部错误捕获集中交给 error 组件处理。

• Main 主协程
  • error 当主协程中的抛出 panic 时，Application 会内部使用了 recover 将错误信息传递到 error 组件处理。
• 子协程：子协程里的 panic 只能在子协程中使用 recover 捕获。
  • catch.Error 可以手动在子协程通过 recover 将错误信息使用该方法传递给 error 组件处理，如：catch.Error(err) 该方法会打印堆栈信息。
  • catch.Call 更加省事的方法就是在开启子协程的位置使用该方法，如：go foo() 修改为 go catch.Call(foo)

错误信息将会集中到 error 处理，该组件会调用 logger 组件打印到日志，logger 组件会将 panic 的错误堆栈信息打印到日志中，这样就不用怕忽略错误信息，并且 debug 将变得更加容易，该组件还会使用 eventDispatcher 组件调度 console.HandleErrorEvent 事件，用户可将错误信息自定接入 Sentry 等第三方平台。

Application

我们在 Command: &HelloCommand{} 中编写代码时，经常会要调用 App 中的一些功能。

console.App

APP 的一些属性

// 获取基础路径(二进制所在目录路径)
console.App.BasePath

// App名称
console.App.Name

// App版本号
console.App.Version

// 是否开启debug
console.App.Debug

// 依赖注入容器
console.App.Context

由于依赖注入容器使用非常频繁，于是我们可以这样快速获取组件

console.App.Get("logger").(*logrus.Logger)

上面语句实际上等于这个

console.App.Context.Get("logger").(*logrus.Logger)

Bean

控制台基于 Mix Bean 管理程序内部库的全部依赖关系，实现 DI、IoC，上面提到的 console.App.Context 就是控制台通过该库创建，该库设计思想参考 java spring，使用非常灵活。

Logger

控制台 error 组件创建时必须传一个实现 Logger 接口的参数：

type Logger interface {
    ErrorStack(err interface{}, stack *[]byte)
}

这个接口是为了实现可以通过 Logger 打印 panic 的堆栈信息到日志中，Mix Logrus 实现了这个接口，因此可以直接接入，如需要使用其他开源 Logger 就需要用户自行扩展实现上面的接口。

License

Apache License Version 2.0, http://www.apache.org/licenses/

Documentation

Index

• Variables
• type Application
  • func NewApplication(definition ApplicationDefinition, dispatcherName, errorName string) *Application
  • func (t *Application) Get(name string) interface{}
  • func (t *Application) Init()
  • func (t *Application) Run()
• type ApplicationDefinition
• type Command
• type CommandBeforeExecuteEvent
• type CommandDefinition
• type Error
  • func NewError(logger Logger) Error
• type ErrorHandler
  • func (t *ErrorHandler) Handle(err interface{})
• type HandleErrorEvent
• type Logger
• type NotFoundError
  • func NewNotFoundError(err error) *NotFoundError
• type OptionDefinition
• type UnsupportError
  • func NewUnsupportError(err error) *UnsupportError

Variables

var (
	// App 全局APP
	App *Application
	// Version 版本号
	Version = "1.0.23"
	// LastError 最后的错误
	LastError interface{}
)

Types

type Application

type Application struct {
	// App 定义
	ApplicationDefinition
	// Event Dispatcher
	DispatcherName string
	Dispatcher     event.Dispatcher
	// Error
	ErrorName string
	Error     Error
	// 基础路径
	BasePath string
	// 应用上下文
	Context *bean.ApplicationContext
	// 是否单命令
	Singleton bool
}

Application 应用

func NewApplication

func NewApplication(definition ApplicationDefinition, dispatcherName, errorName string) *Application

NewApplication 创建应用

func (*Application) Get

func (t *Application) Get(name string) interface{}

Get 快速获取实例

func (*Application) Init

func (t *Application) Init()

Init 初始化

func (*Application) Run

func (t *Application) Run()

Run 执行

type ApplicationDefinition

type ApplicationDefinition struct {
	// 应用名称
	Name string
	// 应用版本
	Version string
	// 应用调试
	Debug bool
	// 依赖配置
	Beans []bean.BeanDefinition
	// 命令集合
	Commands []CommandDefinition
}

ApplicationDefinition 应用定义

type Command

type Command interface {
	Main()
}

Command 命令接口

type CommandBeforeExecuteEvent

type CommandBeforeExecuteEvent struct {
	event.EventTrait
	Command Command
}

CommandBeforeExecuteEvent 命令行前置事件

type CommandDefinition

type CommandDefinition struct {
	// 命令名称
	Name string
	// 使用描述
	Usage string
	// 选项
	Options []OptionDefinition
	// 命令
	Command Command
	// 是否单命令
	Singleton bool
}

CommandDefinition 命令定义

type Error

type Error interface {
	Handle(err interface{})
}

Error 错误接口

func NewError

func NewError(logger Logger) Error

NewError 创建错误对象

type ErrorHandler

type ErrorHandler struct {
	Logger     Logger
	Dispatcher event.Dispatcher
}

ErrorHandler 错误处理结构体

func (*ErrorHandler) Handle

func (t *ErrorHandler) Handle(err interface{})

Handle 处理错误

type HandleErrorEvent

type HandleErrorEvent struct {
	event.EventTrait
	Error interface{}
}

HandleErrorEvent 处理错误事件

type Logger

type Logger interface {
	ErrorStack(err interface{}, stack *[]byte)
}

Logger 日志接口

type NotFoundError

type NotFoundError struct {
	// contains filtered or unexported fields
}

NotFoundError 未找到错误

func NewNotFoundError

func NewNotFoundError(err error) *NotFoundError

NewNotFoundError 创建未找到错误

type OptionDefinition

type OptionDefinition struct {
	Names []string
	Usage string
}

OptionDefinition 命令选项

type UnsupportError

type UnsupportError struct {
	// contains filtered or unexported fields
}

UnsupportError 不支持错误

func NewUnsupportError

func NewUnsupportError(err error) *UnsupportError

NewUnsupportError 创建不支持错误