【Nacos 学习笔记】01 - 快速入门

---

前言

学习任何技术请先熟读官方文档，本篇仅仅是一个快速开始，版本锁定在 2.1.0

官方网站：https://nacos.io/zh-cn/docs/what-is-nacos.html

一、下载和单机启动

章节地址: https://github.com/alibaba/nacos/releases

---

方式一：下载源码构建

git clone https://github.com/alibaba/nacos.git
cd nacos/
mvn -Prelease-nacos -Dmaven.test.skip=true clean install -U  
ls -al distribution/target/

// change the $version to your actual path
cd distribution/target/nacos-server-$version/nacos/bin

网络原因卡顿的话，可以使用gitee地址
码云仓库地址： https://gitee.com/mirrors/Nacos
注意，windows使用powershell模式会构建失败，请用cmd

---

方式二：下载文本版本解压后启动
下载地址: https://github.com/alibaba/nacos/releases
2.1.0：https://github.com/alibaba/nacos/releases/download/2.1.0/nacos-server-2.1.0.zip

---

单机启动命令, windows 使用对应 .cmd

sh startup.sh -m standalone

---

windows下启动示例:

输入地址：http://192.168.181.1:8848/nacos/index.htm
帐号密码默认 nacos

集群部署：https://nacos.io/zh-cn/docs/cluster-mode-quick-start.html

---

二、Java的SDK：nacos-client

---

nacos 服务端默认不开启鉴权，权限认证章节参考官网：https://nacos.io/zh-cn/docs/auth.html

---

nacos 默认 namespace 是 public，nacos 自带的鉴权体系也是粒度到namespace的读写上
一般来说，如果小规模应用，可以使用 namespace 区分多套环境(dev test prew)
大规模应用，最好不同环境单独部署nacos集群，namespace用来区分租户（项目组or团队or应用等）

---

下文示例代码若无特殊说明，均为未开启鉴权、默认 public 的 namespace 的情况

---

1. 导包

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-client</artifactId>
    <version>1.1.0</version>
</dependency>

---

2. config 相关 API

更多配置参数参考 https://nacos.io/zh-cn/docs/system-configurations.html

	Properties properties = new Properties();
	properties.put(PropertyKeyConst.SERVER_ADDR, "127.0.0.1:8848");
	// properties.put(PropertyKeyConst.NAMESPACE, "name1");
	// properties.put(PropertyKeyConst.USERNAME, "ZT-group-app");
	// properties.put(PropertyKeyConst.PASSWORD, "password");
	ConfigService configService = NacosFactory.createConfigService(properties);
	String dataId = "my-config";
	// 发布配置，注意 第二个参数 group 传null或空串，就会默认为 DEFAULT_GROUP
	configService.publishConfig(dataId, null, "config content xxxx", ConfigType.TEXT.getType());
	// 获取配置, 此处可能立马获取返回的是null，后续章节分析
	System.out.println("读取配置：" + configService.getConfig(dataId, null,5000));

	// 监听器相关API
	Listener listener = new Listener() {
	    @Override
	    public Executor getExecutor() {
		// 返回null时使用内置的线程池执行，内置线程池最多5个，如果满了则占用拉取线程执行
		System.out.println("==== 获取 executor=====");
		return null;
	    }
	    @Override
	    @SneakyThrows
	    public void receiveConfigInfo(String configInfo) {
		// 接受消息的处理方法
		System.out.println("收到消息变更===》" + configInfo);
	    }
	};
	// 添加监听, 此时，可能会收到上一步发送出来的消息
	configService.addListener(dataId, null, listener);
	
	// 测试内容变更
	configService.publishConfig(dataId, null, "change content xxxx");
	Thread.sleep(5000);
	// 此处每隔开1s变更一次配置，发现监听线程每到执行周期时只会拉取到最新的配置
	for (int i = 0; i < 10; i++) {
	    System.out.println("== 发送消息 " + i + " ====");
	    configService.publishConfig(dataId, null, "change content to:" + i);
	    Thread.sleep(1000);
	}
	Thread.sleep(1000 * 10);
	// 删除配置，发现监听会接受到一条 null
	configService.removeConfig(dataId, null);
	Thread.sleep(5000);
	// 移除监听
	configService.removeListener(dataId, null, listener);

// 获取配置
String getConfig(String dataId, String group, long timeoutMs) throws NacosException;

// 发布配置
boolean publishConfig(String dataId, String group, String content, String type) throws NacosException;

// 删除配置
boolean removeConfig(String dataId, String group) throws NacosException;

// 设置监听
void addListener(String dataId, String group, Listener listener);

// 移除监听
void removeListener(String dataId, String group, Listener listener);

参数	含义	其它
dataId	ID，同一namespace + group下需保证唯一，不超过256，允许(. : - _)四种特殊字符	Spring Cloud 项目中设置默认为 ${prefix}-${spring.profiles.active}.${file-extension}
group	分组名，不超过128，默认为 DEFAULT_GROUP	-
timeout	超时时间，单位ms	推荐 3000 - 5000

---

3. 服务发现相关 API

// 注册实例
void registerInstance(String serviceName, String ip, int port) throws NacosException;

void registerInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;

void registerInstance(String serviceName, Instance instance) throws NacosException;

// 注销实例
void deregisterInstance(String serviceName, String ip, int port) throws NacosException;

void deregisterInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;

// 获取全部实例
List<Instance> getAllInstances(String serviceName) throws NacosException;

List<Instance> getAllInstances(String serviceName, List<String> clusters) throws NacosException;

// 获取健康或不健康实例列表
List<Instance> selectInstances(String serviceName, boolean healthy) throws NacosException;

List<Instance> selectInstances(String serviceName, List<String> clusters, boolean healthy) throws NacosException;

// 根据负载均衡算法随机获取一个健康实例
Instance selectOneHealthyInstance(String serviceName) throws NacosException;

Instance selectOneHealthyInstance(String serviceName, List<String> clusters) throws NacosException;

// 监听服务下的实例列表变化
void subscribe(String serviceName, EventListener listener) throws NacosException;

void subscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;

// 取消监听
void unsubscribe(String serviceName, EventListener listener) throws NacosException;

void unsubscribe(String serviceName, List<String> clusters, EventListener listener) throws NacosException;

详细说明参考官网文档 https://nacos.io/zh-cn/docs/sdk.html

---

三、nacos-spring-project

github地址: https://github.com/nacos-group/nacos-spring-project

注意 Nacos 的 Spring Cloud 集成包并未引入此包，本章节也不详细说明

1. 导包

本篇文章写作时，最新版本只有 1.1.1，且依赖的nacos版本还在 1.4.1, 故手动引入 2.1.0。根据官网 Nacos 2.0.0 兼容性，客户端 SDK 完全兼容，可以不担心发生其他大修改情况。

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-spring-context</artifactId>
    <version>1.1.1</version>
    <exclusions>
    	<exclusion>
        	<groupId>com.alibaba.nacos</groupId>
        	<artifactId>nacos-client</artifactId>
    	</exclusion>
	</exclusions>
</dependency>

<dependency>
	<groupId>com.alibaba.nacos</groupId>
	<artifactId>nacos-client</artifactId>
	<version>2.1.0</version>
</dependency>

2. 核心功能

官网参考： https://nacos.io/zh-cn/docs/nacos-spring.html

---

四. nacos-spring-boot-project

https://github.com/nacos-group/nacos-spring-boot-project
注意 Nacos 的 Spring Cloud 集成包并未引入此包，本章节也不详细说明

1. 导包

<dependency>
    <groupId>com.alibaba.boot</groupId>
    <artifactId>nacos-config-spring-boot-starter</artifactId>
    <!-- 写作时是该最新beta版本支持 2.1.0 -->
    <version>0.2.11-beta</version>
</dependency>

2. 使用

https://nacos.io/zh-cn/docs/quick-start-spring-boot.html

---

五. for spring-cloud-alibaba

https://github.com/alibaba/spring-cloud-alibaba

基于版本 spring-cloud-alibaba 2.2.7.RELEASE
对应 cloud 版本 2.2.9.RELEASE
boot版本 2.3.12.RELEASE

1. 创建pom

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.3.12.RELEASE</version>
        <relativePath/>
    </parent>

    <groupId>com.mcx.lab</groupId>
    <artifactId>nacos-spring-cloud</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <java.version>11</java.version>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
    </properties>


    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.alibaba.cloud</groupId>
                <artifactId>spring-cloud-alibaba-dependencies</artifactId>
                <version>2.2.7.RELEASE</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <dependency>
                <groupId>com.alibaba.nacos</groupId>
                <artifactId>nacos-client</artifactId>
                <version>2.1.0</version>
            </dependency>

        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

---

2. 代码

• 启动类:

@SpringBootApplication
@EnableDiscoveryClient
public class ApplicationRunner {
    public static void main(String[] args) {
		SpringApplication.run(ApplicationRunner.class, args);
    }
}

---

• 测试类

@RestController
@RefreshScope
public class TestController {

   @Value("${config.name:}")
   private String name;

   @GetMapping("/name")
   public String getName() {
   	return name;
   }

   @PostConstruct
   public void PostConstruct() {
   	System.out.println("TestController===PostConstruct");
   }
}

加上 @RefreshScope 实现配置变更刷新能力，它是SpringCloud中提供的能力。
简单理解核心过程：

1. nacos 的 NacosContextRefresher.registerNacosListener 方法注册了nacos的配置变更监听，发出RefreshEvent
2. RefreshEventListener.handle 处理刷新事件， 调用到 ContextRefresher.refresh()
3. 其中的 addConfigFilesToEnvironment() 方法通过SpringApplicationBuilder.run() 触发了 PropertySourceBootstrapConfiguration.initialize()，从而又触发了 NacosPropertySourceLocator 从新重远程加载数据并更新到 environment
4. 然后调用 RefreshScope.refreshAll() 清空缓存。因为@RefreshScope的bean是一个代理对象，也就意味着，下次调用时将触发重新生成的bean（此时使用 environment 中的新值）并放入缓存。

参考文章：
https://docs.spring.io/spring-cloud-commons/docs/2.2.9.RELEASE/reference/html/#refresh-scope
https://zhuanlan.zhihu.com/p/52577840

---

• bootstrap.properties文件

注意下面操作已经在nacos控制台配置了相关的 namespace 以及相关账号密码角色
以下示例采用这种隔离方案：

1. 不同应用组（项目组）单独分配一个 namespace
2. 应用连接nacos使用对应空间的读权限账号
3. 本地、dev、test 等都使用一个nacos集群，pro 环境单独集群
4. 注册中心按照环境分配 namespace，如开发环境的服务发现都连接到 dev 这个namesapace

spring.application.name=nacos-cloud-lab
spring.cloud.nacos.server-addr=127.0.0.1:8848

spring.profiles.active=local

# 命名空间ID
spring.cloud.nacos.config.namespace=79220a92-9258-400f-b121-7c71a0f3e8ff
spring.cloud.nacos.config.username=nacos-cloud-lab-read
spring.cloud.nacos.config.password=nacos

1. nacos 默认启动读取远程配置文件 ${spring.application.name}-${spring.profiles.active}.${spring.cloud.nacos.config.file-extension}，此处即读取 nacos-cloud-lab-local.properties
2. 远程文件配置如下，定义 spring.cloud.config.overrideNone=true 支持本地配置文件可以覆盖远程配置。这样，本地设置一个 application-local 的配置文件并设置不提交git，就可以让个人电脑启动使用自己的配置

# local环境设置本地变量可覆盖远程（实际是调整资源的顺序）
spring.cloud.config.overrideNone=true

# discovery 配置

# 使用dev环境的服务注册专用namespace
spring.cloud.nacos.discovery.namespace=dev-discovery-namespace
spring.cloud.nacos.discovery.username=dev-discovery-namespace
spring.cloud.nacos.discovery.password=nacos
# 只订阅不注册
spring.cloud.nacos.discovery.registerEnabled=false

# 业务参数配置
config.name=远程配置的name

3. 可以自定义加载名以及附加文件(ext-config、shared-dataids、refreshable-dataids等)，本章不说明了，详细可以拉下源码查看 nacos-config.adoc 文件
4. 构建环境可以通过命令行参数 --spring.profiles.active=xxx 、 spring.cloud.nacos.server-addr=xxx 去更改一些bootstrap的配置
5. 详细配置可以参考 NacosConfigProperties NacosDiscoveryProperties

---

• 本地配置文件示例

spring.cloud.nacos.discovery.service=${spring.application.name}-mine
spring.cloud.nacos.discovery.registerEnabled=true
config.name=本地配置的name

启动完成后，调用 http://127.0.0.1:8080/name 返回本地配置的name
本地配置去掉后重启，返回远程的name
修改远程配置，请求返回更新后的数。此时观察控制台，请求接口时会打印 TestController===PostConstruct, 验证了 spring cloud freshscope 的原理

---