Spring Cloud Gateway启动报错tokenRelayGatewayFilterFactory无法注册如何解决？

问题根因 #

• 这个启动报错本质是Bean定义冲突：Spring Cloud Gateway的TokenRelayAutoConfiguration会自动注册TokenRelayGatewayFilterFactory相关Bean，如果你同时引入了spring-boot-starter-oauth2-resource-server和spring-cloud-starter-gateway还有spring-boot-starter-oauth2-client的不当组合，就会出现同类型Bean重复注册的冲突。
• 你加的spring.main.allow-bean-definition-overriding=true只是强制覆盖了冲突的Bean，但是真正需要的Token Relay相关Bean被其他无关Bean覆盖了，所以功能自然失效。

修复方案 #

第一步：检查依赖组合 #

确认你的pom.xml（Maven）或者build.gradle（Gradle）里的依赖只保留必要项，不要同时引入多余的OAuth2依赖：

如果你的网关只做Token Relay（把请求带的Token透传给下游微服务），只需要保留这两个核心依赖即可：

• spring-cloud-starter-gateway
• spring-boot-starter-oauth2-client
  不要额外引入spring-boot-starter-oauth2-resource-server，除非你同时需要网关本身做资源服务器校验Token，两个功能同时开启需要额外配置，新手不要同时加。

第二步：移除Bean覆盖配置 #

删除application.properties里的spring.main.allow-bean-definition-overriding=true配置，这个配置本身是临时规避方案，不是修复方案，会隐藏很多依赖冲突问题。

第三步：正确配置Token Relay #

在application.properties里添加基础的Token Relay配置示例：

# 网关路由配置，以转发到order-service为例
spring.cloud.gateway.routes[0].id=order-service
spring.cloud.gateway.routes[0].uri=lb://order-service
spring.cloud.gateway.routes[0].predicates[0]=Path=/api/order/**
# 开启Token Relay过滤器
spring.cloud.gateway.routes[0].filters[0]=TokenRelay=

# OAuth2客户端配置，对应你的授权服务器参数
spring.security.oauth2.client.provider.your-auth-server.issuer-uri=你的授权服务器地址
spring.security.oauth2.client.registration.gateway.client-id=你的客户端ID
spring.security.oauth2.client.registration.gateway.client-secret=你的客户端密钥
spring.security.oauth2.client.registration.gateway.authorization-grant-type=authorization_code
spring.security.oauth2.client.registration.gateway.scope=openid,profile

配置完成后重新启动应用即可。

特殊情况处理 #

如果你确实需要网关同时作为资源服务器校验Token，又需要开启Token Relay，需要手动注册TokenRelayGatewayFilterFactory Bean，优先级高于自动配置的Bean：

import org.springframework.cloud.gateway.filter.factory.TokenRelayGatewayFilterFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientManager;

@Configuration
public class TokenRelayConfig {
    @Bean
    public TokenRelayGatewayFilterFactory tokenRelayGatewayFilterFactory(OAuth2AuthorizedClientManager authorizedClientManager) {
        return new TokenRelayGatewayFilterFactory(authorizedClientManager);
    }
}

这个配置会强制使用你手动定义的Token Relay过滤器工厂，不会被资源服务器的相关Bean覆盖。

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