runner

README

go-runner：Go 框架总入口

go-runner 设计初衷是提供一个 all-in-one 入口，尽可能减少使用者的思考负担。

由于 v1 版本相对之前版本有非常大的变化，详细迁移方法请参考 v0 到 v1 迁移指南。

使用方法

一般来说，业务的 main 函数里面只需要注册各种启动函数，最终调用 Main 函数即可完成启动。

所有 altstory 中的 client/server 库都已经完成跟 go-runner 的集成，一般来说无需操心初始化工作即可直接使用。 只要业务代码中使用了这些库，则这些库就会在服务启动时候自动初始化，无需显式的写任何初始化代码。

import (
    "github.com/altstory/go-http/server"
    "github.com/altstory/go-runner"
    "github.com/project/server/routes"
)

func main() {
    // 将所有业务 route 注册到 http server 里面，
    // 一旦注册了 routes，http server 就被自动启动起来了。
    server.AddRoutes(routes.Routes)

    // 启动服务。
    runner.Main()
}

自定义业务配置

如果业务代码中需要使用一些从配置文件中读出来的信息，推荐用以下模式来实现。

首先，在项目目录中创建一个 ./config/ 目录。

假设这个配置项名字叫做 resource，那么创建文件 ./config/resource.go 并写下如下代码。

package config

import "github.com/altstory/go-runner"

// ResourceType 是资源相关接口的配置。
type ResourceType struct {
    Foo string `config:"foo"`
    Bar int `config:"bar"`
}

// Resource 是资源相关配置的值。
var Resource *ResourceType

func init() {
    // 注册自动解析配置的函数，在服务启动后即可自动从配置文件中读取对应内容。
    runner.LoadConfig("resource", &Resource)
}

命令行参数

默认情况下，通过 Main 启动的服务会提供以下参数：

• -config：指定配置文件，默认是 ./conf/service.conf；
• -version：返回当前服务版本信息，这需要 CI 系统配合生成 .meta.json。

修改日志配置

go-runner 会假定配置文件中 [log] 的部分是日志配置。

# [log] 部分对应 log.Config 的各个配置项，可以用来控制日志的细节配置。
[log]
log_level = "debug"

通过环境变量追加配置

为了方便管理生成出来的 docker 镜像里面的配置，框架提供了一个环境变量 ALTSTORY_RUNNER_EXT_CONFIG 来设置一个额外的配置文件，用于覆盖镜像里自带的配置。

例如，有一个额外的配置文件 path/to/service-ext.conf。

# 可以删除指定的配置项。
_deletes = ['http.server.debug', 'other.key']

# 也可以覆盖指定的配置项。
[log]
log_level = "info"

在启动服务前，设置以下环境变量即可将这个配置追加到默认配置里面去。

docker run --env ALTSTORY_RUNNER_EXT_CONFIG=path/to/service-ext.conf

获取环境信息

根据公司的 CI 脚本设计，我们会在每个通过 CI build 的 docker 镜像里面放入一个 .meta.json 文件，用来告诉服务当前环境信息。如果服务希望读取这个文件里面的信息，可以通过调用 Meta 方法来获得所有数据。

// 任何业务代码里面都可以直接调用这个函数。
meta := runner.Meta()
fmt.Println(meta.Project)

注册启动和退出函数

业务代码可以通过 OnStart 和 OnExit 来注册启动和退出函数，它们的调用时机是：

• OnStart 会在所有 client 初始化完成、所有 server 还未初始化的时候调用，注册到 OnStart 的函数的执行顺序是不保证有序的，业务不应该依赖这个执行顺序来执行业务代码。
• OnExit 会在服务退出时候调用，注册到 OnExit 的函数的执行顺序是不保证有序的，业务不应该依赖这个执行顺序来执行业务代码。

这两个函数都应该在 init 中调用。

func init() {
    runner.OnStart(func(ctx context.Context) error {
        // 业务初始化代码……

        // nil 表示初始化正常，继续执行其他的启动过程。
        // 如果返回错误，则会阻止服务继续启动，程序会退出和报错。
        return nil
    })

    runner.OnExit(func(ctx context.Context) {
        // 业务退出代码……
    })
}

Documentation

Index

• Constants
• func AddClient(section string, handler Handler)
• func AddServer(section string, handler Handler)
• func LoadConfig(section string, v interface{})
• func LoadConfigFile(path string, section string, v interface{})
• func Main()
• func OnExit(handler func(ctx context.Context))
• func OnStart(handler func(ctx context.Context) error)
• func WithStats(ctx context.Context, stats *Stats) context.Context
• type Handler
• type MetaInfo
  • func Meta() *MetaInfo
• type Stats
  • func StatsFromContext(ctx context.Context) *Stats
  • func (stats *Stats) Add(key string, value int)
  • func (stats *Stats) Info() []log.Info
  • func (stats *Stats) Set(key string, value int)

Constants

const (
	// ExitCodeOK 是正常退出时候的错误码。
	ExitCodeOK = iota

	// ExitCodeInvalidHandler 是系统错误码，表示执行的 handler 类型非法。
	ExitCodeInvalidHandler

	// ExitCodeInvalidConfig 是配置文件解析失败时候的错误码。
	ExitCodeInvalidConfig

	// ExitCodeHandlerError 是 handler 执行出错或者 panic 返回的错误码。
	ExitCodeHandlerError
)

Functions

func AddClient

func AddClient(section string, handler Handler)

AddClient 注册一个自注册的 client 工厂。

func AddServer

func AddServer(section string, handler Handler)

AddServer 注册一个自启动的服务。 这个 handler 执行之后必须保持阻塞，直到停止服务为止才应该返回。

func LoadConfig

func LoadConfig(section string, v interface{})

LoadConfig 将 v 注册到启动逻辑里面，一旦配置文件读取之后，会从指定的 secion 给 v 赋值。

例如：

type FooConfig struct {
    Bar int `config:"bar"`
}

// 声明一个全局变量，用来方便业务代码读取配置。
var Foo *FooConfig

func init() {
    // 在自启动函数里面注册 Foo，这样服务启动后就会自动从配置里面读取 Foo 的值。
    // 假如读取过程中出现任何问题，比如配置里面没有 foo 这个字段，Foo 为 nil。
    runner.LoadConfig("foo", &Foo)
}

func LoadConfigFile

func LoadConfigFile(path string, section string, v interface{})

LoadConfigFile 将 v 注册到启动逻辑里面，一旦配置文件读取之后，会从指定的 secion 给 v 赋值。 跟 LoadConfig 不一样的是，通过指定 path，可以指定一个跟默认配置文件不一样的配置文件。

func Main

func Main()

Main 是整个框架的启动入口，这个函数永远不会返回。

func OnExit

func OnExit(handler func(ctx context.Context))

OnExit 将 handler 注册到 runner 的启动列表里面。

func OnStart

func OnStart(handler func(ctx context.Context) error)

OnStart 将 handler 注册到 runner 的启动列表里面。

func WithStats

func WithStats(ctx context.Context, stats *Stats) context.Context

WithStats 将 stats 追加到 ctx 中，并返回新的 ctx。

Types

type Handler

type Handler interface{}

Handler 是一个可以执行的函数。

允许的函数形式包括：

• func(ctx context.Context)： 执行一个函数，ctx 由 runner 传入。

• func(ctx context.Context) error：与上面的形式类似，只是允许返回一个 error，框架会自动报错。

• func(ctx context.Context, config *Config)： 这里的 `Config` 是配置文件里面对应的数据结构， Run 会自动解析配置文件并反序列化到 Config 里面去。

• func(ctx context.Context, config *Config) error：与上面的形式类似，只是允许返回一个 error，框架会自动报错。

type MetaInfo

type MetaInfo struct {
	Project     string `json:"project"`
	Namespace   string `json:"namespace"`
	Env         string `json:"env"`
	Type        string `json:"type"`
	GitRefName  string `json:"git_ref_name"`
	GitRevision string `json:"git_revision"`
}

MetaInfo 是当前环境的信息，由 CI 系统自动生成。

func Meta

func Meta() *MetaInfo

Meta 返回项目的 meta 信息。

type Stats

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

Stats 用于记录运行时的统计信息。

func StatsFromContext

func StatsFromContext(ctx context.Context) *Stats

StatsFromContext 返回 ctx 中存放的 stats，如果之前没有设置 stats 则返回 nil。 由于 stats 做了 nil 兼容，所有函数在 stats == nil 时候依然可以正常调用， 所以业务代码永远不需要检查这个返回值是否为 nil 就可以正常使用。

func (*Stats) Add

func (stats *Stats) Add(key string, value int)

Add 为一个 key 增加 value 的统计值。

func (*Stats) Info

func (stats *Stats) Info() []log.Info

Info 返回当前记录的所有的统计值，用于记录日志。

func (*Stats) Set

func (stats *Stats) Set(key string, value int)

Set 将 key 的统计值设置为 value。