Golang基于环境变量递归实例化配置结构体的插件库Swap使用指南

简介

Swap是一个Golang库，可以根据构建环境动态实例化和配置结构体，以及递归解析配置文件到结构体中。它可以帮助你保持项目和配置文件的组织性和可维护性，同时提高生产力。

安装

import "github.com/oblq/swap"

快速开始

假设有以下项目结构：

├── config
│   ├── Tool1.yaml
│   ├── Tool1.production.yaml
│   ├── Tool2.yaml
│   ├── Tool3.yaml
│   └── Tool4.yaml
└── main.go

我们可以加载一个结构体，并根据当前构建环境使用正确的配置文件配置其字段：

// main.go

import (
    "reflect"

    "github.com/oblq/swap"
)

// 共享单例
var ToolBox struct {
    // 默认情况下，swap会查找与结构体字段名相同的文件(Tool1.*，区分大小写)
    // 可选地通过标签传递一个或多个配置文件名，
    // 它们将被添加到工厂方法中传递的配置文件中
    // 可以省略文件扩展名
    Tool1 tools.ToolConfigurable
    Tool2 tools.ToolWFactory `swap:"Tool3|Tool4"`
    Tool3 tools.ToolRegistered
    Tool4 tools.ToolNotRecognized

    Nested1 struct {
        Tool1   tools.ToolConfigurable
        Nested2 struct {
            Tool2   tools.ToolConfigurable
            Nested3 struct {
                Tool3 tools.ToolConfigurable
            }
        }
    }

    // 添加'-'值可以跳过该字段
    OmittedTool        tools.ToolConfigurable `swap:"-"`
}

func init() {
    // 获取给定配置路径的新Builder实例
    builder := swap.NewBuilder("./config")

    // 为`tools.ToolRegistered`类型注册一个`FactoryFunc`
    builder.RegisterType(reflect.TypeOf(tools.ToolRegistered{}),
        func(configFiles ...string) (i interface{}, err error) {
            instance := &tools.Tool{}
            err = swap.Parse(&instance, configFiles...)
            return instance, err
        })

    // 手动将当前构建环境强制设置为`production`
    // 这样生产配置文件(如果存在)将与默认配置文件一起传递给构造函数/配置函数
    // 但会在之后传递，因此它将覆盖先前传递的参数
    builder.EnvHandler.SetCurrent("production")

    // 构建ToolBox
    if err := builder.Build(&ToolBox); err != nil {
        panic(err)
    }
}

Builder

Builder是一种Director模式的实现，它递归地构建和/或配置给定结构体的每个字段。它必须使用包含配置文件的路径进行初始化，并且可以选择使用自定义的EnvironmentHandler：

// 获取给定配置路径的新Builder实例
builder := swap.NewBuilder("./config")

// 可选设置自定义EnvironmentHandler
envHandler := swap.NewEnvironmentHandler(swap.DefaultEnvs.Slice())
builder = builder.WithCustomEnvHandler(envHandler)

结构体字段可以通过以下方式自动"创建"或"配置"：

1. 实现swap.Factory接口：

// Factory是抽象工厂接口
type Factory interface {
    New(configFiles ...string) (interface{}, error)
}

// 例如：
func (t *Tool) New(configFiles ...string) (i interface{}, err error) {
    instance := &Tool{}
    err = swap.Parse(&instance, configFiles...)
    return instance, err
}

1. 实现swap.Configurable接口：

// Configurable接口允许自动初始化为零值的字段的配置
type Configurable interface {
    Configure(configFiles ...string) error
}

// 例如：
func (t *Tool) Configure(configFiles ...string) (err error) {
    return swap.Parse(t, configFiles...)
}

1. 为该特定字段类型注册了swap.FactoryFunc：

// 为`Tool`类型注册`FactoryFunc`
builder.RegisterType(reflect.TypeOf(Tool{}),
    func(configFiles ...string) (i interface{}, err error) {
        instance := &Tool{}
        err = swap.Parse(&instance, configFiles...)
        return instance, err
    })

EnvironmentHandler

EnvironmentHandler使用环境列表([]*Environment)初始化，当前环境通过将标签与其特定的正则表达式匹配来确定。

提供了五个标准构建环境以便使用：

// 默认环境配置
var DefaultEnvs = defaultEnvs{
    Production:  NewEnvironment("production", `(production)|(master)|(^v(0|[1-9]+)(\.(0|[1-9]+)+)?(\.(\*|(0|[1-9]+)+))?$)`),
    Staging:     NewEnvironment("staging", `(staging)|(release/*)|(hotfix/*)|(bugfix/*)`),
    Testing:     NewEnvironment("testing", `(testing)|(test)`),
    Development: NewEnvironment("development", `(development)|(develop)|(dev)|(feature/*)`),
    Local:       NewEnvironment("local", `local`),
}

ConfigParser (无感知、分层配置解析)

Swap实现了两个配置解析函数：

• swap.Parse()
• swap.ParseByEnv()

两者都使用三个特定的结构体字段标签：

• `swapcp:"default=<default_value>"` 提供一个默认值，如果解析的配置文件没有提供该值，将使用默认值
• `swapcp:"env=<system_environment_var_name>"` 将从环境变量中获取值(如果存在)，覆盖配置文件提供的值和/或默认值
• `swapcp:"required"` 如果没有为该字段提供值，将返回错误

完整示例

package main

import (
	"fmt"
	"os"
	"reflect"

	"github.com/oblq/swap"
)

// 定义一个可配置的工具结构体
type Tool struct {
	Name string `yaml:"name"`
	Port int    `yaml:"port"`
}

// 实现swap.Configurable接口
func (t *Tool) Configure(configFiles ...string) error {
	return swap.Parse(t, configFiles...)
}

// 主配置结构体
var Config struct {
	Database struct {
		Host     string `swapcp:"env=DB_HOST,default=localhost"`
		Port     int    `swapcp:"env=DB_PORT,default=5432"`
		User     string `swapcp:"env=DB_USER,required"`
		Password string `swapcp:"env=DB_PASSWORD,required"`
	}

	Tools struct {
		Tool1 Tool
		Tool2 Tool `swap:"custom_tool_config"`
	}
}

func main() {
	// 设置环境变量
	_ = os.Setenv("DB_USER", "admin")
	_ = os.Setenv("DB_PASSWORD", "secret")

	// 创建builder实例
	builder := swap.NewBuilder("./config")

	// 注册Tool类型的工厂函数
	builder.RegisterType(reflect.TypeOf(Tool{}),
		func(configFiles ...string) (interface{}, error) {
			instance := &Tool{}
			err := swap.Parse(instance, configFiles...)
			return instance, err
		})

	// 构建配置
	if err := builder.Build(&Config); err != nil {
		fmt.Printf("Error building config: %v\n", err)
		return
	}

	// 打印配置
	fmt.Printf("Database config: %+v\n", Config.Database)
	fmt.Printf("Tool1 config: %+v\n", Config.Tools.Tool1)
	fmt.Printf("Tool2 config: %+v\n", Config.Tools.Tool2)
}

假设有以下配置文件：

config/Database.yaml:

host: db.example.com
port: 3306

config/Tool1.yaml:

name: Tool One
port: 8080

config/custom_tool_config.yaml:

name: Custom Tool
port: 9090

运行程序后，输出将显示从配置文件和环境变量合并的配置值。

Swap是一个强大的配置管理工具，特别适合需要根据不同环境(开发、测试、生产等)动态加载配置的应用程序。