Spring Cloud Gateway自定义GlobalFilter报错：找不到UserFilter工厂类

核心结论 #

全局过滤器不需要使用GatewayFilterFactory，你遇到的报错是因为混淆了全局过滤器和路由级过滤器的使用方式。

具体原因&解决方案 #

• 全局过滤器的生效逻辑：实现GlobalFilter+Ordered接口的Bean，只要被Spring容器注册（比如通过@Component或配置类的@Bean），就会自动作用于所有路由，完全不需要在application.yml的路由filters节点中配置。你现在在路由配置里写- UserFilter，Spring Cloud Gateway会默认把它当成GatewayFilterFactory的名称去查找，自然找不到对应实现，所以抛出IllegalArgumentException。

• 如果需要路由级过滤器（仅作用于特定路由）：

  • 方案1：自定义GatewayFilterFactory（通常继承AbstractGatewayFilterFactory），此时可以在配置文件的filters里用工厂类的简写名称（比如工厂类名为UserFilterGatewayFilterFactory，配置时写- UserFilter）。
  • 方案2：直接实现GatewayFilter接口，但这种方式无法通过配置文件指定，只能通过Java代码构建路由时（比如使用RouteLocatorBuilder）手动添加该过滤器实例。

官方文档相关说明位置 #

Spring Cloud Gateway官方文档中：

• 「Global Filters」章节明确指出，全局过滤器会自动应用到所有路由，无需在路由配置中声明。
• 「GatewayFilter Factories」章节说明，配置文件中filters字段对应的是GatewayFilterFactory的名称，用于配置路由级别的过滤器。

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