aconfig - Golang 配置加载器插件库使用指南

aconfig 是一个简单实用的 Golang 配置加载器库，支持从多种来源加载配置，包括环境变量、命令行参数、JSON/YAML 文件等。下面我将详细介绍其使用方法。

安装

go get github.com/cristalhq/aconfig

基本用法

1. 定义配置结构

首先定义一个结构体来表示你的配置：

type Config struct {
    Port     int    `default:"8080" env:"PORT" flag:"port" usage:"port to listen on"`
    LogLevel string `default:"info" env:"LOG_LEVEL" flag:"log-level" usage:"log level"`
    DBURL    string `required:"true" env:"DB_URL" flag:"db-url" usage:"database connection string"`
}

标签说明：

• default: 默认值
• env: 环境变量名
• flag: 命令行参数名
• usage: 帮助信息
• required: 是否为必填项

2. 加载配置

package main

import (
    "fmt"
    "github.com/cristalhq/aconfig"
)

func main() {
    var cfg Config
    
    // 创建加载器
    loader := aconfig.LoaderFor(&cfg, aconfig.Config{
        SkipFlags: false, // 是否跳过命令行参数解析
        SkipEnv:   false, // 是否跳过环境变量解析
        Files:     []string{"./config.json", "./config.yaml"}, // 配置文件路径
        FileDecoders: map[string]aconfig.FileDecoder{
            ".json": aconfig.JSONDecoder,
            ".yaml": aconfig.YAMLDecoder,
        },
    })
    
    // 加载配置
    if err := loader.Load(); err != nil {
        panic(err)
    }
    
    fmt.Printf("Config: %+v\n", cfg)
}

高级用法

1. 自定义文件加载器

loader := aconfig.LoaderFor(&cfg, aconfig.Config{
    Files: []string{"./config.toml"},
    FileDecoders: map[string]aconfig.FileDecoder{
        ".toml": func(bytes []byte) (map[string]interface{}, error) {
            var data map[string]interface{}
            if err := toml.Unmarshal(bytes, &data); err != nil {
                return nil, err
            }
            return data, nil
        },
    },
})

2. 自定义环境变量前缀

loader := aconfig.LoaderFor(&cfg, aconfig.Config{
    EnvPrefix: "MYAPP_", // 环境变量前缀
})

这样会查找 MYAPP_PORT 而不是 PORT

3. 从多个来源合并配置

aconfig 会按照以下顺序加载配置，后面的会覆盖前面的：

1. 结构体中的默认值
2. 配置文件中的值
3. 环境变量
4. 命令行参数

4. 验证配置

if err := loader.Load(); err != nil {
    if errors.Is(err, aconfig.ErrRequiredNotSet) {
        fmt.Println("Missing required configuration")
    }
    panic(err)
}

完整示例

package main

import (
    "fmt"
    "github.com/cristalhq/aconfig"
)

type Config struct {
    Host     string `default:"localhost" env:"HOST" flag:"host" usage:"server host"`
    Port     int    `default:"8080" env:"PORT" flag:"port" usage:"server port"`
    Debug    bool   `default:"false" env:"DEBUG" flag:"debug" usage:"debug mode"`
    Timeout  int    `default:"30" env:"TIMEOUT" flag:"timeout" usage:"request timeout in seconds"`
}

func main() {
    var cfg Config
    
    loader := aconfig.LoaderFor(&cfg, aconfig.Config{
        Files: []string{"./config.yaml", "./config.json"},
        FileDecoders: map[string]aconfig.FileDecoder{
            ".yaml": aconfig.YAMLDecoder,
            ".json": aconfig.JSONDecoder,
        },
    })
    
    if err := loader.Load(); err != nil {
        panic(err)
    }
    
    fmt.Printf("Server running on %s:%d\n", cfg.Host, cfg.Port)
    fmt.Printf("Debug mode: %v\n", cfg.Debug)
    fmt.Printf("Timeout: %d seconds\n", cfg.Timeout)
}

配置文件示例

config.yaml:

host: "0.0.0.0"
port: 9000
debug: true

或者 config.json:

{
    "host": "0.0.0.0",
    "port": 9000,
    "debug": true
}

命令行使用

编译程序后可以这样运行：

./myapp --port 9090 --debug=true

或者查看帮助：

./myapp --help

aconfig 是一个轻量级但功能强大的配置加载库，特别适合需要从多种来源加载配置的应用程序。它的设计简洁，易于集成到现有项目中。