【后端】【Java】一文详解Spring Boot 统一日志与链路追踪实践

Spring Boot 统一日志与链路追踪实践

在真实的 Spring Boot 项目中，仅仅“能跑”远远不够。
能定位问题、能还原请求、能快速排障，才是一个成熟后端系统的核心能力。

而这一切，都离不开统一日志与链路追踪（Trace）。

一、为什么要做统一日志与链路追踪？

如果没有统一日志，常见问题包括：

• 日志格式杂乱无章

• 不同接口日志风格不一致

• 一次请求的日志散落在多行、多个类中

• 微服务场景下无法串联完整调用链

❌ 出现线上问题时，只能“猜”。

✅ 统一日志与链路追踪能解决什么？

• 一次请求 = 一个 TraceId

• 所有日志都能被串起来

• 快速定位慢接口、异常接口

• 为监控、告警、埋点提供基础数据

二、日志、链路追踪的整体设计思路

推荐分层设计

请求入口（Filter） ↓ 生成 TraceId ↓ 放入 MDC（日志上下文） ↓ 业务日志自动携带 TraceId ↓ 请求结束清理 MDC

三、Spring Boot 日志体系基础

Spring Boot 默认使用：

• SLF4J（门面）

• Logback（实现）

推荐日志使用方式

private static final Logger log = LoggerFactory.getLogger(UserController.class);

不要直接使用：

System.out.println()

四、什么是链路追踪（Trace）？

核心概念

在单体应用中：

TraceId 就足够

五、基于 MDC 的链路追踪实现

1️⃣ 什么是 MDC？

MDC（Mapped Diagnostic Context）是 Logback 提供的线程级上下文变量存储。

MDC.put("traceId", "xxx");

日志中即可自动打印。

2️⃣ 请求入口生成 TraceId（Filter）

@Component public class TraceFilter implements Filter { private static final String TRACE_ID = "traceId"; @Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) { try { String traceId = UUID.randomUUID().toString().replace("-", ""); MDC.put(TRACE_ID, traceId); chain.doFilter(request, response); } catch (Exception e) { throw new RuntimeException(e); } finally { MDC.remove(TRACE_ID); } } }

3️⃣ 日志配置中打印 TraceId（logback-spring.xml）

<pattern> %d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} [traceId=%X{traceId}] - %msg%n </pattern>

4️⃣ 日志效果示例

2025-01-01 10:00:01.123 [http-nio-8080-exec-1] INFO UserController [traceId=9f8a3b7c2d1a4e] - 查询用户信息

👉 同一次请求的所有日志traceId 完全一致

六、统一请求日志（接口维度）

使用 HandlerInterceptor

@Component public class LogInterceptor implements HandlerInterceptor { private static final Logger log = LoggerFactory.getLogger(LogInterceptor.class); @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) { log.info("请求开始: {} {}", request.getMethod(), request.getRequestURI()); return true; } @Override public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) { log.info("请求结束: {} {}", request.getMethod(), request.getRequestURI()); } }

注册拦截器

@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(new LogInterceptor()) .addPathPatterns("/**"); } }

七、记录接口耗时（性能关键）

long start = System.currentTimeMillis(); // 业务逻辑 long cost = System.currentTimeMillis() - start; log.info("接口耗时: {} ms", cost);

推荐统一在拦截器中处理，避免重复代码。

八、异常日志统一记录

结合全局异常处理：

@ExceptionHandler(Exception.class) public ApiResponse<Void> handleException(Exception e) { log.error("系统异常", e); return ApiResponse.error(500, "服务器内部错误"); }

👉 异常日志必须打印堆栈

九、日志分级规范（非常重要）

❌ 不要滥用 ERROR
❌ 不要把正常流程打成 WARN

十、微服务场景下的链路追踪（扩展）

1️⃣ TraceId 透传

• 网关生成 TraceId

• HTTP Header 传递：

X-Trace-Id: xxx

2️⃣ Spring Cloud 场景

• Sleuth（旧）

• Micrometer Tracing（新）

• Zipkin / SkyWalking

十一、统一日志最佳实践总结

✅ Filter 生成 TraceId
✅ MDC 保存上下文
✅ 日志格式统一
✅ 接口日志 + 异常日志
✅ 日志分级清晰

十二、总结

统一日志与链路追踪，是后端系统“可运维性”的基石。

在 Spring Boot 项目中：

• MDC 是最低成本的链路追踪方案

• 单体应用足够用

• 微服务可平滑升级到专业链路系统

写日志不是为了“看”，
而是为了在出问题时能快速定位问题。