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

> Integrate r-nacos with Spring Cloud Config and Dubbo using nacos-client SDK. Use Rust-based r-nacos as a Nacos server replacement for seamless centralized configuration and service discovery in Java microservices.

- Repository: [Nacos Group/r-nacos](https://github.com/nacos-group/r-nacos)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/nacos-group/r-nacos/blob/main/pom.xml). As shown in [`sdk-examples/java/spring-cloud-config-nacos-v3/pom.xml`](https://github.com/nacos-group/r-nacos/blob/main/sdk-examples/java/spring-cloud-config-nacos-v3/pom.xml), use version `2025.0.0.0-preview` or compatible:

```xml
<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:

```properties
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:

```java
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`](https://github.com/nacos-group/r-nacos/blob/main/sdk-examples/java/dubbo_v3.x/pom.xml), declare both the client and Dubbo dependencies:

```xml
<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`](https://github.com/nacos-group/r-nacos/blob/main/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:

```java
@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`](https://github.com/nacos-group/r-nacos/blob/main/DemoServiceImpl.java) example in the same directory demonstrates automatic registration with r-nacos:

```java
@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:

```java
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:

```java
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`](https://github.com/nacos-group/r-nacos/blob/main/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.