在Java中开发操作日志链路追踪_Java请求上下文设计说明_网络技术

发布时间 - 2025-12-26 00:00:00 点击率：次

操作日志与链路追踪需共享统一RequestContext以保障审计合规与故障定位；该上下文含traceId、spanId、userId等字段，基于ThreadLocal+不可变设计，通过Filter/Interceptor初始化，并在异步、RPC、MQ等场景显式透传。

操作日志关注“谁在什么时间、对什么资源做了什么”，强调业务语义和审计合规；链路追踪聚焦“一次请求经过了哪些服务、耗时多少、是否出错”，用于性能分析和故障定位。两者需共用同一请求上下文（Request Context），避免重复透传、ID不一致或上下文丢失。

定义一个轻量、不可变的 RequestContext 类，封装关键字段：

使用 ThreadLocal 绑定当前线程，配合过滤器（Filter）或拦截器（Interceptor）在请求入口初始化、出口清理。异步场景下需显式传递（如 CompletableFuture.supplyAsync(..., contextAwareExecutor)）。

操作日志（如 @LogOperation 注解切面）和链路追踪（如 OpenTelemetry 或 SkyWalking 的 Span）都应从同一个 RequestContext 中读取 traceId、userId 等字段，而非各自解析或生成：

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 框架中行为不可靠。