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

试想这样一个场景：用户反馈下单失败，客服丢给你一个订单号。你一头扎进日志，开始大海捞针——

• 如果每个请求没有唯一标识，就得在一堆并发线程里手动拼凑属于那个用户的那一次调用，效率低到令人崩溃。
• 如果接口跨了多个服务，还要跨机器、跨进程，把零散的日志片段像拼图一样拼起来，简直是一场噩梦。

问题的症结很明确：我们需要一套机制，让日志不仅能“看”，还能“追”。通俗点讲，就是给每个请求发一张“身份证”，贯穿整个调用链路，自动记录它的来龙去脉，同时把敏感信息藏好——这其实是构建可观测性系统的第一步，也是生产级应用的基础设施。

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

回到刚才的场景：用户反馈下单失败，客服给你一个订单号。你开始查日志……

• 不带唯一标识：一堆杂乱的并发请求中，找到属于那个用户的那一次请求，如同大海捞针。
• 接口多、服务多：涉及多个服务调用时，需要跨机器拼接日志片段，耗时又容易出错。

为了解决这些问题，我们需要两个核心能力：

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

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

MDC 是 Slf4j 提供的一个机制，它本质上是一个线程安全的 ThreadLocal。我们可以往里面放入键值对（比如 TraceId），然后在 Logback 配置中通过 %X{key} 的格式输出。这个设计很巧妙——它让日志与线程上下文绑定，自动实现“同一请求、同一 ID”的效果。

1. 生成 TraceId

需要写一个工具类来管理 TraceId，核心逻辑就是围绕 MDC 的 get、put、remove。

public class TraceIdUtil {
    
    private static final String TRACE_ID_KEY = "traceId";

    /**
     * 获取当前线程的 TraceId
     */
    public static String getTraceId() {
        String traceId = MDC.get(TRACE_ID_KEY);
        return StringUtils.isEmpty(traceId) ? "" : traceId;
    }

    /**
     * 设置 TraceId
     */
    public static void setTraceId(String traceId) {
        MDC.put(TRACE_ID_KEY, traceId);
    }

    /**
     * 清除 TraceId (非常重要，防止线程池复用导致数据污染)
     */
    public static void removeTraceId() {
        MDC.remove(TRACE_ID_KEY);
    }
}

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

在请求进入 Controller 之前，通过一个 Filter 来生成并设置 TraceId。这里有个细节：如果上游网关已经传了 TraceId（比如通过 HTTP 头 X-Trace-Id），我们直接复用；否则自己生成一个 UUID。

@Slf4j
@Component
@Order(Ordered.HIGHEST_PRECEDENCE) // 确保最先执行
public class TraceIdFilter implements Filter {

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        
        try {
            // 尝试从请求头获取 TraceId（适用于网关传递过来的场景）
            String traceId = 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 输出格式

在 pattern 中加入 %X{traceId}，日志就会自动带上这个 ID。

    
    
        
            ${LOG_PATTERN}
        
    
    
        
    

配置完成后，日志输出会变成类似这样：2023-10-01 12:00:00.001 [http-nio-8080-exec-1] [a1b2c3d4e5f6...] INFO c.e.controller.UserController - User created successfully。一眼就能看出哪个请求对应哪条日志，排查问题的效率直接翻倍。

三、 AOP 实现全局接口日志

MDC 帮我们串联了日志，但还有一个痛点：每个接口的入参、出参、耗时，难道都要手动写 log.info？当然不——用 AOP 一把梭，既优雅又省力。

1. 引入依赖与启用 AOP

确保引入了 spring-boot-starter-aop，并在启动类或配置类上加上 @EnableAspectJAutoProxy（Spring Boot 通常自动配置）。

2. 编写日志切面

定义一个切面，拦截所有 Controller 层的 public 方法。核心逻辑：在方法执行前后记录请求信息与响应信息，并计算耗时。

@Slf4j
@Aspect
@Component
public class ControllerLogAspect {

    // 定义切点：拦截 Controller 包下的所有方法
    @Pointcut("execution(public * com.example..controller..*.*(..))")
    public void controllerLog() {}

    @Around("controllerLog()")
    public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
        long startTime = System.currentTimeMillis();
        
        // 获取请求信息
        ServletRequestAttributes attributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        HttpServletRequest request = attributes.getRequest();
        
        // 构建日志对象
        LogInfo logInfo = new LogInfo();
        logInfo.setTraceId(TraceIdUtil.getTraceId());
        logInfo.setMethod(request.getMethod());
        logInfo.setUrl(request.getRequestURI());
        logInfo.setIp(request.getRemoteAddr());
        logInfo.setClassMethod(joinPoint.getSignature().getDeclaringTypeName() + "." + joinPoint.getSignature().getName());
        
        // 获取入参，过滤掉 HttpServletRequest、HttpServletResponse 等无法序列化的参数
        Object[] args = joinPoint.getArgs();
        Object[] logArgs = Arrays.stream(args)
                .filter(arg -> !(arg instanceof HttpServletRequest) && !(arg instanceof HttpServletResponse))
                .toArray();
        logInfo.setArgs(logArgs);
        
        // 打印入参日志
        log.info("Request Info: {}", JSON.toJSONString(logInfo));

        Object result;
        try {
            result = joinPoint.proceed();
        } catch (Exception e) {
            // 记录异常日志（通常由全局异常处理器处理，这里也可以记录一份用于审计）
            log.error("Controller Exception: ", e);
            throw e;
        }
        
        // 计算耗时
        long costTime = System.currentTimeMillis() - startTime;
        logInfo.setCostTime(costTime);
        logInfo.setResult(result);
        
        // 打印出参日志
        log.info("Response Info ({}ms): {}", costTime, JSON.toJSONString(logInfo));
        
        return result;
    }

    @Data
    public static class LogInfo {
        private String traceId;
        private String method;
        private String url;
        private String ip;
        private String classMethod;
        private Object[] args;
        private Object result;
        private Long costTime;
    }
}

四、 敏感信息脱敏

生产环境里，明文密码、身份证号、手机号等敏感信息绝对不能出现在日志里。怎么做？一种常见方案是在序列化输出时做脱敏处理，比如用 Jackson 自定义序列化器。

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

public class SensitiveDataSerializer extends JsonSerializer {
    @Override
    public void serialize(String value, JsonGenerator gen, SerializerProvider serializers) throws IOException {
        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 的敏感字段上添加注解

public class UserDTO {
    
    @JsonSerialize(using = SensitiveDataSerializer.class)
    private String phone;
    
    // ...
}

如果想更通用，也可以在 AOP 中通过正则替换整个 JSON 字符串后再打印，具体看项目需求。

五、 最佳实践

1. 异步日志 (AsyncAppender)：生产环境日志量巨大，同步打印日志会阻塞业务线程。务必在 Logback 配置中使用 AsyncAppender 包装 Console 和 File Appender。
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 应用的标配。掌握它，就等于给系统的可观测性打下了坚实的基础——排查问题时，你不再是那个“大海捞针”的苦命人，而是拿着 TraceId 精准定位问题的专家。