微服务快速集成 TraceId
在微服务中快速集成 TraceId，推荐以下三种主流方案，按“零侵入 → 轻侵入 → 全功能”递进，可根据团队现状任选其一落地。
✅ 方案一：Spring Cloud Sleuth（零侵入，5分钟集成）
适用场景：Spring Cloud 体系，追求最快速度，不需手动传递 TraceId。
步骤：
- 加依赖（Gateway、各业务服务都加）
<dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
- 日志模板（logback-spring.xml）
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level [%X{traceId}] %logger{50} - %msg%n</pattern>
- 启动验证
访问任意接口 → 日志自动出现形如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 服务。
步骤：
- 网关过滤器（以 Spring Cloud Gateway 为例）
@Component
public class TraceFilter implements GlobalFilter, Ordered {@Overridepublic 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; }
}
- 下游服务过滤器（只放一次即可）
@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();}
}
- logback 模板同方案一，日志里即可看到贯穿所有服务的统一 TraceId 。
✅ 方案三：SkyWalking Agent（全功能，1分钟接入 + 可视化）
适用场景：需要 UI 级链路追踪、方法级耗时、跨语言、跨线程异步追踪。
步骤：
-
下载 agent
https://skywalking.apache.org/downloads/ -
启动参数（所有服务通用）
-javaagent:/path/skywalking-agent.jar
-DSW_AGENT_NAME=order-service
-DSW_AGENT_COLLECTOR_BACKEND_SERVICES=oap.skywalking.svc:11800
- 代码零改动，启动后访问 UI (
http://skywalking-ui:8080) 即可查看完整 Trace 链路和 TraceId 。
✅ 选型对比
| 方案 | 侵入性 | 耗时 | 额外能力 | 推荐场景 |
|---|---|---|---|---|
| Sleuth | 0 | 5 分钟 | 与 Zipkin 集成 | Spring Cloud 全家桶 |
| MDC 过滤器 | 小 | 10 分钟 | 灵活 Header 传递 | 多语言 / 异构网关 |
| SkyWalking | 0 | 1 分钟 | UI、指标、告警 | 中大型系统可视化治理 |
✅ 一句话总结
- 只想看日志链路 → Sleuth
- 需要统一网关/自定义 → MDC 过滤器
- 想要完整 APM → SkyWalking
任选其一即可在 10 分钟内完成 TraceId 集成，后续排查问题只需 grep 一个 ID 即可串起全链路。