关联 ID 的作用
关联 ID 是为一次业务请求生成的唯一标识，从入口一路透传到网关、各服务、消息队列与数据库操作日志，把分散在不同系统里的日志串成一条时间线。它和分布式追踪的 trace ID 目标相近但更轻量：关联 ID 只要求“同一次业务请求在各处带上同一个值”，不要求记录父子调用关系与耗时。联调定位、用户报障排查和跨服务故障归因，通常先靠它缩小范围。
基本信息
| 生成 | 入口生成或接收上游传入，格式固定 |
|---|---|
| 透传 | HTTP 头、消息属性、线程上下文全程携带 |
| 使用 | 日志字段与错误响应携带，支持按 ID 检索 |
| 命名 | 常见为 X-Request-ID 或 X-Correlation-ID，全链路统一一个名字 |
典型使用场景
- 用户报障排查：从用户提供的编号反查整条调用链的日志
- 跨服务故障归因：定位是哪一跳开始变慢或开始报错
- 异步链路排查：消息生产与消费通过同一 ID 关联
- 灰度验证：按 ID 抽样比对新旧版本的处理结果
- 安全审计：把同一请求在各系统留下的操作串成完整记录
透传示意
透传示意
HTTP：X-Correlation-ID 头，网关缺失时生成
消息：写入消息属性，消费端读取并继续传递
日志：每条日志携带该字段
响应：错误响应回传该 ID 便于报障实现位置对照
| 环节 | 要做的事 | 常见遗漏 |
|---|---|---|
| 入口网关 | 生成或校验 ID，写入请求上下文 | 对已存在但格式非法的 ID 未做处理 |
| 同步调用 | 通过拦截器自动注入请求头 | 手工拼装某几个调用，漏掉部分客户端 |
| 异步消息 | 写入消息属性并设置消费端上下文 | 只透传 HTTP 头，消息链路断开 |
| 线程池与协程 | 在任务提交时捕获上下文并恢复 | 跨线程后上下文丢失，日志缺少字段 |
| 响应与日志 | 错误响应回传 ID，日志统一字段名 | 字段名在各服务不一致，无法统一检索 |
使用要点
- 统一字段名与格式：全链路一个头名、一个日志字段名，否则检索要写多套条件
- 入口校验外部传入的 ID：格式非法时重新生成，避免日志注入与超长字段
- 线程池与异步任务要显式传递上下文，用框架的上下文传播机制而非全局变量
- 对外响应回传关联 ID 便于报障：注意不要用它暴露内部服务名与拓扑
- 关联 ID 不能替代追踪：需要耗时分解与父子关系时仍要用分布式追踪
对外响应可回传关联 ID 便于报障；敏感场景注意不要用它暴露内部调用拓扑，ID 本身应是不含业务含义的随机串。
直接使用客户端传入的关联 ID 存在风险：超长或含特殊字符的值会污染日志，可能被用来做日志注入，入口必须做长度与字符集校验。