SpringCloud Gateway为何获取不到自定义请求头信息？

Question

在使用Spring Cloud Gateway时，有时会遇到无法获取自定义请求头信息的问题。这通常是由于Gateway的过滤器链对请求头进行了过滤或重写所致。例如，默认情况下，某些敏感头（如`Cookie`、`Authorization`）可能被移除或未正确转发。此外，如果自定义过滤器逻辑中未显式保留或传递这些头信息，也可能导致丢失。 解决此问题的关键在于配置`setAllowedHeaders`方法，确保自定义头被加入白名单。同时检查全局过滤器或路由特定过滤器是否无意中修改了请求对象。最后，确认客户端发送请求时，头信息确实已正确附加。通过以上步骤，可以有效定位并解决Spring Cloud Gateway中自定义请求头缺失的问题。

Answer 1

摘星参考千问来帮您回答这个问题！

在使用 Spring Cloud Gateway 时，确实可能会遇到“无法获取自定义请求头信息”的问题。这类问题通常与 网关的过滤器链、请求头的处理机制 或 客户端请求配置 相关。以下将从原因分析、解决方案和代码示例三个方面进行详细解答。

---

一、问题原因分析

1. 默认的请求头过滤机制

Spring Cloud Gateway 默认会过滤掉一些“敏感”或“不安全”的请求头（如 Authorization、Cookie、Set-Cookie 等），这是出于安全考虑。如果这些头是您自定义的（比如 X-Custom-Header），但被误认为是“敏感头”，也会被移除。

✅ 常见错误现象：客户端发送了 X-Custom-Header: test，但在下游服务中却读不到这个头。

2. 过滤器链对请求头的修改

如果你在网关中使用了自定义的 GatewayFilter 或全局过滤器，可能在处理请求时对请求头进行了重写、删除或覆盖，导致自定义头丢失。

3. 请求头未正确设置

有时候客户端发送请求时没有正确设置请求头，或者使用了不兼容的 HTTP 客户端库，也可能导致请求头没有被正确传递到网关。

4. Spring Cloud Gateway 的 Header 处理限制

某些版本的 Spring Cloud Gateway 对于请求头的处理方式存在限制，例如：

• 请求头名称必须符合一定规范（如不能包含特殊字符）；
• 某些框架或中间件（如 Nginx）可能对请求头进行过滤或重写；
• 使用了 ForwardedHeaderFilter 或 X-Forwarded-* 头时，可能导致原有头被覆盖。

---

二、解决方案详解

1. 允许自定义请求头通过网关

✅ 方法一：使用 setAllowedHeaders 配置白名单

在 application.yml 中配置允许的请求头，确保自定义头不会被过滤掉。

spring:
  cloud:
    gateway:
      globalfilters:
        - StripPrefix=1
      httpclient:
        ssl:
          use-insecure-trust-manager: true
      routes:
        - id: my-service
          uri: http://localhost:8081
          predicates:
            - Path=/api/**
          filters:
            - SetPath=/api/{segment}

❗ 注意：上面的配置只是基本路由配置，若要允许自定义头，需在 全局过滤器 或 特定路由的过滤器 中显式保留头信息。

✅ 方法二：使用 SetRequestHeader 过滤器显式添加头

如果你需要在网关中保留并传递某个自定义头，可以在路由配置中使用 SetRequestHeader 来显式设置该头。

spring:
  cloud:
    gateway:
      routes:
        - id: my-service
          uri: http://localhost:8081
          predicates:
            - Path=/api/**
          filters:
            - SetRequestHeader=X-Custom-Header, custom-value
            - StripPrefix=1

✅ 这样可以确保即使原始请求头被过滤，也可以在网关中重新设置。

✅ 方法三：在自定义过滤器中保留头信息

如果你编写了自定义的 GatewayFilter，请确保在处理请求时保留所需的请求头。

public class CustomHeaderFilter implements GatewayFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 获取原始请求头
        HttpHeaders headers = exchange.getRequest().getHeaders();

        // 打印所有请求头（调试用）
        headers.forEach((name, values) -> System.out.println(name + ": " + values));

        // 如果需要，可以在这里添加或修改头
        // exchange.getRequest().mutate().header("X-Custom-Header", "value").build();

        return chain.filter(exchange);
    }
}

然后在配置中注册该过滤器：

spring:
  cloud:
    gateway:
      routes:
        - id: my-service
          uri: http://localhost:8081
          predicates:
            - Path=/api/**
          filters:
            - CustomHeaderFilter
            - StripPrefix=1

---

2. 检查客户端请求是否正确

确保客户端发送请求时，确实附带了自定义头信息。例如使用 curl 测试：

curl -H "X-Custom-Header: test" http://localhost:8080/api/test

或者使用 Postman 发送带有自定义头的请求。

---

3. 检查代理服务器或负载均衡器配置

如果你使用了 Nginx、HAProxy 或其他反向代理，它们可能对请求头进行过滤或重写。请确认它们的配置中是否允许 X-Custom-Header 通过。

---

4. 使用 ForwardedHeaderFilter 时注意

如果你启用了 ForwardedHeaderFilter（用于支持 X-Forwarded-* 头），它可能会覆盖原始请求头。你可以通过配置来避免这种情况：

spring:
  cloud:
    gateway:
      forward-headers-strategy: none

或者在代码中禁用：

@Bean
public ForwardedHeaderFilter forwardedHeaderFilter() {
    return new ForwardedHeaderFilter();
}

---

三、完整配置示例

示例 1：YAML 配置允许自定义头

spring:
  cloud:
    gateway:
      routes:
        - id: my-service
          uri: http://localhost:8081
          predicates:
            - Path=/api/**
          filters:
            - SetRequestHeader=X-Custom-Header, custom-value
            - StripPrefix=1
      httpclient:
        ssl:
          use-insecure-trust-manager: true

示例 2：Java 配置方式（启用自定义过滤器）

@Configuration
public class GatewayConfig {

    @Bean
    public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
        return builder.routes()
                .route("my-service", r -> r.path("/api/**")
                        .filters(f -> f.setPath("/api/{segment}")
                                .setRequestHeader("X-Custom-Header", "custom-value"))
                        .uri("http://localhost:8081"))
                .build();
    }

    @Bean
    public GatewayFilter customHeaderFilter() {
        return (exchange, chain) -> {
            ServerHttpRequest request = exchange.getRequest();
            HttpHeaders headers = request.getHeaders();

            // 打印所有请求头
            headers.forEach((k, v) -> System.out.println(k + ": " + v));

            return chain.filter(exchange);
        };
    }
}

---

四、总结

问题点	解决方案
默认过滤器移除了自定义头	使用 SetRequestHeader 显式设置头，或在 application.yml 中配置 setAllowedHeaders
自定义过滤器修改了请求头	检查自定义过滤器逻辑，确保不删除或覆盖目标头
客户端请求头未正确设置	使用 curl 或 Postman 验证请求头是否发送成功
反向代理/负载均衡器干扰	检查 Nginx/Haproxy 配置，确保允许自定义头
ForwardedHeaderFilter 覆盖头	设置 forward-headers-strategy: none

---

五、扩展建议

• 使用 Postman 或 curl 做测试验证。
• 在网关中打印请求头日志，便于排查问题。
• 使用 Spring Cloud Gateway 的 Debug 模式（开启 logging.level.org.springframework.cloud.gateway=DEBUG）查看请求处理流程。

---

如有更多关于 Spring Cloud Gateway 的问题，欢迎继续提问！