Spring Gateway自定义CustomAddRequestHeaderGatewayFilterFactory未触发执行的问题排查求助

我之前在使用Spring Gateway时也碰到过自定义过滤器工厂不生效的情况，结合你的代码和配置，咱们一步步排查解决：

1. 确认过滤器组件被Spring正确扫描 #

首先，你的CustomAddRequestHeaderGatewayFilterFactory类上加了@Component注解，但要确保这个类所在的包在Spring Boot主类的扫描范围内。比如如果你的主类在com.dolphin.gateway包下，而过滤器在com.dolphin.gateway.filters，那没问题；如果过滤器在完全不相关的包，比如com.dolphin.common，那需要在主类上添加@ComponentScan(basePackages = {"com.dolphin.gateway", "com.dolphin.common"})来指定扫描范围，不然Spring找不到这个过滤器组件，自然不会执行。

2. 修正配置中的过滤器名称 #

Spring Gateway对自定义过滤器工厂的命名有规则：类名必须以GatewayFilterFactory结尾，配置时只需要写前面的前缀部分。你的类是CustomAddRequestHeaderGatewayFilterFactory，所以配置里的过滤器名称应该是CustomAddRequestHeader，而不是带GatewayFilterFactory后缀的。

你之前尝试过这个写法，但再确认下最终的配置应该是：

spring.cloud.gateway.routes[0].filters[0]=CustomAddRequestHeader=customHeaderName,customHeaderValue

3. 验证路由是否被正确匹配 #

你的请求URL是https://music-api.example.com/music/playlist/v1/playlist，路由的Path=/music/**看起来是匹配的，但有可能存在其他优先级更高的路由先匹配了这个请求，导致你的目标路由没生效。

可以开启Spring Gateway的DEBUG日志来查看路由匹配过程，在application.properties中添加：

logging.level.org.springframework.cloud.gateway=DEBUG

启动服务后，发送请求，查看控制台日志，搜索RoutePredicateHandlerMapping相关的日志，确认你的dolphin-music-service路由是否被选中。

4. 在过滤器中添加日志验证执行状态 #

为了直观确认过滤器是否被触发，你可以在apply方法里添加日志输出，比如：

@Override
public GatewayFilter apply(CustomAddRequestHeaderConfig config) {
    return ((exchange, chain) -> {
        // 添加日志，确认过滤器执行
        System.out.println("✅ CustomAddRequestHeaderFilter 正在执行，将添加Header: " + config.getHeaderName());
        ServerHttpRequest request = exchange.getRequest().mutate().headers(httpHeaders -> {
            httpHeaders.set(config.getHeaderName(), config.getHeaderValue());
        }).build();
        return chain.filter(exchange.mutate().request(request).build());
    });
}

重启服务后发送请求，如果控制台能看到这条日志，说明过滤器已经生效；如果看不到，再回到前面的步骤排查组件扫描和路由匹配的问题。

5. 检查Spring版本兼容性 #

最后，确保你的Spring Boot和Spring Cloud版本是兼容的，版本不兼容也可能导致过滤器无法正常加载。比如：

• Spring Boot 3.x 对应 Spring Cloud 2022.x（代号Kilburn）
• Spring Boot 2.7.x 对应 Spring Cloud 2021.x（代号Jubilee）

你可以在pom.xml（或build.gradle）中确认版本对应关系，避免因版本不匹配导致的问题。

按照上面的步骤逐一排查，应该就能让你的自定义过滤器正常触发执行了。

内容的提问来源于stack exchange，提问作者Dolphin