企业官网建设流程全解析

日志排查有多痛苦，做过分布式系统的都应该有体会。一条用户请求从网关进来，打到订单服务，订单服务又去调库存服务，中间还穿插着MQ异步消息、缓存查询、定时任务……一旦出问题，你得打开五六个服务的日志文件，对着时间戳一条条人工拼链路。运气好半小时能拼出来，运气不好，日志时间差个几百毫秒，直接对不上，整个下午就耗进去了。

我当时接手一个老系统，日均请求量上千万，服务拆了七八个，排查问题基本靠猜。后来定了个规矩：所有服务必须在日志里打上TraceId，一次请求从入口到出口，日志必须能通过同一个ID串起来。这个决定回头来看，是用最小成本把排查效率拉高了一个量级。这篇文章就说说SpringBoot里落地TraceId日志追踪的完整思路，从日志基座改造到过滤器埋点，再到跨线程、跨服务传递，最后聊几个生产环境才踩得到的坑。适合正在被分布式日志困扰的后端开发，也适合想系统化梳理日志链路的团队参考。

1. 为什么日志里需要一条"追踪码"——排查现场与核心思路

1.1 一次真实到不想再经历的排查过程

去年有个线上事故，用户反馈下单后一直收不到确认通知。我们查支付回调日志，发现回调确实到了，但后续的订单状态更新、消息发送链路断掉了。问题在哪一段？没人知道。支付服务打出的日志有序号，订单服务有自己的requestId，消息服务则是完全按时间戳打点。三个服务的日志ID体系互不相认，只能靠时间反推。更惨的是支付回调和订单状态的更新之间隔了两秒多，中间还夹着好几个线程池，日志顺序完全乱掉。

那次我们三个人花了快一下午，最后在一个线程池Executor的日志里发现任务执行时抛了一段JSON解析异常。但因为日志里没有统一ID，我们根本无法确认这条异常和用户的订单到底是不是同一条链路。事情解决后我们复盘，结论特别一致：日志系统缺一个贯穿全链路的身份标识。这个标识就是TraceId。

1.2 TraceId到底是什么，它解决了什么问题

TraceId，翻译过来就是追踪ID。它是一次外部请求进入系统时生成的一个全局唯一ID，然后在整条调用链路上一直传递下去：网关生成一条，HTTP头里带着走，每个服务收到后把它写进自己的日志上下文，下游继续往下传，直到整条链路结束。

它的作用和快递单号非常像。你寄一个包裹，快递单号从发货到中转再到达收货人手上，全程不变。任何一段出了岔子，你只要报出单号，客服就能查出包裹在哪一步滞留了。TraceId就是这条请求链路的物流单号。没有它，你在快递堆里找一个包裹，只能凭感觉翻；有了它，输入单号直接定位。

它能解决的三个核心问题：

• 日志串联：一次请求的多个服务日志，通过同一个TraceId可以一次性搜索出来，按时间线还原完整生命周期。
• 耗时分析：把同一条TraceId的日志按时间戳排列，能看出时间到底耗在哪个服务、哪个环节上。
• 异常聚类：某段时间某个服务错误率飙升，按TraceId前缀或包含关系快速聚合同一批失败请求，从而缩小故障范围。

1.3 三种常用实现方案对比

网上搜TraceId方案，能搜出来一堆，但落地路径其实就三条。我排了个对比表，方便你们选型时参考：

我个人对中小团队的建议是从方案B起步。原因很简单：它能解决80%的日志排查痛点，但成本和入侵性只有方案C的20%。等以后业务真复杂到需要拓扑图、耗时火焰图那一步，再平滑迁移到方案C也不迟，因为TraceId的传递思路是通用的，你前期加的TraceId字段到后期一样能复用。

2. 环境准备与日志基座改造——先让每条日志都有"目击证词"

2.1 动手前的工程结构设计

TraceId的能力不属于任何单一业务模块，它属于公共基础设施。所以建议单独建一个模块或者至少一个独立package放相关的类和配置，比如叫trace或common-log。这样业务模块引用时只需要加一行依赖，不污染主流程代码。

如果你用的是多模块Maven工程，大概会长这样：

your-project ├── trace-starter # TraceId基础能力模块 │ ├── TraceIdFilter.java # 请求入口过滤器 │ ├── TraceIdContext.java # MDC封装 │ ├── TraceIdTaskDecorator.java # 线程池装饰器 │ └── TraceIdRestInterceptor.java # HTTP客户端拦截器 ├── order-service # 业务模块，依赖trace-starter ├── user-service └── gateway

这个设计的核心思路是：业务代码里不要出现任何TraceId的操作逻辑。Filter自动做，线程池自动做，HTTP调用自动做，业务代码完全无感知。这种"横切关注点"就该用切面技术解决，而不是让每个业务开发手写一遍。

2.2 改造logback日志格式：把traceId塞进每一行

SpringBoot默认的日志格式是时间戳+日志级别+线程名+logger名+消息内容，没有TraceId的位置。我们要做的第一件事就是改日志pattern，加一个%X{traceId}输出占位符。

创建一个logback-spring.xml放在src/main/resources下，下面是我在项目中实际在用的基础配置：

<?xml version="1.0" encoding="UTF-8"?> <configuration> <!-- 控制台输出 --> <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender"> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - [%X{traceId}] %msg%n</pattern> <charset>UTF-8</charset> </encoder> </appender> <!-- 文件输出 --> <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"> <file>logs/app.log</file> <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy"> <fileNamePattern>logs/app.%d{yyyy-MM-dd}.log</fileNamePattern> <maxHistory>30</maxHistory> </rollingPolicy> <encoder> <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - [%X{traceId}] %msg%n</pattern> <charset>UTF-8</charset> </encoder> </appender> <root level="INFO"> <appender-ref ref="CONSOLE"/> <appender-ref ref="FILE"/> </root> </configuration>

重点是pattern里的[%X{traceId}]。%X是Logback读取MDC（Mapped Diagnostic Context，日志诊断上下文）的语法，大括号里的traceId就是我们要写入MDC的key。写完之后，每行日志会变成这样：

2024-06-18 14:32:10.456 [http-nio-8080-exec-3] INFO com.example.OrderService - [a7f3b91c8d2e4f5a] 订单创建成功, orderId=123456

以后再用日志搜索，直接在关键字后面加一个a7f3b91c8d2e4f5a，整条链路的日志就能全部捞出来。这一步做完，日志就已经具备了"身份标识"的存储能力，但还缺一个关键环节——谁负责把TraceId写进MDC。

2.3 MDC的原理：一个可编程的日志上下文

这里有必要把MDC讲透，因为后面所有的TraceId操作都在围绕它打转。

MDC是SLF4J日志门面提供的一个功能，本质是一个线程私有的Map。每个线程往MDC里put的key-value，只对当前线程可见，当前线程打印的所有日志都会自动带上这个Map里的内容。这正是Logback在pattern里通过%X{traceId}取到值的原理。

import org.slf4j.MDC; // 写入 MDC.put("traceId", "a7f3b91c8d2e4f5a"); // 使用 log.info("业务日志打印，traceId会自动出现在pattern对应位置"); // 移除 MDC.remove("traceId");

注意MDC底层用的是ThreadLocal，这意味着父子线程天然隔离。这个特性在同步场景下没问题，但一旦牵涉到线程池、@Async异步方法、MQ消费，就会出现子线程打印日志时TraceId为空的情况。这正好是后面第四章要专门处理的核心坑。

3. 拦截器与过滤器：请求进来时生成并绑定TraceId

3.1 用Filter还是Interceptor？为什么选Filter

SpringBoot里实现请求前拦截有两个常用组件：Servlet的Filter和SpringMVC的HandlerInterceptor。绝大多数方案贴子推荐用Interceptor，但我建议用Filter，而且是OncePerRequestFilter。

核心区别在于请求到达的时序。Filter是Servlet容器级别的组件，在请求进入DispatcherServlet之前就执行了；Interceptor则是在SpringMVC的HandlerMapping定位到处理器之后才执行。也就是说，Filter更早、更外层，连静态资源请求、其他Servlet路径都能覆盖到，而且Filter天然支持异步请求的多次调用。

还有一个实际原因：如果你以后接网关、接链路追踪组件，它们绝大多数都是在Filter层面工作的。你早点在Filter层把TraceId的规范确定下来，后面对接会更省事。OncePerRequestFilter是Spring提供的一个Filter封装，它保证同一个请求只执行一次过滤逻辑，解决了Servlet规范中Filter在转发场景下可能被多次调用的问题。

3.2 完整实现：添加、传递、移除的三个关键时刻

先看代码，这是TraceId过滤器最核心的实现：

import org.slf4j.MDC; import org.springframework.core.Ordered; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; import org.springframework.web.filter.OncePerRequestFilter; import javax.servlet.FilterChain; import javax.servlet.ServletException; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; import java.util.UUID; @Component @Order(Ordered.HIGHEST_PRECEDENCE) public class TraceIdFilter extends OncePerRequestFilter { public static final String TRACE_ID = "traceId"; @Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { // 1. 从请求头中尝试获取上游传递进来的TraceId String traceId = request.getHeader("X-Trace-Id"); if (traceId == null || traceId.isEmpty()) { // 2. 上游没有，则生成一个新的 traceId = UUID.randomUUID().toString().replace("-", ""); } // 3. 写入MDC上下文 MDC.put(TRACE_ID, traceId); try { // 4. 继续执行后续业务逻辑 filterChain.doFilter(request, response); } finally { // 5. 请求结束，必须清理 MDC.remove(TRACE_ID); } } }

这段代码看着简单，但三个关键决策点需要解释清楚：

为什么要从请求头里先取一次？因为在一个微服务架构里，你处理的请求很可能不是用户直接打进来的，而是上游服务转发过来的。如果上游已经在Header里放了TraceId，你直接"接住"它继续用，整条链路才能连成线。如果你无视上游ID重新生成一个，那上游日志和下游日志就彻底断了。这一点到第五章讲跨服务传递时会再次体现。

为什么用UUID还是其他生成器？UUID是通用做法，而且去掉横杠后长度16位，日志里不占太多空间。生产环境如果对ID生成有更高要求，可以换成雪花算法或美团开源的Leaf那种发号器，但从日志追踪的角度来说，UUID的冲突概率已经足够低了，没必要过度设计。

为什么要在finally里面MDC.remove？这个动作最容易被忽略，但如果漏了，后果相当严重。Tomcat的线程池是复用的，一个请求处理完了线程会回到线程池待命，下一个请求可能拿到同一个线程。如果上一个请求在MDC里留下的TraceId没被清理，下个请求打印日志时就会"继承"上一个请求的ID，两个毫无关系的请求日志搅合在一起，排查时会出现幻觉一样的跨请求串号。这个坑，我见过不止一次。

3.3 兼容标准链路参数的接法

现在很多团队已经开始接入OpenTelemetry规范了，如果你们系统里已经有链路追踪中间件，最好在Filter里做一层兼容，让TraceId和规范的traceparent头对齐。

业界比较通用的链路上下文头是W3C标准的traceparent，格式是"版本号-全局TraceId-SpanId-标志位"。既然标准已经定好了，我们自己定义的X-Trace-Id最好能兼容读取它：

private String extractTraceId(HttpServletRequest request) { // 优先取自定义头，方便外部排查开放 String traceId = request.getHeader("X-Trace-Id"); if (traceId != null && !traceId.isEmpty()) { return traceId; } // 兼容W3C标准：traceparent的第二个字段就是全局TraceId String traceParent = request.getHeader("traceparent"); if (traceParent != null && !traceParent.isEmpty()) { String[] parts = traceParent.split("-"); if (parts.length >= 2 && parts[1].length() == 32) { return parts[1]; } } return null; }

这样做的意义在于，今天你用的是自研TraceId，明天如果要升级到专业的链路追踪系统，TraceId的来源和格式不需要迁移，日志侧完全不用动。

4. 异步线程池：子线程丢失TraceId的坑与TaskDecorator解法

4.1 为什么异步日志里traceId会"断线"

上一章我提到，MDC底层是ThreadLocal，线程之间天然隔离。这意味着在同步调用链路中，TraceId从Filter写入MDC后，后续同线程的每行日志都能正常输出。但一旦你把任务丢给一个线程池处理，情况就变了：

// 伪代码示意 @Async public void sendAsyncMessage(Order order) { // 这里打印的日志，[%X{traceId}]是空的！ log.info("异步发送消息, orderId={}", order.getOrderId()); }

原因就是@Async会把方法提交到另一个线程执行，而这个新线程的MDC是空的。父线程在MDC里存的TraceId不会自动"遗传"给子线程。

这个问题的隐蔽性在于：同步链路里日志完全正常，唯独异步链路里TraceId时有时无，日志文件看起来一段有一截没有。如果你不知道MDC的线程隔离机制，很容易怀疑是Filter写丢数据，然后反复在Filter代码里加日志排查，最后发现Filter一点问题没有，问题出在线程切换。

4.2 一个TaskDecorator把上下文"复印"过去

Spring的ThreadPoolTaskExecutor和@Async底层都支持一个叫TaskDecorator的扩展点。它的作用是在任务真正执行前做一些包装操作。我们完全可以利用它，把父线程的MDC内容复制到子线程里，任务执行完再清掉。

import org.slf4j.MDC; import org.springframework.core.task.TaskDecorator; import java.util.Map; public class TraceIdTaskDecorator implements TaskDecorator { @Override public Runnable decorate(Runnable runnable) { // 父线程的MDC上下文 Map<String, String> contextMap = MDC.getCopyOfContextMap(); return () -> { if (contextMap != null) { // 把父线程的MDC复制到当前线程 MDC.setContextMap(contextMap); } try { runnable.run(); } finally { // 清理当前线程的MDC，防止线程池复用串号 MDC.clear(); } }; } }

用的时候，只需要在线程池Bean上装配装饰器：

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor; @Configuration public class AsyncConfig { @Bean("asyncExecutor") public ThreadPoolTaskExecutor asyncExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(8); executor.setMaxPoolSize(16); executor.setQueueCapacity(1000); executor.setThreadNamePrefix("async-"); // 关键步骤：绑定装饰器 executor.setTaskDecorator(new TraceIdTaskDecorator()); executor.initialize(); return executor; } }

如果你用的核心线程池是java.util.concurrent.ThreadPoolExecutor，Spring也提供了对应的适配器ThreadPoolTaskExecutor；如果你的代码里直接new了原生ThreadPoolExecutor，就需要手动在任务提交前复制MDC，或者用中介包装Runnable。这里更推荐直接统一用ThreadPoolTaskExecutor，这样装饰器能统一管理。

4.3 踩坑实录：装饰器漏配导致的半小时定位事故

讲一个实际发生的案例。某次压测，架构组要求全链路日志必须带TraceId。订单服务接了Filter，日志打印正常。但发现一个问题：订单创建成功后发Kafka消息、发短信通知的日志里，TraceId要么是空的，要么是上一次请求残留的。

我们当时以为是MQ生产者配置问题，翻遍了Kafka相关的配置类，毫无头绪。后来发现这个服务里混用了两种线程池：一部分Bean是ThreadPoolTaskExecutor，一部分是裸ThreadPoolExecutor。前者通过setTaskDecorator配置了装饰器，TraceId正常传递；后者没有任何包装，直接execute任务，MDC当然是空的。

更隐蔽的是，因为线程池里线程是复用的，那些裸ThreadPoolExecutor处理的日志里，TraceId有时候显示的是上一个任务的ID——看起来"好像有值"，实际上完全是串号的脏数据。这种日志如果你不仔细关联请求时间线，根本发现不了。

排查经验总结成一条：不要在一个应用里混用多种线程池执行异步逻辑，统一用ThreadPoolTaskExecutor并且统一配TaskDecorator。如果有历史裸线程池，写个工具类，统一提交时复制MDC，别让这个坑留到生产爆雷。

5. 跨服务传递：把TraceId装进HTTP头寄给下一个系统

5.1 为什么TraceId必须随RPC请求"出门"

本地日志做得再好，一次业务请求如果跨了三个服务，A服务日志里TraceId是a7f3...，B服务里TraceId却是新生成的一个ID，那这条链路在跨服务层面又断了。所以TraceId必须跟着请求"出门"——每次发起HTTP调用时，把当前线程MDC里的TraceId塞进请求头，下游服务的Filter才能通过request.getHeader("X-Trace-Id")把它接住。

远程调用主要分两种场景：RestTemplate/WebClient这种HTTP客户端，以及OpenFeign这种声明式客户端。两个场景都要做拦截器注入。

5.2 RestTemplate与OpenFeign的请求头注入

RestTemplate是Spring最经典的HTTP客户端，它提供了ClientHttpRequestInterceptor扩展点，可以在请求发出前统一设置请求头：

import org.slf4j.MDC; import org.springframework.http.HttpRequest; import org.springframework.http.client.ClientHttpRequestExecution; import org.springframework.http.client.ClientHttpRequestInterceptor; import org.springframework.http.client.ClientHttpResponse; import java.io.IOException; public class TraceIdRestInterceptor implements ClientHttpRequestInterceptor { @Override public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException { String traceId = MDC.get("traceId"); if (traceId != null && !traceId.isEmpty()) { request.getHeaders().set("X-Trace-Id", traceId); } return execution.execute(request, body); } }

然后在构建RestTemplate实例时把它注册进去：

@Configuration public class RestTemplateConfig { @Bean public RestTemplate restTemplate() { RestTemplate restTemplate = new RestTemplate(); restTemplate.setInterceptors(List.of(new TraceIdRestInterceptor())); return restTemplate; } }

如果你的服务用的是OpenFeign，也有一个非常对口的扩展点RequestInterceptor：

import feign.RequestInterceptor; import feign.RequestTemplate; import org.slf4j.MDC; public class TraceIdFeignInterceptor implements RequestInterceptor { @Override public void apply(RequestTemplate template) { String traceId = MDC.get("traceId"); if (traceId != null && !traceId.isEmpty()) { template.header("X-Trace-Id", traceId); } } }

Feign的RequestInterceptor会在模板构建完成、真正发送请求之前执行，所以这里设置Header是安全且有效的。注册方式也简单，在Feign的配置类里把这个类声明成Bean即可。

如果你用的是Spring Cloud Gateway网关，甚至可以在全局过滤器里统一透传，避免每个下游服务都自己加拦截器。网关侧逻辑就是：从ServerWebExchange的请求头里取TraceId，如果没有则生成，然后塞进MDC，转发时通过ServerWebExchange.Builder改写请求头。这一层做好之后，下游服务理论上可以无感接入，因为它们只需要在Filter里读取Header。

5.3 消费方如何优雅地"认领"头部TraceId

请求到了下游服务之后，就是第三章TraceIdFilter的活了。Filter里优先读Header，读到了就用Header里的值写入MDC，读不到才自己生成。这段逻辑我在3.2节已经给了完整实现，这里想补充一个设计原则：Header里的TraceId优先级永远大于本地生成。

原因是整条链路需要一个唯一的根TraceId，如果每个服务都优先生成自己的，链路就断了。严谨的做法是在Filter里做好上接下传，HTTP客户端侧做好下发，两边配合，链路才能完整。我把这条路线的数据流画出来（别嫌我用文字描述，流程图在博客里经常排版乱，文字反而更清楚）：

用户请求 -> 网关Filter(生成TraceId: a7f3...) -> 设置响应头X-Trace-Id: a7f3... -> 转发请求头X-Trace-Id: a7f3... -> 订单服务Filter(读到a7f3...,写入MDC) -> 订单服务RestTemplate拦截器(从MDC取a7f3...,加到下游请求头) -> 库存服务Filter(读到a7f3...,写入MDC) -> ... -> 整条链路日志都带a7f3...

整条链路只要有一个环节没传TraceId，链路就会断一截。这也是为什么我强烈建议把TraceId传递做成公共starter，而不是每个业务服务自己复制粘贴一份代码。公共组件意味着一次改造，全链路生效，少一个遗忘角落。

6. 响应头输出与生产排查的实战技巧

6.1 在HTTP响应中带回TraceId

日志追踪不只是给后端开发自己看的，前端调用接口报错时，如果接口响应头里带着一个TraceId，前后端联动排查的效率会高很多。用户在前端页面看到"网络异常"，客服把浏览器开发者工具里的TraceId报给后端，后端拿这个ID直接捞日志，几分钟就能定位。

实现方式是在入口Filter里把TraceId设置到响应头：

@Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { String traceId = extractTraceId(request); if (traceId == null || traceId.isEmpty()) { traceId = UUID.randomUUID().toString().replace("-", ""); } MDC.put(TRACE_ID, traceId); // 关键：把TraceId写入响应头 response.setHeader("X-Trace-Id", traceId); try { filterChain.doFilter(request, response); } finally { MDC.remove(TRACE_ID); } }

这一步动作很小，但收益很直接。尤其是用了API网关做统一入口的系统，在网关层统一注入响应头，所有服务的HTTP响应都自带TraceId，临时的联调排错都不需要扒日志看半天。

6.2 日志检索的三条黄金经验

TraceId落地之后，怎么用好它才是真正见功夫的地方。分享三条我在生产环境摸索出来的经验：

经验一：用TraceId做全链路耗时分析。找出同一条TraceId下的所有日志，按时间戳排序，重点看每个服务入口日志和出口日志的时间差，能迅速定位耗时集中在哪个节点。比如一条请求总耗时800ms，其中商品服务占50ms，库存服务占700ms，问题在库存服务就非常明显。

经验二：ERROR日志必须带上TraceId一起告警。我们后来给日志采集加了规则：ERROR级别的日志，必须从MDC里把TraceId提取出来作为一个独立维度字段上报到监控系统。这样告警平台触发的每一条告警，都能在日志平台里按TraceId一键关联上下文，大幅缩短了值班人员的定位路径。

经验三：定期抽查"空TraceId日志"。如果你发现日志里有一批日志的TraceId是空的，排查顺序是：入口Filter是否被其他Filter拦截了？异步线程池是否都配了TaskDecorator？MQ消费是否在消费端入口补充了TraceId生成逻辑？日志里空TraceId的比例，某种程度上反映了你的TraceId链路覆盖率的健康程度。

6.3 TraceId之外的衍生玩法：全链路标签池

TraceId只是日志追踪的第一层。等这套机制跑稳了，你会发现MDC里还能放更多维度，比如用户ID、订单号、渠道来源、环境标识。把它们都放进MDC，日志的检索维度会一下子丰富起来。

MDC.put("traceId", traceId); MDC.put("userId", String.valueOf(userId)); MDC.put("channel", channel);

日志配置里统一加上对应输出项：

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

这样排障的时候，不只知道你这条链路是谁（traceId），还知道是哪个用户、从哪个渠道进来的。前端的电商客服一报"用户ID是123456，在支付宝渠道下单失败"，后端直接拿userId刷日志，比拿TraceId更快进入场景。不同领域可以从这个思路延伸出自己的标签体系，核心逻辑是一样的——在日志里建立多维度的诊断上下文。

TraceId这件事从需求提出到全链路跑通，我们走了大概两周，真正写代码的时间三四天，剩下时间都在补历史线程池的坑和规范统一。回头来看，这可能是最近一年里性价比最高的一次架构改造。如果你也在被多服务日志问题困扰，建议找个下午把Filter和日志Pattern先搭起来，跑通一条最简单的链路，再逐步覆盖异步线程和跨服务调用。这一层基建越早铺好，后面排查问题的时间就越值钱。