Use Nacos as a Registry for Automatic Service Discovery

This example demonstrates automatic service discovery using Nacos as a registry based on a Spring Boot application. You can view the complete example code.

1 Basic Configuration

1.1 Add Dependencies

For Spring Boot applications, use the following spring-boot-starter:

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-spring-boot-starter</artifactId>
    <version>3.3.0</version>
</dependency>
<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-nacos-spring-boot-starter</artifactId>
    <version>3.3.0</version>
</dependency>

Non-Spring Boot users can add dubbo and nacos-client dependencies:

<dependencies>
    <dependency>
        <groupId>org.apache.dubbo</groupId>
        <artifactId>dubbo</artifactId>
        <version>3.3.0</version>
    </dependency>
    <dependency>
      <groupId>com.alibaba.nacos</groupId>
      <artifactId>nacos-client</artifactId>
      <version>2.1.0</version>
    </dependency>
</dependencies>

1.2 Nacos Version Mapping

1.3 Configure and Enable Nacos

# application.yml (Spring Boot)
dubbo
 registry
   address: nacos://localhost:8848

or

# dubbo.properties
dubbo.registry.address=nacos://localhost:8848

or

<dubbo:registry address="nacos://localhost:8848" />

2 Advanced Configuration

2.1 Authentication

# application.yml (Spring Boot)
dubbo
 registry
   address: nacos://localhost:8848?username=nacos&password=nacos

or

# dubbo.properties
dubbo.registry.address: nacos://nacos:nacos@localhost:8848

2.2 Custom Namespace

# application.yml (Spring Boot)
dubbo:
 registry:
   address: nacos://localhost:8848?namespace=5cbb70a5-xxx-xxx-xxx-d43479ae0932

or

# application.yml (Spring Boot)
dubbo:
 registry:
   address: nacos://localhost:8848
   parameters.namespace: 5cbb70a5-xxx-xxx-xxx-d43479ae0932

2.3 Custom Group

# application.yml
dubbo:
 registry:
   address: nacos://localhost:8848
   group: dubbo

If not configured, the group is specified by Nacos by default. The group and namespace represent different isolation levels in Nacos; generally, a namespace is used to isolate different users or environments, while a group is used to further categorize data within the same environment.

2.4 Register Interface-level Consumers

Starting from Dubbo 3.0.0, a parameter was added to indicate whether to register consumers. To register the consumer in the Nacos registry, set the parameter (register-consumer-url) to true; the default is false.

# application.yml
dubbo:
  registry:
    address: nacos://localhost:8848?register-consumer-url=true

or

# application.yml
dubbo:
  registry:
    address: nacos://localhost:8848
    parameters.register-consumer-url: true

2.5 More Configurations

After version 1.0.0 of nacos-server, clients can report instances with specific metadata to the server to control instance behaviors.

These parameters can be configured similarly to namespace by extending parameters in Nacos, such as

dubbo.registry.parameters.preserved.heart.beat.timeout=5000

3 Working Principle

In a previous section, we explained the difference between application-level service discovery and interface-level service discovery. Below are the specific storage structures of both modes in Nacos.

3.1 Dubbo2 Registration Data

Then, restart your Dubbo application, and the service provider and consumer information in Dubbo can be displayed in the Nacos console:

As shown in the figure, the information with the service name prefix providers: is the metadata of the service provider, while consumers: represents the metadata of the service consumer. Click “Details” to view service status details:

3.2 Dubbo3 Registration Data

The application-level service discovery “service name” is the application name.

Dubbo3 defaults to a dual registration mode of “application-level service discovery + interface-level service discovery,” so both application-level services (application name) and interface-level services (interface name) will appear in the Nacos console. You can change the registration behavior by configuring dubbo.registry.register-mode=instance/interface/all.

3.3 Client Caching

3.4 Heartbeat Detection

3.5