diff --git a/spring-cloud-alibaba-examples/nacos-example/nacos-config-example/readme-zh.md b/spring-cloud-alibaba-examples/nacos-example/nacos-config-example/readme-zh.md deleted file mode 100644 index 79bd246c0..000000000 --- a/spring-cloud-alibaba-examples/nacos-example/nacos-config-example/readme-zh.md +++ /dev/null @@ -1,215 +0,0 @@ -# Nacos Config Example - -## 项目说明 - -本项目演示如何使用 Nacos Config Starter 完成 Spring Cloud 应用的配置管理。 - -[Nacos](https://github.com/alibaba/Nacos) 是阿里巴巴开源的一个更易于构建云原生应用的动态服务发现、配置管理和服务管理平台。 - -## 示例 - -### 如何接入 -在启动示例进行演示之前，我们先了解一下 Spring Cloud 应用如何接入 Nacos Config。 -**注意 本章节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您无需再进行修改。** - -1. 首先，修改 pom.xml 文件，引入 Nacos Config Starter。 - - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-config - - -2. 在应用的 /src/main/resources/bootstrap.properties 配置文件中配置 Nacos Config 元数据 - - spring.application.name=nacos-config-example - spring.cloud.nacos.config.server-addr=127.0.0.1:8848 - -3. 完成上述两步后，应用会从 Nacos Config 中获取相应的配置，并添加在 Spring Environment 的 PropertySources 中。假设我们通过 Nacos 配置中心保存 Nacos 的部分配置,有以下四种例子: -- BeanAutoRefreshConfigExample: 通过将配置信息配置为bean，支持配置变自动刷新的例子 -- ConfigListenerExample: 监听配置信息的例子 -- DockingInterfaceExample: 对接 nacos 接口，通过接口完成对配置信息增删改查的例子 -- ValueAnnotationExample: 通过 @Value 注解进行配置信息获取的例子 -- SharedConfigExample: 共享配置的例子 -- ExtensionConfigExample: 扩展配置的例子 - -### 启动 Nacos Server 并添加配置 - -1. 首先需要获取 Nacos Server，支持直接下载和源码构建两种方式。**推荐使用最新版本 Nacos Server** - - 1. 直接下载：[Nacos Server 下载页](https://github.com/alibaba/nacos/releases) - 2. 源码构建：进入 Nacos [Github 项目页面](https://github.com/alibaba/nacos)，将代码 git clone 到本地自行编译打包，[参考此文档](https://nacos.io/zh-cn/docs/quick-start.html)。 - -2. 启动 Server，进入下载到本地并解压完成后的文件夹(使用源码构建的方式则进入编译打包好的文件夹)，再进去其相对文件夹 nacos/bin，并对照操作系统实际情况执行如下命令。[详情参考此文档](https://nacos.io/zh-cn/docs/quick-start.html)。 - - 1. Linux/Unix/Mac 操作系统，执行命令 `sh startup.sh -m standalone` - 2. Windows 操作系统，执行命令 `cmd startup.cmd` - -3. 在命令行执行如下命令，向 Nacos Server 中添加一条配置。 - - curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos-config-example.properties&group=DEFAULT_GROUP&content=spring.cloud.nacos.config.serverAddr=127.0.0.1:8848%0Aspring.cloud.nacos.config.prefix=PREFIX%0Aspring.cloud.nacos.config.group=GROUP%0Aspring.cloud.nacos.config.namespace=NAMESPACE" - - **注：你也可以使用其他方式添加，遵循 HTTP API 规范即可，若您使用的 Nacos 版本自带控制台，建议直接使用控制台进行配置** - - 添加的配置的详情如下 - - dataId 为 nacos-config-example.properties - group 为 DEFAULT_GROUP - - 内容如下: - - spring.cloud.nacos.config.serverAddr=127.0.0.1:8848 - spring.cloud.nacos.config.prefix=PREFIX - spring.cloud.nacos.config.group=GROUP - spring.cloud.nacos.config.namespace=NAMESPACE - -4. 添加共享配置和扩展配置 - - 共享配置: - ``` - dataId为: data-source.yaml - group 为： DEFAULT_GROUP - - 内容如下: - - spring: - datasource: - name: datasource - url: jdbc:mysql://127.0.0.1:3306/nacos?characterEncoding=UTF-8&characterSetResults=UTF-8&zeroDateTimeBehavior=convertToNull&useDynamicCharsetInfo=false&useSSL=false - username: root - password: root - driverClassName: com.mysql.jdbc.Driver - ``` - 扩展配置: - > 可以使用扩展配置覆盖共享配置中的配置 - ``` - dataId为: ext-data-source.yaml - group 为： DEFAULT_GROUP - - 内容如下: - - spring: - datasource: - username: ext-root - password: ext-root - ``` - -### 应用启动 - -1. 增加配置，在应用的 /src/main/resources/application.properties 中添加基本配置信息 - - server.port=18084 - management.endpoints.web.exposure.include=* - - -2. 启动应用，支持 IDE 直接启动和编译打包后启动。 - - 1. IDE直接启动：找到主类 `Application`，执行 main 方法启动应用。 - 2. 打包编译后启动：首先执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar nacos-config-example.jar`启动应用。 - -### 验证 - -#### 验证自动注入 -在浏览器地址栏输入 `http://127.0.0.1:18084/nacos/bean`，并点击调转，可以看到成功从 Nacos Config Server 中获取了数据。 - -![get](https://tva1.sinaimg.cn/large/e6c9d24ely1h2gbowleyrj20o40bo753.jpg) - -#### 验证动态刷新 -1. 执行如下命令，修改 Nacos Server 端的配置数据 - - curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos-config-example.properties&group=DEFAULT_GROUP&content=spring.cloud.nacos.config.serveraddr=127.0.0.1:8848%0Aspring.cloud.nacos.config.prefix=PREFIX%0Aspring.cloud.nacos.config.group=DEFAULT_GROUP%0Aspring.cloud.nacos.config.namespace=NAMESPACE" - -2. 在浏览器地址栏输入 `http://127.0.0.1:18084/nacos/bean`，并点击调转，可以看到应用从 Nacos Server 中获取了最新的数据，group 变成了 DEFAULT_GROUP。 - -![refresh](https://tva1.sinaimg.cn/large/e6c9d24ely1h2gbpram9rj20nq0ccmxz.jpg) - - -## 原理 - - -### Nacos Config 数据结构 - -Nacos Config 主要通过 dataId 和 group 来唯一确定一条配置，我们假定你已经了解此背景。如果不了解，请参考 [Nacos 文档](https://nacos.io/zh-cn/docs/concepts.html)。 - -Nacos Client 从 Nacos Server 端获取数据时，调用的是此接口 `ConfigService.getConfig(String dataId, String group, long timeoutMs)`。 - - -### Spring Cloud 应用获取数据 - -#### dataID - -在 Nacos Config Starter 中，dataId 的拼接格式如下 - - ${prefix} - ${spring.profiles.active} . ${file-extension} - -* `prefix` 默认为 `spring.application.name` 的值，也可以通过配置项 `spring.cloud.nacos.config.prefix`来配置。 - -* `spring.profiles.active` 即为当前环境对应的 profile，详情可以参考 [Spring Boot文档](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-profiles.html#boot-features-profiles) - - **注意，当 active profile 为空时，对应的连接符 `-` 也将不存在，dataId 的拼接格式变成 `${prefix}`.`${file-extension}`** - -* `file-extension` 为配置内容的数据格式，可以通过配置项 `spring.cloud.nacos.config.file-extension`来配置。 -目前只支持 `properties` 类型。 - -#### group -* `group` 默认为 `DEFAULT_GROUP`，可以通过 `spring.cloud.nacos.config.group` 配置。 - - -### 自动注入 -Nacos Config Starter 实现了 `org.springframework.cloud.bootstrap.config.PropertySourceLocator`接口，并将优先级设置成了最高。 - -在 Spring Cloud 应用启动阶段，会主动从 Nacos Server 端获取对应的数据，并将获取到的数据转换成 PropertySource 且注入到 Environment 的 PropertySources 属性中，所以使用 @Value 注解也能直接获取 Nacos Server 端配置的内容。 - -### 动态刷新 - -Nacos Config Starter 默认为所有获取数据成功的 Nacos 的配置项添加了监听功能，在监听到服务端配置发生变化时会实时触发 `org.springframework.cloud.context.refresh.ContextRefresher` 的 refresh 方法 。 - -如果需要对 Bean 进行动态刷新，请参照 Spring 和 Spring Cloud 规范。推荐给类添加 `@RefreshScope` 或 `@ConfigurationProperties ` 注解， - -更多详情请参考 [ContextRefresher Java Doc](http://static.javadoc.io/org.springframework.cloud/spring-cloud-context/2.0.0.RELEASE/org/springframework/cloud/context/refresh/ContextRefresher.html)。 - - - - -## Endpoint 信息查看 - -Spring Boot 应用支持通过 Endpoint 来暴露相关信息，Nacos Config Starter 也支持这一点。 - -在使用之前需要在 maven 中添加 `spring-boot-starter-actuator`依赖，并在配置中允许 Endpoints 的访问。 - -* Spring Boot 1.x 中添加配置 management.security.enabled=false -* Spring Boot 2.x 中添加配置 management.endpoints.web.exposure.include=* - -Spring Boot 1.x 可以通过访问 http://127.0.0.1:18084/nacos_config 来查看 Nacos Endpoint 的信息。 - -Spring Boot 2.x 可以通过访问 http://127.0.0.1:18084/actuator/nacosconfig 来访问。 - -![actuator](https://cdn.nlark.com/lark/0/2018/png/54319/1536986344822-279e1edc-ebca-4201-8362-0ddeff240b85.png) - -如上图所示，Sources 表示此客户端从哪些 Nacos Config 配置项中获取了信息，RefreshHistory 表示动态刷新的历史记录，最多保存20条，NacosConfigProperties 则为 Nacos Config Starter 本身的配置。 - -## More - -#### 更多配置项 -配置项|key|默认值|说明 -----|----|-----|----- -服务端地址|spring.cloud.nacos.config.server-addr||服务器ip和端口 -DataId前缀|spring.cloud.nacos.config.prefix|${spring.application.name}|DataId的前缀，默认值为应用名称 -Group|spring.cloud.nacos.config.group|DEFAULT_GROUP| -DataId后缀及内容文件格式|spring.cloud.nacos.config.file-extension|properties|DataId的后缀，同时也是配置内容的文件格式，目前只支持 properties -配置内容的编码方式|spring.cloud.nacos.config.encode|UTF-8|配置的编码 -获取配置的超时时间|spring.cloud.nacos.config.timeout|3000|单位为 ms -配置的命名空间|spring.cloud.nacos.config.namespace||常用场景之一是不同环境的配置的区分隔离，例如开发测试环境和生产环境的资源隔离等。 -AccessKey|spring.cloud.nacos.config.access-key|| -SecretKey|spring.cloud.nacos.config.secret-key|| -相对路径|spring.cloud.nacos.config.context-path||服务端 API 的相对路径 -接入点|spring.cloud.nacos.config.endpoint||地域的某个服务的入口域名，通过此域名可以动态地拿到服务端地址 -是否开启监听和自动刷新|spring.cloud.nacos.config.refresh-enabled|true| -集群服务名|spring.cloud.nacos.config.cluster-name|| - - - -#### 更多介绍 -Nacos为用户提供包括动态服务发现，配置管理，服务管理等服务基础设施，帮助用户更灵活，更轻松地构建，交付和管理他们的微服务平台，基于Nacos, 用户可以更快速地构建以“服务”为中心的现代云原生应用。Nacos可以和Spring Cloud、Kubernetes/CNCF、Dubbo 等微服务生态无缝融合，为用户提供更卓越的体验。更多 Nacos 相关的信息，请参考 [Nacos 项目](https://github.com/alibaba/Nacos)。 - -如果您对 Spring Cloud Nacos Config Starter 有任何建议或想法，欢迎在 issue 中或者通过其他社区渠道向我们提出。 - diff --git a/spring-cloud-alibaba-examples/nacos-example/nacos-config-example/readme.md b/spring-cloud-alibaba-examples/nacos-example/nacos-config-example/readme.md deleted file mode 100644 index bbaa43138..000000000 --- a/spring-cloud-alibaba-examples/nacos-example/nacos-config-example/readme.md +++ /dev/null @@ -1,222 +0,0 @@ -# Nacos Config Example - -## Project Instruction - -This example illustrates how to use Nacos Config Starter implement externalized configuration for Spring Cloud applications. - -[Nacos](https://github.com/alibaba/Nacos) an easy-to-use dynamic service discovery, configuration and service management platform for building cloud native applications. - -## Demo - -### Connect to Nacos Config -Before we start the demo, let's learn how to connect Nacos Config to a Spring Cloud application. **Note: This section is to show you how to connect to Nacos Config. The configurations have been completed in the following example, so you don't need to modify the code anymore.** - - -1. Add dependency spring-cloud-starter-alibaba-nacos-config in the pom.xml file in your Spring Cloud project. - - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-config - - -2. Add Nacos config metadata configurations to file /src/main/resources/bootstrap.properties - - spring.application.name=nacos-config-example - spring.cloud.nacos.config.server-addr=127.0.0.1:8848 - -3. After completing the above two steps, the application will obtain the corresponding configuration from Nacos Config and add it to the PropertySources of Spring Environment. Suppose we save part of the configuration of Nacos through the Nacos configuration center, there are the following four examples: -- BeanAutoRefreshConfigExample: An example that supports automatic refresh of configuration changes by configuring configuration information as beans -- ConfigListenerExample: Example of listening configuration information -- DockingInterfaceExample: An example of docking the nacos interface and completing the addition, deletion, modification and checking of configuration information through the interface -- ValueAnnotationExample: An example of obtaining configuration information through @Value annotation -- SharedConfigExample: Example of shared configuration -- ExtensionConfigExample: Example of extended configuration - -### Start Nacos Server - -1. Install Nacos Server by downloading or build from source code.**Recommended latest version Nacos Server** - - 1. Download: Download Nacos Server [download page](https://github.com/alibaba/nacos/releases) - 2. Build from source code: Get source code by git clone git@github.com:alibaba/Nacos.git from GitHub Nacos and build your code. See [build reference](https://nacos.io/en-us/docs/quick-start.html) for details. - -2. Unzip the downloaded file and go to the nacos/bin folder(), And according to the actual situation of the operating system, execute the following command。[see reference for more detail](https://nacos.io/en-us/docs/quick-start.html)。 - - 1. Linux/Unix/Mac , execute `sh startup.sh -m standalone` - 2. Windows , execute `cmd startup.cmd -m standalone` - -3. Execute the following command to add a configuration to Nacos Server. - - curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos-config-example.properties&group=DEFAULT_GROUP&content=spring.cloud.nacos.config.serverAddr=127.0.0.1:8848%0Aspring.cloud.nacos.config.prefix=PREFIX%0Aspring.cloud.nacos.config.group=GROUP%0Aspring.cloud.nacos.config.namespace=NAMESPACE" - - **Note: You can also add it in other ways. If you are using the Nacos version with its own console, it is recommended to configure it directly using the console.** - - - Details of the added configuration are as follows - - dataId is nacos-config-example.properties - group is DEFAULT_GROUP - - content is: - - spring.cloud.nacos.config.serverAddr=127.0.0.1:8848 - spring.cloud.nacos.config.prefix=PREFIX - spring.cloud.nacos.config.group=GROUP - spring.cloud.nacos.config.namespace=NAMESPACE - -4. Add shared configuration and extended configuration - - Shared configuration: - ``` - dataId is: data-source.yaml - group is： DEFAULT_GROUP - - content is: - - spring: - datasource: - name: datasource - url: jdbc:mysql://127.0.0.1:3306/nacos?characterEncoding=UTF-8&characterSetResults=UTF-8&zeroDateTimeBehavior=convertToNull&useDynamicCharsetInfo=false&useSSL=false - username: root - password: root - driverClassName: com.mysql.jdbc.Driver - ``` - Extended configuration: - > Configuration in shared configuration can be overridden with extended configuration - ``` - dataId is: ext-data-source.yaml - group is： DEFAULT_GROUP - - content is: - - spring: - datasource: - username: ext-root - password: ext-root - ``` - - -### Start Application - -1. Add necessary configurations to file /src/main/resources/application.properties - - server.port=18084 - management.endpoints.web.exposure.include=* - - -2. Start the application in IDE or by building a fatjar. - - 1. Start in IDE: Find main class `Application`, and execute the main method. - 2. Build a fatjar：Execute command `mvn clean package` to build a fatjar，and run command `java -jar nacos-config-example.jar` to start the application. - -### Verification - -#### Automatic Injection -Enter `http://127.0.0.1:18084/nacos/bean` in the browser address bar and click Go to, we can see the data successfully obtained from Nacos Config Server. - -![get](https://tva1.sinaimg.cn/large/e6c9d24ely1h2gbowleyrj20o40bo753.jpg) - -#### Dynamic Refresh -1. Run the following command to modify the configuration data on the Nacos Server side. - - curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos-config-example.properties&group=DEFAULT_GROUP&content=spring.cloud.nacos.config.serveraddr=127.0.0.1:8848%0Aspring.cloud.nacos.config.prefix=PREFIX%0Aspring.cloud.nacos.config.group=DEFAULT_GROUP%0Aspring.cloud.nacos.config.namespace=NAMESPACE" - -2. Enter `http://127.0.0.1:18084/nacos/bean` in the address bar of the browser, and click Flip, you can see that the application has obtained the latest data from Nacos Server, and the group has become DEFAULT_GROUP. - -![refresh](https://tva1.sinaimg.cn/large/e6c9d24ely1h2gbpram9rj20nq0ccmxz.jpg) - - -## Principle - - -### Nacos Config Data Structure - -Nacos Config primarily determines a piece of config through dataId and group, and we assume that you already know this background. If you don't understand, please refer to [Nacos Doc](https://nacos.io/en-us/docs/concepts.html)。 - -Nacos Client gets data from Nacos Server through this method. `ConfigService.getConfig(String dataId, String group, long timeoutMs)`。 - - -### Spring Cloud Retrieve Data - -#### dataID - -In Nacos Config Starter, the splicing format of dataId is as follows - - ${prefix} - ${spring.profiles.active} . ${file-extension} - -* `prefix` default value is `spring.application.name` value, which can also be configured via the configuration item `spring.cloud.nacos.config.prefix`. - -* `spring.profiles.active` is the profile corresponding to the current environment. For details, please refer to [Spring Boot Doc](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-profiles.html#boot-features-profiles) - - **Note: when the active profile is empty, the corresponding connector `-` will also not exist, and the splicing format of the dataId becomes `${prefix}`.`${file-extension}`** - -* `file-extension` is the data format of the configuration content, which can be configured by the configuration item `spring.cloud.nacos.config.file-extension`. -Currently, only the `properties` type is supported. - -#### group -* `group` defaults to `DEFAULT_GROUP` and can be configured via `spring.cloud.nacos.config.group`. - - -### Automatic Injection -Nacos Config Starter implement `org.springframework.cloud.bootstrap.config.PropertySourceLocator` interface, and set order to 0. - -In the startup phase of the Spring Cloud application, the corresponding data is obtained from the Nacos Server side, and the acquired data is converted into a PropertySource and injected into the PropertySources property of the Spring Environment. so the @Value annotation can also directly obtain the configuration of the Nacos Server side. - -### Dynamic Refresh - -By default, Nacos Config Starter adds a listening function to all Nacos configuration items that have successfully acquired data. It will trigger `org.springframework.cloud.context.refresh.ContextRefresher` 's refresh method in real time when it detects changes in the server configuration. - -If you need to dynamically refresh a bean, please refer to the Spring and Spring Cloud specifications. It is recommended to add `@RefreshScope` or `@ConfigurationProperties ` annotations to the class. - -Please refer to [ContextRefresher Java Doc](http://static.javadoc.io/org.springframework.cloud/spring-cloud-context/2.0.0.RELEASE/org/springframework/cloud/context/refresh/ContextRefresher.html) for more details. - - - - -## Endpoint - -Nacos Config starter also supports the implementation of Spring Boot actuator endpoints. - -**Prerequisite:** - -Add dependency spring-boot-starter-actuator to your pom.xml file, and configure your endpoint security strategy. - -Spring Boot 1.x: Add configuration management.security.enabled=false -Spring Boot 2.x: Add configuration management.endpoints.web.exposure.include=* -To view the endpoint information, visit the following URLS: - -Spring Boot 1.x: Nacos Config Endpoint URL is http://127.0.0.1:18084/nacos_config. -Spring Boot 2.x: Nacos Config Endpoint URL is http://127.0.0.1:18084/actuator/nacosconfig. - -![actuator](https://cdn.nlark.com/lark/0/2018/png/54319/1536986344822-279e1edc-ebca-4201-8362-0ddeff240b85.png) - -As shown in the figure above, Sources indicates which Nacos Config configuration items the client has obtained information, RefreshHistory indicates the dynamic refresh history, and up to 20, and NacosConfigProperties is the configuration of Nacos Config Starter itself. - -## More - -#### More configuration items - -Configuration item|key|default value|Description -----|----|-----|----- -server address|spring.cloud.nacos.config.server-addr||server id and port -DataId prefix|spring.cloud.nacos.config.prefix|${spring.application.name}|the prefix of nacos config DataId -Group|spring.cloud.nacos.config.group|DEFAULT_GROUP| -DataID suffix|spring.cloud.nacos.config.file-extension|properties|the suffix of nacos config DataId, also the file extension of config content. -encoding |spring.cloud.nacos.config.encode|UTF-8|Content encoding -timeout|spring.cloud.nacos.config.timeout|3000|Get the configuration timeout period,unit is ms -namespace|spring.cloud.nacos.config.namespace||One of the common scenarios is the separation of the configuration of different environments, such as the development of the test environment and the resource isolation of the production environment. -AccessKey|spring.cloud.nacos.config.access-key|| -SecretKey|spring.cloud.nacos.config.secret-key|| -context-path|spring.cloud.nacos.config.context-path||Relative path of the server API -endpoint|spring.cloud.nacos.config.endpoint||The domain name of a service, through which the server address can be dynamically obtained. -refresh|spring.cloud.nacos.config.refresh.enabled|true|enable auto refresh -cluster name|spring.cloud.nacos.config.cluster-name|| - - - -#### More introduction -[Nacos](https://github.com/alibaba/Nacos) is committed to help you discover, configure, and manage your microservices. It provides a set of simple and useful features enabling you to realize dynamic service discovery, service configuration, service metadata and traffic management. - -Nacos makes it easier and faster to construct, deliver and manage your microservices platform. It is the infrastructure that supports a service-centered modern application architecture with a microservices or cloud-native approach. - -If you have any ideas or suggestions for Nacos Config starter, please don't hesitate to tell us by submitting GitHub issues. - diff --git a/spring-cloud-alibaba-examples/nacos-example/nacos-discovery-example/readme-zh.md b/spring-cloud-alibaba-examples/nacos-example/nacos-discovery-example/readme-zh.md deleted file mode 100644 index 54356bd4c..000000000 --- a/spring-cloud-alibaba-examples/nacos-example/nacos-discovery-example/readme-zh.md +++ /dev/null @@ -1,236 +0,0 @@ -# Nacos Discovery Example - -## 项目说明 - -本项目演示如何使用 Nacos Discovery Starter 完成 Spring Cloud 应用的服务注册与发现。 - -[Nacos](https://github.com/alibaba/Nacos) 是阿里巴巴开源的一个更易于构建云原生应用的动态服务发现、配置管理和服务管理平台。 - -## 示例 - -### 如何接入 -在启动示例进行演示之前，我们先了解一下 Spring Cloud 应用如何接入 Nacos Discovery。 -**注意 本章节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您无需再进行修改。** - -1. 首先，修改 pom.xml 文件，引入 Nacos Discovery Starter。 - - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-discovery - - -2. 在应用的 /src/main/resources/application.properties 配置文件中配置 Nacos Server 地址 - - spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 - -3. 使用 @EnableDiscoveryClient 注解开启服务注册与发现功能 - - @SpringBootApplication - @EnableDiscoveryClient - public class ProviderApplication { - - public static void main(String[] args) { - SpringApplication.run(ProviderApplication.class, args); - } - - @RestController - class EchoController { - @GetMapping(value = "/echo/{string}") - public String echo(@PathVariable String string) { - return string; - } - } - } - -### 启动 Nacos Server - -1. 首先需要获取 Nacos Server，支持直接下载和源码构建两种方式。 - - 1. 直接下载：[Nacos Server 下载页](https://github.com/alibaba/nacos/releases) - 2. 源码构建：进入 Nacos [Github 项目页面](https://github.com/alibaba/nacos)，将代码 git clone 到本地自行编译打包，[参考此文档](https://nacos.io/zh-cn/docs/quick-start.html)。**推荐使用源码构建方式以获取最新版本** - -2. 启动 Server，进入解压后文件夹或编译打包好的文件夹，找到如下相对文件夹 nacos/bin，并对照操作系统实际情况之下如下命令。 - - 1. Linux/Unix/Mac 操作系统，执行命令 `sh startup.sh -m standalone` - 1. Windows 操作系统，执行命令 `cmd startup.cmd` - -### 应用启动 - -1. 增加配置，在 nacos-discovery-provider-example 项目的 /src/main/resources/application.properties 中添加基本配置信息 - - spring.application.name=service-provider - server.port=18082 - - -2. 启动应用，支持 IDE 直接启动和编译打包后启动。 - - 1. IDE直接启动：找到 nacos-discovery-provider-example 项目的主类 `ProviderApplication`，执行 main 方法启动应用。 - 2. 打包编译后启动：在 nacos-discovery-provider-example 项目中执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar nacos-discovery-provider-example.jar`启动应用。 - -### 验证 - -#### 查询服务 -在浏览器输入此地址 `http://127.0.0.1:8848/nacos/v1/ns/catalog/instances?serviceName=service-provider&clusterName=DEFAULT&pageSize=10&pageNo=1&namespaceId=`，并点击跳转，可以看到服务节点已经成功注册到 Nacos Server。 - -![查询服务](https://cdn.nlark.com/lark/0/2018/png/54319/1536986288092-5cf96af9-9a26-466b-85f6-39ad1d92dfdc.png) - - -### 服务发现 - - -#### 集成 Ribbon -为了便于使用，NacosServerList 实现了 com.netflix.loadbalancer.ServerList 接口，并在 @ConditionOnMissingBean 的条件下进行自动注入。如果您有定制化的需求，可以自己实现自己的 ServerList。 - -Nacos Discovery Starter 默认集成了 Ribbon ，所以对于使用了 Ribbon 做负载均衡的组件，可以直接使用 Nacos 的服务发现。 - - -#### 使用 RestTemplate 和 FeignClient - -下面将分析 nacos-discovery-consumer-example 项目的代码，演示如何 RestTemplate 与 FeignClient。 - -**注意 本章节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您无需再进行修改。此处只涉及Ribbon、RestTemplate、FeignClient相关的内容，如果已经使用了其他服务发现组件，可以通过直接替换依赖来接入 Nacos Discovery。** - -1. 添加 @LoadBlanced 注解，使得 RestTemplate 接入 Ribbon - - @Bean - @LoadBalanced - public RestTemplate restTemplate() { - return new RestTemplate(); - } - -1. FeignClient 已经默认集成了 Ribbon ，此处演示如何配置一个 FeignClient。 - - @FeignClient(name = "service-provider") - public interface EchoService { - @GetMapping(value = "/echo/{str}") - String echo(@PathVariable("str") String str); - } - - 使用 @FeignClient 注解将 EchoService 这个接口包装成一个 FeignClient，属性 name 对应服务名 service-provider。 - - echo 方法上的 @RequestMapping 注解将 echo 方法与 URL "/echo/{str}" 相对应，@PathVariable 注解将 URL 路径中的 `{str}` 对应成 echo 方法的参数 str。 - -1. 完成以上配置后，将两者自动注入到 TestController 中。 - - @RestController - public class TestController { - - @Autowired - private RestTemplate restTemplate; - @Autowired - private EchoService echoService; - - @GetMapping(value = "/echo-rest/{str}") - public String rest(@PathVariable String str) { - return restTemplate.getForObject("http://service-provider/echo/" + str, String.class); - } - @GetMapping(value = "/echo-feign/{str}") - public String feign(@PathVariable String str) { - return echoService.echo(str); - } - } - -1. 配置必要的配置，在 nacos-discovery-consumer-example 项目的 /src/main/resources/application.properties 中添加基本配置信息 - - spring.application.name=service-consumer - server.port=18083 - -1. 启动应用，支持 IDE 直接启动和编译打包后启动。 - - 1. IDE直接启动：找到 nacos-discovery-consumer-example 项目的主类 `ConsumerApplication`，执行 main 方法启动应用。 - 2. 打包编译后启动：在 nacos-discovery-consumer-example 项目中执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar nacos-discovery-consumer-example.jar`启动应用。 - -#### 验证 -1. 在浏览器地址栏中输入 http://127.0.0.1:18083/echo-rest/1234，点击跳转，可以看到浏览器显示了 nacos-discovery-provider-example 返回的消息 "hello Nacos Discovery 1234"，证明服务发现生效。 - -![rest](https://cdn.nlark.com/lark/0/2018/png/54319/1536986302124-ee27670d-bdcc-4210-9f5d-875acec6d3ea.png) - -1. 在浏览器地址栏中输入 http://127.0.0.1:18083/echo-feign/12345，点击跳转，可以看到浏览器显示 nacos-discovery-provider-example 返回的消息 "hello Nacos Discovery 12345"，证明服务发现生效。 - -![feign](https://cdn.nlark.com/lark/0/2018/png/54319/1536986311685-6d0c1f9b-a453-4ec3-88ab-f7922d210f65.png) -## 原理 - - -### 服务注册 -Spring Cloud Nacos Discovery 遵循了 spring cloud common 标准，实现了 AutoServiceRegistration、ServiceRegistry、Registration 这三个接口。 - -在 spring cloud 应用的启动阶段，监听了 WebServerInitializedEvent 事件，当Web容器初始化完成后，即收到 WebServerInitializedEvent 事件后，会触发注册的动作，调用 ServiceRegistry 的 register 方法，将服务注册到 Nacos Server。 - - - -### 服务发现 -NacosServerList 实现了 com.netflix.loadbalancer.ServerList 接口，并在 @ConditionOnMissingBean 的条件下进行自动注入，默认集成了Ribbon。 - -如果需要有更加自定义的可以使用 @Autowired 注入一个 NacosRegistration 实例，通过其持有的 NamingService 字段内容直接调用 Nacos API。 - -## IPv4至IPv6地址迁移方案 -Spring Cloud Alibaba 提供了使用双注册双订阅方式帮助用户实现应用IPv4向IPv6不停机迁移，在使用相关功能之前，需要在服务消费者应用 application.properties 配置客户端负载均衡为 Spring Cloud Alibaba 所提供的 NacosRule 负载均衡算法，配置方式如下，注意需要将[service-name]替换成具体的待消费服务名。 - - [service-name].ribbon.NFLoadBalancerRuleClassName=com.alibaba.cloud.nacos.ribbon.NacosRule - - - -### IPv4和IPv6地址双注册 -在配置完成NacosRule作为负载均衡策略后，应用启动后会默认将微服务的IPv4地址和IPv6地址注册到注册中心中，其中IPv4地址会存放在Nacos服务列表中的IP字段下，IPv6地址在Nacos的metadata字段中，其对应的Key为IPv6。当服务消费者调用服务提供者时，会根据自身的IP地址栈支持情况，选择合适的IP地址类型发起服务调用。具体规则： - 1. 服务消费者本身支持IPv4和IPv6双地址栈或仅支持IPv6地址栈的情况下，服务消费者会使用服务提供的IPv6地址发起服务调用，IPv6地址调用失败如本身还同事支持IPv4地址栈时，暂不支持切换到IPv4再发起重试调用； - 2. 服务消费者本身仅支持IPv4单地址栈的情况下，服务消费者会使用服务提供的IPv4地址发起服务调用。 - -### 仅注册IPv4 -如果只想使用IPv4地址进行注册，可以在application.properties使用以下配置： -``` -spring.cloud.nacos.discovery.ip-type=IPv4 -``` - -### 仅注册IPv6 -如果只想使用IPv6地址，可以在application.properties使用以下配置： -``` -spring.cloud.nacos.discovery.ip-type=IPv6 -``` - -## Endpoint 信息查看 - -Spring Boot 应用支持通过 Endpoint 来暴露相关信息，Nacos Discovery Starter 也支持这一点。 - -在使用之前需要在 maven 中添加 `spring-boot-starter-actuator`依赖，并在配置中允许 Endpoints 的访问。 - -* Spring Boot 1.x 中添加配置 management.security.enabled=false -* Spring Boot 2.x 中添加配置 management.endpoints.web.exposure.include=* - -Spring Boot 1.x 可以通过访问 http://127.0.0.1:18083/nacos_discovery 来查看 Nacos Endpoint 的信息。 - -Spring Boot 2.x 可以通过访问 http://127.0.0.1:18083/actuator/nacos-discovery 来访问。 - -![actuator](https://cdn.nlark.com/lark/0/2018/png/54319/1536986319285-d542dc5f-5dff-462a-9f52-7254776bcd99.png) - -如上图所示，NacosDiscoveryProperties 则为 Spring Cloud Nacos Discovery 本身的配置，也包括本机注册的内容，subscribe 为本机已订阅的服务信息。 - -## More - -#### 更多配置项 -配置项|key|默认值|说明 -----|----|-----|----- -服务端地址|spring.cloud.nacos.discovery.server-addr|| -服务名|spring.cloud.nacos.discovery.service|spring.application.name| -权重|spring.cloud.nacos.discovery.weight|1|取值范围 1 到 100，数值越大，权重越大 -网卡名|spring.cloud.nacos.discovery.network-interface||当IP未配置时，注册的IP为此网卡所对应的IP地址，如果此项也未配置，则默认取第一块网卡的地址 -注册的IP地址|spring.cloud.nacos.discovery.ip||优先级最高 -注册的IP地址类型|spring.cloud.nacos.discovery.ip-type|IPv4|可以配置IPv4和IPv6两种类型，如果网卡同类型IP地址存在多个，希望制定特定网段地址，可使用`spring.cloud.inetutils.preferred-networks`配置筛选地址 -注册的端口|spring.cloud.nacos.discovery.port|-1|默认情况下不用配置，会自动探测 -命名空间|spring.cloud.nacos.discovery.namespace||常用场景之一是不同环境的注册的区分隔离，例如开发测试环境和生产环境的资源（如配置、服务）隔离等。 -AccessKey|spring.cloud.nacos.discovery.access-key|| -SecretKey|spring.cloud.nacos.discovery.secret-key|| -Metadata|spring.cloud.nacos.discovery.metadata||使用Map格式配置 -日志文件名|spring.cloud.nacos.discovery.log-name|| -接入点|spring.cloud.nacos.discovery.endpoint|UTF-8|地域的某个服务的入口域名，通过此域名可以动态地拿到服务端地址 -是否集成Ribbon|ribbon.nacos.enabled|true| -集群|spring.cloud.nacos.discovery.cluster-name|DEFAULT|Nacos集群名称 -是否开启Nacos Watch|spring.cloud.nacos.discovery.watch.enabled|false|可以设置成true来开启 watch -是否启用Nacos|spring.cloud.nacos.discovery.enabled|true|默认启动，设置为false时会关闭自动向Nacos注册的功能 - - - -#### 更多介绍 -Nacos为用户提供包括动态服务发现，配置管理，服务管理等服务基础设施，帮助用户更灵活，更轻松地构建，交付和管理他们的微服务平台，基于Nacos, 用户可以更快速地构建以“服务”为中心的现代云原生应用。Nacos可以和Spring Cloud、Kubernetes/CNCF、Dubbo 等微服务生态无缝融合，为用户提供更卓越的体验。更多 Nacos 相关的信息，请参考 [Nacos 项目](https://github.com/alibaba/Nacos)。 - -如果您对 Spring Cloud Nacos Discovery 有任何建议或想法，欢迎在 issue 中或者通过其他社区渠道向我们提出。 - diff --git a/spring-cloud-alibaba-examples/nacos-example/nacos-discovery-example/readme.md b/spring-cloud-alibaba-examples/nacos-example/nacos-discovery-example/readme.md deleted file mode 100644 index 4539047b3..000000000 --- a/spring-cloud-alibaba-examples/nacos-example/nacos-discovery-example/readme.md +++ /dev/null @@ -1,246 +0,0 @@ -# Nacos Discovery Example - -## Project Instruction - -This example illustrates how to use Nacos Discovery Starter implement Service discovery for Spring Cloud applications. - -[Nacos](https://github.com/alibaba/Nacos) an easy-to-use dynamic service discovery, configuration and service management platform for building cloud native applications. - -## Demo - -### Connect to Nacos Discovery -Before we start the demo, let's learn how to connect Nacos Config to a Spring Cloud application. **Note: This section is to show you how to connect to Nacos Discovery. The configurations have been completed in the following example, so you don't need to modify the code anymore.** - -1. Add dependency spring-cloud-starter-alibaba-nacos-discovery in the pom.xml file in your Spring Cloud project. - - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-discovery - - -2. Add Nacos server address configurations to file /src/main/resources/application.properties. - - spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 - -3. Use the @EnableDiscoveryClient annotation to turn on service registration and discovery. - - @SpringBootApplication - @EnableDiscoveryClient - public class ProviderApplication { - - public static void main(String[] args) { - SpringApplication.run(ProviderApplication.class, args); - } - - @RestController - class EchoController { - @GetMapping(value = "/echo/{string}") - public String echo(@PathVariable String string) { - return string; - } - } - } - -### Start Nacos Server - -1. Install Nacos Server by downloading or build from source code.**Recommended latest version Nacos Server** - - 1. Download: Download Nacos Server [download page](https://github.com/alibaba/nacos/releases) - 2. Build from source code: Get source code by git clone git@github.com:alibaba/Nacos.git from GitHub Nacos and build your code. See [build reference](https://nacos.io/en-us/docs/quick-start.html) for details. - - - -2. Unzip the downloaded file and go to the nacos/bin folder(), And according to the actual situation of the operating system, execute the following command。[see reference for more detail](https://nacos.io/en-us/docs/quick-start.html)。 - - 1. Linux/Unix/Mac , execute `sh startup.sh -m standalone` - 1. Windows , execute `cmd startup.cmd` - -### Start Application - -1. Add necessary configurations to project `nacos-discovery-provider-example`, file /src/main/resources/application.properties. - - spring.application.name=service-provider - server.port=18082 - - -2. Start the application in IDE or by building a fatjar. - - 1. Start in IDE: Find main class `ProviderApplication ` in project `nacos-discovery-provider-example`, and execute the main method. - 2. Build a fatjar：Execute command `mvn clean package` in project ` nacos-discovery-provider-example ` to build a fatjar，and run command `java -jar nacos-discovery-provider-example.jar` to start the application. - -### Verification - -#### Query Service - -Enter `http://127.0.0.1:8848/nacos/#/serviceDetail?name=service-provider&groupName=DEFAULT_GROUP` in the browser address bar and click Go to, we can see that the service node has been successfully registered to Nacos Server. - -![查询服务](https://cdn.nlark.com/lark/0/2018/png/54319/1536986288092-5cf96af9-9a26-466b-85f6-39ad1d92dfdc.png) - - -### Service Discovery - - -#### Integration Ribbon - -For ease of use, NacosServerList implements the com.netflix.loadbalancer.ServerList interface and auto-injects under the @ConditionOnMissingBean condition. If you have customized requirements, you can implement your own ServerList yourself. - -Nacos Discovery Starter integrates Ribbon by default, so for components that use Ribbon for load balancing, you can use Nacos Service discovery directly. - - -#### Use RestTemplate and FeignClient - -The code of `nacos-discovery-consumer-example` project will be analyzed below, demonstrating how RestTemplate and FeignClient. - -**Note This section is to show you how to connect to Nacos Discovery. The configurations have been completed in the following example, so you don't need to modify the code anymore.Only the contents related to Ribbon, RestTemplate, and FeignClient are involved here. If other service discovery components have been used, you can access Nacos Discovery by directly replacing the dependencies.** - -1. Add the @LoadBlanced annotation to make RestTemplate accessible to the Ribbon - - @Bean - @LoadBalanced - public RestTemplate restTemplate() { - return new RestTemplate(); - } - -1. FeignClient has integrated the Ribbon by default, which shows how to configure a FeignClient. - - @FeignClient(name = "service-provider") - public interface EchoService { - @GetMapping(value = "/echo/{str}") - String echo(@PathVariable("str") String str); - } - - Use the @FeignClient annotation to wrap the `EchoService` interface as a FeignClient with the attribute name corresponding to the service name `service-provider`. - - The `@RequestMapping` annotation on the `echo` method corresponds the echo method to the URL `/echo/{str}`, and the `@PathVariable` annotation maps `{str}` in the URL path to the argument `str` of the echo method. - -1. After completing the above configuration, injected them into the TestController. - - @RestController - public class TestController { - - @Autowired - private RestTemplate restTemplate; - @Autowired - private EchoService echoService; - - @GetMapping(value = "/echo-rest/{str}") - public String rest(@PathVariable String str) { - return restTemplate.getForObject("http://service-provider/echo/" + str, String.class); - } - @GetMapping(value = "/echo-feign/{str}") - public String feign(@PathVariable String str) { - return echoService.echo(str); - } - } - -1. Add necessary configurations to project `nacos-discovery-consumer-example` file /src/main/resources/application.properties. - - spring.application.name=service-consumer - server.port=18083 - -1. Start the application in IDE or by building a fatjar. - - 1. Start in IDE: Find main class `ConsumerApplication ` in project `nacos-discovery-consumer-example`, and execute the main method. - 2. Build a fatjar：Execute command `mvn clean package` in project ` nacos-discovery-consumer-example ` to build a fatjar，and run command `java -jar nacos-discovery-consumer-example.jar` to start the application. - -#### Verification -1. Enter `http://127.0.0.1:18083/echo-rest/1234` in the browser address bar and click Go to, we can see that the browser displays the message "hello Nacos Discovery 1234" returned by nacos-discovery-provider-example to prove that the service discovery is in effect. - -![rest](https://cdn.nlark.com/lark/0/2018/png/54319/1536986302124-ee27670d-bdcc-4210-9f5d-875acec6d3ea.png) - -1. Enter `http://127.0.0.1:18083/echo-feign/12345` in the browser address bar and click Go to, we can see that the browser displays the message "hello Nacos Discovery 12345" returned by nacos-discovery-provider-example to prove that the service discovery is in effect. - -![feign](https://cdn.nlark.com/lark/0/2018/png/54319/1536986311685-6d0c1f9b-a453-4ec3-88ab-f7922d210f65.png) - -## Principle - -### Service Registry - -Spring Cloud Nacos Discovery follows the spring cloud common standard and implements three interfaces: AutoServiceRegistration, ServiceRegistry, and Registration. - -During the startup phase of the spring cloud application, the WebServerInitializedEvent event is watched. When the WebServerInitializedEvent event is received after the Web container is initialized, the registration action is triggered, and the ServiceRegistry register method is called to register the service to the Nacos Server. - - - -### Service Discovery - -NacosServerList implements the com.netflix.loadbalancer.ServerList interface and auto-injects it under @ConditionOnMissingBean. The ribbon is integrated by default. - -If you need to be more customizable, you can use @Autowired to inject a NacosRegistration bean and call the Nacos API directly through the contents of the NamingService field it holds. - -## IPv4 to IPv6 address migration - -Spring Cloud Alibaba provides a dual registration and dual subscription method to help users migrate applications from IPv4 to IPv6 without downtime. Before using related functions, it is necessary to configure client load balancing in the application.properties of the service consumer as the NacosRule provided by Spring Cloud Alibaba The load balancing algorithm is configured as follows. Note that [service-name] needs to be replaced with the specific service name to be consumed. - - [service-name].ribbon.NFLoadBalancerRuleClassName=com.alibaba.cloud.nacos.ribbon.NacosRule - -### Both register IPv4 and IPv6 address -After configuring NacosRule as the load balancing policy, the IPv4 address and IPv6 address of the microservice will be registered with the registry by default after the application is started, where the IPv4 address will be stored in the IP field of the Nacos service list, the IPv6 address will be in the metadata field of Nacos, and its corresponding Key will be IPv6. When a service consumer calls a service provider, it selects the appropriate IP address type to initiate a service call based on its IP address stack support. Specific rules: -1. If the service consumer itself supports IPv4 and IPv6 dual address stacks or only supports IPv6 address stacks, the service consumer will use the IPv6 address provided by the service to initiate a service call, and if the IPv6 address call fails, if it also supports the IPv4 address stack, it is temporarily not supported to switch to IPv4 and then initiate a retry call; -2. If the service consumer itself only supports IPv4 single-address stack, the service consumer will use the IPv4 address provided by the service to initiate service calls. - -### Only Register IPv4 address -If you only want to register IPv4 address.Config in application.properties as follows: -``` -spring.cloud.nacos.discovery.ip-type=IPv4 -``` - -### Only Register IPv6 address -If you only want to register IPv6 address.Config in application.properties as follows: -``` -spring.cloud.nacos.discovery.ip-type=IPv6 -``` - -## Endpoint - -Nacos Discovery Starter also supports the implementation of Spring Boot actuator endpoints. - -**Prerequisite:** - -Add dependency spring-boot-starter-actuator to your pom.xml file, and configure your endpoint security strategy. - -Spring Boot 1.x: Add configuration management.security.enabled=false -Spring Boot 2.x: Add configuration management.endpoints.web.exposure.include=* -To view the endpoint information, visit the following URLS: - -Spring Boot1.x: Nacos Discovery Endpoint URL is http://127.0.0.1:18083/nacos_discovery. -Spring Boot2.x: Nacos Discovery Endpoint URL is http://127.0.0.1:18083/actuator/nacos-discovery. - -![actuator](https://cdn.nlark.com/lark/0/2018/png/54319/1536986319285-d542dc5f-5dff-462a-9f52-7254776bcd99.png) - -As shown in the figure above, NacosDiscoveryProperties is the configuration of Nacos Discovery itself, and also includes the contents registered by the application, subscribe is the service information that the application has subscribed to. - - -## More - -#### More configuration items -Configuration item|key|default value|Description -----|----|-----|----- -server address|spring.cloud.nacos.discovery.server-addr|| -service|spring.cloud.nacos.discovery.service|spring.application.name|service id to registry -weight|spring.cloud.nacos.discovery.weight|1|value from 1 to 100, The larger the value, the larger the weight -ip|spring.cloud.nacos.discovery.ip||ip address to registry, Highest priority -ip type|spring.cloud.nacos.discovery.ip-type|IPv4|IPv4 and IPv6 can be configured, If there are multiple IP addresses of the same type of network card, and you want to specify a specific network segment address, you can use `spring.cloud.inetutils.preferred-networks` to configure the filter address. -network interface|spring.cloud.nacos.discovery.network-interface||When the IP is not configured, the registered IP address is the IP address corresponding to the network-interface. If this item is not configured, the address of the first network-interface is taken by default. -port|spring.cloud.nacos.discovery.port|-1|port to registry, Automatically detect without configuration -namesapce|spring.cloud.nacos.discovery.namespace||One of the common scenarios is the separation of the configuration of different environments, such as the development of the test environment and the resource isolation of the production environment. -AccessKey|spring.cloud.nacos.discovery.access-key|| -SecretKey|spring.cloud.nacos.discovery.secret-key|| -Metadata|spring.cloud.nacos.discovery.metadata||Extended data, Configure using Map format -log name|spring.cloud.nacos.discovery.log-name|| -cluster|spring.cloud.nacos.discovery.cluster-name|DEFAULT|Nacos cluster name -endpoint|spring.cloud.nacos.discovery.endpoint||The domain name of a service, through which the server address can be dynamically obtained. -enable Nacos Watch|spring.cloud.nacos.discovery.watch.enabled|false|Switch it to true to enable nacos watch -Integration Ribbon|ribbon.nacos.enabled|true| -enabled|spring.cloud.nacos.discovery.enabled|true|The switch to enable or disable nacos service discovery - - - -#### More introduction - -[Nacos ](https://github.com/alibaba/Nacos) is committed to help you discover, configure, and manage your microservices. It provides a set of simple and useful features enabling you to realize dynamic service discovery, service configuration, service metadata and traffic management. - -Nacos makes it easier and faster to construct, deliver and manage your microservices platform. It is the infrastructure that supports a service-centered modern application architecture with a microservices or cloud-native approach. - -If you have any ideas or suggestions for Nacos Discovery starter, please don't hesitate to tell us by submitting GitHub issues. - diff --git a/spring-cloud-alibaba-examples/nacos-example/nacos-gateway-example/readme-zh.md b/spring-cloud-alibaba-examples/nacos-example/nacos-gateway-example/readme-zh.md deleted file mode 100644 index 807e509e2..000000000 --- a/spring-cloud-alibaba-examples/nacos-example/nacos-gateway-example/readme-zh.md +++ /dev/null @@ -1,97 +0,0 @@ -# Spring Cloud Gateway、 Nacos Discovery Example - -## 项目说明 - -本项目演示如何使用 Nacos Discovery Starter 、 Spring Cloud Gateway Starter 完成 Spring Cloud 服务路由。 - -[Nacos](https://github.com/alibaba/Nacos) 是阿里巴巴开源的一个更易于构建云原生应用的动态服务发现、配置管理和服务管理平台。 -[Spring Cloud Gateway](https://spring.io/projects/spring-cloud-gateway) 是spring cloud 官方开源的一个在SpringMVC 上可以构建API网关的库。 - -## 示例 - -### 如何接入 -在启动示例进行演示之前，我们先了解一下 Spring Cloud 应用如何接入 Spring Cloud 如何接入Nacos Discovery、Spring Cloud Gateway。 -**注意 本章节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您无需再进行修改。** - -1. 首先，修改 pom.xml 文件，引入 Nacos Discovery Starter、Spring Cloud Gateway Starter。 - -```xml - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-discovery - - - org.springframework.cloud - spring-cloud-starter-gateway - -``` - -2. 在应用的 /src/main/resources/application.properties 配置文件中配置 Nacos Server 地址 - - spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 - -3. 在应用的 /src/main/resources/application.properties 配置文件中配置 Spring Cloud Gateway 路由 - -```properties -spring.cloud.gateway.routes[0].id=nacos-route -spring.cloud.gateway.routes[0].uri=lb://service-gateway-provider -spring.cloud.gateway.routes[0].predicates[0].name=Path -spring.cloud.gateway.routes[0].predicates[0].args[pattern]=/nacos/** -spring.cloud.gateway.routes[0].filters[0]=StripPrefix=1 -``` - -4. 使用 @EnableDiscoveryClient 注解开启服务注册与发现功能 - -```java - @SpringBootApplication - @EnableDiscoveryClient - public class GatewayApplication { - - public static void main(String[] args) { - SpringApplication.run(GatewayApplication.class, args); - } - - } -``` - -### 启动 Nacos Server - -1. 首先需要获取 Nacos Server，支持直接下载和源码构建两种方式。 - - 1. 直接下载：[Nacos Server 下载页](https://github.com/alibaba/nacos/releases) - 2. 源码构建：进入 Nacos [Github 项目页面](https://github.com/alibaba/nacos)，将代码 git clone 到本地自行编译打包，[参考此文档](https://nacos.io/zh-cn/docs/quick-start.html)。**推荐使用源码构建方式以获取最新版本** - -2. 启动 Server，进入解压后文件夹或编译打包好的文件夹，找到如下相对文件夹 nacos/bin，并对照操作系统实际情况之下如下命令。 - - 1. Linux/Unix/Mac 操作系统，执行命令 `sh startup.sh -m standalone` - 1. Windows 操作系统，执行命令 `cmd startup.cmd` - -### Spring Cloud Gateway应用启动 -启动应用，支持 IDE 直接启动和编译打包后启动。 - -1. IDE直接启动：找到 nacos-gateway-discovery-example 项目的主类 `GatewayApplication`，执行 main 方法启动应用。 -2. 打包编译后启动：在 nacos-gateway-discovery-example 项目中执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar nacos-gateway-discovery-example.jar`启动应用。 - -### 服务提供方应用启动 -启动应用，支持 IDE 直接启动和编译打包后启动。 -1. IDE直接启动：找到 nacos-gateway-provider-example 项目的主类 `ProviderApplication`，执行 main 方法启动应用。 -2. 打包编译后启动：在 nacos-gateway-provider-example 项目中执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar nacos-gateway-provider-example.jar`启动应用。 - -### 验证 -1. -```bash - curl 'http://127.0.0.1:18085/nacos/echo/hello-world' - - hello Nacos Discovery hello-world⏎ -``` -1. -```bash - curl 'http://127.0.0.1:18085/nacos/divide?a=6&b=2' - - 3⏎ -``` -#### 更多介绍 -Nacos为用户提供包括动态服务发现，配置管理，服务管理等服务基础设施，帮助用户更灵活，更轻松地构建，交付和管理他们的微服务平台，基于Nacos, 用户可以更快速地构建以“服务”为中心的现代云原生应用。Nacos可以和Spring Cloud、Kubernetes/CNCF、Dubbo 等微服务生态无缝融合，为用户提供更卓越的体验。更多 Nacos 相关的信息，请参考 [Nacos 项目](https://github.com/alibaba/Nacos)。 - -如果您对 Spring Cloud Nacos Discovery 有任何建议或想法，欢迎在 issue 中或者通过其他社区渠道向我们提出。 - diff --git a/spring-cloud-alibaba-examples/nacos-example/nacos-gateway-example/readme.md b/spring-cloud-alibaba-examples/nacos-example/nacos-gateway-example/readme.md deleted file mode 100644 index ec0f769da..000000000 --- a/spring-cloud-alibaba-examples/nacos-example/nacos-gateway-example/readme.md +++ /dev/null @@ -1,105 +0,0 @@ -# Spring Cloud Gateway、 Nacos Discovery Example - -## Project Instruction - -This example illustrates how to use Nacos Discovery Starter、 Spring Cloud Gateway Starter implement Service routes for Spring Cloud applications. - -[Nacos](https://github.com/alibaba/Nacos) an easy-to-use dynamic service discovery, configuration and service management platform for building cloud native applications. -[Spring Cloud Gateway](https://spring.io/projects/spring-cloud-gateway) provides a library for building an API Gateway on top of Spring MVC. - - -## Demo - -### Connect to Nacos Discovery -Before we start the demo, let's learn how to connect Nacos Config to a Spring Cloud application. **Note: This section is to show you how to connect to Nacos Discovery、Nacos Discovery、Spring Cloud Gateway. The configurations have been completed in the following example, so you don't need to modify the code anymore.** - -1. Add Nacos Discovery Starter、Spring Cloud Gateway Starter in the pom.xml file in your Spring Cloud project. - -```xml - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-discovery - - - org.springframework.cloud - spring-cloud-starter-gateway - -``` -2. Add Nacos server address configurations to file /src/main/resources/application.properties. - - spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 - -3. Add Spring Cloud Gateway configurations to file /src/main/resources/application.properties. - -```properties -spring.cloud.gateway.routes[0].id=nacos-route -spring.cloud.gateway.routes[0].uri=lb://service-gateway-provider -spring.cloud.gateway.routes[0].predicates[0].name=Path -spring.cloud.gateway.routes[0].predicates[0].args[pattern]=/nacos/** -spring.cloud.gateway.routes[0].filters[0]=StripPrefix=1 -``` -4. Use the @EnableDiscoveryClient annotation to turn on service registration and discovery. - -```java - @SpringBootApplication - @EnableDiscoveryClient - public class GatewayApplication { - - public static void main(String[] args) { - SpringApplication.run(GatewayApplication.class, args); - } - - } -``` - -### Start Nacos Server - -1. Install Nacos Server by downloading or build from source code.**Recommended latest version Nacos Server** - - 1. Download: Download Nacos Server [download page](https://github.com/alibaba/nacos/releases) - 2. Build from source code: Get source code by git clone git@github.com:alibaba/Nacos.git from GitHub Nacos and build your code. See [build reference](https://nacos.io/en-us/docs/quick-start.html) for details. - - - -2. Unzip the downloaded file and go to the nacos/bin folder(), And according to the actual situation of the operating system, execute the following command。[see reference for more detail](https://nacos.io/en-us/docs/quick-start.html)。 - - 1. Linux/Unix/Mac , execute `sh startup.sh -m standalone` - 1. Windows , execute `cmd startup.cmd` - -### Start Spring Cloud Gateway Application -Start the application in IDE or by building a fatjar. - -1. Start in IDE: Find main class `GatewayApplication ` in project `nacos-gateway-discovery-example`, and execute the main method. -2. Build a fatjar：Execute command `mvn clean package` in project `nacos-gateway-discovery-example` to build a fatjar，and run command `java -jar nacos-gateway-discovery-example.jar` to start the application. - - -### Start Service provider Application - -Start the application in IDE or by building a fatjar. - -1. Start in IDE: Find main class `ProviderApplication ` in project `nacos-gateway-provider-example`, and execute the main method. -2. Build a fatjar：Execute command `mvn clean package` in project `nacos-gateway-provider-example` to build a fatjar，and run command `java -jar nacos-gateway-provider-example.jar` to start the application. - - -### Verification -1. -```bash - curl 'http://127.0.0.1:18085/nacos/echo/hello-world' - - hello Nacos Discovery hello-world⏎ -``` -1. -```bash - curl 'http://127.0.0.1:18085/nacos/divide?a=6&b=2' - - 3⏎ -``` - -#### More introduction - -[Nacos ](https://github.com/alibaba/Nacos) is committed to help you discover, configure, and manage your microservices. It provides a set of simple and useful features enabling you to realize dynamic service discovery, service configuration, service metadata and traffic management. - -Nacos makes it easier and faster to construct, deliver and manage your microservices platform. It is the infrastructure that supports a service-centered modern application architecture with a microservices or cloud-native approach. - -If you have any ideas or suggestions for Nacos Discovery starter, please don't hesitate to tell us by submitting GitHub issues. - diff --git a/spring-cloud-alibaba-examples/nacos-example/readme-zh.md b/spring-cloud-alibaba-examples/nacos-example/readme-zh.md new file mode 100644 index 000000000..7ce6bf9d9 --- /dev/null +++ b/spring-cloud-alibaba-examples/nacos-example/readme-zh.md @@ -0,0 +1,618 @@ +# Spring Cloud Alibaba Nacos Example + +## 项目说明 + +本项目演示如何使用 Spring Cloud Alibaba Nacos 相关 Starter 完成 Spring Cloud 应用的服务发现和配置管理。 + +[Nacos](https://github.com/alibaba/Nacos) 是阿里巴巴开源的一个更易于构建云原生应用的动态服务发现、配置管理和服务管理平台。 + +## 正确配置并启动 Nacos Server 2.2.x + +在 Nacos 2.2.x 中，加入了用户鉴权相关的功能，在首次启动 Nacos Server 时，需要正确配置，避免出现启动失败的问题。 + +### 下载 Nacos Server + +> 本示例中使用 Nacos Server 版本为 2.2.0！ + +Nacos 支持直接下载和源码构建两种方式。**推荐在 Spring Cloud Alibaba 2021.x 中使用 Nacos Server 2.2.0 版本。** + +1. 直接下载：[Nacos Server 下载页](https://github.com/alibaba/nacos/releases) +2. 源码构建：进入 Nacos [Github 项目页面](https://github.com/alibaba/nacos)，将代码 git clone 到本地自行编译打包，[参考文档](https://nacos.io/zh-cn/docs/quick-start.html)。 + +### 配置 Nacos Server + +打开 `\nacos-server-2.2.0\conf\application.properties` 配置文件，修改以下配置项： + +#### 配置数据源 + +此处以 MySQL 数据库为例，使用 `nacos-server-2.2.0\conf\mysql-schema.sql` 初始化数据库表文件。同时修改以下配置 + +```properties +#*************** Config Module Related Configurations ***************# +### If use MySQL as datasource: +spring.datasource.platform=mysql + +### Count of DB: +db.num=1 + +### Connect URL of DB: +db.url.0=jdbc:mysql://127.0.0.1:3306/nacos?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true +db.user.0=root +db.password.0=root + +### Connection pool configuration: hikariCP +db.pool.config.connectionTimeout=30000 +db.pool.config.validationTimeout=10000 +db.pool.config.maximumPoolSize=20 +db.pool.config.minimumIdle=2 +``` + +#### 开启鉴权 + +**注意：不开启在 2.2.x 中会出现登陆失败异常！** + +```properties +### The auth system to use, currently only 'nacos' and 'ldap' is supported: +nacos.core.auth.system.type=nacos + +### If turn on auth system: +nacos.core.auth.enabled=true +``` + +#### 设置服务端验证 key + +```properties +nacos.core.auth.server.identity.key=test +nacos.core.auth.server.identity.value=test +``` + +#### 设置默认 token + +```properties +### The default token (Base64 String): +nacos.core.auth.plugin.nacos.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789 +``` + +**在使用 Nacos 服务发现和配置功能时，一定要配置 `username` 和 `password` 属性，否则会出现用户未找到异常！** + +#### Open API 鉴权 + +在 nacos server 2.2.x 中使用 Open api 接口时需要鉴权：更多细节请参考：[Nacos api 鉴权](https://nacos.io/zh-cn/docs/auth.html) + +1. 获取 accessToken：使用用户名和密码登陆 nacos server： + + `curl -X POST '127.0.0.1:8848/nacos/v1/auth/login' -d 'username=nacos&password=nacos'` + + 若用户名和密码正确,返回信息如下: + + `{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyOTE2Nn0.2TogGhhr11_vLEjqKko1HJHUJEmsPuCxkur-CfNojDo","tokenTtl":18000,"globalAdmin":true}` + +2. 使用 accessToken 请求 nacos api 接口： + + `curl -X GET '127.0.0.1:8848/nacos/v1/cs/configs?accessToken=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyMzkyM30.O-s2yWfDSUZ7Svd3Vs7jy9tsfDNHs1SuebJB4KlNY8Q&dataId=nacos.example.1&group=nacos_group'` + +### 启动 Nacos Server + +1. 启动 Nacos Server，进入下载到本地并解压完成后的文件夹(使用源码构建的方式则进入编译打包好的文件夹)，再进去其相对文件夹 `nacos/bin`，并对照操作系统实际情况执行如下命令。[详情参考此文档](https://nacos.io/zh-cn/docs/quick-start.html)。 + + 1. Linux/Unix/Mac 操作系统，执行命令 + + `sh startup.sh -m standalone` + + 2. Windows 操作系统，执行命令 + + `cmd startup.cmd` + +2. 访问 Nacos Server Console + + 浏览器输入地址 http://127.0.0.1:8848/nacos ，**首次登陆需要绑定 nacos 用户，因为新版本增加了鉴权，需要应用注册和配置绑定时配置用户名和密码。** + + + +## Nacos 应用示例 + +### Spring Cloud Alibaba Nacos Config + +#### 应用接入 + +在启动应用示例进行项目功能演示之前，先了解一下 Spring Cloud 应用如何接入 Nacos Config 作为服务配置中心。 + +**注意 本章节只是为了便于理解接入方式，本示例代码中已经完成接入工作，无需再进行修改。** + +1. 首先，修改 `pom.xml` 文件，引入 spring-cloud-starter-alibaba-nacos-config ； + + ```xml + + com.alibaba.cloud + spring-cloud-starter-alibaba-nacos-config + + ``` + +2. 在应用的 `/src/main/resources/application.yaml` 配置文件中配置 Nacos 地址并引入服务配置； + + ```yml + spring: + cloud: + nacos: + serverAddr: 127.0.0.1:8848 + # 以下配置项必须填写 + username: 'nacos' + password: 'nacos' + config: + import: + - nacos:nacos-config-example.properties?refresh=true&group=DEFAULT_GROUP + ``` + +3. 完成上述两步后，应用会从 Nacos Server 中获取相应的配置，并添加在 Spring Environment 的 PropertySources 中。使用 Nacos 配置中心保存 Nacos 的部分配置时，有以下四种方式: + - BeanAutoRefreshConfigExample: 通过将配置信息配置为bean，支持配置变自动刷新的例子； + - ConfigListenerExample: 监听配置信息的例子； + - DockingInterfaceExample: 对接 Nacos 接口，通过接口完成对配置信息增删改查的例子； + - ValueAnnotationExample: 通过 @Value 注解进行配置信息获取的例子。 + +#### Nacos Server 中添加配置 + +在命令行执行如下命令，向 Nacos Server 中添加一条配置。**可直接通过 Nacos 控制台注入！** + +> **注意：需要替换 accessToken。** + +```shell +$ curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?accessToken=XXXXXXXXXXXXXXXXXXXXXXXX&dataId=nacos-config-example.properties&group=DEFAULT_GROUP&content=spring.cloud.nacos.config.serverAddr=127.0.0.1:8848%0Aspring.cloud.nacos.config.prefix=PREFIX%0Aspring.cloud.nacos.config.group=GROUP%0Aspring.cloud.nacos.config.namespace=NAMESPACE" +``` + +添加的配置详情如下： + +```properties +# dataId 为 nacos-config-example.properties +# group 为 DEFAULT_GROUP + +# 内容如下: + +spring.cloud.nacos.config.serveraddr=127.0.0.1:8848 +spring.cloud.nacos.config.prefix=PREFIX +spring.cloud.nacos.config.group=GROUP +spring.cloud.nacos.config.namespace=NAMESPACE +``` + +#### 应用启动 + +1. 增加配置，在应用的 `/src/main/resources/application.yml` 中添加基本配置信息； + + ```yml + server: + port: 18084 + management: + endpoints: + web: + exposure: + include: '*' + ``` + +2. 启动应用，支持 IDE 直接启动和编译打包后启动。 + + 1. IDE直接启动：找到主类 `NacosConfigApplication`，执行 main 方法启动应用。 + 2. 打包编译后启动：首先执行 `mvn clean package` 将工程编译打包，进入 `target` 文件夹执行 `java -jar nacos-config-example.jar` 启动应用。 + +#### 验证 + +##### 验证自动注入 + +在浏览器地址栏输入 `http://127.0.0.1:18084/nacos/bean`，并点击调转，可以看到成功从 Nacos Server 中获取了数据。 + +![get](https://tva1.sinaimg.cn/large/e6c9d24ely1h2gbowleyrj20o40bo753.jpg) + +##### 验证动态刷新 + +1. 执行如下命令，修改 Nacos Server 端的配置数据 + + ```shell + $ curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?accessToken=XXXXXXXXXXXXXXXXXXXXXXXXXXX&dataId=nacos-config-example.properties&group=DEFAULT_GROUP&content=spring.cloud.nacos.config.serveraddr=127.0.0.1:8848%0Aspring.cloud.nacos.config.prefix=PREFIX%0Aspring.cloud.nacos.config.group=DEFAULT_GROUP%0Aspring.cloud.nacos.config.namespace=NAMESPACE" + ``` + +2. 在浏览器地址栏输入 `http://127.0.0.1:18084/nacos/bean`，并点击调转，可以看到应用从 Nacos Server 中获取了最新的数据，group 变成了 DEFAULT_GROUP。 + +![refresh](https://tva1.sinaimg.cn/large/e6c9d24ely1h2gbpram9rj20nq0ccmxz.jpg) + +#### 原理 + +##### Nacos Config 数据结构 + +Nacos Config 主要通过 dataId 和 group 来唯一确定一条配置，假定您已经了解此背景。如果不了解，请参考 [Nacos 文档](https://nacos.io/zh-cn/docs/concepts.html)。 + +Nacos Client 从 Nacos Server 端获取数据时，调用的是此接口 `ConfigService.getConfig(String dataId, String group, long timeoutMs)`。 + +##### Spring Cloud 应用获取数据 + +###### dataID + +在 Nacos Config Starter 中，dataId 的拼接格式如下 + + ${prefix} - ${spring.profiles.active} . ${file-extension} + +* `prefix` 默认为 `spring.application.name` 的值，也可以通过配置项 `spring.cloud.nacos.config.prefix`来配置。 + +* `spring.profiles.active` 即为当前环境对应的 profile，详情可以参考 [Spring Boot文档](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-profiles.html#boot-features-profiles) + + **注意，当 active profile 为空时，对应的连接符 `-` 也将不存在，dataId 的拼接格式变成 `${prefix}`.`${file-extension}`** + +* `file-extension` 为配置内容的数据格式，可以通过配置项 `spring.cloud.nacos.config.file-extension`来配置。 + 目前只支持 `properties` 类型。 + +###### group +* `group` 默认为 `DEFAULT_GROUP`，可以通过 `spring.cloud.nacos.config.group` 配置。 + + +##### 自动注入 +Spring Cloud Alibaba Nacos Config Starter 实现了 `org.springframework.boot.context.config.ConfigDataLoader` 接口，并将优先级设置成了最高。 + +在 Spring Cloud 应用启动阶段，会主动从 Nacos Server 端获取对应的数据，并将获取到的数据转换成 PropertySource 且注入到 Environment 的 PropertySources 属性中，所以使用 @Value 注解也能直接获取 Nacos Server 端配置的内容。 + +##### 动态刷新 + +Nacos Config Starter 默认为所有获取数据成功的 Nacos 的配置项添加了监听功能，在监听到服务端配置发生变化时会实时触发 `org.springframework.cloud.context.refresh.ContextRefresher` 的 refresh 方法 。 + +如果需要对 Bean 进行动态刷新，请参照 Spring 和 Spring Cloud 规范。推荐给类添加 `@RefreshScope` 或 `@ConfigurationProperties ` 注解， + +更多详情请参考 [ContextRefresher Java Doc](http://static.javadoc.io/org.springframework.cloud/spring-cloud-context/2.0.0.RELEASE/org/springframework/cloud/context/refresh/ContextRefresher.html)。 + +#### Endpoint 信息查看 + +Spring Boot 应用支持通过 Endpoint 来暴露相关信息，Spring Cloud Alibaba Nacos Config Starter 也支持这一点。 + +在使用之前需要在 maven 中添加 `spring-boot-starter-actuator`依赖，并在配置中允许 Endpoints 的访问。 + +Spring Boot 3.x 可以通过访问 http://127.0.0.1:18084/actuator/nacosconfig 来访问。 + +![actuator](https://cdn.nlark.com/lark/0/2018/png/54319/1536986344822-279e1edc-ebca-4201-8362-0ddeff240b85.png) + +如上图所示，Sources 表示此客户端从哪些 Nacos Config 配置项中获取了信息，RefreshHistory 表示动态刷新的历史记录，最多保存20条，NacosConfigProperties 则为 Nacos Config Starter 本身的配置。 + +#### More + +##### 更多配置项 +配置项|key|默认值|说明 +----|----|-----|----- +服务端地址|spring.cloud.nacos.config.server-addr||服务器ip和端口 +DataId前缀|spring.cloud.nacos.config.prefix|${spring.application.name}|DataId的前缀，默认值为应用名称 +Group|spring.cloud.nacos.config.group|DEFAULT_GROUP| +DataId后缀及内容文件格式|spring.cloud.nacos.config.file-extension|properties|DataId的后缀，同时也是配置内容的文件格式，目前只支持 properties +配置内容的编码方式|spring.cloud.nacos.config.encode|UTF-8|配置的编码 +获取配置的超时时间|spring.cloud.nacos.config.timeout|3000|单位为 ms +配置的命名空间|spring.cloud.nacos.config.namespace||常用场景之一是不同环境的配置的区分隔离，例如开发测试环境和生产环境的资源隔离等。 +AccessKey|spring.cloud.nacos.config.access-key|| +SecretKey|spring.cloud.nacos.config.secret-key|| +相对路径|spring.cloud.nacos.config.context-path||服务端 API 的相对路径 +接入点|spring.cloud.nacos.config.endpoint||地域的某个服务的入口域名，通过此域名可以动态地拿到服务端地址 +是否开启监听和自动刷新|spring.cloud.nacos.config.refresh-enabled|true| +集群服务名|spring.cloud.nacos.config.cluster-name|| + +### Spring Cloud Alibaba Nacos Discovery + +#### 如何接入 + +在启动 Nacos Discovery 示例进行演示之前，了解一下 Spring Cloud 应用如何接入 Nacos Discovery。 + +**注意 本章节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您无需再进行修改。** + +1. 首先，修改 `pom.xml` 文件，引入 spring-cloud-alibaba-nacos-discovery-starter； + + ```xml + + com.alibaba.cloud + spring-cloud-starter-alibaba-nacos-discovery + + ``` + +2. 在应用的 `/src/main/resources/application.properties` 配置文件中配置 Nacos Server 地址； + + ```properties + spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 + ``` + +3. 使用 @EnableDiscoveryClient 注解开启服务注册与发现功能； + + ```java + @SpringBootApplication + @EnableDiscoveryClient + public class ProviderApplication { + + public static void main(String[] args) { + SpringApplication.run(ProviderApplication.class, args); + } + + @RestController + class EchoController { + @GetMapping(value = "/echo/{string}") + public String echo(@PathVariable String string) { + return string; + } + } + } + ``` + +#### 应用启动 + +1. 增加配置，在 nacos-discovery-provider-example 项目的 `/src/main/resources/application.properties` 中添加基本配置信息； + + ```properties + spring.application.name=service-provider + server.port=18082 + ``` + +2. 启动应用，支持 IDE 直接启动和编译打包后启动。 + + 1. IDE直接启动：找到 nacos-discovery-provider-example 项目的主类 `ProviderApplication`，执行 main 方法启动应用。 + 2. 打包编译后启动：在 nacos-discovery-provider-example 项目中执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar nacos-discovery-provider-example.jar`启动应用。 + +#### 查询服务验证 + +在浏览器输入此地址 `http://127.0.0.1:8848/nacos/v1/ns/catalog/instances?serviceName=service-provider&clusterName=DEFAULT&pageSize=10&pageNo=1&namespaceId=`，并点击跳转，可以看到服务节点已经成功注册到 Nacos Server。 + +![查询服务](https://cdn.nlark.com/lark/0/2018/png/54319/1536986288092-5cf96af9-9a26-466b-85f6-39ad1d92dfdc.png) + +#### 服务发现集成 Spring Cloud Loadbalancer + +```xml + + + org.springframework.cloud + spring-cloud-loadbalancer + + +``` + +增加如下配置，使用 Spring Cloud Alibaba 社区针对 Spring Cloud Loadbalancer 负载均衡依赖提供的负载均衡策略，以便使用 Spring Cloud Alibaba 提供的所有的能力： + +```properties +spring.cloud.loadbalancer.ribbon.enabled=false +spring.cloud.loadbalancer.nacos.enabled=true +``` + +#### IPv4 至 IPv6 地址迁移方案 + +##### IPv4 和 IPv6 地址双注册 + +在配置完成 Spring Cloud Loadbalancer 作为负载均衡策略后，应用启动后会默认将微服务的 IPv4 地址和 IPv6 地址注册到注册中心中，其中 IPv4 地址会存放在 Nacos 服务列表中的 IP 字段下，IPv6 地址在 Nacos 的 metadata 字段中，其对应的 Key 为 IPv6。当服务消费者调用服务提供者时，会根据自身的 IP 地址栈支持情况，选择合适的 IP 地址类型发起服务调用。具体规则： +（1）服务消费者本身支持 IPv4 和 IPv6 双地址栈或仅支持 IPv6 地址栈的情况下，服务消费者会使用服务提供的 IPv6 地址发起服务调用，IPv6 地址调用失败如本身还同事支持 IPv4 地址栈时，暂不支持切换到 IPv4 再发起重试调用； +（2）服务消费者本身仅支持 IPv4 单地址栈的情况下，服务消费者会使用服务提供的 IPv4 地址发起服务调用。 + +##### 仅注册 IPv4 +如果您只想使用 IPv4 地址进行注册，可以在 application.properties 使用以下配置： + +```properties +spring.cloud.nacos.discovery.ip-type=IPv4 +``` + +##### 仅注册 IPv6 + +如果您只想使用 IPv6 地址，可以在 application.properties 使用以下配置： + +```properties +spring.cloud.nacos.discovery.ip-type=IPv6 +``` + +#### 使用 RestTemplate 和 FeignClient + +下面将分析 nacos-discovery-consumer-example 项目的代码，演示如何 RestTemplate 与 FeignClient。 + +**注意 本章节只是为了便于理解接入方式，本示例代码中已经完成接入工作，您无需再进行修改。此处只涉及 Ribbon、RestTemplate、FeignClient 相关的内容，如果已经使用了其他服务发现组件，可以通过直接替换依赖来接入 Nacos Discovery。** + +1. 添加 @LoadBalanced 注解，使得 RestTemplate 接入 Ribbon + + ```java + @Bean + @LoadBalanced + public RestTemplate restTemplate() { + return new RestTemplate(); + } + ``` + +2. FeignClient 已经默认集成了 Ribbon ，此处演示如何配置一个 FeignClient。 + + ```java + @FeignClient(name = "service-provider") + public interface EchoService { + @GetMapping(value = "/echo/{str}") + String echo(@PathVariable("str") String str); + } + ``` + + 使用 @FeignClient 注解将 EchoService 这个接口包装成一个 FeignClient，属性 name 对应服务名 service-provider。 + + echo 方法上的 @RequestMapping 注解将 echo 方法与 URL "/echo/{str}" 相对应，@PathVariable 注解将 URL 路径中的 `{str}` 对应成 echo 方法的参数 str。 + +3. 完成以上配置后，将两者自动注入到 TestController 中。 + + ```java + @RestController + public class TestController { + + @Autowired + private RestTemplate restTemplate; + @Autowired + private EchoService echoService; + + @GetMapping(value = "/echo-rest/{str}") + public String rest(@PathVariable String str) { + return restTemplate.getForObject("http://service-provider/echo/" + str, String.class); + } + @GetMapping(value = "/echo-feign/{str}") + public String feign(@PathVariable String str) { + return echoService.echo(str); + } + } + ``` + +4. 配置必要的配置，在 nacos-discovery-consumer-example 项目的 `/src/main/resources/application.properties` 中添加基本配置信息 + + ```java + @RestController + public class TestController { + + @Autowired + private RestTemplate restTemplate; + @Autowired + private EchoService echoService; + + @GetMapping(value = "/echo-rest/{str}") + public String rest(@PathVariable String str) { + return restTemplate.getForObject("http://service-provider/echo/" + str, String.class); + } + @GetMapping(value = "/echo-feign/{str}") + public String feign(@PathVariable String str) { + return echoService.echo(str); + } + } + ``` + +5.启动应用，支持 IDE 直接启动和编译打包后启动。 + +1. IDE 直接启动：找到 nacos-discovery-consumer-example 项目的主类 `ConsumerApplication`，执行 main 方法启动应用。 +2. 打包编译后启动：在 nacos-discovery-consumer-example 项目中执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar nacos-discovery-consumer-example.jar` 启动应用。 + +#### 验证 + +1. 在浏览器地址栏中输入 http://127.0.0.1:18083/echo-rest/1234，点击跳转，可以看到浏览器显示了 nacos-discovery-provider-example 返回的消息 "hello Nacos Discovery 1234"，证明服务发现生效。 + +![rest](https://cdn.nlark.com/lark/0/2018/png/54319/1536986302124-ee27670d-bdcc-4210-9f5d-875acec6d3ea.png) + +2. 在浏览器地址栏中输入 http://127.0.0.1:18083/echo-feign/12345，点击跳转，可以看到浏览器显示 nacos-discovery-provider-example 返回的消息 "hello Nacos Discovery 12345"，证明服务发现生效。 + +![feign](https://cdn.nlark.com/lark/0/2018/png/54319/1536986311685-6d0c1f9b-a453-4ec3-88ab-f7922d210f65.png) + +#### 原理 + +##### 服务注册 + +Spring Cloud Alibaba Nacos Discovery 遵循了 Spring Cloud Common 标准，实现了 AutoServiceRegistration、ServiceRegistry、Registration 这三个接口。 + +在 Spring Cloud 应用的启动阶段，监听了 WebServerInitializedEvent 事件，当 Web 容器初始化完成后，即收到 WebServerInitializedEvent 事件后，会触发注册的动作，调用 ServiceRegistry 的 register 方法，将服务注册到 Nacos Server。 + +#### Endpoint 信息查看 + +Spring Boot 应用支持通过 Endpoint 来暴露相关信息，Spring Cloud Alibaba Nacos Discovery Starter 也支持这一点。 + +在使用之前需要在 maven 中添加 `spring-boot-starter-actuator`依赖，并在配置中允许 Endpoints 的访问。 + +Spring Boot 3.x 可以通过访问 http://127.0.0.1:18083/actuator/nacos-discovery 来访问。 + +![actuator](https://cdn.nlark.com/lark/0/2018/png/54319/1536986319285-d542dc5f-5dff-462a-9f52-7254776bcd99.png) + +如上图所示，NacosDiscoveryProperties 则为 Spring Cloud Alibaba Nacos Discovery 本身的配置，也包括本机注册的内容，subscribe 为本机已订阅的服务信息。 + +#### More + +##### 更多配置项 + +配置项|key|默认值|说明 +----|----|-----|----- +服务端地址|spring.cloud.nacos.discovery.server-addr|| +服务名|spring.cloud.nacos.discovery.service|${spring.application.name}|注册到Nacos上的服务名称，默认值为应用名称 +权重|spring.cloud.nacos.discovery.weight|1|取值范围 1 到 100，数值越大，权重越大 +网卡名|spring.cloud.nacos.discovery.network-interface||当IP未配置时，注册的IP为此网卡所对应的IP地址，如果此项也未配置，则默认取第一块网卡的地址 +注册的IP地址|spring.cloud.nacos.discovery.ip||优先级最高 +注册的IP地址类型|spring.cloud.nacos.discovery.ip-type|双栈地址|可以配置IPv4和IPv6两种类型，如果网卡同类型IP地址存在多个，希望制定特定网段地址，可使用`spring.cloud.inetutils.preferred-networks`配置筛选地址 +注册的端口|spring.cloud.nacos.discovery.port|-1|默认情况下不用配置，会自动探测 +命名空间|spring.cloud.nacos.discovery.namespace||常用场景之一是不同环境的注册的区分隔离，例如开发测试环境和生产环境的资源（如配置、服务）隔离等。 +AccessKey|spring.cloud.nacos.discovery.access-key|| +SecretKey|spring.cloud.nacos.discovery.secret-key|| +Metadata|spring.cloud.nacos.discovery.metadata||使用Map格式配置 +日志文件名|spring.cloud.nacos.discovery.log-name|| +集群|spring.cloud.nacos.discovery.cluster-name|DEFAULT|Nacos集群名称 +接入点|spring.cloud.nacos.discovery.endpoint||地域的某个服务的入口域名，通过此域名可以动态地拿到服务端地址 +是否集成LoadBalancer|spring.cloud.loadbalancer.nacos.enabled|false| +是否开启Nacos Watch|spring.cloud.nacos.discovery.watch.enabled|false|可以设置成true来开启 watch +是否启用Nacos|spring.cloud.nacos.discovery.enabled|true|默认启动，设置为false时会关闭自动向Nacos注册的功能 + +### Spring Cloud Alibaba Nacos 集成 Spring Cloud Gateway + +#### 如何接入 + +在启动示例进行演示之前，了解一下 Spring Cloud 应用如何接入 Spring Cloud 如何接入 Nacos Discovery、Spring Cloud Gateway。 + +**注意 本章节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您无需再进行修改。** + +1. 首先，修改 `pom.xml` 文件，引入 Spring Cloud Alibaba Nacos Discovery Starter、Spring Cloud Gateway Starter。 + + ```xml + + com.alibaba.cloud + spring-cloud-starter-alibaba-nacos-discovery + + + org.springframework.cloud + spring-cloud-starter-gateway + + ``` + +2. 在应用的 `/src/main/resources/application.properties` 配置文件中配置 Nacos Server 地址 + + ```properties + spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 + ``` + +3. 在应用的 `/src/main/resources/application.properties` 配置文件中配置 Spring Cloud Gateway 路由 + + ```properties + spring.cloud.gateway.routes[0].id=nacos-route + spring.cloud.gateway.routes[0].uri=lb://service-gateway-provider + spring.cloud.gateway.routes[0].predicates[0].name=Path + spring.cloud.gateway.routes[0].predicates[0].args[pattern]=/nacos/** + spring.cloud.gateway.routes[0].filters[0]=StripPrefix=1 + ``` + +4. 使用 @EnableDiscoveryClient 注解开启服务注册与发现功能 + + ```java + @SpringBootApplication + @EnableDiscoveryClient + public class GatewayApplication { + + public static void main(String[] args) { + SpringApplication.run(GatewayApplication.class, args); + } + + } + ```c + +#### Spring Cloud Gateway 应用启动 + +启动应用，支持 IDE 直接启动和编译打包后启动。 + +1. IDE直接启动：找到 nacos-gateway-discovery-example 项目的主类 `GatewayApplication`，执行 main 方法启动应用。 +2. 打包编译后启动：在 nacos-gateway-discovery-example 项目中执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar nacos-gateway-discovery-example.jar`启动应用。 + +#### 服务提供方应用启动 + +启动应用，支持 IDE 直接启动和编译打包后启动。 + +1. IDE 直接启动：找到 nacos-gateway-provider-example 项目的主类 `ProviderApplication`，执行 main 方法启动应用。 +2. 打包编译后启动：在 nacos-gateway-provider-example 项目中执行 `mvn clean package` 将工程编译打包，然后执行 `java -jar nacos-gateway-provider-example.jar`启动应用。 + +#### 验证 + +1. + +```bash + curl 'http://127.0.0.1:18085/nacos/echo/hello-world' + + hello Nacos Discovery hello-world⏎ +``` + +2. + +```bash + curl 'http://127.0.0.1:18085/nacos/divide?a=6&b=2' + + 3⏎ +``` + +## Native Image构建 + +请参考 Spring Cloud Alibaba 官网中的 [Graalvm 快速开始](https://sca.aliyun.com/zh-cn/docs/2021.0.0.0/user-guide/graalvm/quick-start) + +## 更多介绍 + +Nacos 为用户提供包括动态服务发现，配置管理，服务管理等服务基础设施，帮助用户更灵活，更轻松地构建，交付和管理他们的微服务平台，基于 Nacos, 用户可以更快速的构建以“服务”为中心的现代云原生应用。Nacos 可以和 Spring Cloud、Kubernetes/CNCF、Dubbo 等微服务生态无缝融合，为用户提供更卓越的体验。更多 Nacos 相关的信息，请参考 [Nacos 项目](https://github.com/alibaba/Nacos)。 + +如果您对 Spring Cloud Nacos Discovery 有任何建议或想法，欢迎在 issue 中或者通过其他社区渠道向我们提出。 + diff --git a/spring-cloud-alibaba-examples/nacos-example/readme.md b/spring-cloud-alibaba-examples/nacos-example/readme.md new file mode 100644 index 000000000..3bd00cece --- /dev/null +++ b/spring-cloud-alibaba-examples/nacos-example/readme.md @@ -0,0 +1,609 @@ +# Spring Cloud Alibaba Nacos Example + +## Project description + +This project demonstrates how to use Spring Cloud Alibaba Nacos related Starters to complete the service discovery and configuration management of Spring Cloud applications. + +[Nacos](https://github.com/alibaba/Nacos) It is Alibaba's open source dynamic service discovery, configuration management and service management platform that is easier to build cloud-native applications. + +## Nacos Server 2.2.x is properly configured and started + +In Nacos 2.2.x, functions related to user authentication are added. When starting Nacos Server for the first time, it needs to be configured correctly to avoid the problem of startup failure. + +### Download Nacos Server + +> The Nacos serv version used in this example is 2.2.0! + +Nacos supports both direct download and source code construction. **Nacos Server version 2.2.0 is recommended for Spring Cloud Alibaba 2021.x.** + +1. Direct download: [Nacos Server download page](https://github.com/alibaba/nacos/releases) +2. Source code construction: Enter Nacos [Github project page](https://github.com/alibaba/nacos), git clone the code to the local compilation and packaging [参考文档](https://nacos.io/zh-cn/docs/quick-start.html). + +### Configure the Nacos Server + +Open the `\nacos-server-2.2.0\conf\application.properties` configuration file and modify the following configuration items: + +#### Configure the data source + +Take the MySQL database as an example here, and use the `nacos-server-2.2.0\conf\mysql-schema.sql` initialization database table file. Modify the following configuration as well + +```properties +#*************** Config Module Related Configurations ***************# +### If use MySQL as datasource: +spring.datasource.platform=mysql + +### Count of DB: +db.num=1 + +### Connect URL of DB: +db.url.0=jdbc:mysql://127.0.0.1:3306/nacos?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=UTC&allowPublicKeyRetrieval=true +db.user.0=root +db.password.0=root + +### Connection pool configuration: hikariCP +db.pool.config.connectionTimeout=30000 +db.pool.config.validationTimeout=10000 +db.pool.config.maximumPoolSize=20 +db.pool.config.minimumIdle=2 +``` + +#### Turn on authentication + +**Note: If it is not enabled, login failure exception will occur in 2.2.x!** + +```properties +### The auth system to use, currently only 'nacos' and 'ldap' is supported: +nacos.core.auth.system.type=nacos + +### If turn on auth system: +nacos.core.auth.enabled=true +``` + +#### Set the server authentication key + +```properties +nacos.core.auth.server.identity.key=test +nacos.core.auth.server.identity.value=test +``` + +#### Set the default token + +```properties +### The default token (Base64 String): +nacos.core.auth.plugin.nacos.token.secret.key=SecretKey012345678901234567890123456789012345678901234567890123456789 +``` + +** When using the Nacos service discovery and configuration function, be sure to configure `username` and `password` attribute, otherwise the user will not be found! ** + +#### Open API authentication + +Authentication is required when using the Open api interface in nacos server 2.2.x: For more details, please refer to: [Nacos api authentication](https://nacos.io/zh-cn/docs/auth.html) + +1. Obtain accessToken: Use username and password to log in to the nacos server: + + `curl -X POST '127.0.0.1:8848/nacos/v1/auth/login' -d 'username=nacos&password=nacos'` + + If the username and password are correct, the returned information is as follows: + + `{"accessToken":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyOTE2Nn0.2TogGhhr11_vLEjqKko1HJHUJEmsPuCxkur-CfNojDo", "tokenTtl": 18000, "globalAdmin": true}` + +2. Use accessToken to request the nacos api interface: + + `curl -X GET '127.0.0.1:8848/nacos/v1/cs/configs?accessToken=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJuYWNvcyIsImV4cCI6MTYwNTYyMzkyM30.O-s2yWfDSUZ7Svd3Vs7jy9tsfDNHs1SuebJB4KlNY8Q&dataId=nacos.example.1&group=nacos_group'` + +### Start the Nacos Server + +1. Start Nacos Server, enter the folder after downloading to the local and decompressing (enter the folder after compiling and packaging by using the source code construction method), then enter its relative folder `nacos/bin`, and execute the following command according to the actual situation of the operating system. [详情参考此文档](https://nacos.io/zh-cn/docs/quick-start.html)。 + + 1. Linux/Unix/Mac operating system, execute the command + + `sh startup.sh -m standalone` + + 2. Windows operating system, executing command + + `cmd startup.cmd` + +2. Access Nacos Server Console. + + The browser enters the address http://127.0.0.1:8848/nacos , **The first login needs to bind the nacos user, because the new version adds authentication, and the user name and password need to be configured during application registration and configuration binding.** + +## Nacos application example + +### Spring Cloud Alibaba Nacos Config + +#### Application access + +Before starting the application sample to demonstrate the project function, first understand how the Spring Cloud application accesses Nacos Config as the service configuration center. + +**Note that this section is only for the convenience of understanding the access method. The access work has been completed in this sample code, and no further modification is required.** + +1. First, modify the `pom.xml` file to introduce spring-cloud-starter-alibaba-nacos-config; + + ```xml + + com.alibaba.cloud + spring-cloud-starter-alibaba-nacos-config + + ``` + +2. Configuring a Nacos address in an `/src/main/resources/application.yaml` applied configuration file and introducing a service configuration; + + ```yml + spring: + cloud: + nacos: + serverAddr: 127.0.0.1:8848 + username: 'nacos' + password: 'nacos' + config: + import: + - nacos:nacos-config-example.properties?refresh=true&group=DEFAULT_GROUP + ``` + +3. After completing the above two steps, the application will obtain the corresponding configuration from Nacos Server and add it to the Property Sources of Spring Environment. There are four ways to save a portion of the Nacos configuration using the Nacos Configuration Center: + - BeanAutoRefres hConfig Example: An example of supporting automatic refresh of configuration changes by configuring configuration information as beans; + - ConfigListenerEx ample: example of monitoring configuration information; + - Docking Interface Example: An example of docking the Nacos interface and completing the addition, deletion, modification and query of the configuration information through the interface; + - ValueAnnotation Example: An example of obtaining configuration information through the @ Value annotation. + +#### Add Configuration in Nacos Server + +Add a configuration to the Nacos Server by executing the following command from the command line. **Can be injected directly through the Nacos console!** + +```shell +$ curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?accessToken=XXXXXXXXXXXXXXXXXXXXXXXXXXX&dataId=nacos-config-example.properties&group=DEFAULT_GROUP&content=spring.cloud.nacos.config.serverAddr=127.0.0.1:8848%0Aspring.cloud.nacos.config.prefix=PREFIX%0Aspring.cloud.nacos.config.group=GROUP%0Aspring.cloud.nacos.config.namespace=NAMESPACE" +``` + +Details of the added configuration are as follows: + +```properties +# dataId is nacos-config-example.properties +# group is DEFAULT_GROUP + +# content is: + +spring.cloud.nacos.config.serveraddr=127.0.0.1:8848 +spring.cloud.nacos.config.prefix=PREFIX +spring.cloud.nacos.config.group=GROUP +spring.cloud.nacos.config.namespace=NAMESPACE +``` + +#### The application starts + +1. Add configuration, and add basic configuration information in the application `/src/main/resources/application.yml`; + + ```yml + server: + port: 18084 + management: + endpoints: + web: + exposure: + include: '*' + ``` + +2. Start the application, support IDE direct start and start after compilation and packaging. + + 1. IDE direct startup: find the main class `NacosConfigApplication` and execute the main method to start the application. + 2. Start after packaging and compiling: First `mvn clean package`, compile and package the project, and then enter the `target` folder to `java -jar nacos-config-example.jar` start the application. + +#### Validate + +##### Verify automatic injection + +Enter `http://127.0.0.1:18084/nacos/bean` in the browser address bar and click turn around to see that the data is successfully obtained from the Nacos Server. + +![get](https://tva1.sinaimg.cn/large/e6c9d24ely1h2gbowleyrj20o40bo753.jpg) + +##### Verify dynamic refresh + +1. Execute the following command to modify the configuration data on the Nacos Server side + + ```shell + $ curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?accessToken=XXXXXXXXXXXXXXXXXXXXXXXXXXX&dataId=nacos-config-example.properties&group=DEFAULT_GROUP&content=spring.cloud.nacos.config.serveraddr=127.0.0.1:8848%0Aspring.cloud.nacos.config.prefix=PREFIX%0Aspring.cloud.nacos.config.group=DEFAULT_GROUP%0Aspring.cloud.nacos.config.namespace=NAMESPACE" + ``` + +2. Type `http://127.0.0.1:18084/nacos/bean` in the address bar of the browser and click Turn, and you can see that the application obtains the latest data from the Nacos Server, and the group becomes the DEFAULT _ GROUP. + +![refresh](https://tva1.sinaimg.cn/large/e6c9d24ely1h2gbpram9rj20nq0ccmxz.jpg) + +#### Principle + +##### Nacos Config Data Structure + +Nacos Config uniquely identifies a piece of configuration primarily by dataId and group, assuming you already know this background. If you don't know, please refer to [Nacos 文档](https://nacos.io/zh-cn/docs/concepts.html). + +When the Nacos Client obtains data from the Nacos Server, it calls this interface `ConfigService.getConfig(String dataId, String group, long timeoutMs)`. + +##### Spring Cloud App Get Data + +###### dataID + +In the Nacos Config Starter, the concatenation format of dataId is as follow + + ${prefix} - ${spring.profiles.active} . ${file-extension} + +* The `prefix` default value is `spring.application.name`. It can also be configured through configuration items `spring.cloud.nacos.config.prefix`. + +* `spring.profiles.active` This is the profile corresponding to the current environment. For details, please refer to + + ** Note that when the active profile is empty, the corresponding connector `-` does not exist, and the concatenation format of dataId becomes `${prefix}`. `${file-extension}` ** + +* `file-extension` It is used to configure the data format of content, which can be configured by configuration item `spring.cloud.nacos.config.file-extension`. Currently only types are supported `properties`. + +###### group +* `group` The default is `DEFAULT_GROUP`, which can be `spring.cloud.nacos.config.group` configured. + + +##### Automatic injection +The Spring Cloud Alibaba Nacos Config Starter implements the `org.springframework.boot.context.config.ConfigDataLoader` interface and sets the priority to the highest. + +During the Spring Cloud application startup phase, it will actively obtain the corresponding data from the Nacos Server side, convert the obtained data into PropertySource, and inject it into the Property Sources attribute of the Environment. Therefore, the @ Value annotation can also be used to directly obtain the contents of the Nacos Server configuration. + +##### Dynamic refresh + +By default, the Nacos Config Starter is a refresh method that is triggered `org.springframework.cloud.context.refresh.ContextRefresher` in real time when the monitoring function is added to the configuration item of all Nacos that have successfully obtained data and changes in the server configuration are monitored. + +If you need to refresh the Bean dynamically, refer to the Spring and Spring Cloud specifications. It is recommended that you add `@RefreshScope` or `@ConfigurationProperties ` annotate the class, + +For more details, please refer to [ContextRefresher Java Doc](http://static.javadoc.io/org.springframework.cloud/spring-cloud-context/2.0.0.RELEASE/org/springframework/cloud/context/refresh/ContextRefresher.html). + +#### Endpoint information viewing + +Spring Boot applications support the use of Endpoints to expose relevant information, as does the Spring Cloud Alibaba Nacos Config Starter. + +Before using it, you need to add `spring-boot-starter-actuator` a dependency in Maven and allow Endpoints access in the configuration. + +Spring Boot 3.x can be accessed by visiting http://127.0.0.1:18084/actuator/nacosconfig . + +![actuator](https://cdn.nlark.com/lark/0/2018/png/54319/1536986344822-279e1edc-ebca-4201-8362-0ddeff240b85.png) + +As shown in the figure above, Sources indicates which Nacos Config configuration items the client has obtained information from, and RefreshHistory indicates the history of dynamic refresh, with a maximum of 20 entries saved. NacosConfig Properties is the configuration of the Nacos Config Starter itself. + +#### More + +##### More configuration items +Configuration item | key | Default value | Description +----|----|-----|----- +Server address | spring. Cloud. Nacos. Config. Server-addr | | server IP and port +Prefix of DataId | spring. Cloud. Nacos. Config. Prefix | ${ spring. Application. Name } | Prefix of DataId. The default value is the application name +Group|spring.cloud.nacos.config.group|DEFAULT_GROUP| +Suffix of DataId and content file format | spring. Cloud. Nacos. Config. File -extension | properties | Suffix of DataId, which is also the file format of configuration content. Currently, only properties is supported +Encoding method of the configured content | spring. Cloud. Nacos. Config. Encode | UTF-8 | Configured encoding +| Obtain the configured timeout | spring. Cloud. Nacos. Config. Timeout | 3000 | Unit: ms | +Namespace of configuration | spring. Cloud. Nacos. Config. Namespace | | One of the common scenarios is to distinguish and isolate the configurations of different environments, such as the resource isolation between the development and testing environments and the production environment. +AccessKey|spring.cloud.nacos.config.access-key|| +SecretKey|spring.cloud.nacos.config.secret-key|| +Relative path | spring. Cloud. Nacos. Config. Context-path | | Relative path of the server API +Access point | spring. Cloud. Nacos. Config. Endpoint | | The domain name of a service in a region. The server address can be obtained dynamically through this domain name +Whether to enable listening and automatic refresh | spring. Cloud. Nacos. Config. Refresh -enabled | true | +Cluster service name | spring. Cloud. Nacos. Config. Cluster -name | | + +### Spring Cloud Alibaba Nacos Discovery + +#### How to access + +Before launching the Nacos Discovery sample for demonstration, take a look at how Spring Cloud applications access Nacos Discovery. + +**Note that this section is only for your convenience to understand the access method. The access work has been completed in this sample code, and you do not need to modify it.** + +1. First, modify the `pom.xml` file and introduce spring-cloud-alibaba-nacos-discovery-starter; + + ```xml + + com.alibaba.cloud + spring-cloud-starter-alibaba-nacos-discovery + + ``` + +2. Configuring a Nacos Server address in an `/src/main/resources/application.properties` applied configuration file; + + ```properties + spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 + ``` + +3. Use @ EnableDiscoveryClient annotation to enable service registration and discovery; + + ```java + @SpringBootApplication + @EnableDiscoveryClient + public class ProviderApplication { + + public static void main(String[] args) { + SpringApplication.run(ProviderApplication.class, args); + } + + @RestController + class EchoController { + @GetMapping(value = "/echo/{string}") + public String echo(@PathVariable String string) { + return string; + } + } + } + ``` + +#### The application starts + +1. Add the configuration, and add the basic configuration information in the nacos-discovery-provider-example project `/src/main/resources/application.properties`; + + ```properties + spring.application.name=service-provider + server.port=18082 + ``` + +2. Start the application, support IDE direct start and start after compilation and packaging. + + 1. IDE direct startup: Find the main class `ProviderApplication` of the nacos-discovery-provider-example project, and execute the main method to start the application. + 2. Start after compilation: Compile and package `mvn clean package` the project in the nacos-discovery-provider-example project, and then `java -jar nacos-discovery-provider-example.jar` start the application. + +#### Query service validation + +Enter this address `http://127.0.0.1:8848/nacos/v1/ns/catalog/instances?serviceName=service-provider&clusterName=DEFAULT&pageSize=10&pageNo=1&namespaceId=` in the browser and click Jump to see that the service node has been successfully registered to the Nacos Server. + +![查询服务](https://cdn.nlark.com/lark/0/2018/png/54319/1536986288092-5cf96af9-9a26-466b-85f6-39ad1d92dfdc.png) + +#### Service discovery integration Spring Cloud Loadbalancer. + +```xml + + + org.springframework.cloud + spring-cloud-loadbalancer + + +``` + +Add the following configuration to use the load balancing strategy provided by the Spring Cloud Alibaba community for Spring Cloud Loadbalancer load balancing dependencies, so as to use all the capabilities provided by the Spring Cloud Alibaba: + +```properties +spring.cloud.loadbalancer.ribbon.enabled=false +spring.cloud.loadbalancer.nacos.enabled=true +``` + +#### IPv4 to IPv6 address migration schema + +##### Dual registration of IPv4 and IPv6 addresses + +After configuring the Spring Cloud Loadbalancer as a load balancing strategy, the application will register the IPv4 address and IPv6 address of the microservice in the registration center by default after starting, where the IPv4 address will be stored under the IP field in the Nacos service list. The IPv6 address is in the metadata field of Nacos, and its corresponding Key is IPv6. When the service consumer calls the service provider, it will select the appropriate IP address type to initiate the service call according to its own IP address stack support. Specific rules: (1) If the service consumer itself supports both IPv4 and IPv6 address stacks or only supports IPv6 address stacks, the service consumer will use the IPv6 address provided by the service to initiate a service call. If the IPv6 address call fails, if it also supports IPv4 address stacks, (2) When the service consumer itself only supports IPv4 single address stack, the service consumer will use the IPv4 address provided by the service to initiate a service call. + +##### Register IPv4 only +If you want to register using only IPv4 addresses, you can use the following configuration at the application. Properties: + +```properties +spring.cloud.nacos.discovery.ip-type=IPv4 +``` + +##### Register for IPv6 only + +If you want to use only IPv6 addresses, you can use the following configuration on the application. Properties: + +```properties +spring.cloud.nacos.discovery.ip-type=IPv6 +``` + +#### Using RestTemplate and FeignClient + +Here's a look at the code for the nacos-discovery-consumer-example project to show how to RestTemplate and FeignClient. + +**Note that this section is only for the convenience of understanding the access method. The access work has been completed in this sample code, and you do not need to modify it. Only Ribbon, RestTemplate and FeignClient are involved here. If other service discovery components have been used, Nacos Discovery can be accessed by directly replacing dependencies.** + +1. Add the @ LoadBalanced annotation to make the RestTemplate access the Ribbon + + ```java + @Bean + @LoadBalanced + public RestTemplate restTemplate() { + return new RestTemplate(); + } + ``` + +2. FeignClient has been integrated with Ribbon by default. Here is how to configure a FeignClient. + + ```java + @FeignClient(name = "service-provider") + public interface EchoService { + @GetMapping(value = "/echo/{str}") + String echo(@PathVariable("str") String str); + } + ``` + + Use the @ FeignClient annotation to wrap the Echo Service interface as a FeignClient, and the attribute name corresponds to the service name service-provider. + + The @ RequestMapping annotation on the echo method corresponds the echo method to the URL "/echo/{ str}", and the @ PathVariable annotation corresponds the str in `{str}` the URL path to the parameter of the echo method. + +3. After the above configuration is completed, the two are automatically injected into the TestController. + + ```java + @RestController + public class TestController { + + @Autowired + private RestTemplate restTemplate; + @Autowired + private EchoService echoService; + + @GetMapping(value = "/echo-rest/{str}") + public String rest(@PathVariable String str) { + return restTemplate.getForObject("http://service-provider/echo/" + str, String.class); + } + @GetMapping(value = "/echo-feign/{str}") + public String feign(@PathVariable String str) { + return echoService.echo(str); + } + } + ``` + +4. Configure the necessary configuration and add the basic configuration information in the nacos-discovery-consumer-example project `/src/main/resources/application.properties`. + + ```java + @RestController + public class TestController { + + @Autowired + private RestTemplate restTemplate; + @Autowired + private EchoService echoService; + + @GetMapping(value = "/echo-rest/{str}") + public String rest(@PathVariable String str) { + return restTemplate.getForObject("http://service-provider/echo/" + str, String.class); + } + @GetMapping(value = "/echo-feign/{str}") + public String feign(@PathVariable String str) { + return echoService.echo(str); + } + } + ``` + +5.Start the application, support IDE direct start and start after compilation and packaging. + +1. IDE direct startup: Find the main class `ConsumerApplication` of the nacos-discovery-consumer-example project, and execute the main method to start the application. +2. Start after compilation: Compile and package `mvn clean package` the project in the nacos-discovery-consumer-example project, and then `java -jar nacos-discovery-consumer-example.jar` start the application. + +#### Validate + +1. Enter http://127.0.0.1:18083/echo-rest/1234，点击跳转，可以看到浏览器显示了 the message "hello Nacos Discovery 1234" returned by nacos-discovery-provider-example in the browser address bar to prove that the service discovery is valid. + +![rest](https://cdn.nlark.com/lark/0/2018/png/54319/1536986302124-ee27670d-bdcc-4210-9f5d-875acec6d3ea.png) + +2. Enter http://127.0.0.1:18083/echo-feign/12345，点击跳转，可以看到浏览器显示 the message "hello Nacos Discovery 12345" returned by nacos-discovery-provider-example in the browser address bar to prove that the service discovery is effective. + +![feign](https://cdn.nlark.com/lark/0/2018/png/54319/1536986311685-6d0c1f9b-a453-4ec3-88ab-f7922d210f65.png) + +#### Principle + +##### Service registration + +The Spring Cloud Alibaba Nacos Discovery follows the Spring cloud Common standard. The three interfaces of AutoService Registration, Service Registry and Registration are implemented. + +In the startup phase of the Spring Cloud application, the WebServerInitializedEvent event is monitored. After the Web container is initialized, that is, after the WebServerInitializedEvent event is received, the registration action is triggered. Call the register method of the Service Registry to register the service with the Nacos Server. + +#### Endpoint information viewing + +Spring Boot applications support the use of Endpoints to expose relevant information, as does the Spring Cloud Alibaba Nacos Discovery Starter. + +Before using it, you need to add `spring-boot-starter-actuator` a dependency in Maven and allow Endpoints access in the configuration. + +Spring Boot 3.x can be accessed by visiting http://127.0.0.1:18083/actuator/nacos-discovery . + +![actuator](https://cdn.nlark.com/lark/0/2018/png/54319/1536986319285-d542dc5f-5dff-462a-9f52-7254776bcd99.png) + +As shown in the figure above, NacosDiscovery Properties refers to the configuration of the Spring Cloud Alibaba Nacos Discovery itself, including the content registered by the local machine, and subscribe refers to the subscribed service information of the local machine. + +#### More + +##### More configuration items + +Configuration item | key | Default value | Description +----|----|-----|----- +Server address | spring. Cloud. Nacos. Discovery. Server -addr | | +Service Name | spring. Cloud. Nacos. Discovery. Service | ${ spring. Application. Name } | The name of the service registered to Nacos. The default is the application name +Weight | spring. Cloud. Nacos. Discovery. Weight | 1 | Values range from 1 to 100. The larger the value, the greater the weight +Network card name | spring. Cloud. Nacos. Discovery. Network -interface | | When IP is not configured, the registered IP is the IP address corresponding to this network card. If this item is not configured, the address of the first network card is used by default +Registered IP Address | spring. Cloud. Nacos. Discovery. IP | | Highest Priority +Registered IP address type | spring. Cloud. Nacos. Discovery. IP -type | Dual stack address | Both IPv4 and IPv6 types can be configured. If there are multiple IP addresses of the same type in the network card and you want to designate a specific network segment address, you can configure the filtering address with `spring.cloud.inetutils.preferred-networks` +Registered port | spring. Cloud. Nacos. Discovery. Port | -1 | is not configured by default and will be detected automatically +Namespace | spring. Cloud. Nacos. Discovery. Namespace | | One of the common scenarios is to distinguish and isolate the registration of different environments, such as the isolation of resources (such as configurations and services) between the development and testing environments and the production environment. +AccessKey|spring.cloud.nacos.discovery.access-key|| +SecretKey|spring.cloud.nacos.discovery.secret-key|| +Metadata | spring. Cloud. Nacos. Discovery. Metadata | | Configure using Map format +Log file name | spring. Cloud. Nacos. Discovery. Log -name | | +Cluster | spring. Cloud. Nacos. Discovery. Cluster -name | DEFAULT | Nacos cluster name +Access point | spring. Cloud. Nacos. Discovery. Endpoint | | The domain name of a service in a region. The server address can be obtained dynamically through this domain name +Integrate LoadBalancer | spring. Cloud. Loadbalancer. Nacos. Enabled | false | +Nacos Watch enabled | spring. Cloud. Nacos. Discovery. Watch. Enabled | false | can be set to true to enable watch +Enable Nacos | spring. Cloud. Nacos. Discovery. Enabled | true | Start by default. If set to false, automatic registration with Nacos will be disabled + +### Spring Cloud Alibaba Nacos integrated Spring Cloud Gateway. + +#### How to access + +Before starting the demo, learn how Spring Cloud applications connect to Spring Cloud, Nacos Discovery, and Spring Cloud Gateway. + +**Note that this section is only for your convenience to understand the access method. The access work has been completed in this sample code, and you do not need to modify it.** + +1. First, modify the `pom.xml` file to introduce Spring Cloud Alibaba Nacos Discovery Starter and Spring Cloud Gateway Starter. + + ```xml + + com.alibaba.cloud + spring-cloud-starter-alibaba-nacos-discovery + + + org.springframework.cloud + spring-cloud-starter-gateway + + ``` + +2. Configure the Nacos Server address in the applied `/src/main/resources/application.properties` configuration films + + ```properties + spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 + ``` + +3. Configure Spring Cloud Gateway routing in the application's `/src/main/resources/application.properties` configuration file + + ```properties + spring.cloud.gateway.routes[0].id=nacos-route + spring.cloud.gateway.routes[0].uri=lb://service-gateway-provider + spring.cloud.gateway.routes[0].predicates[0].name=Path + spring.cloud.gateway.routes[0].predicates[0].args[pattern]=/nacos/** + spring.cloud.gateway.routes[0].filters[0]=StripPrefix=1 + ``` + +4. Use the @ EnableDiscoveryClient annotation to turn on service registration and discovery + + ```java + @SpringBootApplication + @EnableDiscoveryClient + public class GatewayApplication { + + public static void main(String[] args) { + SpringApplication.run(GatewayApplication.class, args); + } + + } + ``` + +#### Spring Cloud Gateway App Launch + +Start the application, support IDE direct start and start after compilation and packaging. + +1. IDE direct startup: Find the main class `GatewayApplication` of the nacos-gateway-discovery-example project, and execute the main method to start the application. +2. Start after compilation: Compile and package `mvn clean package` the project in the nacos-gateway-discovery-example project, and then `java -jar nacos-gateway-discovery-example.jar` start the application. + +#### Service Provider Application Launch + +Start the application, support IDE direct start and start after compilation and packaging. + +1. Start the IDE directly: find the main class `ProviderApplication` of the nacos-gateway-provider-example project, and execute the main method to start the application. +2. Start after compilation: Compile and package `mvn clean package` the project in the nacos-gateway-provider-example project, and then `java -jar nacos-gateway-provider-example.jar` start the application. + +#### Validate + +1. + +```bash + curl 'http://127.0.0.1:18085/nacos/echo/hello-world' + + hello Nacos Discovery hello-world⏎ +``` + +2. + +```bash + curl 'http://127.0.0.1:18085/nacos/divide?a=6&b=2' + + 3⏎ +``` + +## Native Image build + +Please refer to the Spring Cloud Alibaba website + +## More introduction + +Nacos provides users with service infrastructure including dynamic service discovery, configuration management, service management, etc., to help users build, deliver and manage their microservice platforms more flexibly and easily. Based on Nacos, users can build modern cloud native applications centered on "services" more quickly. Nacos can be seamlessly integrated with Spring Cloud, Kubernetes/CNCF, Dubbo and other micro-service ecosystems to provide users with a better experience. For more information about Nacos, see the [Nacos 项目](https://github.com/alibaba/Nacos). + +If you have any suggestions or ideas about Spring Cloud Nacos Discovery, please feel free to send them to us in the issue or through other community channels.