Route Microservice Traffic via Nacos, Gateway & Zuul - EDAS

A service gateway routes incoming client requests to backend microservices based on configurable rules such as URL path, headers, or query parameters. This topic explains how to build a gateway with Nacos as the service registry, using either Spring Cloud Gateway or Spring Cloud Netflix Zuul.

To skip the step-by-step setup, download the complete demo projects:

How Spring Cloud Gateway routes requests

Spring Cloud Gateway processes requests through three core constructs:

Construct	Description
Route	The basic building block. Each route maps an incoming request to a backend service, defined by an ID, a destination URI, one or more predicates, and optional filters.
Predicate	A matching condition evaluated against the incoming request (path, header, query parameter, etc.). A route is matched when all its predicates return true.
Filter	A processing step that modifies the request or response before or after forwarding. For example, `StripPrefix=1` removes the first path segment before sending the request downstream.

Request flow: Client -> Gateway Handler Mapping (matches a route by evaluating predicates) -> Gateway Web Handler (runs the filter chain) -> Backend Service. Filters run both before and after the proxied request, allowing you to modify headers, rewrite paths, or add authentication at the gateway level.

Prerequisites

Before you begin, make sure you have:

Maven installed with environment variables configured
The latest Nacos Server downloaded
Optional:

Start Nacos Server

Decompress the downloaded Nacos Server package.
Navigate to the nacos/bin directory and start Nacos Server in standalone mode:
- Linux, UNIX, or macOS:
```
sh startup.sh -m standalone
```
- Windows: double-click startup.cmd.

Build a service gateway with Spring Cloud Gateway

Spring Cloud Gateway is built on Project Reactor and Spring WebFlux, providing a non-blocking, reactive gateway.

Step 1: Create the gateway project

Create a Maven project named spring-cloud-gateway-nacos.

Add the following dependencies to pom.xml. This example uses Spring Boot 2.1.4.RELEASE and Spring Cloud Greenwich.SR1:

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.4.RELEASE</version>
        <relativePath/>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-gateway</artifactId>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
            <version>2.1.1.RELEASE</version>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>Greenwich.SR1</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

Create the startup class GatewayApplication:

    @SpringBootApplication
    @EnableDiscoveryClient
    public class GatewayApplication {
        public static void main(String[] args) {
            SpringApplication.run(GatewayApplication.class, args);
        }
    }

Step 2: Configure routing rules

Add the following configuration to application.yaml. Replace 127.0.0.1:8848 with the actual address of your Nacos Server if it runs on a different machine.

server:
  port: 18012

spring:
  application:
    name: spring-cloud-gateway-nacos
  cloud:
    gateway:
      routes:
      - id: service-provider
        uri: lb://service-provider
        predicates:
        - Path=/provider1/**
        filters:
        - StripPrefix=1
    nacos:
      discovery:
        server-addr: 127.0.0.1:8848

This route configuration works as follows:

Component	Value	Description
Predicate	`Path=/provider1/**`	Matches all requests with a path starting with `/provider1/`.
URI	`lb://service-provider`	Forwards matched requests to the `service-provider` service using client-side load balancing.
Filter	`StripPrefix=1`	Removes the first path segment before forwarding. For example, `/provider1/echo/hello` becomes `/echo/hello`.

Step 3: Start the gateway and verify registration

Run the main function of GatewayApplication to start the gateway.
Open the Nacos Server console at http://127.0.0.1:8848/nacos (default username and password: nacos).
In the navigation pane, choose Service Management > Services. Confirm that spring-cloud-gateway-nacos appears in the service list.

Build a service gateway with Spring Cloud Netflix Zuul

Zuul is an alternative gateway option based on a blocking I/O model. It suits applications already using the Netflix OSS stack.

Step 1: Create the gateway project

Create a Maven project named spring-cloud-zuul-nacos.

Add the following dependencies to pom.xml. This example uses Spring Boot 2.1.4.RELEASE, Spring Cloud Greenwich.SR1, and Spring Cloud Alibaba 0.9.0:

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.4.RELEASE</version>
        <relativePath/>
    </parent>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-zuul</artifactId>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
            <version>2.1.1.RELEASE</version>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>Greenwich.SR1</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

Create the startup class ZuulApplication:

    @SpringBootApplication
    @EnableZuulProxy
    @EnableDiscoveryClient
    public class ZuulApplication {
        public static void main(String[] args) {
            SpringApplication.run(ZuulApplication.class, args);
        }
    }

Step 2: Configure routing rules

Add the following configuration to application.properties. Replace 127.0.0.1:8848 with the actual address of your Nacos Server if it runs on a different machine.

spring.application.name=spring-cloud-zuul-nacos
server.port=18022

spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848

zuul.routes.opensource-provider1.path=/provider1/**
zuul.routes.opensource-provider1.serviceId=service-provider

This routes all requests with a path starting with /provider1/ to the service-provider backend service.

Step 3: Start the gateway and verify registration

Run the main function of ZuulApplication to start the gateway.
Open the Nacos Server console at http://127.0.0.1:8848/nacos (default username and password: nacos).
In the navigation pane, choose Service Management > Services. Confirm that spring-cloud-zuul-nacos appears in the service list.

Create a service provider

Both Spring Cloud Gateway and Zuul require a downstream service to forward requests to. For full details, see Implement service registration and discovery.

The following example creates a minimal service provider with a single /echo/{string} endpoint:

@SpringBootApplication
@EnableDiscoveryClient
public class ProviderApplication {

    public static void main(String[] args) {
        SpringApplication.run(ProviderApplication.class, args);
    }

    @RestController
    public class EchoController {
        @RequestMapping(value = "/echo/{string}", method = RequestMethod.GET)
        public String echo(@PathVariable String string) {
            return string;
        }
    }
}

Verify request forwarding

Verify locally

Start both the gateway and the service provider, then send a request through the gateway.

For Spring Cloud Gateway (port 18012):

curl http://127.0.0.1:18012/provider1/echo/hello

For Zuul (port 18022):

curl http://127.0.0.1:18022/provider1/echo/hello

A successful response returns hello, confirming that the gateway forwarded the request to service-provider and stripped the /provider1 prefix.

EDAS Spring Cloud application development: build a Zuul gateway

Deploy to EDAS

Deploy the application to Enterprise Distributed Application Service (EDAS). For deployment instructions, see Implement service registration and discovery.

The EDAS service registry is a commercial version of Nacos. When deploying to EDAS, the platform automatically configures the Nacos connection details -- IP address, service port, namespace, AccessKey ID, AccessKey secret, and context path. No additional configuration is required. Retain or remove the original on-premises Nacos settings as needed.

Version compatibility

Spring Cloud version	Spring Cloud Alibaba version
Greenwich	2.1.1.RELEASE
Finchley	2.0.1.RELEASE
Edgware	1.5.1.RELEASE

Note

Spring Cloud Edgware has reached end of life. Do not use it for new applications.

What's next

Implement service registration and discovery