Go JSON 接口如何只对新增字段做兼容告警

Go 的 encoding/json 解码到结构体时，默认会忽略目标结构体没有的字段。这个行为适合接口平滑演进，却也可能让服务端悄悄漏掉客户端刚发送的配置。若直接调用 Decoder.DisallowUnknownFields()，新增字段会变成请求错误；更稳妥的兼容方案是“业务解码一次、字段名探测一次”：已知字段照常进入结构体，未知字段只进入告警日志。

先把“忽略”与“拒绝”分开

假设接口接收用户动作：

type ActionRequest struct {
	UserID string `json:"user_id"`
	Action string `json:"action"`
}

请求里多出 trace_mode 时，普通 json.Unmarshal 会填好 UserID 和 Action，忽略 trace_mode；严格解码器则会返回未知字段错误。前者没有观测能力，后者会破坏正在升级的客户端，所以目标不是修改解码语义，而是把“字段是否在协议内”单独观测出来。

用两份视图完成一次兼容解码

第一份视图是业务结构体，负责类型转换和后续业务校验；第二份视图只保留 JSON 对象的字段名和原始值。RawMessage 不会把未知值提前转成 float64 或泛型嵌套对象，因此只做字段比较时足够轻量。

func decodeAction(data []byte) (ActionRequest, []string, error) {
	var req ActionRequest
	// 第一次解码保留结构体的类型检查，未知字段仍保持兼容。
	if err := json.Unmarshal(data, &req); err != nil {
		return ActionRequest{}, nil, fmt.Errorf("decode request: %w", err)
	}

	var fields map[string]json.RawMessage
	// 第二次只读取字段名，不把未知值写进业务对象。
	if err := json.Unmarshal(data, &fields); err != nil {
		return ActionRequest{}, nil, fmt.Errorf("read field names: %w", err)
	}

	known := map[string]struct{}{"user_id": {}, "action": {}}
	unknown := make([]string, 0)
	for name := range fields {
		if _, ok := known[name]; !ok {
			unknown = append(unknown, name)
		}
	}
	sort.Strings(unknown) // 排序后日志稳定，便于聚合和测试。
	return req, unknown, nil
}

示例需要导入 encoding/json、fmt 和 sort。若输入不是 JSON 对象，第二次解码会返回类型错误；这与接口本身的输入约束一致，不应把它误报成“新增字段”。

告警里记录字段名，不要记录字段值

调用方收到响应前，可以把未知字段交给结构化日志或指标：

req, unknown, err := decodeAction(body)
if err != nil {
	return err
}
if len(unknown) > 0 {
	// 记录字段名和客户端信息即可，避免把 token、手机号等值写入日志。
	logger.Warn("json contract drift",
		"endpoint", "/v1/actions",
		"client_version", clientVersion,
		"unknown_fields", unknown,
	)
}
return handleAction(req)

告警的聚合键可以是接口名、客户端版本和字段名。不要为每个未知字段打印完整请求体，否则兼容观测很容易变成敏感数据泄露。若同一个字段在短时间内大量出现，再安排协议评审或客户端升级，而不是看到一次告警就立刻改成拒绝。

嵌套字段与 JSON 标签是两个常见坑

上面的白名单只覆盖顶层字段。若结构体里有 Options 嵌套对象，顶层比较只能发现 options 是否存在，不能发现 options.mode。这时要为嵌套对象定义自己的白名单和告警路径，例如 options.timeout，不要把所有 JSON 递归展开后再猜字段与 Go 字段的对应关系。

白名单必须写 JSON 标签名，而不是盲目写 Go 字段名。json:"user_id" 对应的输入键是 user_id；如果协议允许大小写兼容或历史别名，也应把这些别名明确列入已知集合，并在日志中区分“兼容别名”和“真正未知”。

从兼容告警逐步走向严格协议

兼容告警适合协议正在演进、客户端版本分散的阶段。先观察一段时间，确认未知字段来自哪个版本、是否有业务含义，再决定策略：无影响字段继续忽略并统计；已知的未来字段可以加入版本化结构体；会改变安全或计费语义的字段则应先明确协议，再在灰度接口开启严格拒绝。

因此，“只对新增字段做兼容告警”的核心不是寻找一个隐藏开关，而是把结构体解码和协议漂移检测拆开。这样既不会让新字段拖垮旧客户端，又能为后续清理、文档更新和灰度收紧留下证据。

相关问题

为什么不直接忽略未知字段？

默认忽略能保持兼容，但无法知道客户端是否已经发送了服务端未理解的配置。增加字段名检测后，兼容性和可观测性可以同时保留。

能不能用 DisallowUnknownFields 后捕获错误再告警？

不建议把它当作常规方案，因为它会在业务对象完成前返回错误，而且默认只给出一个未知字段线索。需要只告警时，双视图比较更直观。

为什么要用 RawMessage 而不是 map[string]any？

这里只关心键名，RawMessage 可以延迟值的解析，避免数字、嵌套对象等未知内容先被转换成泛型值。

参考资料：https://pkg.go.dev/encoding/json