微服务快速集成 TraceId

在微服务中快速集成 TraceId，推荐以下三种主流方案，按“零侵入 → 轻侵入 → 全功能”递进，可根据团队现状任选其一落地。

✅ 方案一：Spring Cloud Sleuth（零侵入，5分钟集成）

适用场景：Spring Cloud 体系，追求最快速度，不需手动传递 TraceId。
步骤：

1. 加依赖（Gateway、各业务服务都加）

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>

2. 日志模板（logback-spring.xml）

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

3. 启动验证
   访问任意接口 → 日志自动出现形如 2025-07-31 10:00:00.123 [http-nio-8080-exec-1] INFO [a1b2c3d4e5f6…] 的 TraceId，Sleuth 还会把它放到 HTTP Header 中向下游传递 。

✅ 方案二：网关 + MDC 过滤器（轻侵入，10分钟集成）

适用场景：已有网关（Spring Cloud Gateway/Nginx），想统一生成并透传 TraceId，兼容非 Spring Cloud 服务。
步骤：

1. 网关过滤器（以 Spring Cloud Gateway 为例）

@Component
public class TraceFilter implements GlobalFilter, Ordered {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String traceId = UUID.randomUUID().toString(true);
        MDC.put("traceId", traceId);
        ServerHttpRequest req = exchange.getRequest()
                .mutate()
                .header("X-Trace-Id", traceId)
                .build();
        return chain.filter(exchange.mutate().request(req).build());
    }
    @Override public int getOrder() { return Ordered.HIGHEST_PRECEDENCE; }
}

2. 下游服务过滤器（只放一次即可）

@Component
public class TraceIdFilter implements Filter {
    public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain)
            throws IOException, ServletException {
        String traceId = ((HttpServletRequest) req).getHeader("X-Trace-Id");
        if (StrUtil.isBlank(traceId)) traceId = UUID.randomUUID().toString(true);
        MDC.put("traceId", traceId);
        chain.doFilter(req, resp);
        MDC.clear();
    }
}

3. logback 模板同方案一，日志里即可看到贯穿所有服务的统一 TraceId 。

✅ 方案三：SkyWalking Agent（全功能，1分钟接入 + 可视化）

适用场景：需要 UI 级链路追踪、方法级耗时、跨语言、跨线程异步追踪。
步骤：

1. 下载 agent
   https://skywalking.apache.org/downloads/

2. 启动参数（所有服务通用）

-javaagent:/path/skywalking-agent.jar
-DSW_AGENT_NAME=order-service
-DSW_AGENT_COLLECTOR_BACKEND_SERVICES=oap.skywalking.svc:11800

3. 代码零改动，启动后访问 UI (http://skywalking-ui:8080) 即可查看完整 Trace 链路和 TraceId 。

✅ 选型对比

✅ 一句话总结

• 只想看日志链路 → Sleuth
• 需要统一网关/自定义 → MDC 过滤器
• 想要完整 APM → SkyWalking

任选其一即可在 10 分钟内完成 TraceId 集成，后续排查问题只需 grep 一个 ID 即可串起全链路。