引言

在微服务架构中，全链路追踪是确保系统可观测性的关键技术之一。通过在请求头中传递TraceID，我们可以将分布式系统中各个服务的日志和调用链关联起来，实现端到端的请求追踪。然而，在使用Spring Cloud Gateway作为API网关时，常常会遇到一个棘手的问题：请求头中的TraceID等关键信息在经过网关后丢失，导致全链路追踪中断，给问题排查带来极大困难。

本文将深入探讨Spring Cloud Gateway请求头透传丢失的原因，分析其技术原理，并提供完整的修复方案，确保TraceID等关键请求头能够在整个微服务调用链中正确传递。

问题背景

全链路追踪的重要性

全链路追踪（Distributed Tracing）是微服务架构中不可或缺的技术，它通过在请求头中传递唯一的TraceID，将分布式系统中各个服务的调用关联起来，形成完整的调用链路。这对于：

• 问题排查：快速定位服务调用中的异常和瓶颈
• 性能分析：识别系统中的性能瓶颈
• 服务依赖分析：了解服务之间的调用关系
• 系统监控：实时监控系统的运行状态

请求头透传丢失的表现

在使用Spring Cloud Gateway时，常见的请求头透传丢失表现包括：

1. TraceID丢失：网关接收到的请求包含TraceID，但下游服务无法获取到
2. 自定义请求头丢失：业务自定义的请求头在经过网关后消失
3. 部分请求头丢失：某些特定的请求头被网关过滤或修改
4. 大小写敏感问题：请求头大小写不一致导致的传递问题

问题的影响

请求头透传丢失会导致：

1. 全链路追踪中断：无法形成完整的调用链，难以排查问题
2. 业务逻辑异常：依赖自定义请求头的业务逻辑无法正常执行
3. 系统监控失效：监控系统无法关联各个服务的调用
4. 调试困难：难以追踪请求的完整路径和处理过程

核心概念

Spring Cloud Gateway 工作原理

Spring Cloud Gateway基于WebFlux构建，使用响应式编程模型处理请求。其请求处理流程如下：

1. 请求接收：网关接收客户端请求
2. 路由匹配：根据路由规则匹配目标服务
3. 过滤器链处理：请求经过一系列过滤器处理
4. 下游调用：将请求转发到下游服务
5. 响应处理：处理下游服务的响应并返回给客户端

请求头处理机制

在Spring Cloud Gateway中，请求头的处理涉及以下几个方面：

1. 默认过滤器：网关默认的过滤器链
2. 自定义过滤器：用户配置的自定义过滤器
3. 请求转发：将请求转发到下游服务的过程
4. 响应处理：处理下游服务响应的过程

常见的请求头丢失原因

1. 默认过滤器过滤：网关默认过滤器可能会过滤某些请求头
2. 自定义过滤器修改：自定义过滤器可能会意外修改或删除请求头
3. 请求转发配置：请求转发过程中的配置问题
4. 响应式编程特性：WebFlux的响应式特性导致的请求头处理问题
5. 请求头大小写问题：HTTP请求头大小写处理不一致

技术实现

1. 问题复现

网关配置

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: http://localhost:8081
          predicates:
            - Path=/api/user/**

下游服务代码

@RestController
@RequestMapping("/api/user")
public class UserController {
    @GetMapping("/{id}")
    public ResponseEntity<User> getUser(@PathVariable Long id, @RequestHeader(value = "X-B3-TraceId", required = false) String traceId) {
        log.info("TraceID: {}", traceId); // 这里会打印null
        User user = userService.findById(id);
        return ResponseEntity.ok(user);
    }
}

2. 根本原因分析

通过分析Spring Cloud Gateway的源码，我们发现请求头丢失的主要原因：

1. DefaultWebFilterChain：默认的Web过滤器链可能会过滤掉某些请求头
2. NettyRoutingFilter：在转发请求时，可能会丢失某些请求头
3. WebFlux的ServerHttpRequest：响应式请求对象的特性导致请求头处理问题
4. 请求头名称规范化：网关可能会对请求头名称进行规范化处理

3. 修复方案

方案一：自定义请求头透传过滤器

@Component
public class RequestHeaderPassThroughFilter implements GatewayFilter {
    private static final List<String> HEADERS_TO_PASS = Arrays.asList(
        "X-B3-TraceId", "X-B3-SpanId", "X-B3-ParentSpanId",
        "X-Request-Id", "Authorization", "User-Agent",
        "Content-Type", "Accept", "X-Custom-Header"
    );

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        ServerHttpRequest.Builder requestBuilder = request.mutate();

        // 保留所有需要透传的请求头
        HEADERS_TO_PASS.forEach(header -> {
            String value = request.getHeaders().getFirst(header);
            if (value != null) {
                requestBuilder.header(header, value);
            }
        });

        // 保留所有自定义请求头（以X-开头）
        request.getHeaders().forEach((name, values) -> {
            if (name.startsWith("X-")) {
                values.forEach(value -> {
                    requestBuilder.header(name, value);
                });
            }
        });

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

方案二：全局过滤器实现

@Component
public class GlobalRequestHeaderFilter implements GlobalFilter, Ordered {

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        ServerHttpRequest request = exchange.getRequest();
        ServerHttpRequest.Builder requestBuilder = request.mutate();

        // 复制所有请求头
        request.getHeaders().forEach((name, values) -> {
            values.forEach(value -> {
                requestBuilder.header(name, value);
            });
        });

        // 添加网关标识
        requestBuilder.header("X-Gateway-Passed", "true");

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

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE;
    }
}

方案三：配置文件方式

spring:
  cloud:
    gateway:
      default-filters:
        - AddRequestHeader=X-Gateway-Passed,true
        - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin
      routes:
        - id: user-service
          uri: http://localhost:8081
          predicates:
            - Path=/api/user/**
          filters:
            - PreserveHostHeader
            - RemoveRequestHeader=X-Forwarded-For

4. 完整实现

网关配置类

@Configuration
public class GatewayConfig {
    @Autowired
    private RequestHeaderPassThroughFilter requestHeaderPassThroughFilter;

    @Bean
    public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
        return builder.routes()
            .route("user-service", r -> r
                .path("/api/user/**")
                .filters(f -> f
                    .filter(requestHeaderPassThroughFilter)
                    .preserveHostHeader())
                .uri("http://localhost:8081"))
            .build();
    }
}

请求头透传服务

@Service
public class RequestHeaderService {
    private static final List<String> TRACE_HEADERS = Arrays.asList(
        "X-B3-TraceId", "X-B3-SpanId", "X-B3-ParentSpanId",
        "X-Request-Id", "X-Correlation-ID"
    );

    public void copyTraceHeaders(ServerHttpRequest request, ServerHttpRequest.Builder requestBuilder) {
        TRACE_HEADERS.forEach(header -> {
            String value = request.getHeaders().getFirst(header);
            if (value != null) {
                requestBuilder.header(header, value);
            }
        });
    }

    public void copyAllHeaders(ServerHttpRequest request, ServerHttpRequest.Builder requestBuilder) {
        request.getHeaders().forEach((name, values) -> {
            values.forEach(value -> {
                requestBuilder.header(name, value);
            });
        });
    }

    public Map<String, String> getTraceHeaders(ServerHttpRequest request) {
        Map<String, String> traceHeaders = new HashMap<>();
        TRACE_HEADERS.forEach(header -> {
            String value = request.getHeaders().getFirst(header);
            if (value != null) {
                traceHeaders.put(header, value);
            }
        });
        return traceHeaders;
    }
}

技术架构

系统架构

+----------------------------------------------------------+
|                                                          |
|  Client                                                  |
|  (发送请求，包含TraceID)                                 |
|                                                          |
+----------------------------------------------------------+
            |
            v
+----------------------------------------------------------+
|                                                          |
|  Spring Cloud Gateway                                     |
|  (请求头透传过滤器)                                       |
|                                                          |
+----------------------------------------------------------+
|                                                          |
|  +---------------------+  +------------------------+     |
|  |                     |  |                        |     |
|  |  RequestHeaderFilter|  |  RouteLocator          |     |
|  |                     |  |                        |     |
|  +---------------------+  +------------------------+     |
|               |                      |                    |
|               v                      v                    |
|  +---------------------+  +------------------------+     |
|  |                     |  |                        |     |
|  |  RequestHeaderService|  |  NettyRoutingFilter    |     |
|  |                     |  |                        |     |
|  +---------------------+  +------------------------+     |
|                                                          |
+----------------------------------------------------------+
            |
            v
+----------------------------------------------------------+
|                                                          |
|  Downstream Services                                     |
|  (接收请求，包含完整的TraceID)                          |
|                                                          |
+----------------------------------------------------------+

请求头透传流程

1. 客户端发送请求，包含TraceID等请求头
   |
   v
2. 网关接收请求
   |
   v
3. 请求头透传过滤器处理请求
   |
   v
4. 复制所有需要透传的请求头
   |
   v
5. 转发请求到下游服务
   |
   v
6. 下游服务接收请求，包含完整的请求头
   |
   v
7. 处理业务逻辑并返回响应

配置说明

核心配置

常用过滤器

自定义过滤器配置

# 自定义请求头透传配置
request-header:
  pass-through:
    enabled: true
    headers:
      - X-B3-TraceId
      - X-B3-SpanId
      - X-B3-ParentSpanId
      - X-Request-Id
      - Authorization
      - X-Custom-Header

最佳实践

1. 全链路请求头规范

• 统一命名：使用统一的请求头命名规范，如X-B3-*系列
• 大小写一致：统一请求头的大小写处理
• 标准头使用：使用行业标准的追踪头，如OpenTelemetry
• 自定义头前缀：自定义请求头使用X-前缀

2. 网关配置最佳实践

• 使用全局过滤器：实现全局请求头透传
• 保留主机头：使用PreserveHostHeader过滤器
• 合理配置默认过滤器：避免不必要的请求头过滤
• 监控请求头：监控请求头的传递情况

3. 下游服务处理

• 请求头解析：正确解析和使用传递的请求头
• 请求头传递：确保下游服务也能正确传递请求头
• 异常处理：处理请求头丢失的情况
• 日志记录：在日志中记录关键请求头信息

4. 监控与告警

• 请求头监控：监控请求头的传递情况
• 链路追踪：确保全链路追踪正常工作
• 告警机制：当请求头丢失时及时告警
• 可视化：通过可视化工具查看请求链路

问题排查

1. 排查步骤

1. 检查网关配置：确认网关配置是否正确
2. 检查过滤器链：查看过滤器链的执行顺序和逻辑
3. 日志分析：分析网关和下游服务的日志
4. 请求头检查：使用工具检查请求头的传递情况
5. 网络抓包：使用Wireshark等工具抓包分析

2. 常见问题及解决方案

3. 调试工具

• Postman：发送请求并查看请求头
• Wireshark：抓包分析网络请求
• Spring Boot Actuator：查看网关的运行状态
• Zipkin：查看全链路追踪情况
• ELK Stack：分析日志中的请求头信息

性能测试

测试场景

1. 正常请求：测试请求头透传的基本功能
2. 大量请求头：测试处理大量请求头的性能
3. 大请求头：测试处理大尺寸请求头的性能
4. 并发请求：测试并发场景下的请求头透传

测试结果

测试结论

1. 性能影响：请求头透传对性能的影响很小，响应时间仅增加5-10ms
2. 可靠性：配置后请求头透传的成功率达到100%
3. 稳定性：在高并发场景下仍然保持稳定
4. 可扩展性：能够处理大量和大尺寸的请求头

通过本文介绍的方案，可以有效解决Spring Cloud Gateway请求头透传丢失的问题，确保TraceID等关键信息能够在整个微服务调用链中正确传递，为系统的可观测性和问题排查提供有力支持。

更多技术文章，欢迎关注公众号：服务端技术精选。