使用 kelseyhightower/envconfig 管理 Go 环境变量配置

envconfig 是由 Kelsey Hightower 开发的一个 Go 库，它提供了一种简单的方式来管理应用程序的环境变量配置。这个库可以帮助你将环境变量自动映射到结构体字段，支持默认值、必填验证等功能。

安装

go get github.com/kelseyhightower/envconfig

基本用法

1. 定义配置结构体

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

type Config struct {
    Port        int    `default:"8080"`
    DatabaseURL string `required:"true"`
    Debug       bool   `default:"false"`
    Timeout     int    `default:"30"`
}

标签说明：

• default: 设置默认值
• required:"true": 表示该字段必须提供

2. 解析环境变量

package main

import (
    "fmt"
    "log"
    
    "github.com/kelseyhightower/envconfig"
)

type Config struct {
    Port        int    `default:"8080"`
    DatabaseURL string `required:"true"`
    Debug       bool   `default:"false"`
    Timeout     int    `default:"30"`
}

func main() {
    var cfg Config
    err := envconfig.Process("myapp", &cfg)
    if err != nil {
        log.Fatal(err.Error())
    }
    
    fmt.Printf("Port: %d\n", cfg.Port)
    fmt.Printf("DatabaseURL: %s\n", cfg.DatabaseURL)
    fmt.Printf("Debug: %t\n", cfg.Debug)
    fmt.Printf("Timeout: %d\n", cfg.Timeout)
}

3. 设置环境变量

在运行程序前设置环境变量：

export MYAPP_DATABASEURL="postgres://user:pass@localhost/dbname"
# 其他变量使用默认值

或者全部设置：

export MYAPP_PORT=9090
export MYAPP_DATABASEURL="postgres://user:pass@localhost/dbname"
export MYAPP_DEBUG=true
export MYAPP_TIMEOUT=60

高级特性

1. 自定义前缀

Process 方法的第一个参数是环境变量前缀，设置为空字符串表示不使用前缀：

err := envconfig.Process("", &cfg)  // 直接使用 PORT, DATABASE_URL 等变量名

2. 嵌套结构体

type Config struct {
    Port    int    `default:"8080"`
    Database struct {
        URL      string `required:"true"`
        PoolSize int    `default:"10"`
    }
}

// 环境变量:
// MYAPP_DATABASE_URL
// MYAPP_DATABASE_POOLSIZE

3. 切片支持

type Config struct {
    Hosts []string `default:"localhost,127.0.0.1"`
}

// 环境变量:
// MYAPP_HOSTS="host1,host2,host3"

4. 自定义分隔符

默认使用逗号分隔切片，可以自定义：

type Config struct {
    Hosts []string `envconfig:"HOSTS" default:"localhost|127.0.0.1" delimiter:"|"`
}

5. 自定义变量名

type Config struct {
    DBURL string `envconfig:"DATABASE_URL" required:"true"`
}

// 使用 DATABASE_URL 而不是 DBURL

完整示例

package main

import (
    "fmt"
    "log"
    "time"
    
    "github.com/kelseyhightower/envconfig"
)

type Config struct {
    Port        int           `default:"8080"`
    Timeout     time.Duration `default:"30s"`
    DatabaseURL string        `required:"true"`
    Debug       bool          `default:"false"`
    
    Redis struct {
        Host     string `default:"localhost"`
        Port     int    `default:"6379"`
        Password string `default:""`
    }
    
    AllowedOrigins []string `default:"http://localhost,https://example.com"`
}

func main() {
    var cfg Config
    err := envconfig.Process("myapp", &cfg)
    if err != nil {
        log.Fatal(err.Error())
    }
    
    fmt.Printf("Server will run on port %d\n", cfg.Port)
    fmt.Printf("Timeout: %v\n", cfg.Timeout)
    fmt.Printf("Database URL: %s\n", cfg.DatabaseURL)
    fmt.Printf("Debug mode: %t\n", cfg.Debug)
    fmt.Printf("Redis: %s:%d\n", cfg.Redis.Host, cfg.Redis.Port)
    fmt.Printf("Allowed origins: %v\n", cfg.AllowedOrigins)
}

环境变量设置示例

export MYAPP_PORT=9090
export MYAPP_TIMEOUT=60s
export MYAPP_DATABASEURL="postgres://user:pass@localhost/db"
export MYAPP_DEBUG=true
export MYAPP_REDIS_HOST="redis.example.com"
export MYAPP_REDIS_PORT=6380
export MYAPP_ALLOWEDORIGINS="https://app.com,https://api.app.com"

优点

1. 类型安全：自动将环境变量转换为正确的Go类型
2. 默认值支持：可以为字段设置默认值
3. 必填验证：确保关键配置不会缺失
4. 嵌套结构支持：支持复杂的配置结构
5. 命名灵活：支持自定义环境变量名

envconfig 是一个轻量级但功能强大的配置管理库，特别适合12-factor应用的环境变量配置管理。