从 MDC 规范到 Data Contract：聊聊后端业务日志字段字典与契约文档的维护实践

最近在把一个老业务模块往 Spring Boot 3.2 迁移，顺便梳理链路日志，被历史遗留的埋点字段坑得不轻。

同一个业务含义的 ID，A 服务打的是 userId（String），B 服务打的是 user_id（Long），到了数仓和 Flink 那边清洗逻辑写得极度痛苦。之前团队尝试过用 Wiki / Markdown 维护「日志字段字典」，但经验证明只要文档脱离了代码生命周期，基本两周就会事实性失效。

目前我们正在探索「代码即契约（Schema as Code）」的方式：

1. 业务日志元数据由统一的 Java POJO / Record 承载，禁用裸奔的 log.info("..., {}", a, b) 拼接。
2. 配合 Logstash Logback Encoder 输出结构化 JSON，Trace 上下文依赖 Micrometer Tracing 自动注入。
3. 字典文档考虑在 CI 阶段通过注解扫描自动生成 JSON Schema，并推送到内网元数据平台。

这里补充一个我们最近踩到的坑：如果有计划上 GraalVM Native Image（比如 Spring Boot 3.x + Native Build Tools 0.9.x+），这套结构化日志对象如果包含复杂的泛型或依赖 Jackson 动态反射序列化，AOT 编译期必须提前配好 @RegisterForReflection 或者 Runtime Hints，否则打出来的二进制制品在运行时输出日志会直接丢字段甚至报空指针。

想请教一下各位：大家团队目前是如何维护日志字段字典与下游消费契约的？是有专门的 Schema Registry 做门禁校验，还是有更轻量的元数据同步方案？