在Go中使用Viper将YAML配置绑定到结构体时，主要依赖 `mapstructure` 标签（而非 `json` 或 `yaml` 标签）实现字段名映射。
---
### 1. **基础绑定方法**
使用 `viper.Unmarshal(&config)` 或 `viper.UnmarshalKey("key", &subConfig)` 进行绑定：
```go
package main
import (
"fmt"
"github.com/spf13/viper"
)
type Config struct {
Server struct {
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
} `mapstructure:"server"`
LogLevel string `mapstructure:"log_level"`
}
func main() {
viper.SetConfigFile("config.yaml")
viper.ReadInConfig()
var config Config
viper.Unmarshal(&config) // 自动绑定到结构体
fmt.Printf("Host: %s, Port: %d, LogLevel: %s\n",
config.Server.Host, config.Server.Port, config.LogLevel)
}
```
---
### 2. **字段名映射规则**
#### a) **默认行为（无标签时）**
- Viper 默认将 **结构体字段名转换为小写 + 下划线** 的形式匹配 YAML 键。
```go
type Config struct {
LogLevel string // 默认匹配 YAML 中的 "log_level"
}
```
#### b) **显式指定标签**
- 使用 `mapstructure:"yaml_key"` 标签强制指定 YAML 键名：
```go
type Config struct {
LogLevel string `mapstructure:"logLevel"` // 匹配 YAML 中的 "logLevel"
}
```
#### c) **嵌套结构体**
- 嵌套结构体需通过 `mapstructure` 标签指定父级键：
```yaml
# config.yaml
server:
host: "localhost"
port: 8080
```
```go
type Config struct {
Server struct {
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
} `mapstructure:"server"` // 对应 YAML 中的 "server" 键
}
```
---
### 3. **特殊场景处理**
#### a) **忽略字段**
- 使用 `mapstructure:"-"` 忽略字段：
```go
type Config struct {
IgnoredField string `mapstructure:"-"`
}
```
#### b) **默认值**
- 结合结构体字段的默认值和 `default` 标签（需在代码中设置）：
```go
type Config struct {
Timeout int `mapstructure:"timeout" default:"30"`
}
```
#### c) **必填字段**
- 使用 `required` 标签（需手动验证或结合其他库）：
```go
type Config struct {
APIKey string `mapstructure:"api_key" validate:"required"`
}
```
---
### 4. **完整示例**
#### **YAML 文件 (`config.yaml`)**
```yaml
app:
name: "myapp"
debug: true
database:
host: "db.local"
port: 3306
credentials:
username: "admin"
password: "secret"
```
#### **Go 结构体定义**
```go
type Config struct {
App struct {
Name string `mapstructure:"name"`
Debug bool `mapstructure:"debug"`
} `mapstructure:"app"`
Database struct {
Host string `mapstructure:"host"`
Port int `mapstructure:"port"`
Credentials struct {
Username string `mapstructure:"username"`
Password string `mapstructure:"password"`
} `mapstructure:"credentials"`
} `mapstructure:"database"`
}
```
#### **绑定代码**
```go
viper.SetConfigFile("config.yaml")
viper.ReadInConfig()
var config Config
viper.Unmarshal(&config)
```
---
### 5. **关键注意事项**
1. **字段导出性**：结构体字段必须为首字母大写（可导出）才能被 Viper 处理。
2. **标签优先级**：`mapstructure` 标签优先级高于默认的字段名转换。
3. **嵌套匹配**：嵌套结构体必须通过 `mapstructure` 标签逐级指定父键。
4. **环境变量覆盖**：可通过 `viper.AutomaticEnv()` 允许环境变量覆盖配置，但需设置 `mapstructure` 兼容的键名。
