SpringCloud 應(yīng)用 Nacos 配置中心注解
前言
在 Spring Cloud 應(yīng)用中可以非常低成本地集成 Nacos 實(shí)現(xiàn)配置動(dòng)態(tài)刷新，在應(yīng)用程序代碼中通過 Spring 官方的注解 @Value 和 @ConfigurationProperties，引用 Spring enviroment 上下文中的屬性值，關(guān)于這部分的介紹可以參照《Spring Cloud+Nacos+KMS 動(dòng)態(tài)配置最佳實(shí)踐》一文，這種用法的最大優(yōu)點(diǎn)是無代碼層面侵入性，但也存在諸多限制，比如：
- Nacos 中配置是作為 Spring 上下文 enviroment 的屬性源之一，獲取屬性時(shí)會(huì)收到其他屬性源的干擾，比如通過 JVM 參數(shù)和環(huán)境變量注入的屬性優(yōu)先級比 Nacos 中的更高。
- 通過 spring.config.import 導(dǎo)入多個(gè) Nacos 配置時(shí)，其中相同的 key 對應(yīng)的屬性只會(huì)有一個(gè)生效，需要控制多個(gè)屬性源的 key 不重復(fù)或者處理因優(yōu)先級問題導(dǎo)致的屬性覆蓋問題。無法精準(zhǔn)獲取指定 Nacos 配置中的屬性。
- 無法將 Nacos 配置自動(dòng)注入對象類型的字段。
- 只能被動(dòng)接受配置最終內(nèi)容，無法在配置變更時(shí)對配置進(jìn)行二次處理或者觸發(fā)其他業(yè)務(wù)動(dòng)作，無法感知指定的屬性變更前后的詳細(xì)信息。
- 通過 @Value 注解引用的配置要支持動(dòng)態(tài)刷新，需要在 SpringBean 上添加 @RefreshScope，配置更新時(shí)會(huì)先將 Bean 銷毀再重新創(chuàng)建新的 Bean，使用不當(dāng)易產(chǎn)生線上問題。
為了解決以上問題，提升應(yīng)用接入 Nacos 配置中心的易用性，Spring Cloud Alibaba 發(fā)布一套全新的 Nacos 配置中心的注解。
- @NacosConfig：作用于 SpringBean 的字段，將 Nacos 中指定的配置注入字段；作用于 SpringBean Class，將 Nacos 中指定的配置注入 Bean 的屬性中；作用于 FactoryBean 方法，將 Nacos 中指定的配置注入 Bean 的屬性中，不依賴 RefreshScope 注解即可生效。
- @NacosConfigListener：作用于 SpringBean 的方法，在 Nacos 中的配置發(fā)生變化時(shí)，以方法參數(shù)形式接受變更后的最新配置內(nèi)容，支持以對象類型接收結(jié)果。
- @NacosConfigKeysListener：作用于 SpringBean 的方法，在 Nacos 中的配置的指定屬性 key 集合發(fā)生變化時(shí)，以方法參數(shù) ConfigChangeEvent 接受變更前后的屬性值。
以下將詳細(xì)介紹三種注解的用法。
@NacosConfig 注解用法介紹
如果配置格式為 yaml 和 properties，也可以額外指定 key 字段名，加載指定 key 對應(yīng)的屬性值。
注解字段解釋
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.TYPE, ElementType.METHOD})
@Documented
public @interface NacosConfig {
String group();
String dataId();
String key() default "";
String defaultValue() default "";
}- group：引入的配置所屬分組。
- dataId: 引入的配置 DataId。
- key: 配置格式為 yaml 和 properties 時(shí)，也可以額外指定 key 字段名，加載指定 key 對應(yīng)的屬性值。
- defaultValue：當(dāng)配置不存在或者配置內(nèi)指定 key 屬性為空時(shí)，加載的默認(rèn)值。
訪問 nacos 的全局參數(shù)通過 application.properties 中 spring.cloud.nacos.config.server-addr, spring.cloud.nacos.config.namespace 參數(shù)配置。通過 spring.config.import 導(dǎo)入的配置作用于 Spring 的 @Value 引用屬性源，和通過注解引入的方式相互獨(dú)立，但其內(nèi)部是共享同一個(gè) NacosClient 對象，并且訪問的是同一個(gè) Nacos 實(shí)例以及同一個(gè)命名空間下的配置。
用法示例
1. 加載完整配置內(nèi)容至 String 類型字段
@NacosConfig(dataId = "SampleApp.application.properties", group = "default")
String configContent;將 dataId=SampleApp.application.properties，group = default 對應(yīng)的配置的完整內(nèi)容注入到 configContent 字段。
2. 加載配置中的指定 key 屬性至基礎(chǔ)類型字段
@NacosConfig(dataId = "SampleApp.application.properties", group = "default", key = "useCache", defaultValue = "false")
boolean booleanValue;將 dataId=SampleApp.application.properties，group = default 對應(yīng)的配置中的 useCache 屬性值注入到 booleanValue 字段。
支持 int, long,float,double,boolean 5 種基礎(chǔ)類型以及其封裝類型。
3. 加載 JSON 格式配置至基礎(chǔ)類型數(shù)組字段
@NacosConfig(dataId = "scoreintArray.json", group = "default")
int[] scores;將 dataId=scoreintArray.json，group = default 對應(yīng)的 json 格式配置注入到 scores 字段，需保證配置格式可正常反序列化。
支持 int, long,float,double,boolean 5 種基礎(chǔ)類型數(shù)組以及其封裝類型。
配置需以 .json 結(jié)尾且配置內(nèi)容為 json 格式。
4. 加載配置至 Properties 類型字段
@NacosConfig(dataId = "SampleApp.application.properties", group = "default")
Properties properties = new Properties();將 dataId = "SampleApp.application.properties", group = "default" 的配置內(nèi)容注入到 properties 字段中?？梢酝ㄟ^ properties.getProperty 方法獲取其內(nèi)部屬性值。當(dāng)遠(yuǎn)端 Nacos 配置發(fā)生變化中，properties 對象會(huì)被替換，引用也會(huì)更新。
支持 properties 及 yaml 格式，dataId 需以 properties,yaml,yml 結(jié)尾，其中 yaml 格式中不能包含數(shù)組列表格式屬性。
5. 加載至自定義 JavaBean 字段
@NacosConfig(dataId = "myobject.json", group = "default")
MyObject json2Object;
@NacosConfig(dataId = "myobjectArray.json", group = "default")
MyObject[] json2ObjectArray;
@NacosConfig(dataId = "myobjectArray.json", group = "default")
List<MyObject> json2ObjectList;
@NacosConfig(dataId = "myobjectMap.json", group = "default")
Map<String, MyObject> json2ObjectMap;將 dataId = "myobject.json", group = "default" 的配置加載至 json2Object 字段。
將 dataId = "myobjectArray.json", group = "default" 的 json 數(shù)組/列表格式的配置加載至 json2ObjectArray 字段。
將 dataId = "myobjectArray.json", group = "default" 的 json 數(shù)組/列表格式的配置加載至 json2ObjectList 字段。
將 dataId = "myobjectMap.json", group = "default" 的 json map 格式的配置加載至 json2ObjectMap 字段。
支持自定義數(shù)組，集合類型，支持自動(dòng)根據(jù)指定泛型進(jìn)行反序列化。
當(dāng)遠(yuǎn)端 Nacos 配置發(fā)生變化中，字段對應(yīng)的對象會(huì)被替換，引用也會(huì)更新。
6. 加載 JSON 格式配置至 SpringBean
@Component
@NacosConfig(dataId = "myobject.json", group = "default")
public class MyObject {
String name;
String age;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getAge() {
return age;
}
public void setAge(String age) {
this.age = age;
}
}將 dataId = "myobject.json", group = "default" 的 JSON 配置加載至指定 SpringBean 的字段中，配置中的 JSON 屬性名需要和 SpringBean 中字段完全一致，且保證每個(gè)字段有 getter 及 setter 方法。
@NacosConfig 所在的類必須被發(fā)布為一個(gè) SpringBean 才能生效。
@NacosConfig 類級別的注入優(yōu)先級高于字段級別，如在其 Bean 內(nèi)部字段中額外添加 @NacosConfig 將不會(huì)生效。
7. 加載 JSON 格式配置至工廠 Bean
public class SampleConfiguration {
@NacosConfig(dataId = "myobject1.json", group = "default")
@Bean
public MyObject bean1(){
return new MyObject();
}
@NacosConfig(dataId = "myobject2.json", group = "default")
@Bean
public MyObject bean2(){
return new MyObject();
}
}將 dataId = "myobject1.json", group = "default" 的配置內(nèi)容加載至 beanName=bean1 的 MyObject 類型的 SpringBean 中。
將 dataId = "myobject2.json", group = "default" 的配置內(nèi)容加載至 beanName=bean2 的 MyObject 類型的 SpringBean 中。
必須配合 @Bean 注解使用。
@NacosConfigListener 注解用法介紹
如果希望在 Bean 初始化時(shí)接受初始回調(diào)，可以設(shè)置 initNotify=true，默認(rèn)為 false。
以下示例中的回調(diào)方法名均為示例，方法名可以自定義。
用法示例
1. String 參數(shù)方法接收原生配置內(nèi)容
@NacosConfigListener(dataId = "myobjectArray.json", group = "default")
private void fullContentChanged(String content) {
System.out.println("receive ：" + content);
}當(dāng) dataId = "myobjectArray.json", group = "default" 的配置發(fā)生變更時(shí)，將完整內(nèi)容以 content 參數(shù)回調(diào) fullContentChanged 方法。
2. 基礎(chǔ)類型參數(shù)方法接受指定 key 值內(nèi)容
@NacosConfigListener(dataId = "SampleApp.application.properties", group = "default",key="score")
private void scoreChanged(int score) {
System.out.println("receive ：" + score);
}當(dāng) dataId = "SampleApp.application.properties", group = "default" 的配置中key="score" 的屬性值發(fā)生變更時(shí)，將對應(yīng)屬性值 score 參數(shù)回調(diào) scoreChanged 方法。
支持 int, long,float,double,boolean 5 種基礎(chǔ)類型。
3. 基礎(chǔ)類型數(shù)組參數(shù)方法接受 JSON 格式配置內(nèi)容
@NacosConfigListener(dataId = "scoresArray.json", group = "default")
private void scoresChanged(int[] scores) {
System.out.println("receive ：" + scores);
}當(dāng) dataId = "scoresArray.json", group = "default" 的 JSON 格式配置發(fā)生變更時(shí)，將配置內(nèi)容反序列化為基礎(chǔ)類型數(shù)組對象以 scores 參數(shù)回調(diào) scoresChanged 方法。
支持 int, long,float,double,boolean 5 種基礎(chǔ)類型數(shù)組。
配置 dataId 必須以 .json 結(jié)尾，并且配置內(nèi)容必須為 json 數(shù)組格式。
4. Properties 參數(shù)方法接受屬性參數(shù)
@NacosConfigListener(dataId = "SampleApp.application.properties", group = "default")
private void propertiesChanged(Properties properties) {
System.out.println("receive ：" + properties);
}當(dāng) dataId = "SampleApp.application.properties", group = "default" 的 properties 格式配置發(fā)生變更時(shí)，將配置內(nèi)容解析為Properties對象以 Properties 類型參數(shù)回調(diào) propertiesChanged 方法。
5. 自定義 Java Bean 參數(shù)
@NacosConfigListener(dataId = "myobject.json", group = "default")
private void myObjectChanged(MyObject object) {
System.out.println("receive ：" + object);
}
@NacosConfigListener(dataId = "myobjectArray.json", group = "default")
private void myObjectArrayChanged(MyObject[] objectArray) {
System.out.println("receive ：" + objectArray);
}
@NacosConfigListener(dataId = "myobjectArray.json", group = "default")
private void myObjectListChanged(List<MyObject> objectList) {
System.out.println("receive ：" + objectList);
}
@NacosConfigListener(dataId = "myobjectMap.json", group = "default")
private void myObjectMapChanged(Map<String,MyObject> objectMap) {
System.out.println("receive ：" + objectMap);
}當(dāng)指定配置內(nèi)容發(fā)生變更時(shí)，以對象，對象數(shù)組，對象列表，對象模式類型回調(diào)方法。
支持自定義數(shù)組，集合類型，自動(dòng)根據(jù)指定泛型進(jìn)行反序列化。
@NacosConfigKeysListener 注解用法介紹
通過 interestedKeys 指定監(jiān)聽的 keys 集合，通過 interestedKeyPrefixes 指定需要監(jiān)聽的 key 前綴集合，如果符合任意任一條件的 key 發(fā)生變化時(shí)都會(huì)觸發(fā)回調(diào)。
用法示例
@NacosConfigKeysListener(dataId = "SampleApp.122110test.properties", group = "default", interestedKeys = {
"useLocalCache,"}, interestedKeyPrefixes = {"122110."})
private void onKeysChangeSingle(ConfigChangeEvent changeEvent) {
System.out.println("interestedKeyPrefixes:nacos." + changeEvent.getChangeItems());
}支持 properties 及 yaml 格式，dataId 需以 properties,yaml,yml 結(jié)尾。
結(jié)語
當(dāng)前 Spring Cloud Alibaba 在全系列版本（包括 2.2.x，2021.x，2022.x，2023.x）中都已經(jīng)正式發(fā)布新版本支持以上注解。
- 2023.x 系列需升級版本至 2023.0.3.2
- 2022.x 系列需升級版本至 2022.0.0.2
- 2021.x 系列需升級版本至 2021.0.6.2
- 2.2.x 系列需升級至 2.2.11
其中在 2023.x 版本中，我們對 spring-cloud-alibaba 配置模塊進(jìn)行了重構(gòu)，單獨(dú)抽取了 spring-alibaba-nacos-config 模塊，該模塊不依賴 SpringCloud 框架，所以基于 SpringBoot3 的應(yīng)用通過單獨(dú)引入 spring-alibaba-nacos-config 也可以使用 @Value 引用 Nacos 中的配置以及本文介紹的三種注解。
#pom.xml中引入spring-alibaba-nacos-config依賴
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-alibaba-nacos-config</artifactId>
<version>2023.0.3.2</version>
</dependency>
#application.properties中添加如下配置
spring.config.import=nacos:optional:nacos:{此處按需替換為需導(dǎo)入的nacos dataId}?group={此處按需替換為需導(dǎo)入的nacos group}&refreshEnabled=true
spring.nacos.config.server-addr={此處按需替換為nacos的serverAddr}
spring.nacos.config.namespace={此處按需替換為nacos的命名空間，public請?zhí)羁諁
//其他參數(shù)請參照sca官方文檔，將spring.cloud.nacos前綴替換為spring.nacos即可,本文中的注解用法完全一致
