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

在微服务和高并发架构下日志是排查问题的“救命稻草”。本文将讲解如何利用 AOP、MDC 等技术构建一套包含请求追踪、出入参记录、敏感信息脱敏的全局日志系统。一、 为什么需要全局日志和链路追踪想象一下这样的场景用户反馈下单失败客服给你一个订单号。你开始查日志…如果不带唯一标识你需要在一堆杂乱的并发请求中找到属于那个用户的那一次请求犹如大海捞针。如果接口多如果涉及多个服务调用你需要跨机器拼接日志片段。为了解决这些问题我们需要链路追踪 (TraceId)为每个请求生成唯一的 ID贯穿整个处理流程串联起所有相关日志。全局日志自动记录接口入参、出参、耗时减少手动写log.info(...)的工作量。二、 核心组件MDC (Mapped Diagnostic Context)MDC 是 Slf4j 提供的一个机制它实际上是一个线程安全的ThreadLocalMap。我们可以往里面放入键值对如 TraceId然后在 Logback 配置中通过%X{key}的格式输出。1. 生成 TraceId我们需要一个工具类来管理 TraceId。publicclassTraceIdUtil{privatestaticfinalStringTRACE_ID_KEYtraceId;/** * 获取当前线程的 TraceId */publicstaticStringgetTraceId(){StringtraceIdMDC.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。Slf4jComponentOrder(Ordered.HIGHEST_PRECEDENCE)// 确保最先执行publicclassTraceIdFilterimplementsFilter{OverridepublicvoiddoFilter(ServletRequestrequest,ServletResponseresponse,FilterChainchain)throwsIOException,ServletException{HttpServletRequesthttpRequest(HttpServletRequest)request;try{// 尝试从请求头获取 TraceId适用于网关传递过来的场景StringtraceIdhttpRequest.getHeader(X-Trace-Id);if(StringUtils.isEmpty(traceId)){traceIdUUID.randomUUID().toString().replace(-,);}TraceIdUtil.setTraceId(traceId);chain.doFilter(request,response);}finally{// 务必清理防止内存泄漏或线程池复用导致的脏数据TraceIdUtil.removeTraceId();}}}3. 配置 Logback 输出格式修改logback-spring.xml在 pattern 中加入%X{traceId}configurationpropertynameLOG_PATTERNvalue%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{36} - %msg%n/appendernameCONSOLEclassch.qos.logback.core.ConsoleAppenderencoderpattern${LOG_PATTERN}/pattern/encoder/appenderrootlevelINFOappender-refrefCONSOLE//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方法。Slf4jAspectComponentpublicclassControllerLogAspect{// 定义切点拦截 Controller 包下的所有方法Pointcut(execution(public * com.example..controller..*.*(..)))publicvoidcontrollerLog(){}Around(controllerLog())publicObjectdoAround(ProceedingJoinPointjoinPoint)throwsThrowable{longstartTimeSystem.currentTimeMillis();// 获取请求信息ServletRequestAttributesattributes(ServletRequestAttributes)RequestContextHolder.getRequestAttributes();HttpServletRequestrequestattributes.getRequest();// 构建日志对象LogInfologInfonewLogInfo();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[]argsjoinPoint.getArgs();// 注意过滤掉 HttpServletRequest, HttpServletResponse 等无法序列化的参数Object[]logArgsArrays.stream(args).filter(arg-!(arginstanceofHttpServletRequest)!(arginstanceofHttpServletResponse)).toArray();logInfo.setArgs(logArgs);// 打印入参日志log.info(Request Info: {},JSON.toJSONString(logInfo));Objectresult;try{resultjoinPoint.proceed();}catch(Exceptione){// 记录异常日志通常由全局异常处理器处理这里也可以记录一份用于审计log.error(Controller Exception: ,e);throwe;}// 计算耗时longcostTimeSystem.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 为例)publicclassSensitiveDataSerializerextendsJsonSerializerString{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(usingSensitiveDataSerializer.class)privateStringphone;// ...}或者在 AOP 中通过正则替换整个 JSON 字符串后再打印。五、 最佳实践异步日志 (AsyncAppender)生产环境日志量巨大同步打印日志会阻塞业务线程。务必在 Logback 配置中使用AsyncAppender包装Console和FileAppender。线程池透传 MDC如果你的代码使用了Async或自定义线程池MDC 的值不会自动传递到子线程。你需要实现TaskDecorator或ThreadPoolTaskExecutor的包装类在提交任务时拷贝 MDC 上下文执行完毕后恢复。避免打印大对象如果入参包含大文件流MultipartFile或巨大的列表不要直接打印 JSON会撑爆日志文件。在 AOP 中判断参数类型进行过滤。日志级别控制不要把所有日志都设为 INFO。开发环境可以是 DEBUG生产环境建议 INFO 或 WARNError 必须报警。六、 总结通过 MDC Filter AOP 的组合拳我们实现了全链路追踪每个请求都有唯一的 TraceId。自动审计无需修改业务代码自动记录接口出入参和耗时。数据安全敏感信息脱敏避免合规风险。这套方案是构建生产级 SpringBoot 应用的标配掌握它将为你的系统可观测性打下坚实基础。 福利时间如果你正在备战面试或者想要学习其他知识给大家推荐一个宝藏知识库作者整理了一些列 Java 程序员需要掌握的核心知识有需要的自取不谢。知识库地址https://farerboy.com/