微服务链路追踪实战：从网关到OpenFeign的TraceID全链路透传方案

上周同事跑过来让我帮忙排查一个线上资损问题，会员服务和积分服务两边都拉了日志，各执一词说是对方环境的问题。我把两份日志放到一起对的时候，一眼就发现了根因——两边的 traceId 根本对不上，用户信息在服务 B 的日志里全是 null。这场景在我做过的好几个微服务项目里都出现过：请求从网关进来，网关生成好 TraceID，服务 A 通过 OpenFeign 去调服务 B，结果到了服务 B 之后，日志里的链路编号变成了一个新的，用户信息也凭空消失了。问题几乎都出在 OpenFeign 这一跳的网关透传上下文没做好。

这篇我就把 TraceID、用户信息经过网关到 OpenFeign、再到下游服务的完整透传方案拆开讲一遍。包括每一层该在哪个位置写代码、为什么放在那个位置、线程一换之后遇到的问题，以及我在线上实际踩过的几个坑。

1. 问题从哪来：TraceID 在跨服务时是怎么断的

先明确一个现实：现在微服务的调用基本都是“浏览器/Nginx → 网关 → 服务 A → OpenFeign → 服务 B”这种链式结构。你在网关这一层能拿到用户的登录态，能在服务 A 里用 ThreadLocal 存用户信息，但这些信息默认是不会跟着 OpenFeign 的 HTTP 请求跑到服务 B 的。

为什么不会？

因为 OpenFeign 本质上帮你创建了一个全新的 HTTP 请求模板，它只知道自己要调哪个 URL、带什么参数，并不知道“上一个 HTTP 请求”曾经带过哪些 Header，也不知道你当前进程里的日志 ID 叫什么。跨服务的链路信息想要往下走，唯一靠谱的通道就是 HTTP Header。

我处理过的一个现场大概是这样的：

code复制订单服务   [http-nio-8080-exec-7] 收到下单请求，订单号=1001
商品服务   [http-nio-8081-exec-2] 收到扣库存请求，订单号=1001，userId=null

如果日志系统里没有做任何透传，两边都能处理业务，但一出问题你想把这两条日志拉回同一条时间线，基本只能靠订单号去猜。订单号还是业务主键，有时候调用的下游没有业务主键，只有内部 ID，那就更没法排查了。

1.1 微服务日志排障为什么必须靠 TraceID

排障时最好用的线索不是某个参数值，而是一个能贯穿全链路的 TraceID。你只需要确认一次请求入口产生的 ID，然后在订单服务、商品服务、积分服务各自的日志里搜同一个 ID，就能把这个请求在哪个服务上花了多长时间、哪个环节抛了异常全部串起来。

但这里有个前提：从网关到服务 A，再从服务 A 通过 OpenFeign 到服务 B，所有参与方写日志时用的都是同一个 TraceID。

拆开看就是两个动作：

• 入口处生成或接收 TraceID，把它放进 org.slf4j.MDC 里，这样当前服务的每行日志都能自动带上；
• 调用下游前，从 MDC 取出 TraceID，放到 HTTP Header 里发给下游；下游再将它放进自己的 MDC。

OpenFeign 在中间扮演的角色，就是“本地 MDC 到下游 HTTP Header”之间的搬运工。如果你没给 OpenFeign 配置 RequestInterceptor，这一个环节默认就是断的。

1.2 除了 TraceID，还有哪些上下文会被弄丢

TraceID 丢失只是最明显的一个问题。实际线上跨服务丢得更多的还有几样：

• 当前登录用户 ID、用户名：服务 B 想做数据权限过滤、审计日志、风控判断时拿不到身份；
• 租户 ID：SaaS 系统里几乎所有表都要按租户隔离，接口收到请求后没有租户信息，要么报错要么串数据；
• 来源端类型：比如来自 App 还是来自管理后台，这会影响限流策略和错误提示；
• 设备号、语言、时区等弱上下文：通常只在网关层需要，但部分业务也依赖。

我们把这类信息统一叫“业务上下文”或“请求上下文”。它们和 TraceID 有一点不同：TraceID 是给日志和监控系统看的，本质上就是字符串；用户信息是业务代码要用的，需要还原成一个对象，不能只往 MDC 里塞一个字符串就完事。

所以一个健壮的透传方案要同时解决两类问题：日志链路的串接，以及业务上下文的跨服务还原。

2. 先想清楚再动手：Header、MDC、ThreadLocal 各自该管什么

很多方案写着写着就失控，往往是没分清楚三个概念：HTTP Header、MDC、ThreadLocal（或自定义的上下文对象）。这三样东西各有自己的生命周期，用错了地方就会出怪问题。

2.1 三个载体的分工

HTTP Header 是服务之间传递信息的唯一通道。我们所有的跨进程数据，最终都要落到 Header 上。但它有一个缺点：不会自动进入代码，需要手动解析、手动清理。

MDC 是 SLF4J 提供的一个“每线程日志上下文”，底层其实就是一个线程绑定的 Map。你把 traceId 放进 MDC，再用带 %X{traceId} 的日志格式，当前线程所有日志都会自动带上。它是给日志框架看的，不是给业务代码取数用的。

ThreadLocal 是我们自己写的用户上下文容器，专门给业务代码用。业务代码里调 UserContext.get() 就能拿到当前用户对象，比每个接口都从 Header 取参数干净很多。

它们的关系是这样的：

调用发起侧（服务 A）的代码逻辑是：从 ThreadLocal 读取用户上下文，从 MDC 读取 TraceID，写入到即将发出的 Feign 请求 Header。接收侧（服务 B）的逻辑正好相反：从收到的 Header 里解析出 TraceID 和用户信息，分别放入 MDC 和 ThreadLocal。

2.2 每个角色都只需要做好一个动作

网关层要做的动作最少：接收外部请求，如果没有 TraceID 就生成一个，然后把它连同用户信息一起塞进转发的请求 Header。

服务 A 作为调用方要做的动作也少：它的入口 Filter 已经把自己的 MDC 和 UserContext 建好了，正常处理业务。当 OpenFeign 发起调用时，拦截器读取本地上下文并写入 Header。

服务 B 作为被调方要做的动作是：在入口 Filter 里读取 Header，重新构造 MDC 和 UserContext。接下来它在本地怎么打日志、怎么取用户信息，都和使用服务 A 内部一样，不需要感知上游是谁。

这三步各自独立，但必须同时做齐。缺了网关那一步，入口没有统一 ID；缺了 OpenFeign 拦截器，服务 A 调服务 B 时 ID 断掉；缺了服务 B 的入口 Filter，Header 里的 ID 到了服务 B 却没人写进 MDC，日志照样串不起来。

2.3 为什么不用 Sleuth / Micrometer Tracing 一步到位

听到这里可能有人会问：Spring Cloud 不是有 Sleuth、Micrometer Tracing 吗，引入之后 Feign、RestTemplate 会自动生成并传递 TraceID，为什么还要自己手写？

确实，如果团队直接上了 Spring Boot 3 + Spring Cloud 2022+，并且愿意搭建链路追踪后端，比较省事的做法是用 Micrometer Tracing，它自动生成 traceId、spanId，并处理了 HTTP Header 的入站和出站。OpenFeign 不需要额外配置，框架就会把 trace 相关的 Header 带到下游。

但很多项目实际面临的情况是：链路追踪体系还没建，监控后端还没上，只是想先把多服务日志串联起来，让出问题时能快速定位。这时候为了一条日志 ID 去引入一个完整的 Tracing 体系，改造成本并不低。手搓一条 Header 链路反而更可控：代码量不大，也不限制日志框架，后续真要迁移到 Micrometer Tracing，原本的 Filter 和拦截器只是多了一层自定义字段，处理 TraceID 的逻辑可以平滑替换。

另外一个现实原因是，Micrometer Tracing 默认只管 TraceID、SpanID 这类链路数据，并不管用户 ID、租户 ID 这类业务上下文。就算你上了 Tracing 框架，业务上下文透传仍然需要自己写 Feign RequestInterceptor。所以本文方案并不白做，它解决的是比 TraceID 更广的一层问题。

3. 网关入口实现：生成 TraceID 并给每个出站请求装上“用户牌”

网关是整个链路的源头，绝大多数情况下外部请求只会经过网关进入内部服务。所以我把 TraceID 的生成放到网关，而不是每个微服务各自生成。原因很简单：如果每个服务都自己生成一个，链路就永远串不到一条线上。

3.1 基于 Spring Cloud Gateway 的 GlobalFilter 代码

如果你们用的网关是 Spring Cloud Gateway，注意它基于 WebFlux，请求处理模型是非阻塞的。网上很多老文章教你在 Gateway 的 Filter 里直接 MDC.put，这在某些场景下确实会失效，因为 Netty 线程和后续业务线程不是同一个，日志里不一定能打出来。

对于网关，我的建议是把主要精力放在“修改出站请求 Header”上。网关日志要不要带 TraceID 可以单独考虑，但给下游服务塞 Header 这件事必须做。

下面是一个可以直接用的全局过滤器：

java复制@Component
public class GatewayContextFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String traceId = exchange.getRequest().getHeaders().getFirst(ContextHeaders.TRACE_ID);
        if (!StringUtils.hasText(traceId)) {
            traceId = UUID.randomUUID().toString().replace("-", "");
        }

        // 如果网关启用了 WebFlux 日志，可以把 traceId 放进 exchange 属性，
        // 自定义的日志 Filter 从 attribute 里读取后手动打印
        exchange.getAttributes().put(ContextHeaders.TRACE_ID, traceId);

        UserInfo userInfo = parseUser(exchange);

        ServerHttpRequest mutatedRequest = exchange.getRequest().mutate()
                .headers(httpHeaders -> {
                    httpHeaders.set(ContextHeaders.TRACE_ID, traceId);
                    if (userInfo != null) {
                        httpHeaders.set(ContextHeaders.USER_ID, userInfo.getUserId());
                        httpHeaders.set(ContextHeaders.USER_NAME, userInfo.getUsername());
                        httpHeaders.set(ContextHeaders.TENANT_ID, userInfo.getTenantId());
                    }
                })
                .build();

        return chain.filter(exchange.mutate().request(mutatedRequest).build());
    }

    private UserInfo parseUser(ServerWebExchange exchange) {
        // 从 Authorization Header 解析 JWT，或者从网关 Session 中取用户信息
        // String token = exchange.getRequest().getHeaders().getFirst("Authorization");
        // 解析成功后封装成 UserInfo 返回
        return null;
    }

    @Override
    public int getOrder() {
        return -100;
    }
}

注意这里用 httpHeaders.set(...) 而不是 httpHeaders.add(...)。原因是外部调用方可能已经手工传了 TraceID 或用户 ID，如果服务端不加校验地信任并透传，攻击者就可以伪造身份。在网关层，我通常的做法是：不存在的 TraceID 生成一个，已经存在的则判断它是否来自可信前置代理，否则也强制覆盖成新生成的。具体策略和你们网关前面的链路有关，但原则是“下游只信网关写好的 Header”。

3.2 用户信息从哪里取

网关把外部请求转换成内部请求时，需要完成认证，并从令牌或 Session 中解析出用户信息。

最常见的做法是从 JWT 中解析。网关先校验 JWT 签名和过期时间，然后把 sub、username、tenantId 这些标准字段取出。这里有一点很重要：网关塞给下游的 X-User-Id 不是原始 token，而是已经经过校验后的用户标识。下游服务如果还需要做细粒度鉴权，更安全的做法是继续传递原始 JWT，由下游校验签名，而不是只看一个裸的 X-User-Id Header。

如果项目里有统一登录平台或 passport 服务，网关一般也是先调用 passport 校验凭证换用户信息，再塞到 Header。做法类似，核心就是要在 Request 里把用户身份标准化。

3.3 网关层常见的顺序坑

自定义 GlobalFilter 的 getOrder() 返回顺序不要太随意。如果过滤器返回的优先级比某些内置 GatewayFilter 还低，可能出现一种诡异现象：你有的时候在日志里看得到 TraceID，有时候看不到，取决于具体走了哪一个路由 Filter。

我习惯把上下文过滤器放在执行链相对靠前的位置，但不会极端到 Integer.MIN_VALUE，给后续安全过滤、限流过滤留出空间。如果你们启用了 Sentinel、Spring Security 等网关插件，要留意它们是否在过滤器里自己创建了新请求对象，如果会，新对象会丢掉之前请求添加的 Header。这种问题排查起来非常隐蔽，调试手段只有一个：在路由转发前把最终 Request 的 Header 全部打出来看一眼。

4. OpenFeign 请求拦截器：从本地上下文里把 TraceID 和用户信息搬到 Header

网关只负责入口，真正实现“服务 A 调服务 B 时自动带上上下文”的，是 OpenFeign 的 RequestInterceptor。这也是整条链路最核心的一个点。

4.1 最小完整的 RequestInterceptor 配置

OpenFeign 里有一个 feign.RequestInterceptor 接口，Spring Cloud OpenFeign 会把容器中所有该类型的 Bean 自动应用到每个 Feign Client 上。我们只需要写一个配置类：

java复制@Configuration(proxyBeanMethods = false)
public class FeignContextPropagationConfig {

    @Bean
    public RequestInterceptor feignContextInterceptor() {
        return template -> {
            // 1. TraceID 从 MDC 取，取不到就不写，让下游自己生成
            String traceId = MDC.get(ContextHeaders.TRACE_ID);
            if (StringUtils.hasText(traceId)) {
                template.header(ContextHeaders.TRACE_ID, traceId);
            }

            // 2. 用户信息从 UserContext 取，业务代码里更常用
            UserInfo userInfo = UserContext.get();
            if (userInfo != null) {
                template.header(ContextHeaders.USER_ID, userInfo.getUserId());
                template.header(ContextHeaders.USER_NAME, userInfo.getUsername());
                template.header(ContextHeaders.TENANT_ID, userInfo.getTenantId());
            }
        };
    }
}

这个拦截器会发生在 Feign 拼接请求阶段。同步调用时，发起 Feign 请求的线程就是当前处理 HTTP 请求的线程，所以 MDC.get 和 UserContext.get() 都能取到正确值。代码量很少，但把 TraceID 和用户信息漏传的问题一次性解决了。

为什么不用手动在每个 Feign 方法上加 @RequestHeader("X-User-Id") String userId ？一是侵入性太强，每新增一个 Feign 接口都要加一遍参数，漏一个就断一条链路；二是用户信息本身属于横切关注点，把它绑到接口签名上是设计上的污染。拦截器统一处理，以后字段有变化，只需要改一个类。

4.2 只想给特定服务的请求加 Header 怎么办

如果 Feign Client 数量多，有些服务并不需要用户信息，你可以在拦截器里按目标服务名过滤：

java复制@Override
public void apply(RequestTemplate template) {
    String targetService = template.feignTarget().name();
    if (!"user-center".equals(targetService)) {
        return;
    }
    // 只给 user-center 的调用增加上下文 Header
}

template.feignTarget().name() 来自 @FeignClient(name = "xxx") 配置的服务名，不是 URL 路径。如果你的工程里大量使用 @FeignClient(url = "http://...") 直连方式，这个值可能为空，过滤时需要额外判断 URL。

4.3 OpenFeign 的负载均衡只是附带说明

顺带回答一个经常被问到的问题：OpenFeign 内部集成了负载均衡吗？严格说，OpenFeign 本身不做负载均衡，是 spring-cloud-starter-openfeign 配合 spring-cloud-loadbalancer 在做客户端负载均衡。如果没有引入 loadbalancer，@FeignClient(name = "user-center") 这种写法是没法通过服务名找到地址的。不过这不影响上下文透传：不管有没有负载均衡，RequestInterceptor 都在请求发出前执行，只是被拦截的请求最终交给谁处理的问题。

5. 下游服务收包：从 Header 还原上下文，并把日志串回同一条线

前面做了这么多，如果服务 B 收到 Header 后没人解析，等于白做。下游服务必须有一个统一的入口 Filter，负责把 Header 里的 TraceID 和用户信息还原到本地上下文。

5.1 Servlet 环境下最稳妥的 Filter 写法

在 Spring Boot 的 Web 应用中，建议用 OncePerRequestFilter。它保证一次请求只执行一次，避免被不同的 Filter 链重复调用两次导致 MDC 里出现两个值：

java复制@Component
@Order(Ordered.HIGHEST_PRECEDENCE + 10)
public class ContextRestoreFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        String traceId = request.getHeader(ContextHeaders.TRACE_ID);
        if (!StringUtils.hasText(traceId)) {
            traceId = UUID.randomUUID().toString().replace("-", "");
        }
        MDC.put(ContextHeaders.TRACE_ID, traceId);

        String userId = request.getHeader(ContextHeaders.USER_ID);
        if (StringUtils.hasText(userId)) {
            try {
                UserInfo userInfo = new UserInfo();
                userInfo.setUserId(userId);
                userInfo.setUsername(request.getHeader(ContextHeaders.USER_NAME));
                userInfo.setTenantId(request.getHeader(ContextHeaders.TENANT_ID));
                UserContext.set(userInfo);

                //