Design and Implementation of a High‑Performance Spring WebFlux Gateway

In the background the author was inspired by the Soul gateway on GitHub and decided to implement a high‑performance gateway from scratch, noting the lack of a management UI as the main shortcoming.

Design

The gateway must handle massive request volume, so two asynchronous I/O options were considered: Tomcat/Jetty+NIO+Servlet3 (widely used by Zuul) and Netty+NIO (used by VIPShop for higher throughput). The author chose Spring WebFlux, which is built on Netty, to avoid manual HTTP handling.

Key requirements include custom routing rules (by version, header, query), cross‑language support, high performance, high availability via clustering, gray release (canary), authentication plug‑ins, and multiple load‑balancing algorithms (random, round‑robin, weighted). Service registration and discovery are handled by Nacos.

Architecture

The system is divided into several modules (gateway core, admin, client starter, server, common utilities). The following diagram (omitted) shows module relationships.

Implementation

ship-client-spring-boot-starter registers the service to Nacos and notifies the admin on startup. Core class example:

public class AutoRegisterListener implements ApplicationListener
{
    private static final Logger LOGGER = LoggerFactory.getLogger(AutoRegisterListener.class);
    private final ClientConfigProperties properties;
    @NacosInjected private NamingService namingService;
    // ... constructor, check(), onApplicationEvent(), registerShutDownHook(), doRegister() ...
}

The ship-server module implements dynamic routing via a WebFilter that builds a PluginChain based on the request URL. Plugins such as DynamicRoutePlugin and AuthPlugin are executed in order.

public class PluginFilter implements WebFilter {
    private final ServerConfigProperties properties;
    @Override
    public Mono
filter(ServerWebExchange exchange, WebFilterChain chain) {
        String appName = parseAppName(exchange);
        PluginChain pluginChain = new PluginChain(properties, appName);
        pluginChain.addPlugin(new DynamicRoutePlugin(properties));
        pluginChain.addPlugin(new AuthPlugin(properties));
        return pluginChain.execute(exchange, pluginChain);
    }
}

Data synchronization ensures that instance weight and enabled plugins are kept up‑to‑date in Nacos. The NacosSyncListener periodically pushes metadata to Nacos, while DataSyncTaskListener pulls instance information into local caches.

WebSocket is used for real‑time rule propagation. The server side ( WebsocketSyncCacheServer ) receives rule change messages and updates the in‑memory RouteRuleCache . The client side ( WebsocketSyncCacheClient ) connects to the server, sends an initial full rule set, and reconnects automatically on failure.

Testing

Dynamic routing was verified by launching two service instances with different versions (gray_1.0 and prod_1.0) and configuring a header‑based routing rule. Requests with header name=ship were correctly routed to the gray version, as shown by the server logs.

Performance testing using wrk on a MacBook Pro (2.3 GHz i7, 16 GB RAM) with a single backend node achieved roughly 9,400 requests per second with 20 threads and 500 connections.

Conclusion

The project demonstrates that building a custom high‑performance gateway is feasible with Spring WebFlux, Netty, and Nacos, and that a modular plugin architecture combined with real‑time synchronization simplifies extensibility and operational management.