多格式配置

env 库支持 .env、JSON、YAML 三种配置格式，可自动检测格式并加载。

格式检测

自动检测规则

扩展名	格式	常量
`.env`	.env 格式	`FormatEnv`
`.json`	JSON	`FormatJSON`
`.yaml`, `.yml`	YAML	`FormatYAML`
其他	自动	`FormatAuto`

DetectFormat 函数

format := env.DetectFormat("config.json")   // FormatJSON
format = env.DetectFormat("settings.yaml")  // FormatYAML
format = env.DetectFormat("app.yml")        // FormatYAML
format = env.DetectFormat(".env")           // FormatEnv
format = env.DetectFormat("unknown")        // FormatAuto

fmt.Println(format.String())  // "json", "yaml", "dotenv", "auto"

加载多格式文件

单一格式

loader.LoadFiles("config.env")
loader.LoadFiles("settings.json")
loader.LoadFiles("secrets.yaml")

混合格式

// 自动检测每个文件的格式
loader.LoadFiles("config.env", "settings.json", "secrets.yaml")

覆盖顺序

后加载的文件覆盖先加载的：

// 顺序：base -> env -> json -> yaml
loader.LoadFiles(
    ".env",           // 基础配置
    "config.json",    // 覆盖 .env
    "secrets.yaml",   // 覆盖 config.json
)

JSON 格式

文件结构

json

{
    "APP_NAME": "myapp",
    "APP_PORT": "8080",
    "DEBUG": "true",
    "DATABASE": {
        "HOST": "localhost",
        "PORT": "5432"
    }
}

注意

嵌套对象会被扁平化为 DATABASE_HOST、DATABASE_PORT。

键名解析

JSON/YAML 的嵌套结构会被扁平化存储。库支持多种键名访问方式：

loader.LoadFiles("config.json")

// JSON: {"database": {"host": "localhost", "port": 5432}}
// 存储为：DATABASE_HOST=localhost, DATABASE_PORT=5432

// 方式一：扁平化键名（推荐）
host := loader.GetString("DATABASE_HOST")   // localhost
port := loader.GetInt("DATABASE_PORT")      // 5432

// 方式二：点号路径（自动转换）
host := loader.GetString("database.host")   // localhost
port := loader.GetInt("database.port")      // 5432

// 方式三：大写点号路径
host := loader.GetString("DATABASE.HOST")   // localhost

解析规则：

输入键名	转换为
`"DATABASE_HOST"`	`"DATABASE_HOST"`（精确匹配）
`"database.host"`	`"DATABASE_HOST"`（点号转下划线）
`"app.config.name"`	`"APP_CONFIG_NAME"`
`"servers.0.host"`	`"SERVERS_0_HOST"`（数组索引）

推荐用法

代码中使用扁平化键名：GetString("DATABASE_HOST") - 明确、高效
配置文件中可读路径：JSON/YAML 使用自然嵌套结构

扁平化规则：

JSON 路径	存储键
`database.host`	`DATABASE_HOST`
`database.port`	`DATABASE_PORT`
`app.server.name`	`APP_SERVER_NAME`
`servers.0.host`	`SERVERS_0_HOST`

数组访问

JSON 数组会被扁平化为带索引的键：

json

{
    "servers": [
        { "host": "server1.example.com", "port": 8080 },
        { "host": "server2.example.com", "port": 8081 }
    ]
}

// 使用扁平化键名访问数组元素
host0 := loader.GetString("SERVERS_0_HOST")  // server1.example.com
port0 := loader.GetInt("SERVERS_0_PORT")     // 8080
host1 := loader.GetString("SERVERS_1_HOST")  // server2.example.com

// 使用循环获取所有主机
var hosts []string
for i := 0; ; i++ {
    h := loader.GetString(fmt.Sprintf("SERVERS_%d_HOST", i))
    if h == "" {
        break
    }
    hosts = append(hosts, h)
}
// hosts = ["server1.example.com", "server2.example.com"]

JSON 解析配置

cfg := env.DefaultConfig()

// null 值转为空字符串（默认 true）
cfg.JSONNullAsEmpty = true

// 数字转为字符串（默认 true）
cfg.JSONNumberAsString = true

// 布尔值转为字符串（默认 true）
cfg.JSONBoolAsString = true

// 最大嵌套深度（默认 10）
cfg.JSONMaxDepth = 20

类型转换示例

json

{
    "PORT": 8080,
    "DEBUG": true,
    "TIMEOUT": 30,
    "RATES": [0.1, 0.2, 0.3]
}

// JSONNumberAsString = true（默认）
port := loader.GetString("PORT")  // "8080"（字符串）
port := loader.GetInt("PORT")     // 8080（整数）

// JSONBoolAsString = true（默认）
debug := loader.GetString("DEBUG")  // "true"（字符串）
debug := loader.GetBool("DEBUG")    // true（布尔）

YAML 格式

文件结构

yaml

# 应用配置
APP_NAME: myapp
APP_PORT: "8080"
DEBUG: true

# 数据库配置
DATABASE:
  HOST: localhost
  PORT: "5432"
  USER: postgres
  PASSWORD: secret

# 列表值
ALLOWED_HOSTS:
  - localhost
  - example.com

键名解析

YAML 的嵌套结构与 JSON 使用相同的扁平化规则：

loader.LoadFiles("config.yaml")

// 使用扁平化键名访问
host := loader.GetString("DATABASE_HOST")        // localhost
user := loader.GetString("DATABASE_USER")        // postgres

数组访问

YAML 列表被扁平化为带索引的键：

yaml

servers:
  - host: server1.example.com
    port: 8080
  - host: server2.example.com
    port: 8081

// 使用扁平化键名访问
host0 := loader.GetString("SERVERS_0_HOST")  // server1.example.com
port0 := loader.GetInt("SERVERS_0_PORT")     // 8080
host1 := loader.GetString("SERVERS_1_HOST")  // server2.example.com

// 获取整个列表
hosts := env.GetSliceFrom[string](loader, "ALLOWED_HOSTS") // ["localhost", "example.com"]

YAML 解析配置

cfg := env.DefaultConfig()

// null/~ 值转为空字符串（默认 true）
cfg.YAMLNullAsEmpty = true

// 数字转为字符串（默认 true）
cfg.YAMLNumberAsString = true

// 布尔值转为字符串（默认 true）
cfg.YAMLBoolAsString = true

// 最大嵌套深度（默认 10）
cfg.YAMLMaxDepth = 15

类型转换示例

yaml

PORT: 8080
DEBUG: true
TIMEOUT: 30
RATES:
  - 0.1
  - 0.2
  - 0.3

// YAMLNumberAsString = true（默认）
port := loader.GetString("PORT")  // "8080"（字符串）
port := loader.GetInt("PORT")     // 8080（整数）

// YAMLBoolAsString = true（默认）
debug := loader.GetString("DEBUG")  // "true"（字符串）
debug := loader.GetBool("DEBUG")    // true（布尔）

// 列表访问
rates := env.GetSliceFrom[float64](loader, "RATES")  // [0.1, 0.2, 0.3]

.env 格式

文件结构

bash

# 注释
APP_NAME=myapp
APP_PORT=8080
DEBUG=true

# 引号
MESSAGE="Hello World"
LITERAL='literal ${noexpand}'

# 变量展开
BASE_URL=https://api.example.com
API_URL=${BASE_URL}/v1

# 日志级别
LOG_LEVEL=info

变量展开

cfg := env.DefaultConfig()
cfg.ExpandVariables = true  // 默认启用

loader, _ := env.New(cfg)
loader.LoadFiles(".env")

// .env 内容：
// BASE_URL=https://api.example.com
// API_URL=${BASE_URL}/v1

apiURL := loader.GetString("API_URL")
// 输出：https://api.example.com/v1

展开语法

语法	说明
`${VAR}`	引用变量
`${VAR:-default}`	变量不存在时使用默认值

bash

# 展开示例
HOST=localhost
PORT=8080

# 引用其他变量
URL=http://${HOST}:${PORT}

# 默认值（引用其他变量，未定义时使用默认值）
TIMEOUT_VALUE=${TIMEOUT:-30s}
DEBUG_VALUE=${DEBUG:-false}

export 语法

bash

# 支持 export 前缀（AllowExportPrefix = true 时）
export DATABASE_HOST=localhost
export DATABASE_PORT=5432

YAML 风格语法

cfg := env.DefaultConfig()
cfg.AllowYamlSyntax = true  // 启用 YAML 风格

bash

# 支持 YAML 风格键值对
KEY: value
ANOTHER_KEY: "quoted value"

混合配置模式

开发/生产分离

text

config/
├── base.json          # 基础配置
├── development.env    # 开发覆盖
├── production.yaml    # 生产覆盖
└── local.env          # 本地覆盖（不提交）

func loadConfig(loader *env.Loader) error {
    // 1. 基础配置
    if err := loader.LoadFiles("config/base.json"); err != nil {
        return err
    }

    // 2. 环境配置
    env := os.Getenv("APP_ENV")
    if env == "" {
        env = "development"
    }

    switch env {
    case "production":
        if err := loader.LoadFiles("config/production.yaml"); err != nil {
            return err
        }
    default:
        if err := loader.LoadFiles("config/development.env"); err != nil {
            return err
        }
    }

    // 3. 本地覆盖（可选）
    if _, err := os.Stat("config/local.env"); err == nil {
        if err := loader.LoadFiles("config/local.env"); err != nil {
            return err
        }
    }

    return nil
}

按功能分离

text

config/
├── app.json       # 应用配置
├── database.yaml  # 数据库配置
├── redis.env      # Redis 配置
└── secrets.json   # 密钥配置

loader.LoadFiles(
    "config/app.json",
    "config/database.yaml",
    "config/redis.env",
    "config/secrets.json",
)

配置优先级

text

命令行参数 > 环境变量 > local 配置 > 环境配置 > base 配置

序列化

Marshal

将配置序列化为指定格式。先准备数据，再按目标格式调用 env.Marshal：

data := map[string]string{
    "HOST": "localhost",
    "PORT": "8080",
}

.env（默认）JSONYAML

envStr, _ := env.Marshal(data)
// HOST=localhost
// PORT=8080

jsonStr, _ := env.Marshal(data, env.FormatJSON)
// {
//   "HOST": "localhost",
//   "PORT": 8080
// }

yamlStr, _ := env.Marshal(data, env.FormatYAML)
// HOST: localhost
// PORT: 8080

Marshal 结构体

type Config struct {
    Host string `env:"HOST"`
    Port int    `env:"PORT"`
}

cfg := Config{Host: "localhost", Port: 8080}

转 .env转 JSON转 YAML

envStr, _ := env.Marshal(cfg, env.FormatEnv)

jsonStr, _ := env.Marshal(cfg, env.FormatJSON)

yamlStr, _ := env.Marshal(cfg, env.FormatYAML)

UnmarshalMap

反序列化为 map：

从 .env从 JSON从 YAML

envData := "HOST=localhost\nPORT=8080"
data, _ := env.UnmarshalMap(envData, env.FormatEnv)

jsonData := `{"HOST":"localhost","PORT":"8080"}`
data, _ := env.UnmarshalMap(jsonData, env.FormatJSON)

yamlData := "HOST: localhost\nPORT: \"8080\""
data, _ := env.UnmarshalMap(yamlData, env.FormatYAML)

自动检测格式

传入 env.FormatAuto 可让库按内容自动判断格式：data, _ := env.UnmarshalMap(jsonData, env.FormatAuto)。

UnmarshalStruct

反序列化到结构体：

type Config struct {
    Host string `env:"HOST"`
    Port int    `env:"PORT"`
}

var cfg Config

从 .env从 JSON从 YAML

env.UnmarshalStruct("HOST=localhost\nPORT=8080", &cfg, env.FormatEnv)

env.UnmarshalStruct(`{"HOST":"localhost","PORT":"8080"}`, &cfg, env.FormatJSON)

env.UnmarshalStruct("HOST: localhost\nPORT: \"8080\"", &cfg, env.FormatYAML)

自定义格式

注册解析器

// 定义格式常量
const FormatTOML env.FileFormat = 100

// 实现 EnvParser 接口
type TOMLParser struct {
    cfg       env.Config
    validator env.Validator
    auditor   env.FullAuditLogger
}

func (p *TOMLParser) Parse(r io.Reader, filename string) (map[string]string, error) {
    // 实现 TOML 解析
    result := make(map[string]string)
    // ...
    return result, nil
}

// 注册解析器
func init() {
    env.RegisterParser(FormatTOML, func(cfg env.Config, f *env.ComponentFactory) (env.EnvParser, error) {
        return &TOMLParser{
            cfg:       cfg,
            validator: f.Validator(),
            auditor:   f.Auditor(),
        }, nil
    })
}

详见自定义解析器。

完整示例

package main

import (
    "fmt"
    "log"

    "github.com/cybergodev/env"
)

func main() {
    // 创建加载器
    cfg := env.DefaultConfig()
    cfg.ExpandVariables = true

    loader, err := env.New(cfg)
    if err != nil {
        log.Fatal(err)
    }
    defer loader.Close()

    // 加载混合格式配置
    err = loader.LoadFiles(
        "config/base.json",       // JSON 基础配置
        "config/database.yaml",   // YAML 数据库配置
        "config/app.env",         // .env 应用配置
    )
    if err != nil {
        log.Fatal(err)
    }

    // 读取配置
    fmt.Printf("App: %s\n", loader.GetString("APP_NAME"))
    fmt.Printf("DB Host: %s\n", loader.GetString("DATABASE_HOST"))
    fmt.Printf("DB Port: %d\n", loader.GetInt("DATABASE_PORT"))

    // 导出当前配置
    all := loader.All()
    exported, _ := env.Marshal(all, env.FormatEnv)
    fmt.Println("\nExported config:")
    fmt.Println(exported)
}

多格式配置 ​

格式检测 ​

自动检测规则 ​

DetectFormat 函数 ​

加载多格式文件 ​

单一格式 ​

混合格式 ​

覆盖顺序 ​

JSON 格式 ​

文件结构 ​

键名解析 ​

数组访问 ​

JSON 解析配置 ​

类型转换示例 ​

YAML 格式 ​

文件结构 ​

键名解析 ​

数组访问 ​

YAML 解析配置 ​

类型转换示例 ​

.env 格式 ​

文件结构 ​

变量展开 ​

展开语法 ​

export 语法 ​

YAML 风格语法 ​

混合配置模式 ​

开发/生产分离 ​

按功能分离 ​

配置优先级 ​

序列化 ​

Marshal ​

Marshal 结构体 ​

UnmarshalMap ​

UnmarshalStruct ​

自定义格式 ​

注册解析器 ​

完整示例 ​

相关文档 ​

多格式配置

格式检测

自动检测规则

DetectFormat 函数

加载多格式文件

单一格式

混合格式

覆盖顺序

JSON 格式

文件结构

键名解析

数组访问

JSON 解析配置

类型转换示例

YAML 格式

文件结构

键名解析

数组访问

YAML 解析配置

类型转换示例

.env 格式

文件结构

变量展开

展开语法

export 语法

YAML 风格语法

混合配置模式

开发/生产分离

按功能分离

配置优先级

序列化

Marshal

Marshal 结构体

UnmarshalMap

UnmarshalStruct

自定义格式

注册解析器

完整示例

相关文档