试想这样一个场景：用户反馈下单失败，客服丢给你一个订单号。你一头扎进日志，开始大海捞针——
- 如果每个请求没有唯一标识，就得在一堆并发线程里手动拼凑属于那个用户的那一次调用，效率低到令人崩溃。
- 如果接口跨了多个服务，还要跨机器、跨进程，把零散的日志片段像拼图一样拼起来，简直是一场噩梦。
问题的症结很明确：我们需要一套机制，让日志不仅能“看”，还能“追”。通俗点讲，就是给每个请求发一张“身份证”，贯穿整个调用链路，自动记录它的来龙去脉，同时把敏感信息藏好——这其实是构建可观测性系统的第一步，也是生产级应用的基础设施。
一、 为什么需要全局日志和链路追踪？
回到刚才的场景：用户反馈下单失败，客服给你一个订单号。你开始查日志……
- 不带唯一标识：一堆杂乱的并发请求中，找到属于那个用户的那一次请求，如同大海捞针。
- 接口多、服务多：涉及多个服务调用时，需要跨机器拼接日志片段，耗时又容易出错。
为了解决这些问题，我们需要两个核心能力：
- 链路追踪 (TraceId)：为每个请求生成唯一的 ID，贯穿整个处理流程，串联起所有相关日志。
- 全局日志：自动记录接口入参、出参、耗时，减少手动写
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 字符串后再打印，具体看项目需求。
五、 最佳实践
- 异步日志 (AsyncAppender)：生产环境日志量巨大，同步打印日志会阻塞业务线程。务必在 Logback 配置中使用
AsyncAppender包装Console和FileAppender。 - 线程池透传 MDC：如果你的代码使用了
@Async或自定义线程池，MDC 的值不会自动传递到子线程。需要实现TaskDecorator或ThreadPoolTaskExecutor的包装类，在提交任务时拷贝 MDC 上下文，执行完毕后恢复。 - 避免打印大对象：如果入参包含大文件流（MultipartFile）或巨大的列表，不要直接打印 JSON，会撑爆日志文件。在 AOP 中判断参数类型进行过滤。
- 日志级别控制：不要把所有日志都设为 INFO。开发环境可以是 DEBUG，生产环境建议 INFO 或 WARN，Error 必须报警。
六、 总结
通过 MDC + Filter + AOP 这套组合拳，我们实现了三个关键目标：
- 全链路追踪：每个请求都有唯一的 TraceId，串联起所有相关日志。
- 自动审计：无需修改业务代码，自动记录接口出入参和耗时。
- 数据安全：敏感信息脱敏，避免合规风险。
这套方案已经是生产级 SpringBoot 应用的标配。掌握它，就等于给系统的可观测性打下了坚实的基础——排查问题时，你不再是那个“大海捞针”的苦命人，而是拿着 TraceId 精准定位问题的专家。
