Spring Cloud Gateway：如何刷新基于Consul的CachingRouteLocator？

问题核心 #

你的Spring Cloud Gateway通过Consul注册服务生成路由，但默认的CachingRouteLocator缓存无法自动感知Consul服务的注册/注销变化，配置spring.cloud.gateway.route-cache-timeout-millis未生效，手动调用refresh()又存在耦合性和性能问题。

正确处理方式 #

1. 利用Consul事件触发路由刷新 #

不需要手动调用CachingRouteLocator.refresh()，而是监听Consul的服务变更事件，自动发布RefreshRoutesEvent让缓存路由更新：

import org.springframework.cloud.consul.discovery.event.ServiceRegisteredEvent;
import org.springframework.cloud.consul.discovery.event.ServiceDeregisteredEvent;
import org.springframework.cloud.gateway.event.RefreshRoutesEvent;
import org.springframework.context.ApplicationEventPublisher;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;

@Component
public class ConsulRouteRefreshListener {

    private final ApplicationEventPublisher eventPublisher;

    public ConsulRouteRefreshListener(ApplicationEventPublisher eventPublisher) {
        this.eventPublisher = eventPublisher;
    }

    @EventListener({ServiceRegisteredEvent.class, ServiceDeregisteredEvent.class})
    public void onConsulServiceChange() {
        // 发布路由刷新事件，触发CachingRouteLocator更新缓存
        eventPublisher.publishEvent(new RefreshRoutesEvent(this));
    }
}

2. 确保Consul服务状态感知及时 #

检查Consul相关配置，保证服务上下线能被Gateway快速感知：

• spring.cloud.consul.discovery.health-check-interval: 缩短健康检查间隔，默认10秒，可调整为5秒
• spring.cloud.consul.discovery.catalog-services-watch-delay: 调整Consul目录监听延迟，默认10秒，可适当减小
• spring.cloud.consul.discovery.catalog-services-watch-timeout: 监听超时时间，确保能及时获取最新服务列表

3. 排查CachingRouteLocator的onApplicationEvent方法失效原因 #

你提到的onApplicationEvent(RefreshRoutesEvent)方法逻辑是通过fetch()获取最新路由后更新缓存，而非直接清除缓存。如果该方法未生效，可能的原因：

• 底层DiscoveryClient的缓存未更新：Consul服务列表变更后，Gateway的DiscoveryClient还没同步到最新数据，导致fetch()生成的路由还是旧的
• 路由生成逻辑依赖的元数据未更新：如果你的路由是基于服务元数据生成，需确保元数据变更能被正确读取
• 自定义RouteLocator的fetch逻辑有问题：如果是自定义了RouteLocator，要确保fetch()方法正确从Consul拉取最新服务

如果确认是fetch()未获取到最新数据，可以尝试在发布RefreshRoutesEvent前，先刷新DiscoveryClient的缓存：

import org.springframework.cloud.client.discovery.DiscoveryClient;
import org.springframework.cloud.consul.discovery.ConsulDiscoveryClient;

// 在ConsulRouteRefreshListener中注入DiscoveryClient
private final DiscoveryClient discoveryClient;

@EventListener({ServiceRegisteredEvent.class, ServiceDeregisteredEvent.class})
public void onConsulServiceChange() {
    if (discoveryClient instanceof ConsulDiscoveryClient) {
        // 强制刷新Consul服务缓存
        ((ConsulDiscoveryClient) discoveryClient).getCatalogServices();
    }
    eventPublisher.publishEvent(new RefreshRoutesEvent(this));
}

替代方案：自定义CachingRouteLocator #

如果默认的CachingRouteLocator无法满足需求，可自定义实现，在服务变更时直接清除缓存并重新加载：

import org.springframework.cloud.gateway.route.CachingRouteLocator;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cache.Cache;
import org.springframework.cache.CacheManager;

public class CustomConsulCachingRouteLocator extends CachingRouteLocator {

    private static final String CACHE_KEY = "routes";
    private final Cache cache;

    public CustomConsulCachingRouteLocator(RouteLocator delegate, CacheManager cacheManager) {
        super(delegate, cacheManager);
        this.cache = cacheManager.getCache(CACHE_KEY);
    }

    public void forceRefresh() {
        // 直接清除缓存，下次获取路由时会重新加载
        cache.evict(CACHE_KEY);
    }
}

然后在配置类中替换默认的CachingRouteLocator：

import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class GatewayConfig {

    @Bean
    public RouteLocator customCachingRouteLocator(RouteLocator delegate, CacheManager cacheManager) {
        return new CustomConsulCachingRouteLocator(delegate, cacheManager);
    }
}

之后在Consul事件监听中调用forceRefresh()即可。

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