统一处理未知字段、数字精度和时间格式

接口 JSON 一旦出现版本差异，最容易同时踩中三个坑：结构体默认悄悄忽略未知字段，interface{} 里的数字先变成 float64，时间字符串又因为格式不统一无法直接落库。我的处理方式是把“字段归属、数字策略、时间格式”放进同一个解码入口，而不是在每个 handler 里临时补丁。

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

一、先把固定字段和未知字段分开

标准库把 JSON 对象解码到结构体时，找不到对应字段默认会忽略；这适合接口向后兼容，却不适合审计或灰度期间观察新字段。可以显式保留原始字节，等确认字段含义后再二次解码。

type Envelope struct {
	// 固定字段直接交给 encoding/json 做类型转换。
	ID      string                     `json:"id"`
	Created time.Time                  `json:"created_at"`
	Extra   map[string]json.RawMessage `json:"-"`
}

func (e *Envelope) UnmarshalJSON(data []byte) error {
	// Alias 避免递归调用当前方法；先解析固定字段，再扫描原始对象。
	type Alias Envelope
	var aux struct {
		*Alias
		Raw map[string]json.RawMessage
	}
	aux.Alias = (*Alias)(e)
	if err := json.Unmarshal(data, &aux.Raw); err != nil {
		return fmt.Errorf("读取 JSON 对象: %w", err)
	}
	if err := json.Unmarshal(data, aux.Alias); err != nil {
		return fmt.Errorf("解析固定字段: %w", err)
	}
	delete(aux.Raw, "id")
	delete(aux.Raw, "created_at")
	e.Extra = aux.Raw
	return nil
}

这里的 Extra 只保存原始 JSON，不急着把未知数字转成 Go 数值。生产代码可以把允许的扩展键列成白名单，再对单个 RawMessage 调用 json.Unmarshal，这样错误范围更小。

二、在动态字段入口保住数字精度

当 JSON 解码目标是 map[string]any 或 interface{} 时，标准库默认把数字放进 float64。订单号、雪花 ID 和金额都不应该经过这一步。UseNumber 会让数字先进入 json.Number，随后由业务决定使用 Int64、定点小数库还是原始字符串。

func decodeDynamic(data []byte) (map[string]any, error) {
	dec := json.NewDecoder(bytes.NewReader(data))
	// 先保留数字词法，不能让它们默认落成 float64。
	dec.UseNumber()

	var value map[string]any
	if err := dec.Decode(&value); err != nil {
		return nil, fmt.Errorf("解析动态 JSON: %w", err)
	}
	// 第二次 Decode 应该遇到 EOF，防止请求体拼接了第二个 JSON 值。
	var extra any
	if err := dec.Decode(&extra); err != io.EOF {
		return nil, fmt.Errorf("JSON 后存在尾随数据")
	}
	return value, nil
}

如果确定字段是整数，再执行 number.Int64() 并检查错误；金额则不要为了“方便”调用 Float64()。未知字段和数值解析可以分成两个阶段，既保留兼容性，也能让风险字段单独加规则。

三、把时间格式收敛到可验证的类型

time.Time 的 JSON 解码要求带引号的 RFC3339 时间。接口返回 2026-10-07 10:30:00 或空字符串时，不要在业务层到处 time.Parse；定义一个只接受约定格式的类型，让错误在入口暴露。

type EventTime struct{ time.Time }

func (t *EventTime) UnmarshalJSON(data []byte) error {
	var text string
	// 先拆 JSON 字符串，null、数字和未闭合字符串都会在这里失败。
	if err := json.Unmarshal(data, &text); err != nil {
		return fmt.Errorf("时间必须是字符串: %w", err)
	}
	parsed, err := time.Parse(time.RFC3339, text)
	if err != nil {
		return fmt.Errorf("时间不是 RFC3339: %w", err)
	}
	t.Time = parsed
	return nil
}

如果业务允许“缺失”和“明确为 null”有不同含义，应使用 *EventTime 或额外的存在性字段；不要把零时间误当成请求时间。时区也要在协议中写清楚，带 Z 或偏移量的时间比依赖服务器本地时区更稳。

四、统一入口并检查四个边界

最后把策略集中到一个函数：固定结构体负责核心字段，动态字段负责扩展，数字保留原文，时间由自定义类型校验。上线前至少覆盖未知字段、超大整数、null、错误时间和尾随 JSON 五个用例；不要只测一条正常请求。

func DecodeEnvelope(data []byte) (Envelope, error) {
	// 先用严格解码器拦住拼接值；未知字段是否拒绝由接口契约决定。
	dec := json.NewDecoder(bytes.NewReader(data))
	var env Envelope
	if err := dec.Decode(&env); err != nil {
		return Envelope{}, err
	}
	var tail any
	if err := dec.Decode(&tail); err != io.EOF {
		return Envelope{}, fmt.Errorf("请求包含多个 JSON 值")
	}
	return env, nil
}

需要“未知字段即失败”的内部接口，可以在这个入口调用 DisallowUnknownFields；需要兼容供应商扩展字段的公共接口，则保留 RawMessage 并记录键名。两者不要混在同一条链路里，否则调用方很难判断是版本扩展还是输入错误。

相关问题

为什么不直接用 map[string]any？

它适合探查未知结构，但数字默认是 float64，时间也失去类型约束；稳定接口应优先用结构体。

未知字段必须全部拒绝吗？

内部强契约接口可以拒绝，面向多版本供应商的接口更适合保留原始字段并记录审计信息。

时间格式不是 RFC3339 怎么办？

不要静默按服务器时区猜测；为该供应商单独实现解码类型，解析成功后再转换为统一的 UTC 或带时区时间。