操作日志与链路追踪需共享统一RequestContext以保障审计合规与故障定位；该上下文含traceId、spanId、userId等字段，基于ThreadLocal+不可变设计，通过Filter/Interceptor初始化，并在异步、RPC、MQ等场景显式透传。
操作日志与链路追踪的核心目标
操作日志关注“谁在什么时间、对什么资源做了什么”，强调业务语义和审计合规；链路追踪聚焦“一次请求经过了哪些服务、耗时多少、是否出错”，用于性能分析和故障定位。两者需共用同一请求上下文（Request Context），避免重复透传、ID不一致或上下文丢失。
统一上下文对象设计（ThreadLocal + 不可变）
定义一个轻量、不可变的 RequestContext 类，封装关键字段：
- traceId：全局唯一，由网关或首入服务生成（如 UUID 或 Snowflake ID）
- spanId：当前方法/组件的局部标识，用于构建调用树（如 traceId-1, traceId-1.1）
- userId / operatorId：登录用户标识（从 token 或 session 解析，非请求参数直取）
- tenantId / orgId：租户或组织上下文（多租户系统必需）
- clientIp / userAgent：客户端信息（经反向代理后需读 X-Forwarded-For）
- reqPath / method：原始请求路径与 HTTP 方法（便于日志归类）
使用 ThreadLocalCompletableFuture.supplyAsync(..., contextAwareExecutor)）。
日志记录与链路埋点协同方式
操作日志（如 @LogOperation 注解切面）和链路追踪（如 OpenTelemetry 或 SkyWalking 的 Span）都应从同一个 RequestContext 中读取 traceId、userId 等字段，而非各自解析或生成：
立即学习“Java免费学习笔记（深入）”；
- SLF4J 日志通过 MDC（Mapped Diagnostic Context）自动注入 traceId 和 userId：
MDC.put("traceId", ctx.getTraceId()); MDC.put("userId", ctx.getUserId()); - 操作日志切面中直接获取 RequestContext，提取 operatorId、reqPath、业务参数等，组装结构化日志体
- 链路 SDK（如 OpenTelemetry）的 Span 属性可复用 RequestContext 中的 tenantId、clientIp 等，避免重复采集
- 数据库操作日志、MQ 发送日志等中间件日志，也通过 RequestContext 携带 traceId，确保跨系统可追溯
跨线程与异步调用的上下文传递
Java 默认 ThreadLocal 不跨线程，需主动透传。常见场景处理方式：
- 线程池任务：包装 Runnable/Callable，构造时捕获当前 RequestContext，执行前 set，完成后 remove
-
CompletableFuture：自定义
ContextAwareExecutor，或使用CompletableFuture.supplyAsync(() -> {...}, ctx.executor()) - Feign / RestTemplate 调用：通过拦截器将 traceId、tenantId 等写入 HTTP Header（如 X-Trace-ID、X-Tenant-ID），下游服务解析并重建 RequestContext
- 消息队列（如 Kafka/RocketMQ）：发送前将 RequestContext 关键字段注入消息 Headers，消费者端从 headers 构建新上下文
避免使用 InheritableThreadLocal —— 它无法穿透线程池，且在 Netty 等 NIO 框架中行为不可靠。
