## Mix Console
命令行控制臺程序開發框架
Command line console program development framework
> 該庫還有 php 版本:https://github.com/mix-php/console
## Overview
Mix Console 不僅僅只是一個命令行骨架,它還包括命令行參數獲取、依賴注入、事件驅動、全局 panic 捕獲,錯誤信息接入日志或者第三方、程序后臺執行等各種命令行開發常用功能,是一個完整的命令行程序開發框架。
## Installation
- 安裝
```
go get -u github.com/mix-go/console
```
## Quick start
下面這些復雜的配置,在 [mix](https://github.com/mix-go/mix) 生成的骨架中都已經配置好了,并且做了合理的目錄規劃。
```go
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](https://github.com/mix-go/event) 管理本身的核心事件調度,讓用戶可以自定義處理
- `console.CommandBeforeExecuteEvent` 當命令執行前會調度該事件,用戶可監聽該事件在命令執行前處理前置邏輯,比如:將程序后臺執行
- `console.HandleErrorEvent` 當程序捕獲到全局 panic 或者代碼中手動捕獲的錯誤信息時調度該事件,用戶可監聽該事件將錯誤信息打印到日志或者發送到 Sentry 等平臺。
## Daemon
將命令行程序變為后臺執行,該方法只可在 Main 協程中使用。
```
process.Daemon()
```
我們可以通過配合 `console.CommandBeforeExecuteEvent` 和 `flag` 獲取參數,實現通過某幾個參數控制程序后臺執行。
```go
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](https://github.com/mix-go/bean) 管理程序內部庫的全部依賴關系,實現 DI、IoC,上面提到的 `console.App.Context` 就是控制臺通過該庫創建,該庫設計思想參考 java spring,使用非常靈活。
## Logger
控制臺 `error` 組件創建時必須傳一個實現 Logger 接口的參數:
```go
type Logger interface {
ErrorStack(err interface{}, stack *[]byte)
}
```
這個接口是為了實現可以通過 Logger 打印 panic 的堆棧信息到日志中,[Mix Logrus](https://github.com/mix-go/logrus) 實現了這個接口,因此可以直接接入,如需要使用其他開源 Logger 就需要用戶自行擴展實現上面的接口。
## License
Apache License Version 2.0, http://www.apache.org/licenses/