前言

Cloud Native

在 Spring Cloud 应用中可以非常低成本地集成 Nacos 实现配置动态刷新，在应用程序代码中通过 Spring 官方的注解 @Value 和 @ConfigurationProperties，引用 Spring enviroment 上下文中的属性值，关于这部分的介绍可以参照《Spring Cloud+Nacos+KMS 动态配置最佳实践》一文，这种用法的最大优点是无代码层面侵入性，但也存在诸多限制，比如：

• Nacos 中配置是作为 Spring 上下文 enviroment 的属性源之一，获取属性时会收到其他属性源的干扰，比如通过 JVM 参数和环境变量注入的属性优先级比 Nacos 中的更高。
• 通过 spring.config.import 导入多个 Nacos 配置时，其中相同的 key 对应的属性只会有一个生效，需要控制多个属性源的 key 不重复或者处理因优先级问题导致的属性覆盖问题。无法精准获取指定 Nacos 配置中的属性。
• 无法将 Nacos 配置自动注入对象类型的字段。
• 只能被动接受配置最终内容，无法在配置变更时对配置进行二次处理或者触发其他业务动作，无法感知指定的属性变更前后的详细信息。
• 通过 @Value 注解引用的配置要支持动态刷新，需要在 SpringBean 上添加 @RefreshScope，配置更新时会先将 Bean 销毁再重新创建新的 Bean，使用不当易产生线上问题。

为了解决以上问题，提升应用接入 Nacos 配置中心的易用性，Spring Cloud Alibaba 发布一套全新的 Nacos 配置中心的注解。

• @NacosConfig：作用于 SpringBean 的字段，将 Nacos 中指定的配置注入字段；作用于 SpringBean Class，将 Nacos 中指定的配置注入 Bean 的属性中；作用于 FactoryBean 方法，将 Nacos 中指定的配置注入 Bean 的属性中，不依赖 RefreshScope 注解即可生效。
• @NacosConfigListener：作用于 SpringBean 的方法，在 Nacos 中的配置发生变化时，以方法参数形式接受变更后的最新配置内容，支持以对象类型接收结果。
• @NacosConfigKeysListener：作用于 SpringBean 的方法，在 Nacos 中的配置的指定属性 key 集合发生变化时，以方法参数 ConfigChangeEvent 接受变更前后的属性值。

以下将详细介绍三种注解的用法。

@NacosConfig 注解用法介绍

Cloud Native

使用该注解可以将指定 nacos 配置注入 Spring Bean 的字段中，可以作用于 SpringBean 的单一字段上，也可以作用于 SpringBean 上（包括将注解加在 BeanClass 上以及结合 @Bean 注解工厂 Bean 注入模式），注入的目标类型中支持基础类型，Properties，集合 List<T>，Set<T>，Map<T> 泛型，以及其他任意自定义 Java Bean。

如果配置格式为 yaml 和 properties，也可以额外指定 key 字段名，加载指定 key 对应的属性值。

注解字段解释

@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 时，也可以额外指定 key 字段名，加载指定 key 对应的属性值。
• defaultValue：当配置不存在或者配置内指定 key 属性为空时，加载的默认值。

访问 nacos 的全局参数通过 application.properties 中 spring.cloud.nacos.config.server-addr, spring.cloud.nacos.config.namespace 参数配置。通过 spring.config.import 导入的配置作用于 Spring 的 @Value 引用属性源，和通过注解引入的方式相互独立，但其内部是共享同一个 NacosClient 对象，并且访问的是同一个 Nacos 实例以及同一个命名空间下的配置。

用法示例

1. 加载完整配置内容至 String 类型字段

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

String configContent;

将 dataId=SampleApp.application.properties，group = default 对应的配置的完整内容注入到 configContent 字段。

2. 加载配置中的指定 key 属性至基础类型字段

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

将 dataId=SampleApp.application.properties，group = default 对应的配置中的 useCache 属性值注入到 booleanValue 字段。

支持 int, long,float,double,boolean 5 种基础类型以及其封装类型。

3. 加载 JSON 格式配置至基础类型数组字段

@NacosConfig(dataId = "scoreintArray.json", group = "default")

int[] scores;

将 dataId=scoreintArray.json，group = default 对应的 json 格式配置注入到 scores 字段，需保证配置格式可正常反序列化。

支持 int, long,float,double,boolean 5 种基础类型数组以及其封装类型。

配置需以 .json 结尾且配置内容为 json 格式。

4. 加载配置至 Properties 类型字段

@NacosConfig(dataId = "SampleApp.application.properties", group = "default")
Properties properties = new Properties();

将 dataId = "SampleApp.application.properties", group = "default" 的配置内容注入到 properties 字段中。可以通过 properties.getProperty 方法获取其内部属性值。当远端 Nacos 配置发生变化中，properties 对象会被替换，引用也会更新。

支持 properties 及 yaml 格式，dataId 需以 properties,yaml,yml 结尾，其中 yaml 格式中不能包含数组列表格式属性。

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 数组/列表格式的配置加载至 json2ObjectArray 字段。

将 dataId = "myobjectArray.json", group = "default" 的 json 数组/列表格式的配置加载至 json2ObjectList 字段。

将 dataId = "myobjectMap.json", group = "default" 的 json map 格式的配置加载至 json2ObjectMap 字段。

支持自定义数组，集合类型，支持自动根据指定泛型进行反序列化。

当远端 Nacos 配置发生变化中，字段对应的对象会被替换，引用也会更新。

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 中字段完全一致，且保证每个字段有 getter 及 setter 方法。

@NacosConfig 所在的类必须被发布为一个 SpringBean 才能生效。

@NacosConfig 类级别的注入优先级高于字段级别，如在其 Bean 内部字段中额外添加 @NacosConfig 将不会生效。

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" 的配置内容加载至 beanName=bean1 的 MyObject 类型的 SpringBean 中。

将 dataId = "myobject2.json", group = "default" 的配置内容加载至 beanName=bean2 的 MyObject 类型的 SpringBean 中。

必须配合 @Bean 注解使用。

@NacosConfigListener 注解用法介绍

Cloud Native

NacosConfig 注解作用的目标主体是字段，是将目标字段的属性直接变更，当我们需要对配置的内容进行二次处理时，比如当某个属性发生变化时触动程序执行一个业务动作或者在变更后的配置基础上在代码中做二次处理时，NacosConfig 注解将无法胜任，此时可以使用 NacosConfigListener 注解来实现这个诉求，该注解作用于 SpringBean 的方法上，支持指定配置发生变化时将配置内容以方法参数形式回调指定方法。和 NacosConfig 注解相似，方法参数支持基础类型，Properties，数组，集合以及自定义 JavaBean。

如果希望在 Bean 初始化时接受初始回调，可以设置 initNotify=true，默认为 false。

以下示例中的回调方法名均为示例，方法名可以自定义。

用法示例

1. String 参数方法接收原生配置内容

@NacosConfigListener(dataId = "myobjectArray.json", group = "default")

private void fullContentChanged(String content) {

    System.out.println("receive ：" + content);

}

当 dataId = "myobjectArray.json", group = "default" 的配置发生变更时，将完整内容以 content 参数回调 fullContentChanged 方法。

2. 基础类型参数方法接受指定 key 值内容

@NacosConfigListener(dataId = "SampleApp.application.properties", group = "default",key="score")

private void scoreChanged(int score) {

    System.out.println("receive ：" + score);

}

当 dataId = "SampleApp.application.properties", group = "default" 的配置中key="score" 的属性值发生变更时，将对应属性值 score 参数回调 scoreChanged 方法。

支持 int, long,float,double,boolean 5 种基础类型。

3. 基础类型数组参数方法接受 JSON 格式配置内容

@NacosConfigListener(dataId = "scoresArray.json", group = "default")

private void scoresChanged(int[] scores) {

    System.out.println("receive ：" + scores);

}

当 dataId = "scoresArray.json", group = "default" 的 JSON 格式配置发生变更时，将配置内容反序列化为基础类型数组对象以 scores 参数回调 scoresChanged 方法。

支持 int, long,float,double,boolean 5 种基础类型数组。

配置 dataId 必须以 .json 结尾，并且配置内容必须为 json 数组格式。

4. Properties 参数方法接受属性参数

@NacosConfigListener(dataId = "SampleApp.application.properties", group = "default")

private void propertiesChanged(Properties properties) {

    System.out.println("receive ：" + properties);

}

当 dataId = "SampleApp.application.properties", group = "default" 的 properties 格式配置发生变更时，将配置内容解析为Properties对象以 Properties 类型参数回调 propertiesChanged 方法。

5. 自定义 Java Bean 参数

    @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);

    }

当指定配置内容发生变更时，以对象，对象数组，对象列表，对象模式类型回调方法。

支持自定义数组，集合类型，自动根据指定泛型进行反序列化。

@NacosConfigKeysListener 注解用法介绍

Cloud Native

该注解支持 propertie 及 yaml 格式配置中指定 keys 发生变更时，通过 ConfigChangeEvent 参数接受指定 keys 变更前后的内容。

通过 interestedKeys 指定监听的 keys 集合，通过 interestedKeyPrefixes 指定需要监听的 key 前缀集合，如果符合任意任一条件的 key 发生变化时都会触发回调。

用法示例

@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 结尾。

结语

Cloud Native

当前 Spring Cloud Alibaba 在全系列版本（包括 2.2.x，2021.x，2022.x，2023.x）中都已经正式发布新版本支持以上注解。

• 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 配置模块进行了重构，单独抽取了 spring-alibaba-nacos-config 模块，该模块不依赖 SpringCloud 框架，所以基于 SpringBoot3 的应用通过单独引入 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:{此处按需替换为需导入的nacos dataId}?group={此处按需替换为需导入的nacos group}&refreshEnabled=true

spring.nacos.config.server-addr={此处按需替换为nacos的serverAddr}

spring.nacos.config.namespace={此处按需替换为nacos的命名空间，public请填空}







//其他参数请参照sca官方文档，将spring.cloud.nacos前缀替换为spring.nacos即可,本文中的注解用法完全一致相关链接：[1] Nacos 官网https://nacos.io[2] Nacos Github 主仓库https://github.com/alibaba/nacos[3] 生态组仓库https://github.com/nacos-group[4] Spring Cloud Alibabahttps://sca.aliyun.com/docs/2023/user-guide/nacos/quick-start/Nacos 多语言生态仓库：[1] Nacos-GO-SDKhttps://github.com/nacos-group/nacos-sdk-go[2] Nacos-Python-SDKhttps://github.com/nacos-group/nacos-sdk-python[3] Nacos-Rust-SDKhttps://github.com/nacos-group/nacos-sdk-rust[4] Nacos C# SDKhttps://github.com/nacos-group/nacos-sdk-csharp[5] Nacos C++ SDKhttps://github.com/nacos-group/nacos-sdk-cpp[6] Nacos PHP-SDKhttps://github.com/nacos-group/nacos-sdk-php[7] Rust Nacos Serverhttps://github.com/nacos-group/r-nacos