Design and Implementation of a High‑Performance Spring WebFlux Gateway with Nacos Service Discovery

Background : Inspired by the Soul gateway on GitHub, the author set out to build a high‑performance gateway from scratch, completing the core functionality of the ship-gate project after two weeks of development.

Design – Technical Selection : The gateway must handle massive request throughput, so asynchronous processing is required. Two common approaches were evaluated: Tomcat/Jetty + NIO + Servlet3 (widely used by JD, Youzan, Zuul) and Netty + NIO (used by VIP.com with >300k QPS). The author chose Spring WebFlux (built on Netty) to avoid manual HTTP handling while retaining high performance.

Requirements : The gateway should support custom routing rules (by version, header, query), be language‑agnostic, provide high performance, high availability, gray‑release (canary) deployment, interface authentication, and multiple load‑balancing algorithms (random, round‑robin, weighted). Service registration and discovery are handled via Nacos.

Architecture : The system is divided into modules such as ship-client-spring-boot-starter , ship-server , and admin components. Diagrams illustrate the relationships between these modules and the data flow between Nacos, ship‑admin, and ship‑server.

Core Code – Client Starter :

public class AutoRegisterListener implements ApplicationListener
{
    private static final Logger LOGGER = LoggerFactory.getLogger(AutoRegisterListener.class);
    private volatile AtomicBoolean registered = new AtomicBoolean(false);
    @NacosInjected private NamingService namingService;
    // register service to Nacos and notify ship‑admin on startup
    // add shutdown hook to unregister
}

Core Code – Server Filter :

public class PluginFilter implements WebFilter {
    private ServerConfigProperties properties;
    @Override
    public Mono
filter(ServerWebExchange exchange, WebFilterChain chain) {
        String appName = parseAppName(exchange);
        if (CollectionUtils.isEmpty(ServiceCache.getAllInstances(appName))) {
            throw new ShipException(ShipExceptionEnum.SERVICE_NOT_FIND);
        }
        PluginChain pluginChain = new PluginChain(properties, appName);
        pluginChain.addPlugin(new DynamicRoutePlugin(properties));
        pluginChain.addPlugin(new AuthPlugin(properties));
        return pluginChain.execute(exchange, pluginChain);
    }
}

Data Synchronization : Two listeners keep Nacos and local caches in sync. NacosSyncListener periodically updates instance metadata (weight, plugins) to Nacos, while DataSyncTaskListener pulls all service instances from Nacos into in‑memory caches and refreshes enabled plugins.

WebSocket Synchronization : A WebSocket server pushes route‑rule changes to connected clients. The client ( WebsocketSyncCacheClient ) establishes a connection, sends the current enabled rules on open, and reconnects automatically if the connection drops.

Testing : The author provides step‑by‑step instructions to start Nacos, ship‑admin, and two ship‑example instances with different versions (gray and prod). A header‑based routing rule is added to route requests with name=ship to the gray version. Functional testing with Postman confirms correct routing, and a performance test using wrk shows ~9,400 requests per second with 20 threads and 500 connections.

Conclusion : Building a gateway is approachable; the first step is the hardest. The project’s source code is available at https://github.com/2YSP/ship-gate , and the author shares lessons learned and future improvements.