Go YAML 配置转 JSON 时类型为什么变化

把 YAML 配置读进 Go，再转成 JSON 后发现数字、布尔值或嵌套对象的类型和预期不一样，通常不是 YAML 文件“自动改写”了，而是数据在不同解码目标之间经过了两套类型映射。最稳妥的做法是：固定配置字段就绑定结构体；必须保留动态字段时，检查每一层 interface{} 的实际类型，并用 UseNumber 或 RawMessage 延迟决定数字类型。

官方地址：https://pkg.go.dev/encoding/json

先确认类型变化发生在哪一层

先不要只比较打印出来的 JSON 文本。JSON 本身只有 number、string、boolean、array、object 和 null，并不区分 Go 的 int、int64、float64。真正需要定位的是 Go 值在 YAML 解码、JSON 编码和 JSON 再解码之间经过了哪一个目标类型。

package main

import (
	"encoding/json"
	"fmt"

	"gopkg.in/yaml.v3"
)

func main() {
	input := []byte("port: 8080\nenabled: true\nratio: 0.5\n")
	var yamlValue map[string]any
	if err := yaml.Unmarshal(input, &yamlValue); err != nil {
		panic(err)
	}

	// 先看 YAML 解码后的真实 Go 类型，不要只看 fmt.Println 的值。
	fmt.Printf("YAML port=%T, ratio=%T\n", yamlValue["port"], yamlValue["ratio"])

	b, err := json.Marshal(yamlValue)
	if err != nil {
		panic(err)
	}
	var jsonValue map[string]any
	if err := json.Unmarshal(b, &jsonValue); err != nil {
		panic(err)
	}

	// JSON 解码到 any 时，标准库默认把 number 放入 float64。
	fmt.Printf("JSON port=%T, ratio=%T\n", jsonValue["port"], jsonValue["ratio"])
}

这里的关键不是 Marshal 把 int 改成了浮点数，而是后面的 json.Unmarshal 没有目标字段类型，只能按标准库对 interface{} 的默认规则接收 JSON number。若只是把 YAML 读入 Go 后立即编码成 JSON，JSON 文本里的 8080 仍然是一个合法数字。

理解 YAML 解码与 JSON 再解码的映射差异

YAML 库会根据你传入的目标值决定如何落地。把节点解码到 Config.Port int，端口就有明确的整数边界；把它放进 map[string]any，结果依赖 YAML 标量解析规则。随后 JSON 的默认映射又会把对象放进 map[string]any、数组放进 []any、数字放进 float64。

还要留意语义差异：端口号、重试次数、毫秒超时通常是整数；比例、阈值可能需要浮点数；带前导零的编号、版本号和账号标识则应当是字符串。不要根据“看起来像数字”来决定类型。

用结构体固定配置契约

配置结构稳定时，结构体是最简单的修正方案。YAML 和 JSON 只负责文本表示，Go 结构体负责业务语义。标签可以让同一个类型同时兼容两种文件格式，也能在配置错误时尽早返回类型不匹配。

type Config struct {
	Port    int     `yaml:"port" json:"port"`
	Enabled bool    `yaml:"enabled" json:"enabled"`
	Ratio   float64 `yaml:"ratio" json:"ratio"`
}

func loadConfig(data []byte) ([]byte, error) {
	var cfg Config
	if err := yaml.Unmarshal(data, &cfg); err != nil {
		return nil, fmt.Errorf("解析 YAML 配置: %w", err)
	}

	// 结构体字段已经表达业务类型，编码阶段不会再靠 any 猜测。
	return json.Marshal(cfg)
}

这条路径适合服务端配置、命令行参数和部署清单。若字段缺失需要默认值，可以在解码前填充默认配置，或在解码后显式检查；不要让下游通过类型断言猜测 port 到底是 int 还是 float64。

动态字段使用 UseNumber 或 RawMessage

如果配置允许用户扩展字段，不能强行把整个对象改成结构体。此时用 json.Decoder.UseNumber 读取 JSON，可以把动态数字保留成 json.Number，之后再根据字段名选择 Int64 或 Float64。如果字段类型还没有确定，则用 json.RawMessage 暂存原始 JSON，等看到旁边的 kind 字段后再解码。

func decodeDynamic(data []byte) (map[string]any, error) {
	dec := json.NewDecoder(bytes.NewReader(data))
	dec.UseNumber() // 保留数字字面量，避免无意间先变成 float64。

	var value map[string]any
	if err := dec.Decode(&value); err != nil {
		return nil, err
	}
	return value, nil
}

// 使用时按业务含义选择转换方式，并处理溢出或小数错误。
func readPort(value any) (int64, error) {
	n, ok := value.(json.Number)
	if !ok {
		return 0, fmt.Errorf("port 不是 JSON number，而是 %T", value)
	}
	return n.Int64()
}

排查时可以按这张清单走：先记录 YAML 解码目标，再打印 %T；确认是否经过 JSON 二次解码；稳定字段迁移到结构体；动态数字启用 UseNumber；最后对端口、超时和编号做范围及字符串语义检查。

常见问题

为什么 JSON 输出中的 8080 看起来没有变化？

JSON 文本只表达 number，不表达 Go 的整数宽度。类型差异通常在再次解码到 any 后才显现，此时默认类型是 float64。

把所有数字改成字符串是不是最安全？

不是。端口、计数和超时仍应保持整数；只有编号、版本或不能参与计算的标识才适合声明为字符串。

YAML 和 JSON 能共用一个配置结构体吗？

可以。为字段同时写 yaml 和 json 标签，解码时分别交给对应包，业务层只使用同一份明确的 Go 类型。

参考资料

• https://pkg.go.dev/encoding/json：Go JSON 默认类型映射与 Decoder.UseNumber。
• https://gopkg.in/yaml.v3：YAML v3 API 文档与安装入口。
• https://github.com/go-yaml/yaml：go-yaml 的兼容性说明与维护状态。