跨服务传播关联 ID

概述

关联 ID 是连接跨服务日志最廉价的手段。在边界生成一次，逐跳透传，并回传给调用方，使支持人员只需引用一个值即可定位问题。

关键步骤

1. 接收上游关联头，缺失时生成新的 UUID。
2. 把关联 ID 绑定到每请求的日志上下文，并在响应头中回传。
3. 在出站 HTTP 调用与异步消息属性中转发该 ID。
4. 限制 ID 长度，并拒绝过长或明显伪造的客户端 ID。

验证

• 每个入站请求在业务逻辑执行前已有非空关联 ID。
• 同一请求在各服务的日志中共享同一 ID。
• ID 通过响应头回传给客户端。
• 异步消费者能从消息中还原该 ID。

注意事项

• 关联 ID 标识的是请求而非用户，不能当作认证令牌。
• 若日志管道未整链保留采样，部分关联日志可能丢失。

适用范围

本条目围绕「跨服务传播关联 ID」给出可复制的步骤、验证方式与常见问题，适合需要按此流程落地的工程团队。执行时请结合自身上下文调整命令与阈值，并在变更前后留存证据，便于后续复核与回滚。

const cid = req.headers['x-correlation-id'] ?? crypto.randomUUID();
logger.child({ correlationId: cid }).info('request.start');
res.setHeader('x-correlation-id', cid);