SpringBoot实战：全局日志记录与请求链路追踪

在微服务和高并发架构下，日志是排查问题的“救命稻草”。本文将讲解如何利用 AOP、MDC 等技术，构建一套包含请求追踪、出入参记录、敏感信息脱敏的全局日志系统。

一、 为什么需要全局日志和链路追踪？

想象一下这样的场景：用户反馈下单失败，客服给你一个订单号。你开始查日志…

  • 如果不带唯一标识：你需要在一堆杂乱的并发请求中找到属于那个用户的那一次请求，犹如大海捞针。
  • 如果接口多：如果涉及多个服务调用，你需要跨机器拼接日志片段。

为了解决这些问题，我们需要：

  1. 链路追踪 (TraceId)：为每个请求生成唯一的 ID，贯穿整个处理流程，串联起所有相关日志。
  2. 全局日志：自动记录接口入参、出参、耗时，减少手动写log.info(...)的工作量。

二、 核心组件：MDC (Mapped Diagnostic Context)

MDC 是 Slf4j 提供的一个机制，它实际上是一个线程安全的ThreadLocal<Map>。我们可以往里面放入键值对（如 TraceId），然后在 Logback 配置中通过%X{key}的格式输出。

1. 生成 TraceId

我们需要一个工具类来管理 TraceId。

publicclassTraceIdUtil{privatestaticfinalStringTRACE_ID_KEY="traceId";/** * 获取当前线程的 TraceId */publicstaticStringgetTraceId(){StringtraceId=MDC.get(TRACE_ID_KEY);returnStringUtils.isEmpty(traceId)?"":traceId;}/** * 设置 TraceId */publicstaticvoidsetTraceId(StringtraceId){MDC.put(TRACE_ID_KEY,traceId);}/** * 清除 TraceId (非常重要，防止线程池复用导致数据污染) */publicstaticvoidremoveTraceId(){MDC.remove(TRACE_ID_KEY);}}

2. 通过 Filter 拦截请求并设置 TraceId

在请求进入 Controller 之前，我们通过一个 Filter 来生成并设置 TraceId。

@Slf4j@Component@Order(Ordered.HIGHEST_PRECEDENCE)// 确保最先执行publicclassTraceIdFilterimplementsFilter{@OverridepublicvoiddoFilter(ServletRequestrequest,ServletResponseresponse,FilterChainchain)throwsIOException,ServletException{HttpServletRequesthttpRequest=(HttpServletRequest)request;try{// 尝试从请求头获取 TraceId（适用于网关传递过来的场景）StringtraceId=httpRequest.getHeader("X-Trace-Id");if(StringUtils.isEmpty(traceId)){traceId=UUID.randomUUID().toString().replace("-","");}TraceIdUtil.setTraceId(traceId);chain.doFilter(request,response);}finally{// 务必清理，防止内存泄漏或线程池复用导致的脏数据TraceIdUtil.removeTraceId();}}}

3. 配置 Logback 输出格式

修改logback-spring.xml，在 pattern 中加入%X{traceId}：

<configuration><propertyname="LOG_PATTERN"value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{36} - %msg%n"/><appendername="CONSOLE"class="ch.qos.logback.core.ConsoleAppender"><encoder><pattern>${LOG_PATTERN}</pattern></encoder></appender><rootlevel="INFO"><appender-refref="CONSOLE"/></root></configuration>

现在，你的日志输出将类似这样：
2023-10-01 12:00:00.001 [http-nio-8080-exec-1] [a1b2c3d4e5f6...] INFO c.e.controller.UserController - User created successfully

三、 AOP 实现全局接口日志

虽然 MDC 帮我们串联了日志，但我们还需要知道每个接口的入参、出参和耗时。手动打印太麻烦，使用 AOP (Aspect Oriented Programming) 是最好的选择。

1. 引入依赖与启用 AOP

确保引入了spring-boot-starter-aop。

2. 编写日志切面

我们定义一个切面，拦截所有 Controller 层的public方法。

@Slf4j@Aspect@ComponentpublicclassControllerLogAspect{// 定义切点：拦截 Controller 包下的所有方法@Pointcut("execution(public * com.example..controller..*.*(..))")publicvoidcontrollerLog(){}@Around("controllerLog()")publicObjectdoAround(ProceedingJoinPointjoinPoint)throwsThrowable{longstartTime=System.currentTimeMillis();// 获取请求信息ServletRequestAttributesattributes=(ServletRequestAttributes)RequestContextHolder.getRequestAttributes();HttpServletRequestrequest=attributes.getRequest();// 构建日志对象LogInfologInfo=newLogInfo();logInfo.setTraceId(TraceIdUtil.getTraceId());logInfo.setMethod(request.getMethod());logInfo.setUrl(request.getRequestURI());logInfo.setIp(request.getRemoteAddr());logInfo.setClassMethod(joinPoint.getSignature().getDeclaringTypeName()+"."+joinPoint.getSignature().getName());// 获取入参Object[]args=joinPoint.getArgs();// 注意：过滤掉 HttpServletRequest, HttpServletResponse 等无法序列化的参数Object[]logArgs=Arrays.stream(args).filter(arg->!(arginstanceofHttpServletRequest)&&!(arginstanceofHttpServletResponse)).toArray();logInfo.setArgs(logArgs);// 打印入参日志log.info("Request Info: {}",JSON.toJSONString(logInfo));Objectresult;try{result=joinPoint.proceed();}catch(Exceptione){// 记录异常日志（通常由全局异常处理器处理，这里也可以记录一份用于审计）log.error("Controller Exception: ",e);throwe;}// 计算耗时longcostTime=System.currentTimeMillis()-startTime;logInfo.setCostTime(costTime);logInfo.setResult(result);// 打印出参日志log.info("Response Info ({}ms): {}",costTime,JSON.toJSONString(logInfo));returnresult;}@DatapublicstaticclassLogInfo{privateStringtraceId;privateStringmethod;privateStringurl;privateStringip;privateStringclassMethod;privateObject[]args;privateObjectresult;privateLongcostTime;}}

四、 敏感信息脱敏

在实际生产环境中，日志里绝对不能出现明文密码、身份证号、手机号等敏感信息。我们可以在序列化（如 Jackson 或 Fastjson）输出日志前进行处理。

自定义脱敏序列化器 (以 Jackson 为例)

publicclassSensitiveDataSerializerextendsJsonSerializer<String>{@Overridepublicvoidserialize(Stringvalue,JsonGeneratorgen,SerializerProviderserializers)throwsIOException{if(StringUtils.isEmpty(value)){gen.writeNull();return;}// 简单的脱敏逻辑：保留前 3 后 4，中间星号if(value.length()>8){gen.writeString(value.substring(0,3)+"****"+value.substring(value.length()-4));}else{gen.writeString("****");}}}

使用方式：在 DTO 的敏感字段上添加注解

publicclassUserDTO{@JsonSerialize(using=SensitiveDataSerializer.class)privateStringphone;// ...}

或者在 AOP 中通过正则替换整个 JSON 字符串后再打印。

五、 最佳实践

  1. 异步日志 (AsyncAppender)：生产环境日志量巨大，同步打印日志会阻塞业务线程。务必在 Logback 配置中使用AsyncAppender包装Console和FileAppender。
  2. 线程池透传 MDC：如果你的代码使用了@Async或自定义线程池，MDC 的值不会自动传递到子线程。你需要实现TaskDecorator或ThreadPoolTaskExecutor的包装类，在提交任务时拷贝 MDC 上下文，执行完毕后恢复。
  3. 避免打印大对象：如果入参包含大文件流（MultipartFile）或巨大的列表，不要直接打印 JSON，会撑爆日志文件。在 AOP 中判断参数类型进行过滤。
  4. 日志级别控制：不要把所有日志都设为 INFO。开发环境可以是 DEBUG，生产环境建议 INFO 或 WARN，Error 必须报警。

六、 总结

通过 MDC + Filter + AOP 的组合拳，我们实现了：

  1. 全链路追踪：每个请求都有唯一的 TraceId。
  2. 自动审计：无需修改业务代码，自动记录接口出入参和耗时。
  3. 数据安全：敏感信息脱敏，避免合规风险。

这套方案是构建生产级 SpringBoot 应用的标配，掌握它将为你的系统可观测性打下坚实基础。

🎁 福利时间

如果你正在备战面试或者想要学习其他知识，给大家推荐一个宝藏知识库，作者整理了一些列 Java 程序员需要掌握的核心知识，有需要的自取不谢。

知识库地址：https://farerboy.com/