Master Dynamic Nacos Config in Spring Cloud: New @NacosConfig Annotations Explained

Background and Limitations

In Spring Cloud applications, the traditional way to read Nacos configuration uses @Value or @ConfigurationProperties. This approach suffers from several issues: Nacos properties compete with other property sources, duplicate keys cause priority conflicts, injection into object fields is not supported, and dynamic refresh requires @RefreshScope which recreates beans and may cause runtime problems.

New Nacos Annotations (Spring Cloud Alibaba)

@NacosConfig

Injects configuration from Nacos directly into a field, class, or factory‑bean method without needing @RefreshScope. Attributes:

group : configuration group

dataId : configuration dataId

key (optional): specific key for yaml or properties files

defaultValue (optional): fallback when the key is missing

Supported target types include primitive wrappers, String, Properties, collections ( List<T>, Set<T>, Map<K,V>), arrays, and any custom Java bean with standard getters/setters.

@NacosConfig(dataId = "SampleApp.application.properties", group = "default")
String configContent;

Injects the whole file content.

@NacosConfig(dataId = "SampleApp.application.properties", group = "default", key = "useCache", defaultValue = "false")
boolean booleanValue;

Injects a single key as a primitive.

@NacosConfig(dataId = "scoreintArray.json", group = "default")
int[] scores;

Injects a JSON array into an int[] field.

@NacosConfig(dataId = "myobject.json", group = "default")
MyObject json2Object;

Injects a JSON object into a custom bean.

@NacosConfigListener

Placed on a Spring bean method; the method is invoked when the specified Nacos entry changes. The method parameter can be a primitive, String, Properties, array, collection, or custom bean.

@NacosConfigListener(dataId = "myobjectArray.json", group = "default")
private void fullContentChanged(String content) {
    System.out.println("receive : " + content);
}

@NacosConfigListener(dataId = "SampleApp.application.properties", group = "default", key = "score")
private void scoreChanged(int score) {
    System.out.println("receive : " + score);
}

@NacosConfigListener(dataId = "myobject.json", group = "default")
private void myObjectChanged(MyObject object) {
    System.out.println("receive : " + object);
}

@NacosConfigKeysListener

Monitors a set of keys (or key prefixes) within a properties or yaml file. When any of the specified keys change, the method receives a ConfigChangeEvent containing before‑and‑after values.

@NacosConfigKeysListener(dataId = "SampleApp.122110test.properties", group = "default", interestedKeys = {"useLocalCache"}, interestedKeyPrefixes = {"122110."})
private void onKeysChangeSingle(ConfigChangeEvent changeEvent) {
    System.out.println("changed items: " + changeEvent.getChangeItems());
}

Version Compatibility and Upgrade Guidance

2023.x series → upgrade to 2023.0.3.2 2022.x series → upgrade to 2022.0.0.2 2021.x series → upgrade to 2021.0.6.2 2.2.x series → upgrade to 2.2.11 From 2023.x onward the Nacos configuration module is refactored into spring-alibaba-nacos-config, which can be used independently of Spring Cloud and is compatible with Spring Boot 3.

Dependency and Configuration Snippet

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>spring-alibaba-nacos-config</artifactId>
    <version>2023.0.3.2</version>
</dependency>

Add the following to application.properties (or application.yml) to enable Nacos import and set server address/namespace:

spring.config.import=nacos:optional:nacos:{dataId}?group={group}&refreshEnabled=true
spring.nacos.config.server-addr={your-nacos-server-addr}
spring.nacos.config.namespace={your-namespace-or-empty-for-public}

References

Nacos Official Site: https://nacos.io

Nacos GitHub Repository: https://github.com/alibaba/nacos

Spring Cloud Alibaba Documentation: https://sca.aliyun.com/docs/2023/user-guide/nacos/quick-start/