Cleanenv：轻量级Go配置文件读取库

Cleanenv是一个轻量级的Go语言配置文件读取库，它支持多种格式的配置文件，包括JSON、YAML、TOML、ENV等，并提供了简洁的API来读取和解析配置。

主要特性

• 支持多种配置文件格式：JSON、YAML、TOML、ENV
• 支持环境变量覆盖配置
• 支持默认值设置
• 简洁易用的API
• 轻量级，无额外依赖

安装

go get github.com/ilyakaznacheev/cleanenv@latest

基本使用

1. 定义配置结构体

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

type Config struct {
    Port     int    `yaml:"port" env:"PORT" env-default:"8080"`
    LogLevel string `yaml:"log_level" env:"LOG_LEVEL" env-default:"info"`
    DB       struct {
        Host     string `yaml:"host" env:"DB_HOST" env-default:"localhost"`
        Port     int    `yaml:"port" env:"DB_PORT" env-default:"5432"`
        Name     string `yaml:"name" env:"DB_NAME" env-default:"postgres"`
        User     string `yaml:"user" env:"DB_USER" env-default:"postgres"`
        Password string `yaml:"password" env:"DB_PASSWORD" env-default:""`
    } `yaml:"db"`
}

标签说明：

• yaml：指定YAML文件中的字段名
• env：指定环境变量名
• env-default：设置默认值

2. 读取配置文件

package main

import (
    "fmt"
    "log"

    "github.com/ilyakaznacheev/cleanenv"
)

func main() {
    var cfg Config
    
    // 从config.yaml读取配置
    err := cleanenv.ReadConfig("config.yaml", &cfg)
    if err != nil {
        log.Fatalf("cannot read config: %s", err)
    }
    
    fmt.Printf("Port: %d\n", cfg.Port)
    fmt.Printf("Log Level: %s\n", cfg.LogLevel)
    fmt.Printf("DB Host: %s\n", cfg.DB.Host)
}

3. 环境变量覆盖

Cleanenv会自动检查环境变量，如果找到匹配的环境变量，会覆盖配置文件中的值。

例如，设置环境变量：

export PORT=9090
export DB_HOST=db.example.com

然后运行程序，这些值会覆盖配置文件中的设置。

4. 仅使用环境变量

如果你只想使用环境变量而不需要配置文件：

var cfg Config
err := cleanenv.ReadEnv(&cfg)
if err != nil {
    log.Fatalf("cannot read env: %s", err)
}

5. 生成配置文档

Cleanenv可以生成配置文档，方便查看所有可用的配置项：

help, err := cleanenv.GetDescription(&cfg, nil)
if err != nil {
    log.Fatalf("cannot generate config help: %s", err)
}
fmt.Println(help)

高级用法

自定义配置文件路径

// 从指定路径读取配置
err := cleanenv.ReadConfig("/path/to/config.yml", &cfg)

支持多种文件格式

Cleanenv会自动根据文件扩展名识别格式：

• .yaml, .yml - YAML
• .json - JSON
• .toml - TOML
• .env - ENV

必填字段验证

type Config struct {
    APIKey string `yaml:"api_key" env:"API_KEY" env-required:"true"`
}

如果设置了env-required:"true"且该字段为空，会返回错误。

完整示例

package main

import (
    "fmt"
    "log"
    "os"

    "github.com/ilyakaznacheev/cleanenv"
)

type Config struct {
    AppName string `yaml:"app_name" env:"APP_NAME" env-default:"MyApp"`
    Port    int    `yaml:"port" env:"PORT" env-default:"8080"`
    Debug   bool   `yaml:"debug" env:"DEBUG" env-default:"false"`
    
    Database struct {
        Host     string `yaml:"host" env:"DB_HOST" env-default:"localhost"`
        Port     int    `yaml:"port" env:"DB_PORT" env-default:"5432"`
        Username string `yaml:"username" env:"DB_USER" env-default:"user"`
        Password string `yaml:"password" env:"DB_PASSWORD" env-required:"true"`
    } `yaml:"database"`
}

func main() {
    var cfg Config
    
    // 尝试从config.yaml读取配置
    err := cleanenv.ReadConfig("config.yaml", &cfg)
    if err != nil {
        // 如果文件不存在，尝试仅从环境变量读取
        if os.IsNotExist(err) {
            log.Println("config file not found, using environment variables only")
            err = cleanenv.ReadEnv(&cfg)
            if err != nil {
                log.Fatalf("cannot read env: %s", err)
            }
        } else {
            log.Fatalf("cannot read config: %s", err)
        }
    }
    
    // 打印配置
    fmt.Printf("App Name: %s\n", cfg.AppName)
    fmt.Printf("Port: %d\n", cfg.Port)
    fmt.Printf("Debug Mode: %t\n", cfg.Debug)
    fmt.Printf("Database Host: %s\n", cfg.Database.Host)
    fmt.Printf("Database Port: %d\n", cfg.Database.Port)
    fmt.Printf("Database Username: %s\n", cfg.Database.Username)
    
    // 生成并打印配置帮助
    help, err := cleanenv.GetDescription(&cfg, nil)
    if err != nil {
        log.Printf("cannot generate config help: %s", err)
    } else {
        fmt.Println("\nConfiguration help:")
        fmt.Println(help)
    }
}

总结

Cleanenv是一个简单而强大的Go配置管理库，它提供了：

1. 多格式配置文件支持
2. 环境变量覆盖机制
3. 默认值设置
4. 必填字段验证
5. 自动生成的配置文档

对于需要轻量级配置管理的Go项目，Cleanenv是一个很好的选择，它避免了复杂配置框架的臃肿，同时提供了足够的灵活性。