Golang环境变量解析与结构体映射插件库env的使用

env是一个用于Go的环境变量工具包，它提供了简单的函数来获取和设置环境变量，包括支持将环境变量解组到结构体中，支持嵌套结构、默认值和必填字段。

功能特性

• 基本获取/设置：简单的获取、设置和取消设置环境变量的函数
• 类型转换：将环境变量作为不同类型（int、bool、float）获取的函数
• 回退值：支持在环境变量未设置时使用回退值
• 解组：使用结构体标签将环境变量加载到结构体中
• 嵌套结构体：支持嵌套结构体前缀来分组环境变量

安装

go get github.com/syntaqx/env

基本使用

package main

import (
    "fmt"
    "github.com/syntaqx/env"
)

func main() {
    port := env.GetWithFallback("PORT", "8080")
    fmt.Printf("Port: %s\n", port)

    // 假设HOSTS的值是一个逗号分隔的字符串列表
    // 例如: some-host:8000,another-host:8000
    hosts, err := env.GetStringSliceWithFallback("HOSTS", []string{"fallback-host-1:8000", "fallback-host-2:8000"})
    if err != nil {
        fmt.Printf("Error getting hosts: %v\n", err)
    } else {
        fmt.Printf("Hosts: %v\n", hosts)
    }
}

解组到结构体

Unmarshal函数允许你基于结构体标签将环境变量加载到结构体中。你可以使用default或fallback作为回退值，使用required来强制要求必须设置环境变量。

package main

import (
    "fmt"
    "log"

    "github.com/syntaqx/env"
)

type DatabaseConfig struct {
    Host     string `env:"DATABASE_HOST,default=localhost"`
    Port     int    `env:"DATABASE_PORT|DB_PORT,fallback=3306"`
    Username string `env:"DATABASE_USERNAME,default=root"`
    Password string `env:"DATABASE_PASSWORD,required"`
    Database string `env:"DATABASE_NAME"`
}

type Config struct {
    Debug    bool           `env:"DEBUG"`
    Port     string         `env:"PORT,default=8080"`
    Database DatabaseConfig
}

func main() {
    var cfg Config

    // 设置示例环境变量
    _ = env.Set("DEBUG", "true")
    _ = env.Set("PORT", "9090")
    _ = env.Set("DATABASE_HOST", "dbhost")
    _ = env.Set("DATABASE_PORT", "5432")
    _ = env.Set("DATABASE_USERNAME", "admin")
    _ = env.Set("DATABASE_PASSWORD", "secret")
    _ = env.Set("DATABASE_NAME", "mydb")

    if err := env.Unmarshal(&cfg); err != nil {
        log.Fatalf("Error unmarshalling config: %v", err)
    }

    fmt.Printf("Config: %+v\n", cfg)
}

嵌套结构体前缀

你可以使用嵌套前缀来分组环境变量。这允许你在多个地方重用相同的结构体，而不必担心环境变量冲突。

package main

import (
    "fmt"
    "log"

    "github.com/syntaqx/env"
)

type DatabaseConfig struct {
    Host     string `env:"HOST,default=localhost"`
    Port     int    `env:"PORT,fallback=3306"`
    Username string `env:"USERNAME,default=root"`
    Password string `env:"PASSWORD,required"`
    Database string `env:"NAME"`
}

type Config struct {
    Debug         bool           `env:"DEBUG"`
    Port          string         `env:"PORT,default=8080"`
    ReadDatabase  DatabaseConfig `env:"READ_DATABASE"`
    WriteDatabase DatabaseConfig `env:"WRITE_DATABASE"`
}

func main() {
    var cfg Config

    // 设置示例环境变量
    _ = env.Set("DEBUG", "true")
    _ = env.Set("PORT", "9090")
    _ = env.Set("READ_DATABASE_HOST", "read-dbhost")
    _ = env.Set("READ_DATABASE_PORT", "5432")
    _ = env.Set("READ_DATABASE_USERNAME", "read-admin")
    _ = env.Set("READ_DATABASE_PASSWORD", "read-secret")
    _ = env.Set("READ_DATABASE_NAME", "read-mydb")
    _ = env.Set("WRITE_DATABASE_HOST", "write-dbhost")
    _ = env.Set("WRITE_DATABASE_PORT", "5432")
    _ = env.Set("WRITE_DATABASE_USERNAME", "write-admin")
    _ = env.Set("WRITE_DATABASE_PASSWORD", "write-secret")
    _ = env.Set("WRITE_DATABASE_NAME", "write-mydb")

    if err := env.Unmarshal(&cfg); err != nil {
        log.Fatalf("Error unmarshalling config: %v", err)
    }

    fmt.Printf("Config: %+v\n", cfg)
}

切片类型默认值

当使用切片类型时，如果你声明单个值作为默认值，可以像平常一样使用default标签：

type Config struct {
    Hosts []string `env:"HOSTS,default=localhost"`
}

但是如果你想声明多个值作为默认值，必须将值括在方括号中：

type Config struct {
    Hosts []string `env:"HOSTS,default=[localhost,localhost2]"`
}

代码中的默认值

你也可以通过在代码中初始化结构体数据来定义默认值，然后再由env.Unmarshal填充。但是，定义为结构体标签的默认值将优先于代码中定义的默认值。

type Config struct {
    Username string `env:"USERNAME,default=admin"`
    Password string `env:"PASSWORD"`
}

cfg := Config{
    Username: "test",
    Password: "password123",
}

if err := env.Unmarshal(&cfg); err != nil {
    log.Fatalf("Error unmarshalling config: %v", err)
}

// { Username: "admin", Password: "password123" }

从文件读取

file标签选项可用于指示变量的值应从文件中加载。文件的路径由变量的值给出。

echo "password123" > /run/secrets/password

type Config struct {
    Username string `env:"USERNAME"`
    Password string `env:"PASSWORD,file"`
}

cfg := Config{
    Username: "test",
    Password: "/run/secrets/password",
}

if err := env.Unmarshal(&cfg); err != nil {
    log.Fatalf("Error unmarshalling config: %v", err)
}

// { "Username": "test", "Password": "password123" }

扩展变量

expand标签选项可用于指示变量的值应在设置前扩展（以${var}或$var格式）。

type Config struct {
    Username string `env:"USERNAME,expand"`
    Password string `env:"PASSWORD,expand"`
}

这与default标签选项配合使用效果很好：

type Config struct {
    Address string `env:"ADDRESS,expand,default=${HOST}:${PORT}"`
}

此外，默认值可以从其他结构体字段引用。允许你在环境变量未设置时链接默认值，而不是回退到空值：

type Config struct {
    Host string `env:"HOST,default=localhost"`
    Port string `env:"PORT,default=8080"`
    Address string `env:"ADDRESS,expand,default=${HOST}:${PORT}"`
}

贡献

欢迎提出问题或为项目做贡献。贡献总是受欢迎的！

许可证

本项目采用MIT许可证。