Go 中使用 yaml.v2 解析结构可变的 YAML 数据

在实际项目中，我们经常会遇到这样一种情况：一份 YAML 配置文件里，同一层级下的字段类型五花八门——有的字段是单个字符串，比如 mvn_home: /ma ven；有的字段则是一个字符串列表，比如 goals: [clean, install]；甚至还有可能嵌套着更复杂的映射结构。

如果直接用 Go 的固定结构体去解析，比如把 Opts 定义成 map[string][]string，那面对 mvn_home: /ma ven 这种标量值，yaml.v2 会直接报错——因为它没办法把一个字符串自动塞进 []string 类型的坑里。

怎么解决？核心思路其实很简单：先别急着做类型约束，用 map[string]interface{} 作为中间容器，先把 YAML 的原始结构无损地接住，然后再根据具体键名和运行时类型，按需去做二次转换。

下面是一个比较完整的实现示例，也是目前工程里比较主流的做法：

package executors

import (
    "fmt"
    "gopkg.in/yaml.v2"
    "reflect"
)

type Step struct {
    Exec string                 `yaml:"exec"`
    Pwd  string                 `yaml:"pwd"`
    Opts map[string]interface{} `yaml:"opts"` // ✅ 关键：这里用 interface{} 来接受任意值类型
}

// ParseOptValue 将 interface{} 安全转为所需类型
func (s *Step) ParseOptValue(key string, target interface{}) error {
    val, exists := s.Opts[key]
    if !exists {
        return fmt.Errorf("option key %q not found", key)
    }

    // 根据 target 的类型做适配转换
    switch t := target.(type) {
    case *[]string:
        switch v := val.(type) {
        case string:
            *t = []string{v}
        case []interface{}:
            *t = toStringSlice(v)
        default:
            return fmt.Errorf("cannot convert %s to []string", reflect.TypeOf(val).String())
        }
    case *string:
        if str, ok := val.(string); ok {
            *t = str
        } else {
            return fmt.Errorf("cannot convert %s to string", reflect.TypeOf(val).String())
        }
    default:
        return fmt.Errorf("unsupported target type: %T", target)
    }
    return nil
}

// 辅助函数：将 []interface{} 转为 []string（yaml.v2 默认切片类型）
func toStringSlice(in []interface{}) []string {
    out := make([]string, len(in))
    for i, v := range in {
        if s, ok := v.(string); ok {
            out[i] = s
        }
    }
    return out
}

// 使用示例
func main() {
    data := `steps:
  - exec: ma ven
    pwd: /code
    opts:
      goals:
        - clean
        - install
      mvn_home: /ma ven
      profiles:
        - dev
        - ci`

    var config struct {
        Steps []Step `yaml:"steps"`
    }

    if err := yaml.Unmarshal([]byte(data), &config); err != nil {
        panic(err)
    }

    for _, step := range config.Steps {
        var goals []string
        var mvnHome string

        if err := step.ParseOptValue("goals", &goals); err != nil {
            fmt.Printf("warn: parsing 'goals': %v\n", err)
        } else {
            fmt.Printf("goals = %v\n", goals) // [clean install]
        }

        if err := step.ParseOptValue("mvn_home", &mvnHome); err != nil {
            fmt.Printf("warn: parsing 'mvn_home': %v\n", err)
        } else {
            fmt.Printf("mvn_home = %s\n", mvnHome) // /ma ven
        }
    }
}

这里有几个关键点值得注意。

首先，map[string]interface{} 是 yaml.v2 处理异构值的标准方案，也是推荐做法。它能完整保留 YAML 的原始结构：字符串还是字符串，列表会变成 []interface{}，嵌套映射则会变成 map[interface{}]interface{}。这种“无损”的特性，给了我们后续按需转换的灵活空间。

其次，要特别留意一点：yaml.v2 解析出来的切片默认是 []interface{}，而不是 []string。所以你不能直接断言成 []string，必须手动遍历转换。上面的 toStringSlice 函数就是干这个活的。

当然，如果你的业务逻辑更复杂，比如需要动态解析嵌套结构，那也可以借鉴 json.RawMessage 的思路——先用 []byte 把子 YAML 片段暂存起来，再按需调用 yaml.Unmarshal 去处理。不过话说回来，对于绝大多数场景，上面这个 interface{} 方案已经足够覆盖了。

最后，生产环境里建议把 ParseOptValue 这类方法封装好，加上适当的日志和错误分类。这样一旦字段类型出现兼容性问题，调试起来会省心很多。

说到底，这种“先泛化、后特化”的两阶段解析策略，核心价值就在于：既保留了 YAML 的表达灵活性，又能在业务层面拿到强类型的可控性。一举两得。