版本：用户文档

Nacos 融合 Spring，成为注册配置中心

本文主要面向 Spring 的使用者，通过两个示例来介绍如何使用 Nacos 来实现分布式环境下的配置管理和服务发现。

关于 Nacos Spring 的详细文档请参看：nacos-spring-project。

通过 Nacos server 和 Nacos Spring 配置管理模块，实现配置的动态变更；
通过 Nacos server 和 Nacos Spring 服务发现模块，实现服务的注册与发现。

前提条件

您需要先下载 Nacos 并启动 Nacos server。操作步骤参见 Nacos 快速入门。

启动配置管理

启动了 Nacos server 后，您就可以参考以下示例代码，为您的 Spring 应用启动 Nacos 配置管理服务了。完整示例代码请参考：nacos-spring-config-example

添加依赖。

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-spring-context</artifactId>
    <version>${latest.version}</version>
</dependency>

最新版本可以在 maven 仓库，如 "mvnrepository.com" 中获取。

添加 @EnableNacosConfig 注解启用 Nacos Spring 的配置管理服务。以下示例中，我们使用 @NacosPropertySource 加载了 dataId 为 example 的配置源，并开启自动更新：

@Configuration
@EnableNacosConfig(globalProperties = @NacosProperties(serverAddr = "127.0.0.1:8848"))
@NacosPropertySource(dataId = "example", autoRefreshed = true)
public class NacosConfiguration {

}

通过 Nacos 的 @NacosValue 注解设置属性值。

@Controller
@RequestMapping("config")
public class ConfigController {

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

    @RequestMapping(value = "/get", method = GET)
    @ResponseBody
    public boolean get() {
        return useLocalCache;
    }
}

启动 Tomcat，调用 curl http://localhost:8080/config/get尝试获取配置信息。由于此时还未发布过配置，所以返回内容是 false。
通过调用 Nacos Open API 向 Nacos Server 发布配置：dataId 为example，内容为useLocalCache=true

curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=example&group=DEFAULT_GROUP&content=useLocalCache=true"

再次访问 http://localhost:8080/config/get，此时返回内容为true，说明程序中的useLocalCache值已经被动态更新了。

启动服务发现

本节演示如何在您的 Spring 项目中启动 Nacos 的服务发现功能。完整示例代码请参考：nacos-spring-discovery-example

添加依赖。

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-spring-context</artifactId>
    <version>${latest.version}</version>
</dependency>

最新版本可以在 maven 仓库，如 "mvnrepository.com" 中获取。

通过添加 @EnableNacosDiscovery 注解开启 Nacos Spring 的服务发现功能：

@Configuration
@EnableNacosDiscovery(globalProperties = @NacosProperties(serverAddr = "127.0.0.1:8848"))
public class NacosConfiguration {

}

使用 @NacosInjected 注入 Nacos 的 NamingService 实例：

@Controller
@RequestMapping("discovery")
public class DiscoveryController {

    @NacosInjected
    private NamingService namingService;

    @RequestMapping(value = "/get", method = GET)
    @ResponseBody
    public List<Instance> get(@RequestParam String serviceName) throws NacosException {
        return namingService.getAllInstances(serviceName);
    }
}

启动 Tomcat，调用 curl http://localhost:8080/discovery/get?serviceName=example，此时返回为空 JSON 数组[]。
通过调用 Nacos Open API 向 Nacos server 注册一个名称为 example 服务。

curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?serviceName=example&ip=127.0.0.1&port=8080'

再次访问 curl http://localhost:8080/discovery/get?serviceName=example，此时返回内容为：

[
  {
    "instanceId": "127.0.0.1#8080#DEFAULT#example",
    "ip": "127.0.0.1",
    "port": 8080,
    "weight": 1.0,
    "healthy": true,
    "cluster": {
      "serviceName": null,
      "name": "",
      "healthChecker": {
        "type": "TCP"
      },
      "defaultPort": 80,
      "defaultCheckPort": 80,
      "useIPPort4Check": true,
      "metadata": {}
    },
    "service": null,
    "metadata": {}
  }
]

Nacos Spring关键特性

下文将介绍 nacos-spring-context 中的一些关键的特性：

注解驱动
依赖注入
外部化配置
事件驱动

1. 注解驱动

1.1. 启用 Nacos

@EnableNacos是一个模块驱动的注解，它支持 Nacos Spring 的所有功能，包括服务发现和配置管理。它等于 @EnableNacosDiscovery 加上 @EnableNacosConfig，可以单独配置并在不同场景中使用。

1.2. 配置监听

假设在 Nacos 服务中有一个配置，其 dataId 是 "testDataId" 而 groupId 是默认组（"DEFAULT_GROUP"）。现在，您可以使用 ConfigService#publishConfig 方法更改其内容：

@NacosInjected
private ConfigService configService;

@Test
public void testPublishConfig() throws NacosException {
    configService.publishConfig(DATA_ID, DEFAULT_GROUP, "9527");
}

然后您可以添加一个监听器，它将监听配置的变化。您可以通过在 Spring Bean 中添加配置变更监听器方法来执行此操作：

@NacosConfigListener(dataId = DATA_ID)
public void onMessage(String config) {
    assertEquals("mercyblitz", config); // asserts true
}

下面的代码具有相同的效果：

configService.addListener(DATA_ID, DEFAULT_GROUP, new AbstractListener() {
    @Override
    public void receiveConfigInfo(String config) {
        assertEquals("9527", config); // asserts true
    }
});

另外，@NacosConfigListener 支持更丰富的类型转换。

请参看： Simple Sample of @NacosConfigListener

1.2.1. 类型

@NacosConfigListener 的类型转换包括内置和自定义实现。默认情况下，内置类型转换基于 Spring DefaultFormattingConversionService，这意味着它包好了大多数情况以及 Spring 框架更高级版本的丰富功能。

例如，前面示例中的内容 "9527" 也可以通过带 "int" 或 "Integer" 参数的方法进行监听：:

@NacosConfigListener(dataId = DATA_ID)
public void onInteger(Integer value) {
    assertEquals(Integer.valueOf(9527), value); // asserts true
}

@NacosConfigListener(dataId = DATA_ID)
public void onInt(int value) {
    assertEquals(9527, value); // asserts true
}

当然, nacos-spring-context 为开发人员提供弹性扩展。如果定义名为nacosConfigConversionService的Spring Bean，其类型为ConversionService，则将忽略DefaultFormattingConversionService。此外，您可以自定义NacosConfigConverter接口的实现，以指定类型转换的侦听器方法：

public class UserNacosConfigConverter implements NacosConfigConverter<User> {

    @Override
    public boolean canConvert(Class<User> targetType) {
        return true;
    }

    @Override
    public User convert(String source) {
        return JSON.parseObject(source, User.class);
    }
}

UserNacosConfigConverter 类绑定在 @NacosConfigListener.converter() 属性上，如下:

@NacosInjected
private ConfigService configService;

@Test
public void testPublishUser() throws NacosException {
    configService.publishConfig("user", DEFAULT_GROUP, "{\"id\":1,\"name\":\"mercyblitz\"}");
}

@NacosConfigListener(dataId = "user", converter = UserNacosConfigConverter.class)
public void onUser(User user) {
    assertEquals(Long.valueOf(1L), user.getId()); 
    assertEquals("mercyblitz", user.getName());
}

请参看：Type Conversion Sample of @NacosConfigListener

1.2.2. 超时时间

由于运行自定义的 NacosConfigConverter 可能需要一些时间，因此您可以在 @NacosConfigListener.timeout() 属性中设置最大执行时间，以防止它阻塞其他侦听器：

@Configuration
public class Listeners {

    private Integer integerValue;

    private Double doubleValue;

    @NacosConfigListener(dataId = DATA_ID, timeout = 50)
    public void onInteger(Integer value) throws Exception {
        Thread.sleep(100); // timeout of execution
        this.integerValue = value;
    }

    @NacosConfigListener(dataId = DATA_ID, timeout = 200)
    public void onDouble(Double value) throws Exception {
        Thread.sleep(100); // normal execution
        this.doubleValue = value;
    }

    public Integer getIntegerValue() {
        return integerValue;
    }

    public Double getDoubleValue() {
        return doubleValue;
    }
}

Listeners Bean 的 integerValue 总是为null，不会改变。因此，以下断言都将是 true：

@Autowired
private Listeners listeners;

@Test
public void testPublishConfig() throws NacosException {
    configService.publishConfig(DATA_ID, DEFAULT_GROUP, "9527");
    assertNull(listeners.getIntegerValue()); // asserts true
    assertEquals(Double.valueOf(9527), listeners.getDoubleValue());   // asserts true
}

请参看：Timeout Sample of @NacosConfigListener

1.3. 全局和自定义 Nacos 属性

globalProperties 是任何 @EnableNacos，@EnableNacosDiscovery 或 @EnableNacosConfig 中的必选属性，其类型为 @NacosProperties。

globalProperties 将初始化为其他注解或组件的 "全局 Nacos 属性"，例如：@NacosInjected。

换句话说，全局 Nacos 属性 定义全局和默认属性。它设置为具有最低优先级，并且也可以被覆盖。覆盖优先级如下表所示：

Precedence Order	Nacos Annotation	Required
1	`*.properties()`	N
2	`@EnableNacosConfig.globalProperties()` or `@EnableNacosDiscovery.globalProperties()`	Y
3	`@EnableNacos.globalProperties()`	Y

*.properties() 定义来自以下之一的自定义 Nacos 属性：

@NacosInjected.properties()
@NacosConfigListener.properties()
@NacosPropertySource.properties()
@NacosConfigurationProperties.properties()

自定义的 Nacos 属性也由 @NacosProperties 配置。不过，它们是可选的，用于在特殊情况下覆盖全局 Nacos 属性。如果没有定义，Nacos 属性将尝试从 @EnableNacosConfig.globalProperties() 或 @EnableNacosDiscovery.globalProperties() 或 @EnableNacos.globalProperties() 中查找属性。

1.4. `@NacosProperties`

@NacosProperties 是全局和自定义 Nacos 属性的统一注解。它充当Java Properties 和 NacosFactory 类之间的中介。NacosFactory 负责创建 ConfigService 或 NamingService 实例。

@NacosProperties 的属性完全支持占位符，它的源是Spring Environment 抽象中的各种 PropertySource，通常是Java System Properties 和操作系统环境变量。所有占位符的前缀都是 nacos.。@NacosProperties 和 Nacos 属性的属性之间的映射如下所示：

Attribute	Property	Placeholder	Required
`endpoint()`	`endpoint`	`${nacos.endpoint:}`	N
`namespace()`	`namespace`	`${nacos.namespace:}`	N
`accessKey()`	`access-key`	`${nacos.access-key:}`	N
`secretKey()`	`secret-key`	`${nacos.secret-key:}`	N
`serverAddr()`	`server-addr`	`${nacos.server-addr:}`	Y
`contextPath()`	`context-path`	`${nacos.context-path:}`	N
`clusterName()`	`cluster-name`	`${nacos.cluster-name:}`	N
`encode()`	`encode`	`${nacos.encode:UTF-8}`	N

请注意，@EnableNacosDiscovery 和 @EnableNacosConfig 之间 globalProperties() 的占位符存在一些差异：

Attribute	`@EnableNacosDiscovery`'s Placeholder	`@EnableNacosConfig`'s Placeholder
`endpoint()`	`${nacos.discovery.endpoint:${nacos.endpoint:}}`	`${nacos.config.endpoint:${nacos.endpoint:}}`
`namespace()`	`${nacos.discovery.namespace:${nacos.namespace:}}`	`${nacos.config.namespace:${nacos.namespace:}}`
`accessKey()`	`${nacos.discovery.access-key:${nacos.access-key:}}`	`${nacos.config.access-key:${nacos.access-key:}}`
`secretKey()`	`${nacos.discovery.secret-key:${nacos.secret-key:}}`	`${nacos.config.secret-key:${nacos.secret-key:}}`
`serverAddr()`	`${nacos.discovery.server-addr:${nacos.server-addr:}}`	`${nacos.config.server-addr:${nacos.server-addr:}}`
`contextPath()`	`${nacos.discovery.context-path:${nacos.context-path:}}`	`${nacos.config.context-path:${nacos.context-path:}}`
`clusterName()`	`${nacos.discovery.cluster-name:${nacos.cluster-name:}}`	`${nacos.config.cluster-name:${nacos.cluster-name:}}`
`encode()`	`${nacos.discovery.encode:${nacos.encode:UTF-8}}`	`${nacos.config.encode:${nacos.encode:UTF-8}}`

这些 @EnableNacosDiscovery 和 @EnableNacosConfig 的占位符用于隔离不同的 Nacos 服务，在大多数情况下都是不必要的。默认情况下，将使用常规占位符。

2. 依赖注入

@NacosInjected 是一个核心注解，用于在Spring Beans 中注入 ConfigService 或 NamingService 实例，并使这些实例可缓存。这意味着如果它们的 @NacosProperties 相等，则实例将是相同的，无论属性是来自全局还是自定义的 Nacos 属性：

@NacosInjected
private ConfigService configService;

@NacosInjected(properties = @NacosProperties(encode = "UTF-8"))
private ConfigService configService2;

@NacosInjected(properties = @NacosProperties(encode = "GBK"))
private ConfigService configService3;

@NacosInjected
private NamingService namingService;

@NacosInjected(properties = @NacosProperties(encode = "UTF-8"))
private NamingService namingService2;

@NacosInjected(properties = @NacosProperties(encode = "GBK"))
private NamingService namingService3;

@Test
public void testInjection() {

    Assert.assertEquals(configService, configService2);
    Assert.assertNotEquals(configService2, configService3);

    Assert.assertEquals(namingService, namingService2);
    Assert.assertNotEquals(namingService2, namingService3);
}

属性 configService 使用 @EnableNacos#globalProperties() 或 @EnableNacosConfig#globalProperties()，因为 encode 属性的默认值是 "UTF-8"，因此 configService 实例和由 @NacosProperties(encode ="UTF-8") 注解的 configService2 实例是相同的。 namingService 和 namingService2 也是如此。

值得注意的是，与 NacosFactory.createConfigService() 方法创建的 ConfigService 实例不同，@NacosInjected 注解创建的 ConfigService 实例支持 Nacos Spring 事件。例如，在增强的 ConfigService 调用 publishConfig() 方法之后会有一个 NacosConfigPublishedEvent。有关更多详细信息，请参阅"事件驱动"部分。

请参看：Dependency Injection Sample

3. 外部化配置

外部化配置是 Spring Boot 引入的概念，它允许应用程序接收外部属性源以控制运行时行为。 Nacos Server 在应用程序外部运行单独的进程以维护应用程序配置。 nacos-spring-context 提供了对象绑定，动态配置（自动刷新）等功能。

这里有 nacos-spring-context 和 Spring Stack 之间的简单比较：

Spring Stack	Nacos Spring	Highlight
`@Value`	`@NacosValue`	auto-refreshed
`@ConfigurationProperties`	`@NacosConfigurationProperties`	auto-refreshed,`@NacosProperty`,`@NacosIgnore`
`@PropertySource`	`@NacosPropertySource`	auto-refreshed, precedence order control
`@PropertySources`	`@NacosPropertySources`

请参看：Auto-Refreshed Sample of @NacosConfigurationProperties
请参看：Sample of @NacosPropertySources and @NacosPropertySource

4. 事件驱动

Nacos 事件驱动基于标准的 Spring Event / Listener 机制。 Spring 的 ApplicationEvent 是所有 Nacos Spring 事件的抽象超类：

Nacos Spring Event	Trigger
`NacosConfigPublishedEvent`	After `ConfigService.publishConfig()`
`NacosConfigReceivedEvent`	After`Listener.receiveConfigInfo()`
`NacosConfigRemovedEvent`	After `configService.removeConfig()`
`NacosConfigTimeoutEvent`	`ConfigService.getConfig()` on timeout
`NacosConfigListenerRegisteredEvent`	After `ConfigService.addListner()` or `ConfigService.removeListener()`
`NacosConfigurationPropertiesBeanBoundEvent`	After `@NacosConfigurationProperties` binding
`NacosConfigMetadataEvent`	After Nacos Config operations

请参看：Event/Listener Sample

Nacos 融合 Spring，成为注册配置中心

前提条件​

启动配置管理​

启动服务发现​

Nacos Spring关键特性

1. 注解驱动​

1.1. 启用 Nacos​

1.2. 配置监听​

1.2.1. 类型​

1.2.2. 超时时间​

1.3. 全局和自定义 Nacos 属性​

1.4. @NacosProperties​

2. 依赖注入​

3. 外部化配置​

4. 事件驱动​

相关项目