解码到结构体并检查配置#

将配置解码为结构体，理解 mapstructure 标签、严格解码与业务校验。

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

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

初始示例#

初始配置 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 main() {
30
  v := viper.New()
31
  v.SetConfigFile("config/config.yaml")
32
  v.SetDefault("app.port", 3000)
33
  v.SetDefault("app.timeout", "5s")
34

35
  if err := v.ReadInConfig(); err != nil {
36
    log.Fatal(err)
37
  }
38

39
  var cfg Config
40
  if err := v.Unmarshal(&cfg); err != nil {
41
    log.Fatal(err)
42
  }
43

44
  fmt.Println("应用名称:", cfg.App.Name)
45
  fmt.Println("监听端口:", cfg.App.Port)
46
  fmt.Println("调试模式:", cfg.App.Debug)
47
  fmt.Println("超时时间:", cfg.App.Timeout)
48
  for i, host := range cfg.App.AllowedHosts {
49
    fmt.Printf("允许的域名 %d: %s\n", i+1, host)
50
  }
51
  for _, server := range cfg.Servers {
52
    fmt.Printf("服务器 %s: %s\n", server.Name, server.Address)
53
  }
54
  for key, value := range cfg.App.Labels {
55
    fmt.Printf("标签 %s: %s\n", key, value)
56
  }
57
}

执行 go run main.go，应打印名称、端口、调试开关、超时、域名、服务器和标签。map 的遍历顺序不固定，标签输出顺序可能变化。

字段首字母要大写，解码器才能设置。mapstructure 标签指定对应的配置键。固定字段用 struct，字符串列表用 []string，对象列表用 []Server，可以自由增加键名的字典用 map。

第一次修改#

在 YAML 的 app 下替换这两行：

1
  debug: false
2
  timeout: 500ms

重新运行，调试模式为 false，超时为 500ms。时间需要带单位，可用 ms、s、m、h，例如 1m30s；1d 不是支持的时间单位。

第二次修改#

在 YAML 的 app.labels 下增加：

1
region: shanghai

Go 结构体和解码代码不用改，遍历时会自动打印新标签。

第三次修改#

用下面这一块替换原来的 Unmarshal 解码块：

1
var cfg Config
2
if err := v.UnmarshalExact(&cfg); err != nil {
3
    log.Fatal(err)
4
}

将 YAML 中的端口字段临时替换为：

1
  prot: 8080

运行应报告未知字段。将顶层 servers 缩进到 app 下也会造成层级不匹配。普通 Unmarshal 会忽略这些未知字段，可能让拼写或层级错误表现为空值。实验后恢复 port: 8080 和合法层级。

第四次修改#

在 main 外增加：

1
func validateConfig(cfg Config) error {
2
    if cfg.App.Name == "" {
3
        return fmt.Errorf("app.name 不能为空")
4
    }
5
    if cfg.App.Port < 1 || cfg.App.Port > 65535 {
6
        return fmt.Errorf("app.port 必须在 1 到 65535 之间")
7
    }
8
    if cfg.App.Timeout <= 0 {
9
        return fmt.Errorf("app.timeout 必须大于 0")
10
    }
11
    return nil
12
}

再在解码成功后、打印之前增加：

1
if err := validateConfig(cfg); err != nil {
2
    log.Fatal(err)
3
}

每次只替换 YAML 的一个字段进行验证，并在下一项之前恢复合法值。

整数转换失败：

1
  port: abc

端口范围校验失败：

1
  port: 70000

超时校验失败：

1
  timeout: 0s

名称校验失败：

1
  name: ""

严格解码检查未知字段，不要求所有字段出现，也不自动检查业务范围。端口 1～65535 是本例的应用约定。实验结束后恢复合法配置。

HikariTish

解码到结构体并检查配置#

初始示例#

第一次修改#

第二次修改#

第三次修改#

第四次修改#

参考资料#

Viper 学习记录

继续阅读

换条路线

HikariTish

解码到结构体并检查配置#

初始示例#

第一次修改#

第二次修改#

第三次修改#

第四次修改#

参考资料#

分享文章

沿着主题读

换条路线