Golang 环境变量解析到结构体 - env 库使用指南

在 Go 开发中，将环境变量解析到结构体是一种常见的配置管理方式。env 是一个流行的 Go 库，可以方便地将环境变量映射到结构体字段。下面我将详细介绍如何使用这个库。

安装 env 库

首先需要安装 env 库：

go get github.com/caarlos0/env/v7

基本用法

1. 定义配置结构体

package main

import (
	"fmt"
	"time"
	
	"github.com/caarlos0/env/v7"
)

type Config struct {
	Home         string        `env:"HOME"`
	Port         int           `env:"PORT" envDefault:"3000"`
	Password     string        `env:"PASSWORD,required"`
	IsProduction bool          `env:"PRODUCTION"`
	Hosts        []string      `env:"HOSTS" envSeparator:":"`
	Duration     time.Duration `env:"DURATION"`
	TempFolder   string        `env:"TEMP_FOLDER" envDefault:"${HOME}/tmp"`
}

2. 解析环境变量到结构体

func main() {
	cfg := Config{}
	if err := env.Parse(&cfg); err != nil {
		fmt.Printf("%+v\n", err)
	}
	
	fmt.Printf("%+v\n", cfg)
}

标签说明

• env:"VAR_NAME" - 指定环境变量名
• envDefault:"value" - 设置默认值
• required - 标记该字段为必填
• envSeparator:":" - 指定切片类型的分隔符
• unset - 解析后从环境中删除该变量

高级用法

1. 自定义解析器

type CustomType struct {
	Value string
}

func (c *CustomType) UnmarshalText(text []byte) error {
	c.Value = string(text) + "-custom"
	return nil
}

type Config struct {
	Custom CustomType `env:"CUSTOM"`
}

func main() {
	os.Setenv("CUSTOM", "value")
	
	cfg := Config{}
	if err := env.Parse(&cfg); err != nil {
		panic(err)
	}
	
	fmt.Println(cfg.Custom.Value) // 输出: value-custom
}

2. 嵌套结构体

type NestedConfig struct {
	Foo string `env:"FOO"`
	Bar int    `env:"BAR"`
}

type Config struct {
	Nested NestedConfig `envPrefix:"NESTED_"`
}

func main() {
	os.Setenv("NESTED_FOO", "foo")
	os.Setenv("NESTED_BAR", "42")
	
	cfg := Config{}
	if err := env.Parse(&cfg); err != nil {
		panic(err)
	}
	
	fmt.Printf("%+v\n", cfg.Nested) // 输出: {Foo:foo Bar:42}
}

3. 环境变量扩展

type Config struct {
	Home       string `env:"HOME"`
	ConfigPath string `env:"CONFIG_PATH" envDefault:"${HOME}/.config/app"`
}

func main() {
	cfg := Config{}
	if err := env.Parse(&cfg); err != nil {
		panic(err)
	}
	
	fmt.Println(cfg.ConfigPath) // 输出类似: /home/user/.config/app
}

完整示例

package main

import (
	"fmt"
	"log"
	"os"
	"time"
	
	"github.com/caarlos0/env/v7"
)

type Config struct {
	AppName      string        `env:"APP_NAME" envDefault:"MyApp"`
	Debug        bool          `env:"DEBUG"`
	Port         int           `env:"PORT" envDefault:"8080"`
	Timeout      time.Duration `env:"TIMEOUT" envDefault:"30s"`
	DatabaseURL  string        `env:"DATABASE_URL,required"`
	AllowedHosts []string      `env:"ALLOWED_HOSTS" envSeparator:","`
	FeatureFlags struct {
		NewUI    bool `env:"FEATURE_NEW_UI"`
		DarkMode bool `env:"FEATURE_DARK_MODE" envDefault:"true"`
	} `envPrefix:"FEATURE_"`
}

func main() {
	// 设置一些环境变量(实际使用时从系统环境变量获取)
	os.Setenv("DATABASE_URL", "postgres://user:pass@localhost:5432/db")
	os.Setenv("ALLOWED_HOSTS", "localhost,127.0.0.1,example.com")
	os.Setenv("FEATURE_NEW_UI", "true")
	
	var cfg Config
	if err := env.Parse(&cfg); err != nil {
		log.Fatalf("Failed to parse config: %v", err)
	}
	
	fmt.Printf("Config: %+v\n", cfg)
	fmt.Printf("AppName: %s\n", cfg.AppName)
	fmt.Printf("Port: %d\n", cfg.Port)
	fmt.Printf("DatabaseURL: %s\n", cfg.DatabaseURL)
	fmt.Printf("AllowedHosts: %v\n", cfg.AllowedHosts)
	fmt.Printf("FeatureFlags - NewUI: %v, DarkMode: %v\n", 
		cfg.FeatureFlags.NewUI, cfg.FeatureFlags.DarkMode)
}

注意事项

1. 结构体字段必须是可导出的(首字母大写)
2. 对于必填字段(required)，如果未设置会返回错误
3. 默认值仅在环境变量未设置时使用
4. 支持基本类型、切片、嵌套结构体和自定义类型

env 库提供了一种简洁、类型安全的方式来管理应用程序配置，特别适合12-factor应用开发。通过结构体标签，可以清晰地表达配置需求，使代码更易于维护和理解。

希望这个指南能帮助你有效地使用 env 库来管理 Go 应用程序的环境变量配置！