How to Integrate r-nacos with Spring Cloud Config and Dubbo Using the nacos-client SDK

Java microservices can use r-nacos as a drop-in replacement for the official Nacos server by configuring the nacos-client SDK to connect to the Rust-based registry for centralized configuration and service discovery.

r-nacos is a Rust-based implementation of the Nacos service registry and configuration center. It exposes the same OpenAPI endpoints and gRPC protocols as the official Java Nacos server, allowing Spring Cloud Config and Apache Dubbo applications to connect without code changes. This guide demonstrates the integration patterns using the official nacos-client SDK with working examples from the nacos-group/r-nacos repository.

Spring Cloud Config Integration with r-nacos

Spring Cloud applications pull externalized configuration from r-nacos using the standard Alibaba Nacos Config starter. The integration requires three components: the Maven dependency, connection properties, and a data ID stored in r-nacos.

Maven Dependencies

Add the Spring Cloud Alibaba Nacos Config starter to your pom.xml. As shown in sdk-examples/java/spring-cloud-config-nacos-v3/pom.xml, use version 2025.0.0.0-preview or compatible:

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    <version>2025.0.0.0-preview</version>
</dependency>

Application Configuration

Configure the r-nacos server address in application.properties. The example in sdk-examples/java/spring-cloud-config-nacos-v3/src/main/resources/application.properties demonstrates the required settings:

server.port=8083
spring.cloud.nacos.config.server-addr=127.0.0.1:8848
spring.cloud.nacos.config.username=nacos
spring.cloud.nacos.config.password=nacos
spring.application.name=example
spring.config.import=nacos:example.properties
spring.cloud.nacos.config.file-extension=properties

The spring.config.import directive tells Spring Boot to fetch the example.properties data ID from r-nacos during startup.

Live Property Injection

Inject remote configuration values using the @NacosValue annotation with autoRefreshed=true to enable dynamic updates. The ConfigController in the example repository shows the implementation:

package com.alibaba.nacos.example.spring.boot.controller;

import com.alibaba.nacos.api.config.annotation.NacosValue;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;

@Controller
public class ConfigController {

    @NacosValue(value = "${useLocalCache:false}", autoRefreshed = true)
    private boolean useLocalCache;

    @GetMapping("/config/get")
    @ResponseBody
    public boolean get() {
        return useLocalCache;
    }
}

When you update useLocalCache in the r-nacos console, the value refreshes automatically without restarting the application.

Dubbo Service Discovery via r-nacos

Apache Dubbo uses r-nacos as a registry backend through the standard nacos-client library. The NamingService implementation in r-nacos handles heartbeat checks and instance lists exactly like the official server.

Dependency Setup

Include the Nacos client SDK in your Dubbo parent POM. According to sdk-examples/java/dubbo_v3.x/pom.xml, declare both the client and Dubbo dependencies:

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>2.3.3</version>
</dependency>
<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo</artifactId>
    <version>${dubbo.version}</version>
</dependency>

Provider Registration

Enable Dubbo with the @EnableDubbo annotation in your main application class. The App.java file in sdk-examples/java/dubbo_v3.x/dubbo-demo-service/src/main/java/com/rnacos/demo/ shows the standard Spring Boot entry point:

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

Register service implementations using the @DubboService annotation. The DemoServiceImpl.java example in the same directory demonstrates automatic registration with r-nacos:

@DubboService
public class DemoServiceImpl implements DemoService {

    @Value("${spring.application.name}")
    private String serviceName;

    @Override
    public String sayHello(String name) {
        return String.format("[%s] : Hello, %s", serviceName, name);
    }
}

Dubbo automatically pushes the instance metadata (IP, port, service name) to the r-nacos NamingService via the underlying nacos-client SDK.

Consumer Configuration

Inject remote service proxies using @DubboReference. Dubbo queries the r-nacos naming service to resolve provider instances dynamically, handling load balancing and failover automatically.

Direct SDK Usage for Custom Operations

Both Spring Cloud Config and Dubbo rely on the nacos-client SDK internally. For custom logic such as feature flags or manual health checks, instantiate the SDK clients directly.

Programmatic Configuration Management

Push configuration changes programmatically using ConfigClient. This bypasses Spring's abstraction to update raw key-value pairs:

AuthInfo auth = new AuthInfo("nacos", "nacos");
ClientBuilder builder = new ClientBuilder()
        .setServerList("127.0.0.1:8848")
        .setAuthInfo(auth);

ConfigClient configClient = builder.buildConfigClient();
ConfigKey key = new ConfigKey("example.properties", "DEFAULT_GROUP", "public");
configClient.publishConfig(key, "useLocalCache=true");

Manual Service Instance Queries

Query registered instances directly via NamingClient for debugging or custom load balancing:

NamingClient naming = builder.buildNamingClient();
List<Instance> list = naming.getAllInstances("com.rnacos.demo.FooService");
list.forEach(i -> System.out.println(i.getIp() + ":" + i.getPort()));

These low-level APIs mirror the functionality available in the official Nacos Java SDK, as demonstrated in the Rust SDK examples at sdk-examples/rust/nacos_rust_client/naming-register/src/main.rs.

Summary

• Drop-in compatibility: r-nacos implements the same OpenAPI and gRPC protocols as the official Nacos server, requiring no client code changes.
• Spring Cloud Config: Add spring-cloud-starter-alibaba-nacos-config, set spring.config.import, and use @NacosValue for dynamic properties.
• Dubbo integration: Include nacos-client 2.3.3, annotate providers with @DubboService, and enable Dubbo with @EnableDubbo.
• Direct SDK access: Use ConfigClient and NamingClient for programmatic configuration updates and service discovery outside framework abstractions.
• Source examples: Reference implementations are available in sdk-examples/java/spring-cloud-config-nacos-v3/ and sdk-examples/java/dubbo_v3.x/ within the nacos-group/r-nacos repository.

Frequently Asked Questions

Is r-nacos fully compatible with the official Nacos Java client?

Yes. r-nacos implements the complete Nacos OpenAPI specification and gRPC naming protocol. The Java nacos-client SDK (versions 2.3.3 and compatible) connects to r-nacos exactly as it would to the official Java server, supporting configuration polling, long-pushing, heartbeat registration, and service discovery.

What versions of Spring Cloud and Dubbo work with r-nacos?

Spring Cloud Alibaba 2025.0.0.0-preview and Dubbo 3.x integrate seamlessly with r-nacos. The key requirement is using a compatible nacos-client version (2.3.3 or later) that matches the protocol version exposed by your r-nacos server instance.

Can I use r-nacos for both configuration and naming in the same application?

Absolutely. A single r-nacos instance handles both ConfigService (key-value configuration) and NamingService (service registry) simultaneously. Configure spring.cloud.nacos.config.server-addr for Spring Cloud Config and dubbo.registry.address=nacos://127.0.0.1:8848 for Dubbo in the same application.properties file.

How do I migrate from official Nacos to r-nacos?

Migration requires only changing the server address in your client configurations. Update spring.cloud.nacos.config.server-addr and Dubbo registry URLs to point to your r-nacos instance (e.g., 127.0.0.1:8848). r-nacos stores configuration and naming data in local SQLite or MySQL backends, so export your existing Nacos data via OpenAPI and import it into r-nacos before switching client connections.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}