Spring MVC 与 traceId 规范

reference

2026年7月20日阅读约 2 分钟245 字

更新于 2026年7月20日

适用场景

新增或修改 Controller、REST 接口、请求响应 DTO、全局异常、CORS、日志、审计、下游 HTTP 调用或链路跟踪时加载。

统一名称如下，不允许各接口自行命名：

前端所有 HTTP 方法通过同一个请求客户端或拦截器写入 X-Trace-Id，页面和业务组件不得重复拼接请求头。
前端使用 crypto.randomUUID() 为一次请求生成 traceId；同一次自动重试沿用原值。后端调用下游服务时继续传递当前有效值。
traceId 只用于关联日志和审计，不作为身份、权限、幂等键或业务主键。
跨域场景必须允许请求头 X-Trace-Id，并通过 Access-Control-Expose-Headers 暴露同名响应头；CORS 只开放实际前端来源，不使用带凭据的通配来源。

只允许一个继承 OncePerRequestFilter 的 traceId 过滤器统一接收请求头；核心方法为 doFilterInternal(...)。
Controller 不重复声明 @RequestHeader("X-Trace-Id")，Service 方法也不为日志目的层层增加 traceId 参数。
过滤器按以下顺序处理：
1. 读取 X-Trace-Id。
2. 接受 8 至 64 位的字母、数字、点、下划线或连字符；空值、超长值、空白和控制字符均视为非法。
3. 缺失或非法时使用 UUID.randomUUID().toString() 生成新值，不因链路字段缺失拒绝业务请求。
4. 将有效值写入 request attribute、MDC 和 X-Trace-Id 响应头，再调用过滤器链。
5. 在 finally 中删除 MDC 的 traceId，防止线程复用造成串号。
header 名、MDC key 和校验规则各保留一个常量来源，不在过滤器、异常处理器和客户端拦截器中复制字符串。
健康检查、静态资源和错误分派也必须返回有效 traceId；确需排除路径时先证明该路径不产生日志或审计记录。

日志格式统一包含 MDC 的 traceId；业务日志使用参数化日志，不拼接用户输入，不记录令牌、完整支付信息或不必要的供应商敏感字段。
@RestControllerAdvice 从 request attribute 取得当前 traceId 并写入错误响应，不重新生成。
审计记录在应用边界显式保存当前 traceId；领域模型和纯决策服务不得依赖 HttpServletRequest、MDC 或静态请求上下文。
下游 HTTP 客户端使用一个统一拦截器传递 X-Trace-Id，不得由每个 Client 方法手写。
使用 @Async、线程池、消息队列或响应式执行时，必须显式复制并在完成后清理 traceId；不得假设 MDC 自动跨线程传播。
如果后续接入 OpenTelemetry，优先兼容 W3C traceparent，并由观测层映射业务使用的 traceId；不要同时维护两套互不关联的链路标识。