读取 YAML、TOML、JSON 和 envfile#

使用 YAML、TOML、JSON 和 envfile，理解嵌套结构与平面键的区别。

本系列使用 Viper v1.21.0。每章都是独立实验，示例命令在项目目录中执行；开始新一章时，使用该章的完整程序和配置，不累积上一章的临时修改。

尚未准备练习项目时，先完成第 1 章的项目准备。

本章先从 YAML 开始，前三种格式复用同一套结构体，envfile 切换为平面键读取。

初始示例#

初始配置 config/config.yaml：

1
app:
2
  name: viper-demo
3
  port: 8080
4
  debug: true
5
  timeout: 5s
6
  allowed_hosts:
7
    - localhost
8
    - example.com
9
  labels:
10
    environment: local
11
    owner: learner
12

13
servers:
14
  - name: primary
15
    address: "127.0.0.1:9001"
16
  - name: backup
17
    address: "127.0.0.1:9002"

初始完整 main.go：

1
package main
2

3
import (
4
  "fmt"
5
  "github.com/spf13/viper"
6
  "log"
7
  "time"
8
)
9

10
type AppConfig struct {
11
  Name         string            `mapstructure:"name"`
12
  Port         int               `mapstructure:"port"`
13
  Debug        bool              `mapstructure:"debug"`
14
  Timeout      time.Duration     `mapstructure:"timeout"`
15
  AllowedHosts []string          `mapstructure:"allowed_hosts"`
16
  Labels       map[string]string `mapstructure:"labels"`
17
}
18

19
type Server struct {
20
  Name    string `mapstructure:"name"`
21
  Address string `mapstructure:"address"`
22
}
23

24
type Config struct {
25
  App     AppConfig `mapstructure:"app"`
26
  Servers []Server  `mapstructure:"servers"`
27
}
28

29
func validateConfig(cfg Config) error {
30
  if cfg.App.Name == "" {
31
    return fmt.Errorf("app.name 不能为空")
32
  }
33
  if cfg.App.Port < 1 || cfg.App.Port > 65535 {
34
    return fmt.Errorf("app.port 必须在 1 到 65535 之间")
35
  }
36
  if cfg.App.Timeout <= 0 {
37
    return fmt.Errorf("app.timeout 必须大于 0")
38
  }
39
  return nil
40
}
41

42
func main() {
43
  v := viper.New()
44
  v.SetConfigFile("config/config.yaml")
45
  v.SetDefault("app.port", 3000)
46
  v.SetDefault("app.timeout", "5s")
47

48
  if err := v.ReadInConfig(); err != nil {
49
    log.Fatal(err)
50
  }
51

52
  var cfg Config
53
  if err := v.UnmarshalExact(&cfg); err != nil {
54
    log.Fatal(err)
55
  }
56
  if err := validateConfig(cfg); err != nil {
57
    log.Fatal(err)
58
  }
59

60
  fmt.Println("应用名称:", cfg.App.Name)
61
  fmt.Println("监听端口:", cfg.App.Port)
62
  fmt.Println("调试模式:", cfg.App.Debug)
63
  fmt.Println("超时时间:", cfg.App.Timeout)
64
  for i, host := range cfg.App.AllowedHosts {
65
    fmt.Printf("允许的域名 %d: %s\n", i+1, host)
66
  }
67
  for _, server := range cfg.Servers {
68
    fmt.Printf("服务器 %s: %s\n", server.Name, server.Address)
69
  }
70
  for key, value := range cfg.App.Labels {
71
    fmt.Printf("标签 %s: %s\n", key, value)
72
  }
73
}

先执行 go run main.go，确认 YAML 读取和校验成功。

第一次修改#

创建 config/config.toml，完整内容为：

1
[app]
2
name = "viper-demo"
3
port = 8080
4
debug = true
5
timeout = "5s"
6
allowed_hosts = ["localhost", "example.com"]
7

8
[app.labels]
9
environment = "local"
10
owner = "learner"
11

12
[[servers]]
13
name = "primary"
14
address = "127.0.0.1:9001"
15

16
[[servers]]
17
name = "backup"
18
address = "127.0.0.1:9002"

仅将代码中的文件路径替换为：

1
v.SetConfigFile("config/config.toml")

再次运行，读取结果应与 YAML 一致。

TOML 的 [app] 是表，[app.labels] 是嵌套表，每个 [[servers]] 增加一个对象。它用表头决定层级，不依靠缩进；写完 [app.labels] 后，普通键属于该表，直到出现下一个表头。

第二次修改#

创建 config/config.json，完整内容为：

1
{
2
  "app": {
3
    "name": "viper-demo",
4
    "port": 8080,
5
    "debug": true,
6
    "timeout": "5s",
7
    "allowed_hosts": ["localhost", "example.com"],
8
    "labels": {
9
      "environment": "local",
10
      "owner": "learner"
11
    }
12
  },
13
  "servers": [
14
    {"name": "primary", "address": "127.0.0.1:9001"},
15
    {"name": "backup", "address": "127.0.0.1:9002"}
16
  ]
17
}

仅将代码中的文件路径替换为：

1
v.SetConfigFile("config/config.json")

再次运行，读取结果仍应一致。JSON 的键和字符串必须使用双引号，不支持普通注释，也不允许末尾多余逗号。文件语法错误会在 ReadInConfig 阶段出现。

第三次修改#

创建 config/config.env，完整内容为：

1
APP_NAME=viper-demo
2
APP_PORT=8080

envfile 的 APP_PORT 不会自动变成嵌套的 app.port，本次修改整个程序，使用平面键读取。完整替换代码为：

1
package main
2

3
import (
4
  "fmt"
5
  "github.com/spf13/viper"
6
  "log"
7
  "os"
8
)
9

10
func main() {
11
  v := viper.New()
12
  v.SetConfigFile("config/config.env")
13
  if err := v.ReadInConfig(); err != nil {
14
    log.Fatal(err)
15
  }
16

17
  fmt.Println("文件名称:", v.GetString("APP_NAME"))
18
  fmt.Println("文件端口:", v.GetInt("APP_PORT"))
19
  fmt.Println("进程环境变量:", os.Getenv("APP_PORT"))
20
}

分别执行：

1
env -u APP_PORT go run main.go
2
env APP_PORT=9090 go run main.go

第一条命令中文件端口为 8080，进程环境变量为空；第二条中文件端口仍为 8080，进程环境变量为 9090。程序没有绑定环境变量，两份数据彼此独立。

读取 .env 文件不会自动设置进程环境变量，读取环境变量也不会自动寻找 .env 文件。

本文的四种格式是 YAML、TOML、JSON、envfile，而不是把 .yaml 和 .yml 算作两种。v1.21.0 默认 codec 内置这四类；扩展名列表仍出现的 INI、HCL、Properties 等名称，不代表已有默认解析器，需要另行注册相应 codec。

HikariTish

读取 YAML、TOML、JSON 和 envfile#

初始示例#

第一次修改#

第二次修改#

第三次修改#

参考资料#

Viper 学习记录

继续阅读

换条路线

HikariTish

读取 YAML、TOML、JSON 和 envfile#

初始示例#

第一次修改#

第二次修改#

第三次修改#

参考资料#

分享文章

沿着主题读

换条路线