Apache ShenYu: Reactive Java API Gateway Overview and Quick Start Guide

Apache ShenYu is a reactive API gateway built with Java Reactor, providing high performance, dynamic traffic management, hot‑plug extensibility, and out‑of‑the‑box lifecycle features such as API registration, service proxy, protocol conversion, and governance.

Feature Highlights

Proxy: Supports Apache® Dubbo™, Spring Cloud, gRPC, Motan, SOFA, TARS, WebSocket, MQTT.

Security: Sign, OAuth 2.0, JSON Web Tokens, WAF plugin.

API Governance: Request/response handling, parameter mapping, Hystrix, RateLimiter plugin.

Observability: Tracing, metrics, logging plugins.

Dashboard: Visual backend for dynamic traffic control and user menu permissions.

Extensibility: Hot‑plug and dynamic loading of plugins.

Cluster Support: NGINX, Docker, Kubernetes.

Language SDKs: .NET, Python, Go, Java clients for API registration.

Modules

shenyu-admin : Management console for plugins and configuration.

shenyu-bootstrap : Project bootstrap, reference for starting the gateway.

shenyu-client : Provides quick access via Spring MVC, Dubbo, Spring Cloud.

shenyu-disruptor : Disruptor‑based wrapper.

shenyu-register-center : Supports various RPC registration centers.

shenyu-common : Common utilities for the framework.

shenyu-dist : Build distribution.

shenyu-metrics : Prometheus‑based metrics implementation.

shenyu-plugin : Collection of supported plugins.

shenyu-spi : Defines ShenYu SPI.

shenyu-spring-boot-starter : Spring Boot starter support.

shenyu-sync-data-center : Data synchronization via ZooKeeper, HTTP, WebSocket, Nacos.

shenyu-examples : RPC example projects.

shenyu-web : Core handling package for plugins, routing, and forwarding.

Quick Start

Run Apache ShenYu Admin

docker pull apache/shenyu-admin
docker network create shenyu
docker run -d -p 9095:9095 --net shenyu apache/shenyu-admin

Run Apache ShenYu Bootstrap

docker network create shenyu
docker pull apache/shenyu-bootstrap
docker run -d -p 9195:9195 --net shenyu apache/shenyu-bootstrap

Configure Router

Add localKey: 123456 to the header; for custom keys, generate a SHA‑512 key and set shenyu.local.sha512Key .

curl --location --request POST 'http://localhost:9195/shenyu/plugin/selectorAndRules' \
--header 'Content-Type: application/json' \
--header 'localKey: 123456' \
--data-raw '{
  "pluginName": "divide",
  "selectorHandler": "[{\"upstreamUrl\":\"127.0.0.1:8080\"}]",
  "conditionDataList": [{
    "paramType": "uri",
    "operator": "match",
    "paramValue": "/**"
  }],
  "ruleDataList": [{
    "ruleHandler": "{\"loadBalance\":\"random\"}",
    "conditionDataList": [{
      "paramType": "uri",
      "operator": "match",
      "paramValue": "/**"
    }]
  }]
}'

Selector and Rule

Selectors and rules route requests based on HTTP headers.

A selector is a coarse‑grained route (e.g., module level).

A rule is a fine‑grained route (e.g., method level within a module).

Each selector/rule matches once and then returns the match; the coarsest routes should be placed last.

Data Cache and Synchronization

All data is cached in a JVM ConcurrentHashMap for ultra‑fast access.

Cache updates are dynamically triggered by watching ZooKeeper nodes (or via WebSocket push, HTTP long‑polling).

For more details, see the open‑source repository: https://github.com/apache/shenyu .