diff --git a/pom.xml b/pom.xml index 539260af8..ff90f7cd3 100644 --- a/pom.xml +++ b/pom.xml @@ -109,7 +109,6 @@ spring-cloud-alibaba-dependencies spring-cloud-alibaba-examples - spring-cloud-alibaba-docs spring-cloud-alibaba-starters spring-cloud-alibaba-coverage diff --git a/spring-cloud-alibaba-docs/pom.xml b/spring-cloud-alibaba-docs/pom.xml deleted file mode 100644 index 1c03ca68f..000000000 --- a/spring-cloud-alibaba-docs/pom.xml +++ /dev/null @@ -1,54 +0,0 @@ - - - - - com.alibaba.cloud - spring-cloud-alibaba - ${revision} - ../pom.xml - - - 4.0.0 - - spring-cloud-alibaba-docs - Spring Cloud Alibaba Documentation - pom - - - spring-cloud-alibaba - ${basedir}/.. - - - - - docs - - - - org.apache.maven.plugins - maven-dependency-plugin - - - org.asciidoctor - asciidoctor-maven-plugin - false - - ${basedir}/src/main/asciidoc-zh - - - - com.agilejava.docbkx - docbkx-maven-plugin - - - org.codehaus.mojo - build-helper-maven-plugin - false - - - - - - - diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc deleted file mode 100644 index 1bf27292e..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/acm.adoc +++ /dev/null @@ -1,176 +0,0 @@ -== Spring Cloud AliCloud ACM - -Spring Cloud AliCloud ACM 是阿里云提供的商业版应用配置管理(Application Configuration Management) 产品 在 Spring Cloud 应用侧的客户端实现，且目前完全免费。 - -使用 Spring Cloud AliCloud ACM，可基于 Spring Cloud 的编程模型快速接入 ACM 配置管理功能。 - -NOTE: 目前 EDAS 已经支持直接部署 Nacos Config 应用 - -=== 如何引入 Spring Cloud AliCloud ACM - -如果要在您的项目中引入 ACM，使用 group ID 为 `com.alibaba.cloud` 和 artifact ID 为 `spring-cloud-starter-alicloud-acm` 的 starter。 - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alicloud-acm - ----- - -=== 使用 ACM 进行配置管理 - -当客户端引入了 Spring Cloud AliCloud ACM Starter 以后，应用启动时会自动从配置管理的服务端获取配置信息，并注入到 Spring 的 Environment 中。 - -以下是一个简单的应用示例。 - -[source,java] ----- -@SpringBootApplication -public class ProviderApplication { - - public static void main(String[] args) { - ConfigurableApplicationContext applicationContext = SpringApplication.run(ProviderApplication.class, args); - String userName = applicationContext.getEnvironment().getProperty("user.name"); - String userAge = applicationContext.getEnvironment().getProperty("user.age"); - System.err.println("user name :"+userName+"; age: "+userAge); - } -} ----- - -在从配置中心服务端获取配置信息之前，还需要配置服务端的地址，在 bootstrap.properties 中，还需要配置以下信息。 - -[source,properties] ----- -# 必选，应用名会被作为从服务端获取配置 key 的关键词组成部分 -spring.application.name=acm-config -server.port=18081 -# 以下就是配置中心服务端的IP和端口配置 -spring.cloud.alicloud.acm.server-list=127.0.0.1 -spring.cloud.alicloud.acm.server-port=8080 ----- - -NOTE: 此时没有启动配置中心，启动应用会报错，因此在应用启动之前，应当首先启动配置中心。 - - -==== 启动配置中心 - -ACM 使用的配置中心有两种，一种是本地运行的轻量版配置中心，主要用于开发和本地调试，一种是阿里云产品 ACM。通常情况下，可以使用轻量版配置中心作为开发和测试环境，使用云上的 ACM 作为灰度和生产环境。 - -===== 使用轻量版配置中心 - -轻量版配置中心的下载和启动方式可参考 https://help.aliyun.com/document_detail/44163.html[这里] - -NOTE: 只需要执行文档中的第1步 (下载轻量配置中心) 和第2步 (启动轻量配置中心)。 - - -===== 使用阿里云配置中心 - -使用云上 ACM ，可以省去服务端的维护工作，同时稳定性也会更有保障。当使用云上配置中心时，代码部分和使用轻量配置中心并没有区别，但是配置上会有一些区别。 - -以下是一个简单的使用云上配置中心的配置示例，配置详情需要在 https://acm.console.aliyun.com[ACM控制台查询] - -[source,properties] ----- -# 应用名会被作为从服务端获取配置 key 的关键词组成部分，因此是必选 -spring.application.name=acm-config -# 端口配置自由配置即可 -server.port=18081 -# 以下就是配置中心的IP和端口配置 -spring.cloud.alicloud.acm.server-mode=EDAS -spring.cloud.alicloud.access-key=你的阿里云AK -spring.cloud.alicloud.secret-key=你的阿里云SK -spring.cloud.alicloud.acm.endpoint=acm.aliyun.com -spring.cloud.alicloud.acm.namespace=你的 ACM namespace，需要在 ACM 控制台查询 ----- - -NOTE: EDAS 提供应用托管服务，如果你将应用托管到 EDAS，那么 EDAS 将会自动为你填充所有与业务无关的配置。 - -==== 在配置中心添加配置 - -1. 启动好轻量版配置中心之后，在控制台中添加如下的配置。 - -[source,subs="normal"] ----- -Group: DEFAULT_GROOUP - -DataId: acm-config.properties - -Content: user.name=james - user.age=18 ----- - -NOTE: DataId 的格式为 `{prefix}.{file-extension}`,prefix 默认从配置 spring.application.name 中取值，file-extension 默认的值为 "properties"。 - -==== 启动应用验证 - -启动这个Example，可以在控制台看到打印出的值正是我们在轻量版配置中心上预先配置的值。 - -[source,subs="normal"] ----- -user name :james; age: 18 ----- - -=== 更改配置文件扩展名 - -spring-cloud-starter-alicloud-acm 中 DataId 默认的文件扩展名是 properties。除去 properties 格式之外，也支持 yaml 格式。 -支持通过 spring.cloud.alicloud.acm.file-extension 来配置文件的扩展名，yaml 格式可以配置成 `yaml` 或 `yml`。 - -NOTE: 修改文件扩展名后，在配置中心中的 DataID 以及 Content 的格式都必须做相应的修改。 - -=== 动态更新 - -spring-cloud-starter-alicloud-acm 默认支持配置的动态更新，当您在配置中心修改配置的内容时，会发布 Spring 中的 RefreshEvent 事件。 -带有 @RefreshScope 和 @ConfigurationProperties 注解的类会自动刷新。 - -NOTE: 你可以通过配置 spring.cloud.alicloud.acm.refresh.enabled=false 来关闭动态刷新。 - -=== Profile 粒度的配置 - -spring-cloud-starter-alicloud-acm 在加载配置的时候，首先会加载 DataId 为{spring.application.name}.{file-extension}的配置，当 spring.profiles.active 中配置有内容时，还会依次去加载 spring.profile 对应的内容， DataId 的格式为{spring.application.name}-{profile}.{file-extension}的配置，且后者的优先级高于前者。 - -spring.profiles.active 属于配置的元数据，所以也必须配置在 bootstrap.properties 或 bootstrap.yaml 中。比如可以在 bootstrap.properties 中增加如下内容。 - -[sources,properties] ----- -spring.profiles.active={profile-name} ----- - -Note: 也可以通过 JVM 参数 -Dspring.profiles.active=develop 或者 --spring.profiles.active=develop 这类优先级更高的方式来配置，只需遵循 Spring Boot 规范即可。 - - -=== 自定义配置中心超时时间 - -ACM Client 与 Server 通信的超时时间默认是 3000ms，可以通过 `spring.cloud.alicloud.acm.timeout` 来修改超时时间，单位为 ms 。 - -=== 自定义 Group 的配置 - -在没有明确指定 `{spring.cloud.alicloud.acm.group}` 配置的情况下， 默认使用的是 DEFAULT_GROUP 。如果需要自定义自己的 Group，可以通过以下配置来实现： - -[source,properties] ----- -spring.cloud.alicloud.acm.group=DEVELOP_GROUP ----- - -NOTE: 该配置必须放在 bootstrap.properties 文件中。并且在添加配置时 Group 的值要和 `spring.cloud.alicloud.acm.group` 的配置值一致。 - -=== 共享配置 - -ACM 提供了一种多个应用之间共享配置中心的同一个配置的推荐方式，供多个应用共享一些配置时使用，您在使用的时候需要添加在 bootstrap 中添加一个配置项 `spring.application.group`。 - -[source,properties] ----- -spring.application.group=company.department.team ----- - -这时应用在获取上文提到的自身所独有的配置之前，会先依次从这些 DataId 去获取，分别是 company:application.properties, company.department:application.properties, company.department.team:application.properties。 -然后，还会从 {spring.application.group}:{spring.application.name}.{file-extension} 中获取，越往后优先级越高，最高的仍然是应用自身所独有的配置。 - - -NOTE: 共享配置中 DataId 默认后缀为 properties，可以通过 spring.cloud.alicloud.acm.file-extension 配置. `{spring.application.group}:{spring.application.name}.{file-extension}` 。 - -NOTE: 如果设置了 `spring.profiles.active` ，DataId 的格式还支持 `{spring.application.group}:{spring.application.name}-{spring.profiles.active}.{file-extension}`。优先级高于 `{spring.application.group}:{spring.application.name}.{file-extension}` - -=== Actuator 监控 - -ACM 对应的 Actuator 监控地址为 `/acm`，其中 `config` 代表了 ACM 元数据配置的信息，`runtime.sources` 对应的是从 ACM 服务端获取的配置的信息及最后刷新时间， `runtime.refreshHistory` 对应的是动态刷新的历史记录。 \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/ans.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/ans.adoc deleted file mode 100644 index f44c1a183..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/ans.adoc +++ /dev/null @@ -1,96 +0,0 @@ -== Spring Cloud AliCloud ANS - -ANS（Application Naming Service） 是隶属于阿里云 EDAS 产品的组件， Spring Cloud AliCloud ANS 提供了 Spring Cloud 规范下商业版的服务注册与发现，可以让用户方便的在本地开发，同时也可以运行在云环境里。 - -NOTE: 目前 EDAS 已经支持直接部署 Nacos Discovery 应用 - -=== 如何引入 Spring Cloud AliCloud ANS - -如果要在您的项目中引入 ANS，使用 group ID 为 `com.alibaba.cloud` 和 artifact ID 为 `spring-cloud-starter-alicloud-ans` 的 starter。 - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alicloud-ans - ----- - -=== 使用ANS进行服务注册 - -当客户端引入了 Spring Cloud AliCloud ANS Starter 以后，服务的元数据会被自动注册到注册中心，比如IP、端口、权重等信息。客户端会与服务端保持心跳，来证明自己可以正常提供服务。 - -以下是一个简单的应用示例。 - -[source,java] ----- -@SpringBootApplication -@EnableDiscoveryClient -@RestController -public class ProviderApplication { - - @RequestMapping("/") - public String home() { - return "Hello world"; - } - - public static void main(String[] args) { - SpringApplication.run(ProviderApplication.class, args); - } - -} ----- - -既然服务会被注册到注册中心，那么肯定需要配置注册中心的地址，在 application.properties 中，还需要配置上以下地址。 - -[source,properties] ----- -# 应用名会被作为服务名称使用，因此会必选 -spring.application.name=ans-provider -server.port=18081 -# 以下就是注册中心的IP和端口配置 -spring.cloud.alicloud.ans.server-list=127.0.0.1 -spring.cloud.alicloud.ans.server-port=8080 ----- - -NOTE: 此时没有启动注册中心，启动应用会报错，因此在应用启动之前，应当首先启动注册中心。 - -=== 启动注册中心 - -ANS 使用的注册中心有两种，一种是完全免费的轻量版配置中心，主要用于开发和本地调试，一种是云上注册中心，ANS 依托于阿里云 EDAS 产品提供服务注册的功能。通常情况下，可以使用轻量版配置中心作为开发和测试环境，使用云上的 EDAS 作为灰度和生产环境。 - -==== 启动轻量版配置中心 - -轻量版配置中心的下载和启动方式可参考 https://help.aliyun.com/document_detail/44163.html?spm=a2c4g.11186623.6.677.5f206b82Z2mTCF[这里] - -NOTE: 只需要进行第1步（下载轻量配置中心）和第2步（启动轻量配置中心）即可，第3步（配置hosts）在与 ANS 结合使用时，不需要操作。 - -启动完轻量版配置中心以后，直接启动 ProviderApplication ，即可将服务注册到轻量版配置中心，由于轻量版配置中心的默认端口是8080，因此你可以打开 http://127.0.0.1:8080 ，点击左侧"服务列表"，查看注册上来的服务。 - -==== 使用云上注册中心 - -使用云上注册中心，可以省去服务端的维护工作，同时稳定性也会更有保障。当使用云上注册中心时，代码部分和使用轻量配置中心并没有区别，但是配置上会有一些区别。 - -以下是一个简单的使用云上配置中心的配置示例。 - -[source,properties] ----- -# 应用名会被作为服务名称使用，因此是必选 -spring.application.name=ans-provider -# 端口配置自由配置即可 -server.port=18081 -# 以下就是注册中心的IP和端口配置，因为默认就是127.0.0.1和8080，因此以下两行配置也可以省略 -spring.cloud.alicloud.ans.server-mode=EDAS -spring.cloud.alicloud.access-key=你的阿里云AK -spring.cloud.alicloud.secret-key=你的阿里云SK -spring.cloud.alicloud.edas.namespace=cn-xxxxx ----- - -server-mode 的默认值为 LOCAL ，如果要使用云上注册中心，则需要更改为 EDAS 。 - -access-key 和 secret-key 则是阿里云账号的 AK/SK，需要首先注册阿里云账号，然后登陆 https://usercenter.console.aliyun.com/#/manage/ak[阿里云AK/SK管理页面] ，即可看到 AccessKey ID 和 Access Key Secret ，如果没有的话，需要点击"创建 AccessKey"按钮创建。 - -namespace 是阿里云 EDAS 产品的概念，用于隔离不同的环境，比如测试环境和生产环境。要获取 namespace 需要 https://common-buy.aliyun.com/?spm=5176.11451019.0.0.6f5965c0Uq5tue&commodityCode=edaspostpay#/buy[开通 EDAS 服务]，按量计费模式下开通是免费的，开通以后进入 https://edas.console.aliyun.com/#/namespaces?regionNo=cn-hangzhou[EDAS控制台]，即可看到对应的 namespace，比如 cn-hangzhou。 - -NOTE: EDAS 提供应用托管服务，如果你将应用托管到 EDAS，那么 EDAS 将会自动为你填充所有配置。 - diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/appactive.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/appactive.adoc deleted file mode 100644 index 6cca7f497..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/appactive.adoc +++ /dev/null @@ -1,244 +0,0 @@ -== Spring Cloud Alibaba AppActive - -=== AppActive介绍 -AppActive，是一个面向业务应用构建云原生高可用多活容灾架构的开源中间件。它提供了应用多活容灾架构的标准、实现和 Demo，适用于丰富的业务场景（单 AZ、单 Region、单云、多 AZ、多 Region、多云、自建 IDC等）。 - -AppActive 建立在 阿里巴巴 使用 AHAS-MSHA 系统大规模运行生产应用系统的8年经验之上，且结合了来自阿里云商业化服务的外部多家客户和社区的最佳实践，具备高可靠、可拓展等特性。 - -AppActive 具备以下特性 - -==== 单元分流 -===== 流量统一接入 -对流量的把控能力，来源于流量的统一接入，我们将这一层称为接入层。接入层是单元所有流量的入口，它能解析请求协议，并按照设置的分流模式与分流粒度，将请求流量正确引导到正确单元的相应应用服务SLB上。下文若无特殊说明，请求协议默认HTTP。下图为接入层示意图。 - -===== 分流模式 -多活场景下，流量会按照某个纬度切片，分流到不同的单元。多活支持多种分流模式，比如按比例分流，按业务属性分流，具体选择哪种分流模式还是取决于业务场景需要。分流模式最终体现在路由规则里，路由规则是一项配置，它定义了某个流量应该隶属于哪个单元。 - -1. 按比例分流。在某些业务场景下，需要按用户分流，或者按设备号分流。用户、设备等都可以抽象成一个ID，那就可以将ID划为多个区间，每个区间归属于某个单元。这种分流模式，每个单元的流量比例，就可以通过ID区间进行估算，通过设置ID区间与单元容量的比例一致，就可以做到全局的负载均衡。 -2. 按业务属性分流。在某些业务场景下，需要按流量属性分流，比如将爬虫流量引入特定单元，或者按省份分流。爬虫、省份等都可以抽象成一个标签，那就可以将不同的标签值流量引入不同单元。这种分流模式，可以支持对不同业务属性的流量进行物理隔离。 - -===== 分流粒度 -随着应用服务化，当今应用早已不是单体架构，提供用户访问入口的应用也可能成百上千。接入层将用户流量引入正确的应用，支持域名与URI前缀两种粒度。 - -1. 按域名分流。按照不同域名区分不同应用。比如应用app1的域名是app1.example.com，app2的域名是app2.example.com。 -2. 按URI前缀分流。按照不同URI前缀区分不同应用。比如应用app1与app2的域名都是app.example.com，但是将URI中/app1前缀的流量引入app1，将/app2前缀的流量引入app2。 - -===== 流量协议 -接入层支持四层、七层丰富的流量请求协议，以满足用户互联网、物联网等多样化场景需求。 - -1. HTTP协议支持。接入层默认支持HTTP协议，从HTTP协议中解析出域名与URI，进行转发路由。 -2. HTTPS协议支持。接入层支持HTTPS协议，提供集中化的域名证书管理，满足用户可靠传输、安全传输的要求。用户在接入层配置好域名证书，则应用SLB无需再配置证书。 -3. 其他协议支持。接入层除了支持HTTP与HTTPS协议，还支持其他基于HTTP的协议，比如SOAP等。接入层在协议上有很大的扩展性，能以插件的形式迅速支持特殊协议，比如物联网场景下的MQTT，COAP等。 - -===== 路由透传 -为了确保流量能在单元内闭环，接入层、应用层、数据层每一层都会进行路由纠错或单元保护。为了识别流量，需要明确流量所属的单元化类型与分流id，我们称之为路由参数，以便通过路由规则计算出流量所属正确单元，因此，路由参数需要跟随请求路径一路传递，我们称之为路由透传。 - -1. 接入层路由透传。当浏览器发起业务请求时，需要在请求中携带路由参数。路由参数可以在cookie、head或body中，建议cookie。接入层能解析HTTP请求，拿到路由参数并路由到正确的应用SLB，同时应用服务器仍然能从请求中拿到原生的路由参数。 -2. 应用层路由透传。流量到达应用服务器，多活提供插件从HTTP请求中提取路由参数，并保存到上下文，下一步应用可能会发起RPC调用或异步消息，因此路由参数还需要在RPC与消息层面透传。 -3. RPC路由透传。当应用发起RPC调用时，RPC客户端能从上下文中取出路由参数，并跟随RPC请求到远程服务提供者Provider，Provider客户端识别出Request中的路由参数，亦保存到调用上下文。路由参数在RPC中的传递过程对用户透明。 -4. 消息路由透传。MQ客户端在发送消息时，会从当前上下文获取路由参数添加到消息属性中。MQ客户端消费消息时，能从消息属性中取出路由参数，亦保存到调用上下文。路由参数在MQ中的传递过程对用户透明。 -5. 数据层路由透传。数据脏写会造成很严重的后果，因此要保证数据落库到正确单元的DB。多活提供了 DRIVER 插件，对非本单元的请求拒绝。 - -==== 单元协同 -在容灾场景中，理想场景中各个单元独立，但实际上会存在部分跨单元场景的业务场景，为了满足这些场景，产品需要提供单元协同的能力。 - -===== 中心调用 -有些特定业务场景，为保证数据强一致性，特定服务只能在特定中心单元提供，所有对中心服务的调用都会直接路由到中心单元来完成。异地多活产品通过CSB组件和RPC多活插件来完成服务单元间协同调用，满足业务的完整性。 - -==== 单元保护 -产品保证业务逻辑的全局正确性，不会因切流操作导致单元业务逻辑不一致问题。系统自上而下各层都有对错误流量的纠错保护能力，保证业务按单元化规则进行正确的流转。 - -===== 接入层纠错 -流量打入接入层，接入层通过请求附加的路由参数判断流量归属单元，非本单元流量将被代理到正确的目标单元，保证了接入层入口流量的正确性。 - -===== RPC纠错 -RPC服务调用时，RPC多活Plugin在Consumer端会根据请求的单元信息，对服务调用进行正确的路由选址，对错误的流量服务调用，RPC多活Plugin会计算出正确的目标单元，跨单元调用目标单元服务，保证服务流转逻辑的一致性。同时RPC多活Plugin 在Provider端会对过来的请求进行二次校验，保证服务调用的正确。通过双重校验机制，RPC多活Plugin实现对RPC调用的纠错，保证服务调用的正确性。 - -==== 单元扩展 -===== 水平扩展 -当现有单元的业务承载量已达上限且无法扩容时，产品 提供简单快捷单元水平扩展能力： - -1. 全国范围内扩展新单元不受地域限制 -2. 扩展的新单元数量不受限制，单元的稳定性和性能不受单元数量影响 -3. 提供两种单元扩展形式：独立 DB 的异地单元 、 共享 DB 的同城单元 - -=== 如何使用AppActive - -==== 数据面 - -**前置条件** - -- 需要你的应用服务基于 Java 实现，并且以 Spring Cloud 实现服务调用 -- 负载均衡支持 Ribbon，暂不支持 SpringCloudBalancer -- 支持声明式 Http 客户端：OpenFeign 和 RestTemplate，暂不支持 原始 Http 客户端如 OkHttp 和 HttpClient - -**快速接入** -在启动示例进行演示之前，我们先了解一下 Spring Cloud 应用如何使用 AppActive 所提供的异地多活能力。 -**注意 本章节只是为了便于您理解接入方式，本示例代码中已经完成接入工作，您无需再进行修改。** - -1. 首先，修改 pom.xml 文件，在 provider 和 consumer 已添加最新 `spring-cloud-alibaba-dependencies` 的基础上添加以下 maven 依赖。 - - - com.alibaba.cloud - spring-cloud-starter-alibaba-appactive - - -2. 在 Provider 应用的 `application.properties` 配置文件中给特定接口配置分流策略。其中后缀 `core-path` 用于配置核心服务，`global-path` 用于配置全局服务，`general-path` 用于配置一般服务，比如 demo 中的 product 应用分流策略配置如下： - - spring.cloud.appactive.filter.core-path=/detailHidden/*,/detail/* - spring.cloud.appactive.filter.global-path=/buy/* - spring.cloud.appactive.filter.general-path=/* - -3. 在 Consumer 应用的 `application.properties` 配置客户端负载均衡为 AppActive 所提供的负载均衡算法，配置方式如下，注意需要将`[service-name]`替换成具体的待消费服务名。 - - [service-name].ribbon.NFLoadBalancerRuleClassName =com.alibaba.cloud.appactive.consumer.AppactiveRule - -**快速启动** - -1. 启动 Nacos, MySQL, 并往 Nacos 中推送多活规则： - - - 在 `appactive-example` 目录下，执行：`docker-compose -f component-quickstart.yml up -d` 启动 Nacos, MySQL。 - - 执行以下命令：`curl -X POST 'http://127.0.0.1:8848/nacos/v1/console/namespaces' -d 'customNamespaceId=appactiveDemoNamespaceId&namespaceName=appactiveDemoNamespaceName&namespaceDesc=appactiveDemoNamespaceDesc'` 在 Nacos 配置中心中创建一个演示用命名空间 appactiveDemoNamespaceId。 - - 执行以下命令：`sh baseline.sh 2 NACOS appactiveDemoNamespaceId`，往命名空间中推送多活规则。多活规则说明如下： - - `appactive.dataId.idSourceRulePath`: 描述如何从 http 流量中提取路由标 - - `appactive.dataId.transformerRulePath`: 描述如何解析路由标 - - `appactive.dataId.trafficRouteRulePath`: 描述路由标和单元的映射关系 - - `appactive.dataId.dataScopeRuleDirectoryPath_mysql-product`: 描述数据库的属性 - -2. 启动 5 套应用，启动参数分别为： - -- frontend -``` --Dappactive.channelTypeEnum=NACOS --Dappactive.namespaceId=appactiveDemoNamespaceId --Dappactive.unit=unit --Dappactive.app=frontend --Dio.appactive.demo.unitlist=center,unit --Dio.appactive.demo.applist=frontend,product,storage --Dserver.port=8875 -``` -- product -``` --Dappactive.channelTypeEnum=NACOS --Dappactive.namespaceId=appactiveDemoNamespaceId --Dappactive.unit=center --Dappactive.app=product --Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/product?characterEncoding=utf8&useSSL=false&serverTimezone=GMT&activeInstanceId=mysql&activeDbName=product --Dserver.port=8883 -``` -``` --Dappactive.channelTypeEnum=NACOS --Dappactive.namespaceId=appactiveDemoNamespaceId --Dappactive.unit=unit --Dappactive.app=product --Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/product?characterEncoding=utf8&useSSL=false&serverTimezone=GMT&activeInstanceId=mysql&activeDbName=product --Dserver.port=8873 -``` -- storage -``` --Dappactive.channelTypeEnum=NACOS --Dappactive.namespaceId=appactiveDemoNamespaceId --Dappactive.unit=center --Dappactive.app=storage --Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/product?characterEncoding=utf8&useSSL=false&serverTimezone=GMT --Dserver.port=8881 -``` -``` --Dappactive.channelTypeEnum=NACOS --Dappactive.namespaceId=appactiveDemoNamespaceId --Dappactive.unit=unit --Dappactive.app=storage --Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/product?characterEncoding=utf8&useSSL=false&serverTimezone=GMT --Dserver.port=8871 -``` - -**效果演示** - -1. 归属于一般（Unit）单元的普通应用服务调用演示。在浏览器中输入：`http://127.0.0.1:8079/listProduct` 地址，可见请求通过 frontend 应用被发送给了 product。 - -image::pic/image-2022-09-15-16-16-25-989.png[] - - 由于上述路径中的 `/listProduct` 在 product 应用中匹配到的是 `/*` 路径规则，根据规则内容，该服务属于普通应用做了未做单元化拆分，所以frontend 在从注册中心获取的 product 地址列表中不存在倾向性，会随机选择地址进行请求发送。因此多次请求上述路径，会看到请求在 product 的一般（Unit)和 中心（center）单元应用中来回切换。 - -2. 归属于 unit 单元的核心应用服务调用演示。在浏览器中输入：`http://127.0.0.1:8079/detailProduct` 路径，由于上述路径中的 `/detailProduct` 在 product 应用中匹配到的是 `/detail/*` 路径规则，根据规则内容，该服务属于核心应用做了单元会拆分，其会根据请求中 Header, Cookie 或请求参数中的变量具体的值去判断该请求的下游单元类型，由于事先配置如下切流规则（具体可见 rule 目录下的 idUnitMapping.json 文件内容）： - - { - "itemType": "UnitRuleItem", - "items": [ - { - "name": "unit", - "conditions": [ - { - "@userIdBetween": [ - "0~1999" - ] - } - ] - }, - { - "name": "center", - "conditions": [ - { - "@userIdBetween": [ - "2000~9999" - ] - } - ] - } - ] - } - - 上述规则表示，用户Id为 0 ~ 1999 的请求将发送给下游提供者中的一般（Unit）单元中的核心应用实例，用户Id为 2000 ~ 9999 的请求将发送给下游提供者中的中心（Center）单元全局应用实例。 - 如下图，模拟一个用户Id为 1999 的请求，可见请求通过 frontend 发送到了下游中 product 的一般（Unit）单元中的核心应用实例。 - -image::pic/image-2022-09-15-16-15-39-851.png[] - - 如下图，模拟一个用户Id为 2000 的请求，可见请求通过 frontend 发送到了下游中 product 的中心（center）单元中的全局应用实例。 - -image::pic/image-2022-09-15-16-14-50-461.png[] - -3. 归属于中心（Center）单元的全局应用服务调用演示。在浏览器中输入：`http://127.0.0.1:8079/buyProduct` 路径，由于上述路径中的 `/buyProduct` 在 product 和 storage 应用中匹配到的是 `/buy/*` 路径规则，根据规则内容，该服务属于全局应用未做单元会拆分，其会直接将请求发送到下游的中心（Center）单元中全局应用实例。 - -image::pic/image-2022-09-15-16-14-02-388.png[] - - -4. 切流演示。切流时主要做了如下几件事： - - 构建新的映射关系规则和禁写规则（手动） - - 将禁写规则推送给应用 - - 等待数据追平后将新的映射关系规则推送给应用 - 接下来演示的切流规则，会将用户Id为 0 ~ 2999 的请求将发送给下游提供者中的一般（Unit）单元中的核心应用实例，用户Id为 3000 ~ 9999 的请求将发送给下游提供者中的中心（Center）单元中的全局应用实例。具体的规则详情见 idUnitMappingNext.json： - - { - "itemType": "UnitRuleItem", - "items": [ - { - "name": "unit", - "conditions": [ - { - "@userIdBetween": [ - "0~2999" - ] - } - ] - }, - { - "name": "center", - "conditions": [ - { - "@userIdBetween": [ - "3000~9999" - ] - } - ] - } - ] - } - -如下图，模拟一个用户Id为 2999 的请求，可见请求通过 frontend 发送到了下游中 product 的 unit 单元中的核心应用实例，切流规则生效。 - -image::pic/image-2022-09-15-16-12-58-177.png[] - -如下图，模拟一个用户Id为 3000 的请求，可见请求通过 frontend 发送到了下游中 product 的 center 单元中的全局应用实例，切流规则生效。 - -image::pic/image-2022-09-15-16-12-26-461.png[] - diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/dependency-management.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/dependency-management.adoc deleted file mode 100644 index 0783ac041..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/dependency-management.adoc +++ /dev/null @@ -1,23 +0,0 @@ -== 依赖管理 - -Spring Cloud Alibaba BOM 包含了它所使用的所有依赖的版本。 - -如果您是 Maven Central 用户，请将我们的 BOM 添加到您的 pom.xml 中的 部分。 这将允许您省略任何Maven依赖项的版本，而是将版本控制委派给BOM。 - -```xml - - - - com.alibaba.cloud - spring-cloud-alibaba-dependencies - 2.2.10-RC1 - pom - import - - - -``` - -在下面的章节中，假设您使用的是 Spring Cloud Alibaba bom，相关 starter 依赖将不包含版本号。 - - diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/governance.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/governance.adoc deleted file mode 100644 index fb1a9cf21..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/governance.adoc +++ /dev/null @@ -1,125 +0,0 @@ -== Spring Cloud Alibaba Governance - -image::pic/governance-module.png[] - -Spring Cloud Alibaba Governance是Spring Cloud Alibaba最新推出的微服务治理能力，提供了多种类型的微服务治理能力，包括标签路由，服务鉴权等。并且对接了多种控制面，比如 https://istio.io/[Istio]，http://opensergo.io/[OpenSergo]，让用户仅通过添加特定的Adapter模块，就能实时感知到上述治理控制面下发的治理规则，并将此规则作用到应用上，从而完成对应用的治理。 - -=== 配置转换 -image::pic/resource-transform.png[] - -Microservices Governance的规则转换模块会将不同控制面下发的规则进行统一的转换，目前支持将来自Istio，OpenSergo等控制面下发的规则统一转换为Spring Cloud Alibaba统一抽象出的数据结构以供后续使用 - -如果在项目中使用Istio来实现规则转换，首先注意需要搭建一个Kubernetes集群，并且在其中部署Istio，具体参考 https://istio.io/latest/zh/docs/setup/install[Istio安装]。然后在需要接收到来自Istio规则的应用（一般为服务消费者）中添加如下starter依赖： -[source,xml,indent=0] ----- - - com.alibaba.cloud - spring-cloud-starter-xds-adapter - ----- -OpenSergo请参考 https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/governance-example/label-routing-example[Spring Cloud Alibaba Routing Examples] - -之后，在application.yml配置文件中设置如下配置内容： - -[source,yaml,indent=0] ----- -server: - port: ${SERVER_PORT:80} -spring: - cloud: - governance: - auth: - enabled: ${ISTIO_AUTH_ENABLE:true} - istio: - config: - enabled: ${ISTIO_CONFIG_ENABLE:true} - host: ${ISTIOD_ADDR:127.0.0.1} - port: ${ISTIOD_PORT:15010} - polling-pool-size: ${POLLING_POOL_SIZE:10} - polling-time: ${POLLING_TIMEOUT:10} - istiod-token: ${ISTIOD_TOKEN:} - log-xds: ${LOG_XDS:true} ----- - -各字段的含义如下: -|=== -|配置项|key|默认值|说明 -|是否开启鉴权| spring.cloud.governance.auth.enabled|true| -|是否连接Istio获取鉴权配置| spring.cloud.istio.config.enabled|true| -|Istiod的地址| spring.cloud.istio.config.host|127.0.0.1| -|Istiod的端口| spring.cloud.istio.config.port|15012|注：连接15010端口无需TLS，连接15012端口需TLS认证 -|应用从Istio拉取配置的线程池大小| spring.cloud.istio.config.polling-pool-size|10| -|应用从Istio拉取配置的间隔时间| spring.cloud.istio.config.polling-time|30|单位为秒 -|连接Istio 15012端口时使用的JWT token| spring.cloud.istio.config.istiod-token|应用所在pod的 `/var/run/secrets/tokens/istio-token` 文件的内容| -|是否打印xDS相关日志| spring.cloud.istio.config.log-xds|true| -|=== - -注意，应用运行在K8s环境中，在非默认命名空间下的应用，需要接收Istiod下发的规则，需要将运行的应用K8s的元信息注入以下环境变量中，具体操作方式可参考 https://kubernetes.io/zh-cn/docs/tasks/inject-data-application/environment-variable-expose-pod-information[Kubernetes文档]: - -|=== -|环境变量名|K8s pod metadata name -|POD_NAME|metadata.name -|NAMESPACE_NAME|metadata.namespace -|=== - -=== 路由 - -==== 组件支持说明 -目前，路由模块只支持了部分组件： - -远程调用组件：Spring Cloud OpenFeign - -负载均衡组件：Ribbon - -未来会支持更多的比如RestTemplate，Spring Cloud LoadBalancer等组件。 - -==== 使用路由 - -在引入配置转换模块后，就能获取到相应的治理规则来对应用赋予相应的治理能力。标签路由模块可以实现对应用根据请求头，请求参数等标签来路由到不同的服务， - -1.如果在项目中使用Spring Cloud Alibaba 标签路由，需要添加如下starter（一般添加在服务消费者应用上） -[source,xml,indent=0] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-governance-routing - ----- - -2.配置进行路由规则时的负载均衡算法(以随机负载均衡算法为例) -如果未配置，使用Ribbon默认的负载均衡算法ZoneAvoidanceRule ----- -spring.cloud.governance.routing.rule=RandomRule ----- - -在引入Istio配置转换模块的前提下，标签路由模块支持对以下几种请求的元信息做路由： - -* 请求路径 -* 请求头 -* 请求参数 - -使用Istio下发对应的 `DestinationRule` 以及 `VirtualService` ，即可配置对应的标签路由规则，具体的配置方法请参考以下文档与示例： - -* https://istio.io/latest/zh/docs/reference/config/networking/virtual-service/#VirtualService[Istio VirtualService] -* https://istio.io/latest/zh/docs/concepts/traffic-management/#destination-rules[Istio Destination Rule] -* https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/governance-example/label-routing-example[Spring Cloud Alibaba Routing Examples] - -=== 服务鉴权 -image::pic/auth-process.png[] - -在引入规则转换Adapter后，就能获取到相应的治理规则来对应用赋予相应的治理能力。服务鉴权模块给应用提供多种鉴权方式，如IP黑白名单，JWT鉴权等 - -如果使用Spring Cloud Alibaba服务鉴权功能，需要使用添加如下依赖： -[source,xml,indent=0] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-governance-auth - ----- - -使用Istio下发对应的 `AuthorizationPolicy` 以及 `RequestAuthentication` ，即可配置对应的鉴权规则，具体的配置方法请参考以下文档与示例 - -* https://istio.io/latest/zh/docs/reference/config/security/request_authentication/[Istio RequestAuthentication] -* https://istio.io/latest/zh/docs/reference/config/security/authorization-policy/[Authorization Policy] -* https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/governance-example/authentication-example[Spring Cloud Alibaba Authorization Examples] diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/introduction.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/introduction.adoc deleted file mode 100644 index 21bbd4d70..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/introduction.adoc +++ /dev/null @@ -1,19 +0,0 @@ -== 介绍 - -Spring Cloud Alibaba 致力于提供微服务开发的一站式解决方案。此项目包含开发分布式应用服务的必需组件，方便开发者通过 Spring Cloud 编程模型轻松使用这些组件来开发分布式应用服务。 - -依托 Spring Cloud Alibaba，您只需要添加一些注解和少量配置，就可以将 Spring Cloud 应用接入阿里分布式应用解决方案，通过阿里中间件来迅速搭建分布式应用系统。 - -目前 Spring Cloud Alibaba 提供了如下功能: - -1. **服务限流降级**：支持 WebServlet、WebFlux, OpenFeign、RestTemplate、Dubbo 限流降级功能的接入，可以在运行时通过控制台实时修改限流降级规则，还支持查看限流降级 Metrics 监控。 -2. **服务注册与发现**：适配 Spring Cloud 服务注册与发现标准，默认集成了 Ribbon 的支持。 -3. **分布式配置管理**：支持分布式系统中的外部化配置，配置更改时自动刷新。 -4. **Rpc服务**：扩展 Spring Cloud 客户端 RestTemplate 和 OpenFeign，支持调用 Dubbo RPC 服务 -5. **消息驱动能力**：基于 Spring Cloud Stream 为微服务应用构建消息驱动能力。 -6. **分布式事务**：使用 @GlobalTransactional 注解， 高效并且对业务零侵入地解决分布式事务问题。 -7. **阿里云对象存储**：阿里云提供的海量、安全、低成本、高可靠的云存储服务。支持在任何应用、任何时间、任何地点存储和访问任意类型的数据。 -8. **分布式任务调度**：提供秒级、精准、高可靠、高可用的定时（基于 Cron 表达式）任务调度服务。同时提供分布式的任务执行模型，如网格任务。网格任务支持海量子任务均匀分配到所有 Worker（schedulerx-client）上执行。 -9. **阿里云短信服务**：覆盖全球的短信服务，友好、高效、智能的互联化通讯能力，帮助企业迅速搭建客户触达通道。 - -Spring Cloud Alibaba 也提供了丰富的 https://github.com/alibaba/spring-cloud-alibaba/tree/master/spring-cloud-alibaba-examples[examples]。 \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/nacos-config.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/nacos-config.adoc deleted file mode 100644 index 7870f8882..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/nacos-config.adoc +++ /dev/null @@ -1,433 +0,0 @@ -== Spring Cloud Alibaba Nacos Config - -Nacos 是一个 Alibaba 开源的、易于构建云原生应用的动态服务发现、配置管理和服务管理平台。 - -使用 Spring Cloud Alibaba Nacos Config，可基于 Spring Cloud 的编程模型快速接入 Nacos 配置管理功能。 - -=== 如何引入 Nacos Config 进行配置管理 - -如果要在您的项目中使用 Nacos 来实现配置管理，使用 group ID 为 `com.alibaba.cloud` 和 artifact ID 为 `spring-cloud-starter-alibaba-nacos-config` 的 starter。 - -[source,xml,indent=0] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-config - ----- - -=== 快速开始 - -Nacos Config 使用 DataId 和 GROUP 确定一个配置。 - -下图表示 DataId 使用 `myDataid`, GROUP 使用 `DEFAULT_GROUP`，配置格式为 Properties 的一个配置项: - -.Nacos Config Item -image::https://img.alicdn.com/tfs/TB1Yli3bUY1gK0jSZFMXXaWcVXa-2436-1138.png[] - -==== Nacos 服务端初始化 - -具体启动方式参考 Spring Cloud Alibaba Nacos Discovery 小节的 "Nacos Server 启动" 章节。 - -Nacos Server 启动完毕后，添加如何配置: - -[source,subs="normal"] ----- -Data ID: nacos-config.properties - -Group : DEFAULT_GROUP - -配置格式: Properties - -配置内容： user.name=nacos-config-properties - user.age=90 ----- - -NOTE: 注意DataId是以 properties(默认的文件扩展名方式)为扩展名。 - -==== 客户端使用方式 - -如果要在您的项目中使用 Nacos 来实现应用的外部化配置，使用 group ID 为 `com.alibaba.cloud` 和 artifact ID 为 `spring-cloud-starter-alibaba-nacos-config` 的 starter。 - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-config - ----- - -现在创建一个标准的 Spring Boot 应用。 - -[source,java] ----- -@SpringBootApplication -public class NacosConfigApplication { - - public static void main(String[] args) { - ConfigurableApplicationContext applicationContext = SpringApplication.run(ConfigApplication.class, args); - String userName = applicationContext.getEnvironment().getProperty("user.name"); - String userAge = applicationContext.getEnvironment().getProperty("user.age"); - System.err.println("user name :"+userName+"; age: "+userAge); - } -} ----- - -在运行此 NacosConfigApplication 之前， 必须使用 `bootstrap.properties` 配置文件来配置 Nacos Server 地址，例如： - -.bootstrap.properties -[source,properties] ----- -# DataId 默认使用 `spring.application.name` 配置跟文件扩展名结合(配置格式默认使用 properties), GROUP 不配置默认使用 DEFAULT_GROUP。因此该配置文件对应的 Nacos Config 配置的 DataId 为 nacos-config.properties, GROUP 为 DEFAULT_GROUP -spring.application.name=nacos-config -spring.cloud.nacos.config.server-addr=127.0.0.1:8848 ----- - -NOTE: 注意当你使用域名的方式来访问 Nacos 时，`spring.cloud.nacos.config.server-addr` 配置的方式为 `域名:port`。 -例如 Nacos 的域名为abc.com.nacos，监听的端口为 80，则 `spring.cloud.nacos.config.server-addr=abc.com.nacos:80`。 -注意 80 端口不能省略。 - -启动这个 Example，可以看到如下输出结果： - -[source,subs="normal"] ----- -2018-11-02 14:24:51.638 INFO 32700 --- [main] c.a.demo.provider.ConfigApplication : Started ConfigApplication in 14.645 seconds (JVM running for 15.139) -user name :nacos-config-properties; age: 90 -2018-11-02 14:24:51.688 INFO 32700 --- [-127.0.0.1:8848] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@a8c5e74: startup date [Fri Nov 02 14:24:51 CST 2018]; root of context hierarchy ----- - -=== 基于 DataId 为 yaml 的文件扩展名配置方式 - -Nacos Config 除了支持 properties 格式以外，也支持 yaml 格式。这个时候只需要完成以下两步： - -1、在应用的 bootstrap.properties 配置文件中显示的声明 DataId 文件扩展名。如下所示 - -.bootstrap.properties -[source,yaml] ----- -spring.cloud.nacos.config.file-extension=yaml ----- - -2、在 Nacos 的控制台新增一个DataId为yaml为扩展名的配置，如下所示： - -[source,subs="normal"] ----- -Data ID: nacos-config.yaml - -Group : DEFAULT_GROUP - -配置格式: YAML - -配置内容: user.name: nacos-config-yaml - user.age: 68 ----- - -这两步完成后，重启测试程序，可以看到如下输出结果。 - -[source,subs="normal"] ----- -2018-11-02 14:59:00.484 INFO 32928 --- [main] c.a.demo.provider.ConfigApplication:Started ConfigApplication in 14.183 seconds (JVM running for 14.671) -user name :nacos-config-yaml; age: 68 -2018-11-02 14:59:00.529 INFO 32928 --- [-127.0.0.1:8848] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@265a478e: startup date [Fri Nov 02 14:59:00 CST 2018]; root of context hierarchy ----- - -=== 支持配置的动态更新 - -Nacos Config 默认支持配置的动态更新，启动 Spring Boot 应用测试的代码如下： - -[source,java] ----- -@SpringBootApplication -public class ConfigApplication { - - public static void main(String[] args) { - ConfigurableApplicationContext applicationContext = SpringApplication.run(ConfigApplication.class, args); - while(true) { - //当动态配置刷新时，会更新到 Enviroment中，因此这里每隔一秒中从Enviroment中获取配置 - String userName = applicationContext.getEnvironment().getProperty("user.name"); - String userAge = applicationContext.getEnvironment().getProperty("user.age"); - System.err.println("user name :" + userName + "; age: " + userAge); - TimeUnit.SECONDS.sleep(1); - } - } -} ----- - -如下所示，当变更user.name时，应用程序中能够获取到最新的值： - -[source,subs="normal"] ----- -user name :nacos-config-yaml; age: 68 -user name :nacos-config-yaml; age: 68 -user name :nacos-config-yaml; age: 68 -2018-11-02 15:04:25.069 INFO 32957 --- [-127.0.0.1:8848] o.s.boot.SpringApplication : Started application in 0.144 seconds (JVM running for 71.752) -2018-11-02 15:04:25.070 INFO 32957 --- [-127.0.0.1:8848] s.c.a.AnnotationConfigApplicationContext : Closing org.springframework.context.annotation.AnnotationConfigApplicationContext@10c89124: startup date [Fri Nov 02 15:04:25 CST 2018]; parent: org.springframework.context.annotation.AnnotationConfigApplicationContext@6520af7 -2018-11-02 15:04:25.071 INFO 32957 --- [-127.0.0.1:8848] s.c.a.AnnotationConfigApplicationContext : Closing org.springframework.context.annotation.AnnotationConfigApplicationContext@6520af7: startup date [Fri Nov 02 15:04:24 CST 2018]; root of context hierarchy -//从 Enviroment 中 读取到更改后的值 -user name :nacos-config-yaml-update; age: 68 -user name :nacos-config-yaml-update; age: 68 ----- - -NOTE: 你可以通过配置 `spring.cloud.nacos.config.refresh.enabled=false` 来关闭动态刷新 - -=== 支持profile粒度的配置 - -Nacos Config 在加载配置的时候，不仅仅加载了以 DataId 为 `${spring.application.name}.${file-extension:properties}` 为前缀的基础配置，还加载了DataId为 `${spring.application.name}-${profile}.${file-extension:properties}` 的基础配置。在日常开发中如果遇到多套环境下的不同配置，可以通过Spring 提供的 `${spring.profiles.active}` 这个配置项来配置。 - -[source,properties] ----- -spring.profiles.active=develop ----- - -NOTE: ${spring.profiles.active} 当通过配置文件来指定时必须放在 bootstrap.properties 文件中。 - -Nacos 上新增一个DataId为：nacos-config-develop.yaml的基础配置，如下所示： - -[source,subs="normal"] ----- -Data ID: nacos-config-develop.yaml - -Group : DEFAULT_GROUP - -配置格式: YAML - -配置内容: current.env: develop-env ----- - -启动 Spring Boot 应用测试的代码如下： - -[source,java] ----- -@SpringBootApplication -public class ConfigApplication { - - public static void main(String[] args) { - ConfigurableApplicationContext applicationContext = SpringApplication.run(ConfigApplication.class, args); - while(true) { - String userName = applicationContext.getEnvironment().getProperty("user.name"); - String userAge = applicationContext.getEnvironment().getProperty("user.age"); - //获取当前部署的环境 - String currentEnv = applicationContext.getEnvironment().getProperty("current.env"); - System.err.println("in "+currentEnv+" enviroment; "+"user name :" + userName + "; age: " + userAge); - TimeUnit.SECONDS.sleep(1); - } - } -} ----- -启动后，可见控制台的输出结果： - -[source,subs="normal"] ----- -in develop-env enviroment; user name :nacos-config-yaml-update; age: 68 -2018-11-02 15:34:25.013 INFO 33014 --- [ Thread-11] ConfigServletWebServerApplicationContext : Closing org.springframework.boot.web.servlet.context.AnnotationConfigServletWebServerApplicationContext@6f1c29b7: startup date [Fri Nov 02 15:33:57 CST 2018]; parent: org.springframework.context.annotation.AnnotationConfigApplicationContext@63355449 ----- - -如果需要切换到生产环境，只需要更改 `${spring.profiles.active}` 参数配置即可。如下所示： - -[source,properties] ----- -spring.profiles.active=product ----- - -同时生产环境上 Nacos 需要添加对应 DataId 的基础配置。例如，在生产环境下的 Naocs 添加了DataId为：nacos-config-product.yaml的配置： - -[source,subs="normal"] ----- -Data ID: nacos-config-product.yaml - -Group : DEFAULT_GROUP - -配置格式: YAML - -配置内容: current.env: product-env ----- - -启动测试程序，输出结果如下： - -[source,subs="normal"] ----- -in product-env enviroment; user name :nacos-config-yaml-update; age: 68 -2018-11-02 15:42:14.628 INFO 33024 --- [Thread-11] ConfigServletWebServerApplicationContext : Closing org.springframework.boot.web.servlet.context.AnnotationConfigServletWebServerApplicationContext@6aa8e115: startup date [Fri Nov 02 15:42:03 CST 2018]; parent: org.springframework.context.annotation.AnnotationConfigApplicationContext@19bb07ed ----- - - -NOTE: 此案例中我们通过 `spring.profiles.active=` 的方式写死在配置文件中，而在真正的项目实施过程中这个变量的值是需要不同环境而有不同的值。这个时候通常的做法是通过 `-Dspring.profiles.active=` 参数指定其配置来达到环境间灵活的切换。 - -=== 支持自定义 namespace 的配置 - -Nacos 内部有 https://nacos.io/zh-cn/docs/concepts.html[Namespace 的概念]: - -[quote] -用于进行租户粒度的配置隔离。不同的命名空间下，可以存在相同的 Group 或 Data ID 的配置。Namespace 的常用场景之一是不同环境的配置的区分隔离，例如开发测试环境和生产环境的资源（如配置、服务）隔离等。 - -在没有明确指定 `${spring.cloud.nacos.config.namespace}` 配置的情况下， 默认使用的是 Nacos 上 Public 这个namespace。如果需要使用自定义的命名空间，可以通过以下配置来实现： -[source,properties] ----- -spring.cloud.nacos.config.namespace=b3404bc0-d7dc-4855-b519-570ed34b62d7 ----- - -NOTE: 该配置必须放在 bootstrap.properties 文件中。此外 `spring.cloud.nacos.config.namespace` 的值是 namespace 对应的 id，id 值可以在 Nacos 的控制台获取。并且在添加配置时注意不要选择其他的 namespae，否则将会导致读取不到正确的配置。 - -=== 支持自定义 Group 的配置 - -在没有明确指定 `${spring.cloud.nacos.config.group}` 配置的情况下， 默认使用的是 DEFAULT_GROUP 。如果需要自定义自己的 Group，可以通过以下配置来实现： - -[source,properties] ----- -spring.cloud.nacos.config.group=DEVELOP_GROUP ----- - -NOTE: 该配置必须放在 bootstrap.properties 文件中。并且在添加配置时 Group 的值一定要和 `spring.cloud.nacos.config.group` 的配置值一致。 - -=== 支持自定义扩展的 Data Id 配置 - -Nacos Config 从 0.2.1 版本后，可支持自定义 Data Id 的配置。关于这部分详细的设计可参考 https://github.com/alibaba/spring-cloud-alibaba/issues/141[这里]。 -一个完整的配置案例如下所示： - -[source,properties] ----- -spring.application.name=opensource-service-provider -spring.cloud.nacos.config.server-addr=127.0.0.1:8848 - -# config external configuration -# 1、Data Id 在默认的组 DEFAULT_GROUP,不支持配置的动态刷新 -spring.cloud.nacos.config.ext-config[0].data-id=ext-config-common01.properties - -# 2、Data Id 不在默认的组，不支持动态刷新 -spring.cloud.nacos.config.ext-config[1].data-id=ext-config-common02.properties -spring.cloud.nacos.config.ext-config[1].group=GLOBALE_GROUP - -# 3、Data Id 既不在默认的组，也支持动态刷新 -spring.cloud.nacos.config.ext-config[2].data-id=ext-config-common03.properties -spring.cloud.nacos.config.ext-config[2].group=REFRESH_GROUP -spring.cloud.nacos.config.ext-config[2].refresh=true ----- - -可以看到: - -* 通过 `spring.cloud.nacos.config.ext-config[n].data-id` 的配置方式来支持多个 Data Id 的配置。 -* 通过 `spring.cloud.nacos.config.ext-config[n].group` 的配置方式自定义 Data Id 所在的组，不明确配置的话，默认是 DEFAULT_GROUP。 -* 通过 `spring.cloud.nacos.config.ext-config[n].refresh` 的配置方式来控制该 Data Id 在配置变更时，是否支持应用中可动态刷新， -感知到最新的配置值。默认是不支持的。 - - -NOTE: 多个 Data Id 同时配置时，他的优先级关系是 `spring.cloud.nacos.config.ext-config[n].data-id` 其中 n 的值越大，优先级越高。 - -NOTE: `spring.cloud.nacos.config.ext-config[n].data-id` 的值必须带文件扩展名，文件扩展名既可支持 properties，又可以支持 yaml/yml。 -此时 `spring.cloud.nacos.config.file-extension` 的配置对自定义扩展配置的 Data Id 文件扩展名没有影响。 - -通过自定义扩展的 Data Id 配置，既可以解决多个应用间配置共享的问题，又可以支持一个应用有多个配置文件。 - -为了更加清晰的在多个应用间配置共享的 Data Id ，你可以通过以下的方式来配置： - -[source,properties] ----- -spring.cloud.nacos.config.shared-dataids=bootstrap-common.properties,all-common.properties -spring.cloud.nacos.config.refreshable-dataids=bootstrap-common.properties ----- - -可以看到： - -* 通过 `spring.cloud.nacos.config.shared-dataids` 来支持多个共享 Data Id 的配置，多个之间用逗号隔开。 -* 通过 `spring.cloud.nacos.config.refreshable-dataids` 来支持哪些共享配置的 Data Id 在配置变化时，应用中是否可动态刷新， -感知到最新的配置值，多个 Data Id 之间用逗号隔开。如果没有明确配置，默认情况下所有共享配置的 Data Id 都不支持动态刷新。 - -NOTE: 通过 `spring.cloud.nacos.config.shared-dataids` 来支持多个共享配置的 Data Id 时， -多个共享配置间的一个优先级的关系我们约定：按照配置出现的先后顺序，即后面的优先级要高于前面。 - -NOTE: 通过 `spring.cloud.nacos.config.shared-dataids` 来配置时，Data Id 必须带文件扩展名，文件扩展名既可支持 properties，也可以支持 yaml/yml。 -此时 `spring.cloud.nacos.config.file-extension` 的配置对自定义扩展配置的 Data Id 文件扩展名没有影响。 - -NOTE: `spring.cloud.nacos.config.refreshable-dataids` 给出哪些需要支持动态刷新时，Data Id 的值也必须明确给出文件扩展名。 - -=== 配置的优先级 - -Nacos Config 目前提供了三种配置能力从 Nacos 拉取相关的配置 - -* A: 通过 `spring.cloud.nacos.config.shared-dataids` 支持多个共享 Data Id 的配置 -* B: 通过 `spring.cloud.nacos.config.ext-config[n].data-id` 的方式支持多个扩展 Data Id 的配置 -* C: 通过内部相关规则(应用名、应用名+ Profile )自动生成相关的 Data Id 配置 - -若三种配置同时使用，优先级由高到低依次为: A --> B --> C - -=== Nacos Config 对外暴露的 Endpoint - -Nacos Config 内部提供了一个 Endpoint, 对应的 endpoint id 为 `nacos-config`。 - -Endpoint 暴露的 json 中包含了三种属性: - -1. Sources: 当前应用配置的数据信息 - -2. RefreshHistory: 配置刷新的历史记录 - -3. NacosConfigProperties: 当前应用 Nacos 的基础配置信息 - -这是 Endpoint 暴露的 json 示例: - -[source,json,indent=0] ----- -{ - "NacosConfigProperties": { - "serverAddr": "127.0.0.1:8848", - "encode": null, - "group": "DEFAULT_GROUP", - "prefix": null, - "fileExtension": "properties", - "timeout": 3000, - "endpoint": null, - "namespace": null, - "accessKey": null, - "secretKey": null, - "contextPath": null, - "clusterName": null, - "name": null, - "sharedDataids": "base-common.properties,common.properties", - "refreshableDataids": "common.properties", - "extConfig": null - }, - "RefreshHistory": [{ - "timestamp": "2019-07-29 11:20:04", - "dataId": "nacos-config-example.properties", - "md5": "7d5d7f1051ff6571e2ec9f90887d9d91" - }], - "Sources": [{ - "lastSynced": "2019-07-29 11:19:04", - "dataId": "common.properties" - }, { - "lastSynced": "2019-07-29 11:19:04", - "dataId": "base-common.properties" - }, { - "lastSynced": "2019-07-29 11:19:04", - "dataId": "nacos-config-example.properties" - }] -} ----- - - -=== 完全关闭 Nacos Config 的自动化配置 - -通过设置 `spring.cloud.nacos.config.enabled = false` 来完全关闭 `Spring Cloud Nacos Config` - -=== 关于 Nacos Config Starter 更多的配置项信息 - -更多关于 `Nacos Config Starter` 的配置项如下所示: - -|=== -|配置项 |Key |默认值 |说明 -|服务端地址|`spring.cloud.nacos.config.server-addr`|| Nacos Server 启动监听的ip地址和端口 -|配置对应的 DataId|`spring.cloud.nacos.config.name`|| 先取 prefix，再取 name，最后取 spring.application.name -|配置对应的 DataId|`spring.cloud.nacos.config.prefix`|| 先取 prefix，再取 name，最后取 spring.application.name -|配置内容编码|`spring.cloud.nacos.config.encode`||读取的配置内容对应的编码 -|GROUP|`spring.cloud.nacos.config.group`|`DEFAULT_GROUP`|配置对应的组 -|文件扩展名|`spring.cloud.nacos.config.fileExtension`|`properties`|配置项对应的文件扩展名，目前支持 properties 和 yaml(yml) -|获取配置超时时间|`spring.cloud.nacos.config.timeout`|`3000`|客户端获取配置的超时时间(毫秒) -|接入点|`spring.cloud.nacos.config.endpoint`||地域的某个服务的入口域名，通过此域名可以动态地拿到服务端地址 -|命名空间|`spring.cloud.nacos.config.namespace`||常用场景之一是不同环境的配置的区分隔离，例如开发测试环境和生产环境的资源（如配置、服务）隔离等 -|AccessKey|`spring.cloud.nacos.config.accessKey`||当要上阿里云时，阿里云上面的一个云账号名 -|SecretKey|`spring.cloud.nacos.config.secretKey`||当要上阿里云时，阿里云上面的一个云账号密码 -|Nacos Server 对应的 context path|`spring.cloud.nacos.config.contextPath`||Nacos Server 对外暴露的 context path -|集群|`spring.cloud.nacos.config.clusterName`||配置成Nacos集群名称 -|共享配置|`spring.cloud.nacos.config.sharedDataids`||共享配置的 DataId, "," 分割 -|共享配置动态刷新|`spring.cloud.nacos.config.refreshableDataids`||共享配置中需要动态刷新的 DataId, "," 分割 -|自定义 Data Id 配置|`spring.cloud.nacos.config.extConfig`||属性是个集合，内部由 `Config` POJO 组成。`Config` 有 3 个属性，分别是 `dataId`, `group` 以及 `refresh` -|=== diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/nacos-discovery.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/nacos-discovery.adoc deleted file mode 100644 index 8e98080bc..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/nacos-discovery.adoc +++ /dev/null @@ -1,354 +0,0 @@ -== Spring Cloud Alibaba Nacos Discovery - -Nacos 是一个 Alibaba 开源的、易于构建云原生应用的动态服务发现、配置管理和服务管理平台。 - -使用 Spring Cloud Alibaba Nacos Discovery，可基于 Spring Cloud 的编程模型快速接入 Nacos 服务注册功能。 - -=== 服务注册/发现: Nacos Discovery - -服务发现是微服务架构体系中最关键的组件之一。如果尝试着用手动的方式来给每一个客户端来配置所有服务提供者的服务列表是一件非常困难的事，而且也不利于 -服务的动态扩缩容。Nacos Discovery 可以帮助您将服务自动注册到 Nacos 服务端并且能够动态感知和刷新某个服务实例的服务列表。除此之外，Nacos -Discovery 也将服务实例自身的一些元数据信息-例如 host，port, 健康检查URL，主页等内容注册到 Nacos。Nacos 的获取和启动方式可以参考 https://nacos.io/zh-cn/docs/quick-start.html[Nacos 官网]。 - -=== 如何引入 Nacos Discovery 进行服务注册/发现 - -如果要在您的项目中使用 Nacos 来实现服务注册/发现，使用 group ID 为 `com.alibaba.cloud` 和 artifact ID 为 `spring-cloud-starter-alibaba-nacos-discovery` 的 starter。 - -[source,xml,indent=0] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-discovery - ----- - -=== 一个使用 Nacos Discovery 进行服务注册/发现并调用的例子 - -Nacos Discovery 适配了 Netflix Ribbon，可以使用 RestTemplate 或 OpenFeign 进行服务的调用。 - -==== Nacos Server 启动 - -具体启动方式参考 https://nacos.io/zh-cn/docs/quick-start.html[Nacos 官网]。 - -Nacos Server 启动后，进入 http://ip:8848 查看控制台(默认账号名/密码为 nacos/nacos): - -.Nacos Dashboard -image::https://img.alicdn.com/tfs/TB1dyWJbQL0gK0jSZFtXXXQCXXa-2788-1086.png[] - -关于更多的 Nacos Server 版本，可以从 https://github.com/alibaba/nacos/releases[release 页面] 下载最新的版本。 - -==== Provider 应用 - -以下步骤向您展示了如何将一个服务注册到 Nacos。 - -* pom.xml的配置。一个完整的 pom.xml 配置如下所示： - -.pom.xml -[source,xml] ----- - - - 4.0.0 - - open.source.test - nacos-discovery-test - 1.0-SNAPSHOT - nacos-discovery-test - - - org.springframework.boot - spring-boot-starter-parent - ${spring.boot.version} - - - - - UTF-8 - UTF-8 - 1.8 - - - - - - org.springframework.cloud - spring-cloud-dependencies - ${spring.cloud.version} - pom - import - - - com.alibaba.cloud - spring-cloud-alibaba-dependencies - ${spring.cloud.alibaba.version} - pom - import - - - - - - - org.springframework.boot - spring-boot-starter-web - - - - org.springframework.boot - spring-boot-starter-actuator - - - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-discovery - - - - - - - org.springframework.boot - spring-boot-maven-plugin - - - - ----- - -* application.properties 配置。一些关于 Nacos 基本的配置也必须在 application.properties(也可以是application.yaml)配置，如下所示： - -.application.properties -[source,properties,indent=0] ----- -server.port=8081 -spring.application.name=nacos-provider -spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 -management.endpoints.web.exposure.include=* ----- - - -NOTE: 如果不想使用 Nacos 作为您的服务注册与发现，可以将 `spring.cloud.nacos.discovery` 设置为 `false`。 - -* 启动 Provider 示例。如下所示： - -[source,java,indent=0] ----- -@SpringBootApplication -@EnableDiscoveryClient -public class NacosProviderDemoApplication { - - public static void main(String[] args) { - SpringApplication.run(NacosProviderDemoApplication.class, args); - } - - @RestController - public class EchoController { - @GetMapping(value = "/echo/{string}") - public String echo(@PathVariable String string) { - return "Hello Nacos Discovery " + string; - } - } -} ----- - -这个时候你就可以在 Nacos的控制台上看到注册上来的服务信息了。 - -==== Consumer 应用 - -Consumer 应用可能还没像启动一个 Provider 应用那么简单。因为在 Consumer 端需要去调用 Provider 端提供的REST 服务。例子中我们使用最原始的一种方式， -即显示的使用 LoadBalanceClient 和 RestTemplate 结合的方式来访问。 -pom.xml 和 application.properties 的配置可以参考 1.2 小结。启动一个 Consumer应用的示例代码如下所示： - -NOTE: 通过带有负载均衡的RestTemplate 和 FeignClient 也是可以访问的。 - -[source,java,indent=0] ----- -@SpringBootApplication -@EnableDiscoveryClient -public class NacosConsumerApp { - - @RestController - public class NacosController{ - - @Autowired - private LoadBalancerClient loadBalancerClient; - @Autowired - private RestTemplate restTemplate; - - @Value("${spring.application.name}") - private String appName; - - @GetMapping("/echo/app-name") - public String echoAppName(){ - //使用 LoadBalanceClient 和 RestTemplate 结合的方式来访问 - ServiceInstance serviceInstance = loadBalancerClient.choose("nacos-provider"); - String url = String.format("http://%s:%s/echo/%s",serviceInstance.getHost(),serviceInstance.getPort(),appName); - System.out.println("request url:"+url); - return restTemplate.getForObject(url,String.class); - } - - } - - //实例化 RestTemplate 实例 - @Bean - public RestTemplate restTemplate(){ - - return new RestTemplate(); - } - - public static void main(String[] args) { - - SpringApplication.run(NacosConsumerApp.class,args); - } -} ----- - -这个例子中我们注入了一个 LoadBalancerClient 的实例，并且手动的实例化一个 RestTemplate，同时将 `spring.application.name` 的配置值 注入到应用中来， -目的是调用 Provider 提供的服务时，希望将当前配置的应用名给显示出来。 - -NOTE: 在启动 Consumer 应用之前请先将 Nacos 服务启动好。具体启动方式可参考 https://nacos.io/zh-cn/docs/quick-start.html[Nacos 官网]。 - -启动后，访问 Consumer 提供出来的 `http://ip:port/echo/app-name` 接口。我这里测试启动的 port是 8082。访问结果如下所示： - - 访问地址：http://127.0.0.1:8082/echo/app-name - 访问结果：Hello Nacos Discovery nacos-consumer - -=== Nacos Discovery 对外暴露的 Endpoint - -Nacos Discovery 内部提供了一个 Endpoint, 对应的 endpoint id 为 `nacos-discovery`。 - -Endpoint 暴露的 json 中包含了两种属性: - -1. subscribe: 显示了当前服务有哪些服务订阅者 - -2. NacosDiscoveryProperties: 当前应用 Nacos 的基础配置信息 - -这是 Endpoint 暴露的 json 示例: - -[source,json,indent=0] ----- -{ - "subscribe": [ - { - "jsonFromServer": "", - "name": "nacos-provider", - "clusters": "", - "cacheMillis": 10000, - "hosts": [ - { - "instanceId": "30.5.124.156#8081#DEFAULT#nacos-provider", - "ip": "30.5.124.156", - "port": 8081, - "weight": 1.0, - "healthy": true, - "enabled": true, - "cluster": { - "serviceName": null, - "name": null, - "healthChecker": { - "type": "TCP" - }, - "defaultPort": 80, - "defaultCheckPort": 80, - "useIPPort4Check": true, - "metadata": { - - } - }, - "service": null, - "metadata": { - - } - } - ], - "lastRefTime": 1541755293119, - "checksum": "e5a699c9201f5328241c178e804657e11541755293119", - "allIPs": false, - "key": "nacos-provider", - "valid": true - } - ], - "NacosDiscoveryProperties": { - "serverAddr": "127.0.0.1:8848", - "endpoint": "", - "namespace": "", - "logName": "", - "service": "nacos-provider", - "weight": 1.0, - "clusterName": "DEFAULT", - "metadata": { - - }, - "registerEnabled": true, - "ip": "30.5.124.201", - "networkInterface": "", - "port": 8082, - "secure": false, - "accessKey": "", - "secretKey": "" - } -} ----- - -=== 如何开启权重路由 - -==== Ribbon - -.application.properties -[source,properties] ----- -[service_name].ribbon.NFLoadBalancerRuleClassName=com.alibaba.cloud.nacos.ribbon.NacosRule ----- - -=== 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使用以下配置： -[source,properties] ----- -spring.cloud.nacos.discovery.ip-type=IPv4 ----- - -==== 仅注册IPv6 -如果您只想使用IPv6地址，可以在application.properties使用以下配置： -[source,properties] ----- -spring.cloud.nacos.discovery.ip-type=IPv6 ----- - -=== 关于 Nacos Discovery Starter 更多的配置项信息 - -更多关于 Nacos Discovery Starter 的配置项如下所示: - -|=== -|配置项 |Key |默认值 |说明 -|服务端地址|`spring.cloud.nacos.discovery.server-addr`|| Nacos Server 启动监听的ip地址和端口 -|服务名|`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.cluster-name`|`DEFAULT`|Nacos集群名称 -|接入点|`spring.cloud.nacos.discovery.endpoint`||地域的某个服务的入口域名，通过此域名可以动态地拿到服务端地址 -|是否集成Ribbon|`ribbon.nacos.enabled`|`true`|一般都设置成true即可 -|是否开启Nacos Watch|`spring.cloud.nacos.discovery.watch.enabled`|`true`|可以设置成false来关闭 watch -|是否开启Nacos Discovery HeartBeat|`spring.cloud.nacos.discovery.heart-beat.enabled`|`false`|可以设置成 true 来开启 heart beat -|=== - diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/oss.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/oss.adoc deleted file mode 100644 index bff6b663b..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/oss.adoc +++ /dev/null @@ -1,140 +0,0 @@ -== Spring Cloud AliCloud OSS - -OSS（Object Storage Service）是阿里云的一款对象存储服务产品， Spring Cloud AliCloud OSS 提供了Spring Cloud规范下商业版的对象存储服务，提供简单易用的API，并且支持与 Spring 框架中 Resource 的整合。 - -=== 如何引入 Spring Cloud AliCloud OSS - -如果要在您的项目中引入 OSS，使用 group ID 为 `org.springframework.cloud` 和 artifact ID 为 `spring-cloud-starter-alicloud-oss` 的 starter。 - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alicloud-oss - ----- - -=== 如何使用 OSS API - -==== 配置 OSS - -使用 Spring Cloud AliCloud OSS 之前，需要在 application.properties 中加入以下配置。 - -[source,properties] ----- -spring.cloud.alicloud.access-key=你的阿里云AK -spring.cloud.alicloud.secret-key=你的阿里云SK -spring.cloud.alicloud.oss.endpoint=***.aliyuncs.com ----- - -access-key 和 secret-key 是阿里云账号的AK/SK，需要首先注册阿里云账号，然后登陆 https://usercenter.console.aliyun.com/#/manage/ak[阿里云AK/SK管理页面] ，即可看到 AccessKey ID 和 Access Key Secret ，如果没有的话，需要点击"创建AccessKey"按钮创建。 - -endpoint可以到 OSS 的 https://help.aliyun.com/document_detail/31837.html?spm=a2c4g.11186623.2.9.7dc72841Z2hGqa#concept-zt4-cvy-5db[官方文档]中查看，根据所在的 region ，填写对应的 endpoint 即可。 - - -==== 引入 OSS API - -Spring Cloud Alicloud OSS 中的 OSS API 基于阿里云官方OSS SDK提供，具备上传、下载、查看等所有对象存储类操作API。 - -一个简单的使用 OSS API 的应用如下。 - -[source,java] ----- -@SpringBootApplication -public class OssApplication { - - @Autowired - private OSS ossClient; - - @RequestMapping("/") - public String home() { - ossClient.putObject("bucketName", "fileName", new FileInputStream("/your/local/file/path")); - return "upload success"; - } - - public static void main(String[] args) throws URISyntaxException { - SpringApplication.run(OssApplication.class, args); - } - -} ----- - -在上传文件之前，首先需要 https://account.aliyun.com/register/register.htm?spm=5176.8142029.388261.26.e9396d3eaYK2sG&oauth_callback=https%3A%2F%2Fwww.aliyun.com%2F[注册阿里云账号] ，如果已经有的话，请 https://common-buy.aliyun.com/?spm=5176.8465980.unusable.dopen.4cdf1450rg8Ujb&commodityCode=oss#/open[开通OSS服务]。 - -进入 https://oss.console.aliyun.com/overview[OSS控制台]，点击左侧"新建Bucket"，按照提示创建一个Bucket，然后将bucket名称替换掉上面代码中的"bucketName"，而"fileName"取任意文件名，"/your/local/file/path"取任意本地文件路径，然后 curl http://127.0.0.1:端口/ 即可上传文件，可以到 https://oss.console.aliyun.com/overview[OSS控制台]查看效果。 - -更多关于 OSS API 的操作，可以参考 https://help.aliyun.com/document_detail/32008.html[OSS官方SDK文档]。 - -=== 与 Spring 框架的 Resource 结合 - -Spring Cloud AliCloud OSS 整合了 Spring 框架的 Resource 规范，可以让用户很方便的引用 OSS 的资源。 - -一个简单的使用 Resource 的例子如下。 - -[source,java] ----- -@SpringBootApplication -public class OssApplication { - - @Value("oss://bucketName/fileName") - private Resource file; - - @GetMapping("/file") - public String fileResource() { - try { - return "get file resource success. content: " + StreamUtils.copyToString( - file.getInputStream(), Charset.forName(CharEncoding.UTF_8)); - } catch (Exception e) { - return "get resource fail: " + e.getMessage(); - } - } - - public static void main(String[] args) throws URISyntaxException { - SpringApplication.run(OssApplication.class, args); - } - -} ----- - -NOTE: 以上示例运行的前提是，在 OSS 上需要有名为"bucketName"的Bucket，同时在该Bucket下，存在名为"fileName"的文件。 - -=== 采用 STS 授权 - -Spring Cloud AliCloud OSS 除了 AccessKey/SecretKey 的授权方式以外，还支持 STS 授权方式。 STS 是临时访问令牌的方式，一般用于授权第三方，临时访问自己的资源。 - -作为第三方，也就是被授权者，只需要配置以下内容，就可以访问临时被授权的资源。 - -[source,properties] ----- -spring.cloud.alicloud.oss.authorization-mode=STS -spring.cloud.alicloud.oss.endpoint=***.aliyuncs.com -spring.cloud.alicloud.oss.sts.access-key=你被授权的AK -spring.cloud.alicloud.oss.sts.secret-key=你被授权的SK -spring.cloud.alicloud.oss.sts.security-token=你被授权的ST ----- - -其中 spring.cloud.alicloud.oss.authorization-mode 是枚举类型，此时填写 STS ，代表采用 STS 的方式授权。 endpoint可以到 OSS 的 https://help.aliyun.com/document_detail/31837.html?spm=a2c4g.11186623.2.9.7dc72841Z2hGqa#concept-zt4-cvy-5db[官方文档]中查看，根据所在的 region ，填写对应的 endpoint 即可。 - -access-key、secret-key和security-token需要由授权方颁发，如果对 STS 不了解的话，可以参考 https://help.aliyun.com/document_detail/31867.html[STS官方文档]。 - -=== 更多客户端配置 - -除了基本的配置项以外， Spring Cloud AliCloud OSS 还支持很多额外的配置，也是在 application.properties 文件中。 - -以下是一些简单的示例。 - -[source,properties] ----- -spring.cloud.alicloud.oss.authorization-mode=STS -spring.cloud.alicloud.oss.endpoint=***.aliyuncs.com -spring.cloud.alicloud.oss.sts.access-key=你被授权的AK -spring.cloud.alicloud.oss.sts.secret-key=你被授权的SK -spring.cloud.alicloud.oss.sts.security-token=你被授权的ST - -spring.cloud.alicloud.oss.config.connection-timeout=3000 -spring.cloud.alicloud.oss.config.max-connections=1000 ----- - -如果想了解更多的配置项，可以参考 https://help.aliyun.com/document_detail/32010.html?spm=a2c4g.11186623.6.703.50b25413nGsYHc[OSSClient配置项] 的末尾表格。 - -NOTE: 通常情况下，都需要将 https://help.aliyun.com/document_detail/32010.html?spm=a2c4g.11186623.6.703.50b25413nGsYHc[OSSClient配置项] 末尾表格中的参数名更换成"-"连接，且所有字母小写。例如 ConnectionTimeout，对应 connection-timeout。 \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/auth-process.png b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/auth-process.png deleted file mode 100644 index 9e286b356..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/auth-process.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/governance-module.png b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/governance-module.png deleted file mode 100644 index 3e981bd30..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/governance-module.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-12-26-461.png b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-12-26-461.png deleted file mode 100644 index c888c29a9..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-12-26-461.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-12-58-177.png b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-12-58-177.png deleted file mode 100644 index 158803eed..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-12-58-177.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-14-02-388.png b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-14-02-388.png deleted file mode 100644 index 68c0432ac..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-14-02-388.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-14-50-461.png b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-14-50-461.png deleted file mode 100644 index 246eea025..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-14-50-461.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-15-39-851.png b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-15-39-851.png deleted file mode 100644 index 3a3d5d271..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-15-39-851.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-16-25-989.png b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-16-25-989.png deleted file mode 100644 index 5089084bc..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/image-2022-09-15-16-16-25-989.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/resource-transform.png b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/resource-transform.png deleted file mode 100644 index 3865e9458..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/pic/resource-transform.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/rocketmq-new.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/rocketmq-new.adoc deleted file mode 100644 index 6b04f7e56..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/rocketmq-new.adoc +++ /dev/null @@ -1,378 +0,0 @@ -== Spring Cloud Alibaba RocketMQ Binder - -=== RocketMQ 介绍 - -https://rocketmq.apache.org[RocketMQ] 是一款开源的分布式消息系统，基于高可用分布式集群技术，提供低延时的、高可靠的消息发布与订阅服务。同时，广泛应用于多个领域，包括异步通信解耦、企业解决方案、金融支付、电信、电子商务、快递物流、广告营销、社交、即时通信、移动应用、手游、视频、物联网、车联网等。 - -具有以下特点： - -* 能够保证严格的消息顺序 - -* 提供丰富的消息拉取模式 - -* 高效的订阅者水平扩展能力 - -* 实时的消息订阅机制 - -* 亿级消息堆积能力 - -=== RocketMQ 基本使用 - -* 下载 RocketMQ - -下载 https://www.apache.org/dyn/closer.cgi?path=rocketmq/4.3.2/rocketmq-all-4.3.2-bin-release.zip[RocketMQ最新的二进制文件]，并解压 - -解压后的目录结构如下： - -``` -apache-rocketmq -├── LICENSE -├── NOTICE -├── README.md -├── benchmark -├── bin -├── conf -└── lib -``` - -* 启动 NameServer - -```bash -nohup sh bin/mqnamesrv & -tail -f ~/logs/rocketmqlogs/namesrv.log -``` - -* 启动 Broker - -```bash -nohup sh bin/mqbroker -n localhost:9876 & -tail -f ~/logs/rocketmqlogs/broker.log -``` - -* 发送、接收消息 - -发送消息： - -```bash -sh bin/tools.sh org.apache.rocketmq.example.quickstart.Producer -``` - -发送成功后显示：`SendResult [sendStatus=SEND_OK, msgId= ...` - -接收消息： - -```bash -sh bin/tools.sh org.apache.rocketmq.example.quickstart.Consumer -``` - -接收成功后显示：`ConsumeMessageThread_%d Receive New Messages: [MessageExt...` - -* 关闭 Server - -```bash -sh bin/mqshutdown broker -sh bin/mqshutdown namesrv -``` - -=== Spring Cloud Stream 介绍 - -Spring Cloud Stream 是一个用于构建基于消息的微服务应用框架。它基于 SpringBoot 来创建具有生产级别的单机 Spring 应用，并且使用 `Spring Integration` 与 Broker 进行连接。 - -Spring Cloud Stream 提供了消息中间件配置的统一抽象，推出了 publish-subscribe、consumer groups、partition 这些统一的概念。 - -Spring Cloud Stream 内部有两个概念：Binder 和 Binding。 - -* Binder: 跟外部消息中间件集成的组件，用来创建 Binding，各消息中间件都有自己的 Binder 实现。 - -比如 `Kafka` 的实现 `KafkaMessageChannelBinder`，`RabbitMQ` 的实现 `RabbitMessageChannelBinder` 以及 `RocketMQ` 的实现 `RocketMQMessageChannelBinder`。 - -* Binding: 包括 Input Binding 和 Output Binding。 - -Binding 在消息中间件与应用程序提供的 Provider 和 Consumer 之间提供了一个桥梁，实现了开发者只需使用应用程序的 Provider 或 Consumer 生产或消费数据即可，屏蔽了开发者与底层消息中间件的接触。 - -.Spring Cloud Stream -image::https://docs.spring.io/spring-cloud-stream/docs/current/reference/htmlsingle/images/SCSt-overview.png[] - -使用 Spring Cloud Stream 完成一段简单的消息发送和消息接收代码： - -```java -MessageChannel messageChannel = new DirectChannel(); - -// 消息订阅 -((SubscribableChannel) messageChannel).subscribe(new MessageHandler() { - @Override - public void handleMessage(Message message) throws MessagingException { - System.out.println("receive msg: " + message.getPayload()); - } -}); - -// 消息发送 -messageChannel.send(MessageBuilder.withPayload("simple msg").build()); -``` - -这段代码所有的消息类都是 `spring-messaging` 模块里提供的。屏蔽具体消息中间件的底层实现，如果想用更换消息中间件，在配置文件里配置相关消息中间件信息以及修改 binder 依赖即可。 - -**Spring Cloud Stream 底层基于这段代码去做了各种抽象。** - - -=== 如何使用 Spring Cloud Alibaba RocketMQ Binder - -如果要在您的项目中引入 RocketMQ Binder，需要引入如下 maven 依赖： - -```xml - - com.alibaba.cloud - spring-cloud-stream-binder-rocketmq - -``` - -或者可以使用 Spring Cloud Stream RocketMQ Starter： - -```xml - - com.alibaba.cloud - spring-cloud-starter-stream-rocketmq - -``` - -=== Spring Cloud Alibaba RocketMQ Binder 实现 - -这是 Spring Cloud Stream RocketMQ Binder 的实现架构: - -.SCS RocketMQ Binder -image::https://img.alicdn.com/tfs/TB1v8rcbUY1gK0jSZFCXXcwqXXa-1236-773.png[] - -RocketMQ Binder 的重构优化去除了对 https://github.com/apache/rocketmq-spring[RocketMQ-Spring]框架的依赖 。 -RocketMQ Binder 核心类 `RocketMQMessageChannelBinder` 实现了 Spring Cloud Stream 规范，内部会构建 https://github.com/alibaba/spring-cloud-alibaba/blob/rocketmq/spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/integration/inbound/RocketMQInboundChannelAdapter.java[RocketMQInboundChannelAdapter] 和 https://github.com/alibaba/spring-cloud-alibaba/blob/rocketmq/spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/integration/outbound/RocketMQProducerMessageHandler.java[RocketMQProducerMessageHandler]。 - -`RocketMQProducerMessageHandler` 会基于 Binding 配置通过 https://github.com/alibaba/spring-cloud-alibaba/blob/rocketmq/spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/integration/outbound/RocketMQProduceFactory.java[RocketMQProduceFactory]构造 RocketMQ Producer，其内部会把 `spring-messaging` 模块内 `org.springframework.messaging.Message` 消息类转换成 RocketMQ 的消息类 `org.apache.rocketmq.common.message.Message`，然后发送出去。 - -`RocketMQInboundChannelAdapter` 也会基于 Binding 配置通过 https://github.com/alibaba/spring-cloud-alibaba/blob/rocketmq/spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/integration/inbound/RocketMQConsumerFactory.java[RocketMQConsumerFactory]构造 DefaultMQPushConsumer，其内部会启动 RocketMQ Consumer 接收消息。 - -NOTE: 与 https://github.com/apache/rocketmq-spring[RocketMQ-Spring] 框架的兼容需要手动处理 - -目前 Binder 支持在 `Header` 中设置相关的 key 来进行 RocketMQ Message 消息的特性设置。 - -比如 `TAGS`、`KEYS`、`TRANSACTIONAL_ARGS` 等 RocketMQ 消息对应的标签，详情见 https://github.com/alibaba/spring-cloud-alibaba/blob/rocketmq/spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/contants/RocketMQConst.java[com.alibaba.cloud.stream.binder.rocketmq.constant.RocketMQConst] - -```java -MessageBuilder builder = MessageBuilder.withPayload(msg) - .setHeader(RocketMQHeaders.TAGS, "binder") - .setHeader(RocketMQHeaders.KEYS, "my-key"); -Message message = builder.build(); -output().send(message); -``` -NOTE: 更多使用请参考样例: https://github.com/alibaba/spring-cloud-alibaba/blob/rocketmq/spring-cloud-alibaba-examples/rocketmq-example/rocketmq-produce-example/src/main/java/com/alibaba/cloud/examples/SenderService.java[com.alibaba.cloud.examples.SenderService] - -=== MessageSource 支持 - -SCS RocketMQ Binder 支持 `MessageSource`，可以进行消息的拉取，例子如下： - -```java -@SpringBootApplication -@EnableBinding(MQApplication.PolledProcessor.class) -public class MQApplication { - - private final Logger logger = - LoggerFactory.getLogger(MQApplication.class); - - public static void main(String[] args) { - SpringApplication.run(MQApplication.class, args); - } - - @Bean - public ApplicationRunner runner(PollableMessageSource source, - MessageChannel dest) { - return args -> { - while (true) { - boolean result = source.poll(m -> { - String payload = (String) m.getPayload(); - logger.info("Received: " + payload); - dest.send(MessageBuilder.withPayload(payload.toUpperCase()) - .copyHeaders(m.getHeaders()) - .build()); - }, new ParameterizedTypeReference() { }); - if (result) { - logger.info("Processed a message"); - } - else { - logger.info("Nothing to do"); - } - Thread.sleep(5_000); - } - }; - } - - public static interface PolledProcessor { - - @Input - PollableMessageSource source(); - - @Output - MessageChannel dest(); - - } - -} -``` - - - -=== 配置选项 - -==== RocketMQ Binder Properties - -spring.cloud.stream.rocketmq.binder.name-server:: -RocketMQ NameServer 地址(老版本使用 namesrv-addr 配置项)。 -+ -Default: `127.0.0.1:9876`. -spring.cloud.stream.rocketmq.binder.access-key:: -阿里云账号 AccessKey。 -+ -Default: null. -spring.cloud.stream.rocketmq.binder.secret-key:: -阿里云账号 SecretKey。 -+ -Default: null. -spring.cloud.stream.rocketmq.binder.enable-msg-trace:: -是否为 Producer 和 Consumer 开启消息轨迹功能 -+ -Default: `true`. -spring.cloud.stream.rocketmq.binder.customized-trace-topic:: -消息轨迹开启后存储的 topic 名称。 -+ -Default: `RMQ_SYS_TRACE_TOPIC`. - - -==== RocketMQ Consumer Properties - -下面的这些配置是以 `spring.cloud.stream.rocketmq.bindings..consumer.` 为前缀的 RocketMQ Consumer 相关的配置。 -更多见 https://github.com/alibaba/spring-cloud-alibaba/blob/rocketmq/spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/properties/RocketMQConsumerProperties.java[com.alibaba.cloud.stream.binder.rocketmq.properties.RocketMQConsumerProperties]。 - -enable:: -是否启用 Consumer。 -+ -默认值: `true`. -subscription:: -Consumer 基于 TAGS 订阅，多个 tag 以 `||` 分割。更多见 `com.alibaba.cloud.stream.binder.rocketmq.properties.RocketMQConsumerProperties.subscription` -+ -默认值: empty. -messageModel:: -Consumer 消费模式。如果想让每一个的订阅者都能接收到消息，可以使用广播模式。更多见 `org.apache.rocketmq.common.protocol.heartbeat.MessageModel` -+ -默认值: `CLUSTERING`. -consumeFromWhere:: -Consumer 从哪里开始消费。更多见 `org.apache.rocketmq.common.consumer.ConsumeFromWhere` -+ -默认值: `CONSUME_FROM_LAST_OFFSET`. - -#下面的这些配置是 Consumer Push 模式相关的配置。# - `spring.cloud.stream.rocketmq.bindings..consumer.push.` - -orderly:: -是否同步消费消息模式 -+ -默认值: `false`. -delayLevelWhenNextConsume:: -异步消费消息模式下消费失败重试策略： -* -1,不重复，直接放入死信队列 -* 0,broker 控制重试策略 -* >0,client 控制重试策略 -+ -默认值: `0`. -suspendCurrentQueueTimeMillis:: -同步消费消息模式下消费失败后再次消费的时间间隔。 -+ -默认值: `1000`. - -其他更多参数见 `com.alibaba.cloud.stream.binder.rocketmq.properties.RocketMQConsumerProperties.Push` - -#下面的这些配置是 Consumer Pull 模式相关的配置。# -`spring.cloud.stream.rocketmq.bindings..consumer.pull.` - -pullThreadNums:: -消费时拉取的线程数 -+ -默认值: `20`. -pollTimeoutMillis:: -拉取时的超时毫秒数 -+ -默认值: `1000 * 5`. - -其他更多参数见 `com.alibaba.cloud.stream.binder.rocketmq.properties.RocketMQConsumerProperties.Pull`. - -NOTE: 更多参数见 https://github.com/alibaba/spring-cloud-alibaba/blob/rocketmq/spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/properties/RocketMQConsumerProperties.java[com.alibaba.cloud.stream.binder.rocketmq.properties.RocketMQConsumerProperties] - -==== RocketMQ Provider Properties - -下面的这些配置是以 `spring.cloud.stream.rocketmq.bindings..producer.` 为前缀的 RocketMQ Producer 相关的配置。更多见 https://github.com/alibaba/spring-cloud-alibaba/blob/rocketmq/spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/properties/RocketMQProducerProperties.java[com.alibaba.cloud.stream.binder.rocketmq.properties.RocketMQProducerProperties] - -enable:: -是否启用 Producer。 -+ -默认值: `true`. -group:: -Producer group name。 -+ -默认值: empty. -maxMessageSize:: -消息发送的最大字节数。 -+ -默认值: `8249344`. -producerType:: -消息生产者类型，普通或者事务。更多见 `com.alibaba.cloud.stream.binder.rocketmq.properties.RocketMQProducerProperties.ProducerType`. -+ -默认值: `Normal`. -transactionListener:: -事务消息监听器的beanName，在 `producerType=Trans` 时才有效；必须是实现 `org.apache.rocketmq.client.producer.TransactionListener` 接口的Spring Bean。 - -sendType:: -消息发送类型（同步、异步、单向）。更多见`com.alibaba.cloud.stream.binder.rocketmq.properties.RocketMQProducerProperties.SendType`. -+ -默认值: `Sync`. -sendCallBack:: -消息发送后回调函数的beanName，在 `sendType=Async` 时才有效；必须是实现 `org.apache.rocketmq.client.producer.SendCallback` 接口的Spring Bean。 -vipChannelEnabled:: -是否在 Vip Channel 上发送消息。 -+ -默认值: `true`. -sendMessageTimeout:: -发送消息的超时时间(毫秒)。 -+ -默认值: `3000`. -compressMessageBodyThreshold:: -消息体压缩阀值(当消息体超过 4k 的时候会被压缩)。 -+ -默认值: `4096`. -retryTimesWhenSendFailed:: -在同步发送消息的模式下，消息发送失败的重试次数。 -+ -默认值: `2`. -retryTimesWhenSendAsyncFailed:: -在异步发送消息的模式下，消息发送失败的重试次数。 -+ -默认值: `2`. -retryAnotherBroker:: -消息发送失败的情况下是否重试其它的 broker。 -+ -默认值: `false`. - -NOTE: 生产者其他更多参数请见： -https://github.com/alibaba/spring-cloud-alibaba/blob/rocketmq/spring-cloud-alibaba-starters/spring-cloud-starter-stream-rocketmq/src/main/java/com/alibaba/cloud/stream/binder/rocketmq/properties/RocketMQProducerProperties.java[com.alibaba.cloud.stream.binder.rocketmq.properties.RocketMQProducerProperties] - -=== 阿里云 MQ 服务 - -使用阿里云 MQ 服务需要配置 AccessKey、SecretKey 以及云上的 NameServer 地址。 - -NOTE: 0.1.2 & 0.2.2 & 0.9.0 才支持该功能 - -```properties -spring.cloud.stream.rocketmq.binder.access-key=YourAccessKey -spring.cloud.stream.rocketmq.binder.secret-key=YourSecretKey -spring.cloud.stream.rocketmq.binder.name-server=NameServerInMQ -``` - -NOTE: topic 和 group 请以 实例id% 为前缀进行配置。比如 topic 为 "test"，需要配置成 "实例id%test" - -.NameServer 的获取(配置中请去掉 http:// 前缀) -image::https://spring-cloud-alibaba.oss-cn-beijing.aliyuncs.com/MQ.png[] diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/rocketmq.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/rocketmq.adoc deleted file mode 100644 index da78cd994..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/rocketmq.adoc +++ /dev/null @@ -1,360 +0,0 @@ -== Spring Cloud Alibaba RocketMQ Binder - -=== RocketMQ 介绍 - -https://rocketmq.apache.org[RocketMQ] 是一款开源的分布式消息系统，基于高可用分布式集群技术，提供低延时的、高可靠的消息发布与订阅服务。同时，广泛应用于多个领域，包括异步通信解耦、企业解决方案、金融支付、电信、电子商务、快递物流、广告营销、社交、即时通信、移动应用、手游、视频、物联网、车联网等。 - -具有以下特点： - -* 能够保证严格的消息顺序 - -* 提供丰富的消息拉取模式 - -* 高效的订阅者水平扩展能力 - -* 实时的消息订阅机制 - -* 亿级消息堆积能力 - -=== RocketMQ 基本使用 - -* 下载 RocketMQ - -下载 https://www.apache.org/dyn/closer.cgi?path=rocketmq/4.3.2/rocketmq-all-4.3.2-bin-release.zip[RocketMQ最新的二进制文件]，并解压 - -解压后的目录结构如下： - -``` -apache-rocketmq -├── LICENSE -├── NOTICE -├── README.md -├── benchmark -├── bin -├── conf -└── lib -``` - -* 启动 NameServer - -```bash -nohup sh bin/mqnamesrv & -tail -f ~/logs/rocketmqlogs/namesrv.log -``` - -* 启动 Broker - -```bash -nohup sh bin/mqbroker -n localhost:9876 & -tail -f ~/logs/rocketmqlogs/broker.log -``` - -* 发送、接收消息 - -发送消息： - -```bash -sh bin/tools.sh org.apache.rocketmq.example.quickstart.Producer -``` - -发送成功后显示：`SendResult [sendStatus=SEND_OK, msgId= ...` - -接收消息： - -```bash -sh bin/tools.sh org.apache.rocketmq.example.quickstart.Consumer -``` - -接收成功后显示：`ConsumeMessageThread_%d Receive New Messages: [MessageExt...` - -* 关闭 Server - -```bash -sh bin/mqshutdown broker -sh bin/mqshutdown namesrv -``` - -=== Spring Cloud Stream 介绍 - -Spring Cloud Stream 是一个用于构建基于消息的微服务应用框架。它基于 SpringBoot 来创建具有生产级别的单机 Spring 应用，并且使用 `Spring Integration` 与 Broker 进行连接。 - -Spring Cloud Stream 提供了消息中间件配置的统一抽象，推出了 publish-subscribe、consumer groups、partition 这些统一的概念。 - -Spring Cloud Stream 内部有两个概念：Binder 和 Binding。 - -* Binder: 跟外部消息中间件集成的组件，用来创建 Binding，各消息中间件都有自己的 Binder 实现。 - -比如 `Kafka` 的实现 `KafkaMessageChannelBinder`，`RabbitMQ` 的实现 `RabbitMessageChannelBinder` 以及 `RocketMQ` 的实现 `RocketMQMessageChannelBinder`。 - -* Binding: 包括 Input Binding 和 Output Binding。 - -Binding 在消息中间件与应用程序提供的 Provider 和 Consumer 之间提供了一个桥梁，实现了开发者只需使用应用程序的 Provider 或 Consumer 生产或消费数据即可，屏蔽了开发者与底层消息中间件的接触。 - -.Spring Cloud Stream -image::https://docs.spring.io/spring-cloud-stream/docs/current/reference/htmlsingle/images/SCSt-overview.png[] - -使用 Spring Cloud Stream 完成一段简单的消息发送和消息接收代码： - -```java -MessageChannel messageChannel = new DirectChannel(); - -// 消息订阅 -((SubscribableChannel) messageChannel).subscribe(new MessageHandler() { - @Override - public void handleMessage(Message message) throws MessagingException { - System.out.println("receive msg: " + message.getPayload()); - } -}); - -// 消息发送 -messageChannel.send(MessageBuilder.withPayload("simple msg").build()); -``` - -这段代码所有的消息类都是 `spring-messaging` 模块里提供的。屏蔽具体消息中间件的底层实现，如果想用更换消息中间件，在配置文件里配置相关消息中间件信息以及修改 binder 依赖即可。 - -**Spring Cloud Stream 底层基于这段代码去做了各种抽象。** - - -=== 如何使用 Spring Cloud Alibaba RocketMQ Binder - -如果要在您的项目中引入 RocketMQ Binder，需要引入如下 maven 依赖： - -```xml - - com.alibaba.cloud - spring-cloud-stream-binder-rocketmq - -``` - -或者可以使用 Spring Cloud Stream RocketMQ Starter： - -```xml - - com.alibaba.cloud - spring-cloud-starter-stream-rocketmq - -``` - -=== Spring Cloud Alibaba RocketMQ Binder 实现 - -这是 Spring Cloud Stream RocketMQ Binder 的实现架构: - -.SCS RocketMQ Binder -image::https://img.alicdn.com/tfs/TB1v8rcbUY1gK0jSZFCXXcwqXXa-1236-773.png[] - -RocketMQ Binder 的实现依赖于 https://github.com/apache/rocketmq-spring[RocketMQ-Spring] 框架。 - -RocketMQ-Spring 框架是 RocketMQ 与 Spring Boot 的整合，RocketMQ Spring 主要提供了 3 个特性： - -1. 使用 `RocketMQTemplate` 用来统一发送消息，包括同步、异步发送消息和事务消息 -2. `@RocketMQTransactionListener` 注解用来处理事务消息的监听和回查 -3. `@RocketMQMessageListener` 注解用来消费消息 - -RocketMQ Binder 的核心类 RocketMQMessageChannelBinder 实现了 Spring Cloud Stream 规范，内部构建会 `RocketMQInboundChannelAdapter` 和 `RocketMQMessageHandler`。 - -`RocketMQMessageHandler` 会基于 Binding 配置构造 `RocketMQTemplate`，`RocketMQTemplate` 内部会把 `spring-messaging` 模块内 `org.springframework.messaging.Message` 消息类转换成 RocketMQ 的消息类 `org.apache.rocketmq.common.message.Message`，然后发送出去。 - -`RocketMQInboundChannelAdapter` 也会基于 Binding 配置构造 `RocketMQListenerBindingContainer`，`RocketMQListenerBindingContainer` 内部会启动 RocketMQ `Consumer` 接收消息。 - -NOTE: 在使用 RocketMQ Binder 的同时也可以配置 rocketmq.** 用于触发 RocketMQ Spring 相关的 AutoConfiguration - -目前 Binder 支持在 `Header` 中设置相关的 key 来进行 RocketMQ Message 消息的特性设置。 - -比如 `TAGS`、`DELAY`、`TRANSACTIONAL_ARG`、`KEYS`、`WAIT_STORE_MSG_OK`、`FLAG` 表示 RocketMQ 消息对应的标签， - -```java -MessageBuilder builder = MessageBuilder.withPayload(msg) - .setHeader(RocketMQHeaders.TAGS, "binder") - .setHeader(RocketMQHeaders.KEYS, "my-key") - .setHeader(MessageConst.PROPERTY_DELAY_TIME_LEVEL, "1"); -Message message = builder.build(); -output().send(message); -``` - -=== MessageSource 支持 - -SCS RocketMQ Binder 支持 `MessageSource`，可以进行消息的拉取，例子如下： - -```java -@SpringBootApplication -@EnableBinding(MQApplication.PolledProcessor.class) -public class MQApplication { - - private final Logger logger = - LoggerFactory.getLogger(MQApplication.class); - - public static void main(String[] args) { - SpringApplication.run(MQApplication.class, args); - } - - @Bean - public ApplicationRunner runner(PollableMessageSource source, - MessageChannel dest) { - return args -> { - while (true) { - boolean result = source.poll(m -> { - String payload = (String) m.getPayload(); - logger.info("Received: " + payload); - dest.send(MessageBuilder.withPayload(payload.toUpperCase()) - .copyHeaders(m.getHeaders()) - .build()); - }, new ParameterizedTypeReference() { }); - if (result) { - logger.info("Processed a message"); - } - else { - logger.info("Nothing to do"); - } - Thread.sleep(5_000); - } - }; - } - - public static interface PolledProcessor { - - @Input - PollableMessageSource source(); - - @Output - MessageChannel dest(); - - } - -} -``` - - - -=== 配置选项 - -==== RocketMQ Binder Properties - -spring.cloud.stream.rocketmq.binder.name-server:: -RocketMQ NameServer 地址(老版本使用 namesrv-addr 配置项)。 -+ -Default: `127.0.0.1:9876`. -spring.cloud.stream.rocketmq.binder.access-key:: -阿里云账号 AccessKey。 -+ -Default: null. -spring.cloud.stream.rocketmq.binder.secret-key:: -阿里云账号 SecretKey。 -+ -Default: null. -spring.cloud.stream.rocketmq.binder.enable-msg-trace:: -是否为 Producer 和 Consumer 开启消息轨迹功能 -+ -Default: `true`. -spring.cloud.stream.rocketmq.binder.customized-trace-topic:: -消息轨迹开启后存储的 topic 名称。 -+ -Default: `RMQ_SYS_TRACE_TOPIC`. -+ -spring.cloud.stream.rocketmq.binder.access-channel:: -商业版rocketmq消息轨迹topic自适应，值为CLOUD -+ -Default: null. - - -==== RocketMQ Consumer Properties - -下面的这些配置是以 `spring.cloud.stream.rocketmq.bindings..consumer.` 为前缀的 RocketMQ Consumer 相关的配置。 - -enable:: -是否启用 Consumer。 -+ -默认值: `true`. -tags:: -Consumer 基于 TAGS 订阅，多个 tag 以 `||` 分割。 -+ -默认值: empty. -sql:: -Consumer 基于 SQL 订阅。 -+ -默认值: empty. -broadcasting:: -Consumer 是否是广播消费模式。如果想让所有的订阅者都能接收到消息，可以使用广播模式。 -+ -默认值: `false`. -orderly:: -Consumer 是否同步消费消息模式。 -+ -默认值: `false`. -delayLevelWhenNextConsume:: -异步消费消息模式下消费失败重试策略： -* -1,不重复，直接放入死信队列 -* 0,broker 控制重试策略 -* >0,client 控制重试策略 -+ -默认值: `0`. -suspendCurrentQueueTimeMillis:: -同步消费消息模式下消费失败后再次消费的时间间隔。 -+ -默认值: `1000`. - -==== RocketMQ Provider Properties - -下面的这些配置是以 `spring.cloud.stream.rocketmq.bindings..producer.` 为前缀的 RocketMQ Producer 相关的配置。 - -enable:: -是否启用 Producer。 -+ -默认值: `true`. -group:: -Producer group name。 -+ -默认值: empty. -maxMessageSize:: -消息发送的最大字节数。 -+ -默认值: `8249344`. -transactional:: -是否发送事务消息。 -+ -默认值: `false`. -sync:: -是否使用同步得方式发送消息。 -+ -默认值: `false`. -vipChannelEnabled:: -是否在 Vip Channel 上发送消息。 -+ -默认值: `true`. -sendMessageTimeout:: -发送消息的超时时间(毫秒)。 -+ -默认值: `3000`. -compressMessageBodyThreshold:: -消息体压缩阀值(当消息体超过 4k 的时候会被压缩)。 -+ -默认值: `4096`. -retryTimesWhenSendFailed:: -在同步发送消息的模式下，消息发送失败的重试次数。 -+ -默认值: `2`. -retryTimesWhenSendAsyncFailed:: -在异步发送消息的模式下，消息发送失败的重试次数。 -+ -默认值: `2`. -retryNextServer:: -消息发送失败的情况下是否重试其它的 broker。 -+ -默认值: `false`. - -=== 阿里云 MQ 服务 - -使用阿里云 MQ 服务需要配置 AccessKey、SecretKey 以及云上的 NameServer 地址。 - -NOTE: 0.1.2 & 0.2.2 & 0.9.0 才支持该功能 - -```properties -spring.cloud.stream.rocketmq.binder.access-key=YourAccessKey -spring.cloud.stream.rocketmq.binder.secret-key=YourSecretKey -spring.cloud.stream.rocketmq.binder.name-server=NameServerInMQ -spring.cloud.stream.rocketmq.binder.access-channel=CLOUD -``` - -NOTE: topic 和 group 请以 实例id% 为前缀进行配置。比如 topic 为 "test"，需要配置成 "实例id%test" - -.NameServer 的获取(配置中请去掉 http:// 前缀) -image::https://spring-cloud-alibaba.oss-cn-beijing.aliyuncs.com/MQ.png[] diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/schedulerx.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/schedulerx.adoc deleted file mode 100644 index bb23022aa..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/schedulerx.adoc +++ /dev/null @@ -1,114 +0,0 @@ -== Spring Cloud AliCloud SchedulerX - -SchedulerX（分布式任务调度） 是隶属于阿里云EDAS产品的组件， Spring Cloud AliCloud SchedulerX 提供了在Spring Cloud的配置规范下，分布式任务调度的功能支持。SchedulerX可提供秒级、精准、高可靠、高可用的定时任务调度服务，并支持多种类型的任务调度，如简单单机任务、简单多机任务、脚本任务以及网格任务。 - -=== 如何引入 Spring Cloud AliCloud SchedulerX - -如果要在您的项目中引入 SchedulerX，使用 group ID 为 `com.alibaba.cloud` 和 artifact ID 为 `spring-cloud-starter-alicloud-schedulerX` 的 starter。 - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alicloud-schedulerX - ----- - -=== 启动SchedulerX任务调度 - -当客户端引入了 Spring Cloud AliCloud SchedulerX Starter 以后，只需要进行一些简单的配置，就可以自动初始化SchedulerX的任务调度服务。 - -以下是一个简单的应用示例。 - -[source,java] ----- -@SpringBootApplication -public class ScxApplication { - - public static void main(String[] args) { - SpringApplication.run(ScxApplication.class, args); - } - -} ----- - -在application.properties中，需要加上以下配置。 - -[source,properties] ----- -server.port=18033 -# 其中cn-test是SchedulerX的测试区域 -spring.cloud.alicloud.scx.group-id=*** -spring.cloud.alicloud.edas.namespace=cn-test ----- - -在获取group-id之前，需要首先 https://account.aliyun.com/register/register.htm?spm=5176.8142029.388261.26.e9396d3eEIv28g&oauth_callback=https%3A%2F%2Fwww.aliyun.com%2F[注册阿里云账号] ，然后 https://common-buy.aliyun.com/?spm=5176.11451019.0.0.6f5965c0Uq5tue&commodityCode=edaspostpay#/buy[开通EDAS服务] ，并 https://edas.console.aliyun.com/#/edasTools[开通分布式任务管理组件] 。 - -其中group-id的获取，请参考 https://help.aliyun.com/document_detail/98784.html?spm=a2c4g.11186623.2.17.23c87da9P2F3tG[这里]。 - -NOTE: 在创建group的时候，要选择"测试"区域。 - -=== 编写一个简单任务 - -简单任务是最常用的任务类型，只需要实现 ScxSimpleJobProcessor 接口即可。 - -以下是一个简单的单机类型任务示例。 - -[source,java] ----- -public class SimpleTask implements ScxSimpleJobProcessor { - - @Override - public ProcessResult process(ScxSimpleJobContext context) { - System.out.println("-----------Hello world---------------"); - ProcessResult processResult = new ProcessResult(true); - return processResult; - } - -} ----- - -=== 对任务进行调度 - -进入 https://edas.console.aliyun.com/#/edasSchedulerXJob?regionNo=cn-test[SchedulerX任务列表] 页面，选择上方"测试"区域，点击右上角"新建Job"，创建一个Job，即如下所示。 - -[source,text] ----- -Job分组：测试——***-*-*-**** -Job处理接口：org.springframework.cloud.alibaba.cloud.examples.SimpleTask -类型：简单Job单机版 -定时表达式：默认选项——0 * * * * ? -Job描述：无 -自定义参数：无 ----- - -以上任务类型选择了"简单Job单机版"，并且制定了Cron表达式为"0 * * * * ?"，这意味着，每过一分钟，任务将会被执行且只执行一次。 - -更多任务类型，请参考 https://help.aliyun.com/document_detail/43136.html[SchedulerX官方文档]。 - -=== 生产环境使用 - -以上使用的都是SchedulerX的"测试"区域，主要用于本地调试和测试。 - -在生产级别，除了上面的group-id和namespace以外，还需要一些额外的配置，如下所示。 - -[source,properties] ----- -server.port=18033 -# 其中cn-test是SchedulerX的测试区域 -spring.cloud.alicloud.scx.group-id=*** -spring.cloud.alicloud.edas.namespace=*** -# 当应用运行在EDAS上时，以下配置不需要手动配置。 -spring.cloud.alicloud.access-key=*** -spring.cloud.alicloud.secret-key=*** -# 以下配置不是必须的，请参考SchedulerX文档 -spring.cloud.alicloud.scx.domain-name=*** ----- - -其中group-id与之前的获取方式一样，namespace则是从EDAS控制台左侧"命名空间"列表中获取命名空间ID。 - -NOTE: group-id必须创建在namespace当中。 - -access-key以及secret-key为阿里云账号的AK/SK信息，如果应用在EDAS上部署，则不需要填写这两项信息，否则请前往 https://usercenter.console.aliyun.com/#/manage/ak[安全信息管理]获取。 - -domain-name并不是必须的，具体请参考 https://help.aliyun.com/document_detail/35359.html[SchedulerX官方文档]。 \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/seata.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/seata.adoc deleted file mode 100644 index 81ba371b7..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/seata.adoc +++ /dev/null @@ -1,85 +0,0 @@ -== Spring Cloud Alibaba Seata - -=== Seata 介绍 - -Seata是一个分布式事务框架, 用于保证在微服务架构下每个服务的数据一致性。 - - -=== 如何使用seata - -如果要在您的项目中引入 Seata，使用 group ID 为 `com.alibaba.cloud` 和 artifact ID 为 `spring-cloud-starter-alibaba-seata` 的 starter。 - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-seata - ----- - -项目提供了相关实例 https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/seata-example[Example]，在运行之前，您需要完成以下步骤： - -1. 保证本地已经运行 `nacos-server` 在 `8848` 端口。 -2. 配置数据库，将 `account-server`、`order-service`、`storage-service` 这三个应用中的 resources 目录下的 `application.yml` 文件中的如下配置修改成你运行环境中的实际配置。 - - base: - config: - mdb: - hostname: 127.0.0.1 #your mysql server ip address - dbname: seata #your database name for test - port: 3306 #your mysql server listening port - username: root #your mysql server username - password: root #your mysql server password - -3. 创建数据库表，可根据 `spring-cloud-alibaba-examples/seata-example` 下的 `all.sql` 快速操作。 - - 根据选择的事务模式，创建 https://github.com/seata/seata/tree/develop/script/client[事务日志表]。比如默认为AT模式，需要使用到 undo_log 表，则进入 at/db 下选择对应的数据库脚本执行。 - - 创建 seata-server db模式所需要的 https://github.com/seata/seata/tree/develop/script/server/db[状态记录表] ，包括 `global_table` 、`branch_table` 、`lock_table` 、`distributed_lock`。 - - 创建 `spring-cloud-alibaba-examples/seata-example` 示例中所需的数据库表。 -4. 创建 `spring-cloud-alibaba-examples/seata-example` 所需要的Nacos配置。 - - data id: seata.properties, - Group: SEATA_ Group(Seata 1.5.1 默认组) - - 配置内容： - service.vgroupMapping.order-service-tx-group=default - service.vgroupMapping.account-service-tx-group=default - service.vgroupMapping.business-service-tx-group=default - service.vgroupMapping.storage-service-tx-group=default - -5. 启动 Seata Server，有SpringBoot 和下载server两种方式。 - - 运行 `spring-cloud-alibaba-examples/seata-example` 下的seata-server， 启动Seata server。 - - 根据seata官方提供的 https://seata.io/zh-cn/docs/ops/deploy-guide-beginner.html[seata-server.jar]启动Seata Server。 -6. 在本地启动 `spring-cloud-alibaba-examples/seata-example` 文件夹下的子服务 `account-service` , `order-service` , `storage-service` ，最后启动全局事务控制服务 `business-service`。 -7. 启动示例后，通过 HTTP 的 GET 方法访问如下 URL，可以分别验证在 `business-service` 中 通过 RestTemplate 和 FeignClient 调用其他服务的场景。 - - http://127.0.0.1:18081/seata/feign - http://127.0.0.1:18081/seata/rest - -=== Seata Dashboard - -- Seata 1.5.1支持Seata控制台本地访问控制台地址：`http://127.0.0.1:7091`。 -- 通过Seata控制台可以观察到正在执行的事务信息和全局锁信息，并且在事务完成时删除相关信息。 - - -=== 如何验证分布式事务的成功？ -==== Xid 信息是否成功传递 - -在 `account-server`、`order-service` 和 `storage-service` 三个 服务的 Controller 中，第一个执行的逻辑都是输出 RootContext 中的 Xid 信息，如果看到都输出了正确的 Xid 信息，即每次都发生变化，且同一次调用中所有服务的 Xid 都一致。则表明 Seata 的 Xid 的传递和还原是正常的。 - -==== 数据库中数据的一致性 - -在这个例子中，我们模拟一个用户购买商品的场景，StorageService 负责扣除库存数量，OrderService 负责保存订单，BusinessService 负责扣除用户账户余额,AccountService 负责更新账号的余额，并作为全局事务控制入口。 -为了演示示例，我们在 OrderService 和 AcountService 中使用了 Random。NextBoolean() 随机抛出异常，模拟调用服务时随机发生异常的场景。 - -如果分布式事务是有效的，那么下面的等式应该是正确的 - - - 用户原始金额（1000）=用户现有金额+商品单价（2）*订单数量*每个订单的商品数量（2） - - - 初始商品数量 (100) = 现有商品数量 + 订单数量 * 每个订单的商品数量 (2) - -=== Spring Cloud 支持点 - - 通过 Spring MVC 提供服务的服务提供者在收到 HTTP 请求时，可以自动恢复 Seata 上下文，该请求在 header 中包含 Seata 信息。 - - 当服务调用者通过 RestTemplate 调用时，支持自动传递 Seata 上下文。 - - 当服务调用者通过 FeignClient 调用时，支持自动传递 Seata 上下文。 - - 支持同时使用 SeataClient 和 Hystrix 的场景。 - - 支持 SeataClient 和 Sentinel 使用的场景。 \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sentinel.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sentinel.adoc deleted file mode 100644 index 64ffefe97..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sentinel.adoc +++ /dev/null @@ -1,451 +0,0 @@ -== Spring Cloud Alibaba Sentinel - -=== Sentinel 介绍 - -随着微服务的流行，服务和服务之间的稳定性变得越来越重要。 https://github.com/alibaba/Sentinel[Sentinel] 以流量为切入点，从流量控制、熔断降级、系统负载保护等多个维度保护服务的稳定性。 - -https://github.com/alibaba/Sentinel[Sentinel] 具有以下特征: - -* *丰富的应用场景*： Sentinel 承接了阿里巴巴近 10 年的双十一大促流量的核心场景，例如秒杀（即突发流量控制在系统容量可以承受的范围）、消息削峰填谷、实时熔断下游不可用应用等。 -* *完备的实时监控*： Sentinel 同时提供实时的监控功能。您可以在控制台中看到接入应用的单台机器秒级数据，甚至 500 台以下规模的集群的汇总运行情况。 -* *广泛的开源生态*： Sentinel 提供开箱即用的与其它开源框架/库的整合模块，例如与 Spring Cloud、Dubbo、gRPC 的整合。您只需要引入相应的依赖并进行简单的配置即可快速地接入 Sentinel。 -* *完善的 SPI 扩展点*： Sentinel 提供简单易用、完善的 SPI 扩展点。您可以通过实现扩展点，快速的定制逻辑。例如定制规则管理、适配数据源等。 - -=== 如何使用 Sentinel - -如果要在您的项目中引入 Sentinel，使用 group ID 为 `com.alibaba.cloud` 和 artifact ID 为 `spring-cloud-starter-alibaba-sentinel` 的 starter。 - -```xml -[source,yaml] - - com.alibaba.cloud - spring-cloud-starter-alibaba-sentinel - -``` - -下面这个例子就是一个最简单的使用 Sentinel 的例子: - -```java -@SpringBootApplication -public class Application { - - public static void main(String[] args) { - SpringApplication.run(ServiceApplication.class, args); - } - -} - -@RestController -public class TestController { - - @GetMapping(value = "/hello") - @SentinelResource("hello") - public String hello() { - return "Hello Sentinel"; - } - -} -``` - -@SentinelResource 注解用来标识资源是否被限流、降级。上述例子上该注解的属性 'hello' 表示资源名。 - -@SentinelResource 还提供了其它额外的属性如 `blockHandler`，`blockHandlerClass`，`fallback` 用于表示限流或降级的操作，更多内容可以参考 https://github.com/alibaba/Sentinel/wiki/%E6%B3%A8%E8%A7%A3%E6%94%AF%E6%8C%81[Sentinel注解支持]。 - -以上例子都是在 WebServlet 环境下使用的，Sentinel 目前已经支持 WebFlux，需要配合 `spring-boot-starter-webflux` 依赖触发 sentinel-starter 中 WebFlux 相关的自动化配置。 - -```java -@SpringBootApplication -public class Application { - - public static void main(String[] args) { - SpringApplication.run(ServiceApplication.class, args); - } - -} - -@RestController -public class TestController { - - @GetMapping("/mono") - @SentinelResource("hello") - public Mono mono() { - return Mono.just("simple string") - .transform(new SentinelReactorTransformer<>("otherResourceName")); - } - -} -``` - -===== Sentinel 控制台 - -Sentinel 控制台提供一个轻量级的控制台，它提供机器发现、单机资源实时监控、集群资源汇总，以及规则管理的功能。您只需要对应用进行简单的配置，就可以使用这些功能。 - -*注意*: 集群资源汇总仅支持 500 台以下的应用集群，有大概 1 - 2 秒的延时。 - -.Sentinel Dashboard -image::https://github.com/alibaba/Sentinel/wiki/image/dashboard.png[] - -开启该功能需要3个步骤： - -====== 获取控制台 - -您可以从 https://github.com/alibaba/Sentinel/releases[release 页面] 下载最新版本的控制台 jar 包。 - -您也可以从最新版本的源码自行构建 Sentinel 控制台： - -* 下载 https://github.com/alibaba/Sentinel/tree/master/sentinel-dashboard[控制台] 工程 -* 使用以下命令将代码打包成一个 fat jar: `mvn clean package` - - -====== 启动控制台 - -Sentinel 控制台是一个标准的 SpringBoot 应用，以 SpringBoot 的方式运行 jar 包即可。 - -```shell -java -Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080 -Dproject.name=sentinel-dashboard -jar sentinel-dashboard.jar -``` - -如若8080端口冲突，可使用 `-Dserver.port=新端口` 进行设置。 - -==== 配置控制台信息 - -.application.yml ----- -spring: - cloud: - sentinel: - transport: - port: 8719 - dashboard: localhost:8080 ----- - -这里的 `spring.cloud.sentinel.transport.port` 端口配置会在应用对应的机器上启动一个 Http Server，该 Server 会与 Sentinel 控制台做交互。比如 Sentinel 控制台添加了1个限流规则，会把规则数据 push 给这个 Http Server 接收，Http Server 再将规则注册到 Sentinel 中。 - -更多 Sentinel 控制台的使用及问题参考： https://github.com/alibaba/Sentinel/wiki/%E6%8E%A7%E5%88%B6%E5%8F%B0[Sentinel控制台] - -=== OpenFeign 支持 - -Sentinel 适配了 https://github.com/OpenFeign/feign[OpenFeign] 组件。如果想使用，除了引入 `sentinel-starter` 的依赖外还需要 2 个步骤： - -* 配置文件打开 sentinel 对 feign 的支持：`feign.sentinel.enabled=true` -* 加入 `openfeign starter` 依赖使 `sentinel starter` 中的自动化配置类生效： -```xml - - org.springframework.cloud - spring-cloud-starter-openfeign - -``` - -这是一个 `FeignClient` 的简单使用示例： - -```java -@FeignClient(name = "service-provider", fallback = EchoServiceFallback.class, configuration = FeignConfiguration.class) -public interface EchoService { - @GetMapping(value = "/echo/{str}") - String echo(@PathVariable("str") String str); -} - -class FeignConfiguration { - @Bean - public EchoServiceFallback echoServiceFallback() { - return new EchoServiceFallback(); - } -} - -class EchoServiceFallback implements EchoService { - @Override - public String echo(@PathVariable("str") String str) { - return "echo fallback"; - } -} -``` - -NOTE: Feign 对应的接口中的资源名策略定义：httpmethod:protocol://requesturl。`@FeignClient` 注解中的所有属性，Sentinel 都做了兼容。 - -`EchoService` 接口中方法 `echo` 对应的资源名为 `GET:http://service-provider/echo/{str}`。 - -=== RestTemplate 支持 - -Spring Cloud Alibaba Sentinel 支持对 `RestTemplate` 的服务调用使用 Sentinel 进行保护，在构造 `RestTemplate` bean的时候需要加上 `@SentinelRestTemplate` 注解。 - -```java -@Bean -@SentinelRestTemplate(blockHandler = "handleException", blockHandlerClass = ExceptionUtil.class) -public RestTemplate restTemplate() { - return new RestTemplate(); -} -``` - -`@SentinelRestTemplate` 注解的属性支持限流(`blockHandler`, `blockHandlerClass`)和降级(`fallback`, `fallbackClass`)的处理。 - -其中 `blockHandler` 或 `fallback` 属性对应的方法必须是对应 `blockHandlerClass` 或 `fallbackClass` 属性中的静态方法。 - -该方法的参数跟返回值跟 `org.springframework.http.client.ClientHttpRequestInterceptor#interceptor` 方法一致，其中参数多出了一个 `BlockException` 参数用于获取 Sentinel 捕获的异常。 - -比如上述 `@SentinelRestTemplate` 注解中 `ExceptionUtil` 的 `handleException` 属性对应的方法声明如下： - -```java -public class ExceptionUtil { - public static ClientHttpResponse handleException(HttpRequest request, byte[] body, ClientHttpRequestExecution execution, BlockException exception) { - ... - } -} -``` - -NOTE: 应用启动的时候会检查 `@SentinelRestTemplate` 注解对应的限流或降级方法是否存在，如不存在会抛出异常 - -`@SentinelRestTemplate` 注解的限流(`blockHandler`, `blockHandlerClass`)和降级(`fallback`, `fallbackClass`)属性不强制填写。 - -当使用 `RestTemplate` 调用被 Sentinel 熔断后，会返回 `RestTemplate request block by sentinel` 信息，或者也可以编写对应的方法自行处理返回信息。这里提供了 `SentinelClientHttpResponse` 用于构造返回信息。 - -Sentinel RestTemplate 限流的资源规则提供两种粒度： - -* `httpmethod:schema://host:port/path`：协议、主机、端口和路径 - -* `httpmethod:schema://host:port`：协议、主机和端口 - -NOTE: 以 `https://www.taobao.com/test` 这个 url 并使用 GET 方法为例。对应的资源名有两种粒度，分别是 `GET:https://www.taobao.com` 以及 `GET:https://www.taobao.com/test` - -=== 动态数据源支持 - -`SentinelProperties` 内部提供了 `TreeMap` 类型的 `datasource` 属性用于配置数据源信息。 - -比如配置 4 个数据源： - -[source,properties] ----- -spring.cloud.sentinel.datasource.ds1.file.file=classpath: degraderule.json -spring.cloud.sentinel.datasource.ds1.file.rule-type=flow - -#spring.cloud.sentinel.datasource.ds1.file.file=classpath: flowrule.json -#spring.cloud.sentinel.datasource.ds1.file.data-type=custom -#spring.cloud.sentinel.datasource.ds1.file.converter-class=org.springframework.cloud.alibaba.cloud.examples.JsonFlowRuleListConverter -#spring.cloud.sentinel.datasource.ds1.file.rule-type=flow - -spring.cloud.sentinel.datasource.ds2.nacos.server-addr=localhost:8848 -spring.cloud.sentinel.datasource.ds2.nacos.data-id=sentinel -spring.cloud.sentinel.datasource.ds2.nacos.group-id=DEFAULT_GROUP -spring.cloud.sentinel.datasource.ds2.nacos.data-type=json -spring.cloud.sentinel.datasource.ds2.nacos.rule-type=degrade - -spring.cloud.sentinel.datasource.ds3.zk.path = /Sentinel-Demo/SYSTEM-CODE-DEMO-FLOW -spring.cloud.sentinel.datasource.ds3.zk.server-addr = localhost:2181 -spring.cloud.sentinel.datasource.ds3.zk.rule-type=authority - -spring.cloud.sentinel.datasource.ds4.apollo.namespace-name = application -spring.cloud.sentinel.datasource.ds4.apollo.flow-rules-key = sentinel -spring.cloud.sentinel.datasource.ds4.apollo.default-flow-rule-value = test -spring.cloud.sentinel.datasource.ds4.apollo.rule-type=param-flow ----- - -这种配置方式参考了 Spring Cloud Stream Binder 的配置，内部使用了 `TreeMap` 进行存储，comparator 为 `String.CASE_INSENSITIVE_ORDER` 。 - -NOTE: d1, ds2, ds3, ds4 是 `ReadableDataSource` 的名字，可随意编写。后面的 `file` ，`zk` ，`nacos` , `apollo` 就是对应具体的数据源。 它们后面的配置就是这些具体数据源各自的配置。 - -每种数据源都有两个共同的配置项： `data-type`、 `converter-class` 以及 `rule-type`。 - -`data-type` 配置项表示 `Converter` 类型，Spring Cloud Alibaba Sentinel 默认提供两种内置的值，分别是 `json` 和 `xml` (不填默认是json)。 如果不想使用内置的 `json` 或 `xml` 这两种 `Converter`，可以填写 `custom` 表示自定义 `Converter`，然后再配置 `converter-class` 配置项，该配置项需要写类的全路径名(比如 `spring.cloud.sentinel.datasource.ds1.file.converter-class=org.springframework.cloud.alibaba.cloud.examples.JsonFlowRuleListConverter`)。 - -`rule-type` 配置表示该数据源中的规则属于哪种类型的规则(`flow`，`degrade`，`authority`，`system`, `param-flow`, `gw-flow`, `gw-api-group`)。 - -NOTE: 当某个数据源规则信息加载失败的情况下，不会影响应用的启动，会在日志中打印出错误信息。 - -NOTE: 默认情况下，xml 格式是不支持的。需要添加 `jackson-dataformat-xml` 依赖后才会自动生效。 - -关于 Sentinel 动态数据源的实现原理，参考： https://github.com/alibaba/Sentinel/wiki/%E5%8A%A8%E6%80%81%E8%A7%84%E5%88%99%E6%89%A9%E5%B1%95[动态规则扩展] - -=== Zuul 支持 - -https://github.com/alibaba/Sentinel/wiki/%E7%BD%91%E5%85%B3%E9%99%90%E6%B5%81[参考 Sentinel 网关限流] - -若想跟 Sentinel Starter 配合使用，需要加上 `spring-cloud-alibaba-sentinel-gateway` 依赖，同时需要添加 `spring-cloud-starter-netflix-zuul` 依赖来让 `spring-cloud-alibaba-sentinel-gateway` 模块里的 Zuul 自动化配置类生效： - -```xml - - com.alibaba.cloud - spring-cloud-starter-alibaba-sentinel - - - - com.alibaba.cloud - spring-cloud-alibaba-sentinel-gateway - - - - org.springframework.cloud - spring-cloud-starter-netflix-zuul - -``` - -=== Spring Cloud Gateway 支持 - -https://github.com/alibaba/Sentinel/wiki/%E7%BD%91%E5%85%B3%E9%99%90%E6%B5%81[参考 Sentinel 网关限流] - -若想跟 Sentinel Starter 配合使用，需要加上 `spring-cloud-alibaba-sentinel-gateway` 依赖，同时需要添加 `spring-cloud-starter-gateway` 依赖来让 `spring-cloud-alibaba-sentinel-gateway` 模块里的 Spring Cloud Gateway 自动化配置类生效： - -```xml - - com.alibaba.cloud - spring-cloud-starter-alibaba-sentinel - - - - com.alibaba.cloud - spring-cloud-alibaba-sentinel-gateway - - - - org.springframework.cloud - spring-cloud-starter-gateway - -``` - -=== Sentinel 对外暴露的 Endpoint - -Sentinel 内部提供了一个 Endpoint, 对应的 endpoint id 为 `sentinel`。 - -Endpoint 暴露的 json 中包含了多种属性: - -1. appName: 应用名 -2. logDir: 日志所在目录 -3. logUsePid: 日志文件名是否带上进程id -4. blockPage: 限流 block 之后跳转的页面 -5. metricsFileSize: metrics 文件的大小 -6. metricsFileCharset: metrics 文件对应的字符集 -7. totalMetricsFileCount: metrics 最多保留的文件数 -8. consoleServer: sentinel dashboard 地址 -9. clientIp: 客户端 ip -10. heartbeatIntervalMs: 客户端跟 dashboard 的心跳间隔时间 -11. clientPort: 客户端需要暴露的端口跟 dashboard 进行交互 -12. coldFactor: 冷启动因子 -13. filter: CommonFilter 相关的属性， 比如 order, urlPatterns 以及 enable -14. datasource: 客户端配置的数据源信息 -15. rules: 客户端生效的规则，内部含有 flowRules, degradeRules, systemRules, authorityRule, paramFlowRule - -这是 Endpoint 暴露的 json 示例: - - -[source,json,indent=0] ----- -{ - "blockPage": null, - "appName": "sentinel-example", - "consoleServer": "localhost:8080", - "coldFactor": "3", - "rules": { - "flowRules": [{ - "resource": "GET:http://www.taobao.com", - "limitApp": "default", - "grade": 1, - "count": 0.0, - "strategy": 0, - "refResource": null, - "controlBehavior": 0, - "warmUpPeriodSec": 10, - "maxQueueingTimeMs": 500, - "clusterMode": false, - "clusterConfig": null - }, { - "resource": "/test", - "limitApp": "default", - "grade": 1, - "count": 0.0, - "strategy": 0, - "refResource": null, - "controlBehavior": 0, - "warmUpPeriodSec": 10, - "maxQueueingTimeMs": 500, - "clusterMode": false, - "clusterConfig": null - }, { - "resource": "/hello", - "limitApp": "default", - "grade": 1, - "count": 1.0, - "strategy": 0, - "refResource": null, - "controlBehavior": 0, - "warmUpPeriodSec": 10, - "maxQueueingTimeMs": 500, - "clusterMode": false, - "clusterConfig": null - }] - }, - "metricsFileCharset": "UTF-8", - "filter": { - "order": -2147483648, - "urlPatterns": ["/*"], - "enabled": true - }, - "totalMetricsFileCount": 6, - "datasource": { - "ds1": { - "file": { - "dataType": "json", - "ruleType": "FLOW", - "converterClass": null, - "file": "...", - "charset": "utf-8", - "recommendRefreshMs": 3000, - "bufSize": 1048576 - }, - "nacos": null, - "zk": null, - "apollo": null, - "redis": null - } - }, - "clientIp": "30.5.121.91", - "clientPort": "8719", - "logUsePid": false, - "metricsFileSize": 52428800, - "logDir": "...", - "heartbeatIntervalMs": 10000 -} ----- - -=== 关于 Sentinel Starter 更多的配置项信息 - -下表显示当应用的 `ApplicationContext` 中存在对应的Bean的类型时，会进行自动化设置： - -|=== -|存在Bean的类型 |操作 |作用 -|`UrlCleaner`|`WebCallbackManager.setUrlCleaner(urlCleaner)`|资源清理(资源（比如将满足 /foo/:id 的 URL 都归到 /foo/* 资源下）) -|`UrlBlockHandler`|`WebCallbackManager.setUrlBlockHandler(urlBlockHandler)`|自定义限流处理逻辑 -|`RequestOriginParser`|`WebCallbackManager.setRequestOriginParser(requestOriginParser)`|设置来源信息 -|=== - - -Spring Cloud Alibaba Sentinel 提供了这些配置选项 - -|=== -|配置项 |含义 |默认值 -|`spring.application.name` or `project.name`|Sentinel项目名| -|`spring.cloud.sentinel.enabled`|Sentinel自动化配置是否生效|true -|`spring.cloud.sentinel.eager`|是否提前触发 Sentinel 初始化|false -|`spring.cloud.sentinel.transport.port`|应用与Sentinel控制台交互的端口，应用本地会起一个该端口占用的HttpServer|8719 -|`spring.cloud.sentinel.transport.dashboard`|Sentinel 控制台地址| -|`spring.cloud.sentinel.transport.heartbeat-interval-ms`|应用与Sentinel控制台的心跳间隔时间| -|`spring.cloud.sentinel.transport.client-ip`|此配置的客户端IP将被注册到 Sentinel Server 端| -|`spring.cloud.sentinel.filter.order`|Servlet Filter的加载顺序。Starter内部会构造这个filter|Integer.MIN_VALUE -|`spring.cloud.sentinel.filter.url-patterns`|数据类型是数组。表示Servlet Filter的url pattern集合|/* -|`spring.cloud.sentinel.filter.enabled`|Enable to instance CommonFilter|true -|`spring.cloud.sentinel.metric.charset`|metric文件字符集|UTF-8 -|`spring.cloud.sentinel.metric.file-single-size`|Sentinel metric 单个文件的大小| -|`spring.cloud.sentinel.metric.file-total-count`|Sentinel metric 总文件数量| -|`spring.cloud.sentinel.log.dir`|Sentinel 日志文件所在的目录| -|`spring.cloud.sentinel.log.switch-pid`|Sentinel 日志文件名是否需要带上pid|false -|`spring.cloud.sentinel.servlet.block-page`| 自定义的跳转 URL，当请求被限流时会自动跳转至设定好的 URL | -|`spring.cloud.sentinel.flow.cold-factor`| https://github.com/alibaba/Sentinel/wiki/%E9%99%90%E6%B5%81--- -%E5%86%B7%E5%90%AF%E5%8A%A8[冷启动因子] |3 -|`spring.cloud.sentinel.zuul.order.pre`| SentinelZuulPreFilter 的 order | 10000 -|`spring.cloud.sentinel.zuul.order.post`| SentinelZuulPostFilter 的 order | 1000 -|`spring.cloud.sentinel.zuul.order.error`| SentinelZuulErrorFilter 的 order | -1 -|`spring.cloud.sentinel.scg.fallback.mode`| Spring Cloud Gateway 熔断后的响应模式(选择 `redirect` or `response`) | -|`spring.cloud.sentinel.scg.fallback.redirect`| Spring Cloud Gateway 响应模式为 'redirect' 模式对应的重定向 URL | -|`spring.cloud.sentinel.scg.fallback.response-body`| Spring Cloud Gateway 响应模式为 'response' 模式对应的响应内容 | -|`spring.cloud.sentinel.scg.fallback.response-status`| Spring Cloud Gateway 响应模式为 'response' 模式对应的响应码 | 429 -|`spring.cloud.sentinel.scg.fallback.content-type`| Spring Cloud Gateway 响应模式为 'response' 模式对应的 content-type | application/json -|=== - -NOTE: 请注意。这些配置只有在 Servlet 环境下才会生效，RestTemplate 和 Feign 针对这些配置都无法生效 \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sidecar.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sidecar.adoc deleted file mode 100644 index 611ad0929..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sidecar.adoc +++ /dev/null @@ -1,194 +0,0 @@ -== Spring Cloud Alibaba Sidecar - -`Spring Cloud Alibaba Sidecar` 是一个用来快速**完美整合** Spring Cloud -与 *异构微服务* 的框架，灵感来自 -https://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-sidecar[Spring -Cloud Netflix Sidecar]，目前支持的服务发现组件： - -* Nacos -* Consul - -=== 术语 - -==== 异构微服务 - -非Spring Cloud应用，统称异构微服务。比如你的遗留项目，或者非JVM应用。 - -==== "完美整合"的三层含义 - -* 享受服务发现的优势 -* 有负载均衡 -* 有断路器 - -=== Why or Why not? - -==== 为什么要编写Alibaba Sidecar？ - -原因有两点： - -* Spring Cloud子项目 `Spring Cloud Netflix Sidecar` -是可以快速整合异构微服务的。然而，Sidecar只支持使用Eureka作为服务发现，*如果使用其他服务发现组件就抓瞎了*。 -* *Sidecar是基于Zuul 1.x的*，Spring -Cloud官方明确声明，未来将会逐步淘汰Zuul。今年早些时候，我有给Spring -Cloud官方提出需求，希望官方实现一个基于Spring Cloud -Gateway的新一代Sidecar，然而官方表示并没有该计划。详见：https://github.com/spring-cloud/spring-cloud-gateway/issues/735 - -既然没有，索性自己写了。 - -==== 为什么不用Service Mesh？ - -* 目前Mesh主要使用场景在Kubernetes领域（Istio、Linkerd -2等，大多将Kubernetes作为First -Class支持，虽然Istio也可部署在非Kubernetes环境），而目前业界，Spring -Cloud应用未必有试试Mesh的环境； -* 使用Alibaba -Sidecar一个小组件就能解决问题了（核心代码不超过200行），引入整套Mesh方案，颇有点屠龙刀杀黄鳝的意思。 - -=== 原理 - -* Alibaba -Sidecar根据配置的异构微服务的IP、端口等信息，*将异构微服务的IP/端口注册到服务发现组件上* -。 -* Alibaba Sidecar实现了 *健康检查* ，Alibaba -Sidecar会定时检测异构微服务是否健康。如果发现异构微服务不健康，Alibaba -Sidecar会自动将代表异构微服务的Alibaba -Sidecar实例下线；如果异构微服务恢复正常，则会自动上线。最长延迟是30秒，详见 -`Alibaba SidecarChecker#check` 。 - -=== 要求 - -* 【必须】你的异构微服务需使用HTTP通信。这一点严格来说不算要求，因为Spring -Cloud本身就是基于HTTP的； -* 【可选】如果微服务配置了 `sidecar.health-check-url` -，则表示开启健康检查，此时，你的异构微服务需实现健康检查（可以是空实现，只要暴露一个端点，返回类似 -`{"status": "UP"}` 的字符串即可）。 - -=== 使用示例 - -* 如使用Nacos作为服务发现组件，详见`spring-cloud-alibaba-examples/spring-cloud-alibaba-sidecar-examples/spring-cloud-alibaba-sidecar-nacos-example` -* 如使用Consul作为服务发现组件，详见`spring-cloud-alibaba-examples/spring-cloud-alibaba-sidecar-examples/spring-cloud-alibaba-sidecar-nacos-example` - -==== 示例代码（以Nacos服务发现为例） - -* 加依赖： -+ -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-sidecar - ----- -* 写配置： -+ -[source,yaml] ----- -server: - port: 8070 -spring: - cloud: - nacos: - discovery: - server-addr: localhost:8848 - gateway: - discovery: - locator: - enabled: true - application: - name: node-service -sidecar: - # 异构微服务的IP - ip: 127.0.0.1 - # 异构微服务的端口 - port: 8060 - # 异构微服务的健康检查URL - health-check-url: http://localhost:8060/health.json -management: -endpoint: - health: - show-details: always ----- -+ -配置比较简单，就是把Alibaba Sidecar注册到Nacos上，然后添加了几行Alibaba -Sidecar的配置。 - -==== 异构微服务 - -我准备了一个NodeJS编写的简单微服务。 - -[source,javascript] ----- -var http = require('http'); -var url = require("url"); -var path = require('path'); - -// 创建server -var server = http.createServer(function(req, res) { - // 获得请求的路径 - var pathname = url.parse(req.url).pathname; - res.writeHead(200, { 'Content-Type' : 'application/json; charset=utf-8' }); - // 访问http://localhost:8060/，将会返回{"index":"欢迎来到首页"} - if (pathname === '/') { - res.end(JSON.stringify({ "index" : "欢迎来到首页" })); - } - // 访问http://localhost:8060/health，将会返回{"status":"UP"} - else if (pathname === '/health.json') { - res.end(JSON.stringify({ "status" : "UP" })); - } - // 其他情况返回404 - else { - res.end("404"); - } -}); -// 创建监听，并打印日志 -server.listen(8060, function() { - console.log('listening on localhost:8060'); -}); ----- - -==== 测试 - -===== 测试1：Spring Cloud微服务完美调用异构微服务 - -为你的Spring Cloud微服务整合Ribbon，然后构建 `http://node-service/**` -，就可以请求到异构微服务的 `/**` 了。 - -示例： - -Ribbon请求 `http://node-service/` 会请求到 `http://localhost:8060/` -，以此类推。 - -至于断路器，正常为你的Spring -Cloud微服务整合Sentinel或者Hystirx、Resilience4J即可 。 - -===== 测试2：异构微服务完美调用Spring Cloud微服务 - -由于Alibaba Sidecar基于Spring Cloud Gateway，而网关自带转发能力。 - -示例： - -如果你有一个Spring Cloud微服务叫做 `spring-cloud-microservice` -，那么NodeJS应用只需构建 -`http://localhost:8070/spring-cloud-microservice/**` ，Alibaba -Sidecar就会把请求转发到 `spring-cloud-microservice` 的 `/**` 。 - -而Spring Cloud Gateway是整合了Ribbon的，所以实现了负载均衡；Spring Cloud -Gateway还可以整合Sentinel或者Hystirx、Resilience4J，所以也带有了断路器。 - -=== Alibaba Sidecar优缺点分析 - -Alibaba -Sidecar的设计和Sidecar基本一致，优缺点和Sidecar的优缺点也是一样的。 - -优点： - -* 接入简单，几行代码就可以将异构微服务整合到Spring Cloud生态 -* 不侵入原代码 - -缺点： - -* 每接入一个异构微服务实例，都需要额外部署一个Alibaba -Sidecar实例，增加了部署成本（虽然这个成本在Kubernetes环境中几乎可以忽略不计（只需将Alibaba -Sidecar实例和异构微服务作为一个Pod部署即可））； -* 异构微服务调用Spring Cloud微服务时，本质是把Alibaba -Sidecar当网关在使用，经过了一层转发，性能有一定下降。 diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sms.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sms.adoc deleted file mode 100644 index e6f6813e3..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/sms.adoc +++ /dev/null @@ -1,253 +0,0 @@ -== Spring Cloud AliCloud SMS - -短信服务（Short Message Service）是阿里云为用户提供的一种通信服务的能力。 Spring Cloud AliCloud SMS 实现了与 SMS 的简单集成，提供更为简单易用的 API，可以基于 Spring Cloud Alibaba SMS 来快速的接入阿里云的 SMS 服务。 - -=== 如何引入 Spring Cloud AliCloud SMS - -如果要在您的项目中引入 SMS，使用 group ID 为 `com.alibaba.cloud` 和 artifact ID 为 `spring-cloud-starter-alicloud-sms` 的 starter。 - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alicloud-sms - ----- - -=== 如何使用 SMS API - -==== 配置 SMS - -使用 Spring Cloud AliCloud SMS 之前，需要在 application.properties 中加入以下配置。 - -[source,properties] ----- -spring.cloud.alicloud.access-key=你的阿里云 AK -spring.cloud.alicloud.secret-key=你的阿里云 SK ----- - -access-key 和 secret-key 是阿里云账号的 AK/SK，需要首先注册阿里云账号，然后登陆 https://usercenter.console.aliyun.com/#/manage/ak[阿里云AK/SK管理页面] ，即可看到 AccessKey ID 和 Access Key Secret ，如果没有的话，需要点击"创建AccessKey"按钮创建。 - - -==== 引入 SMS API - -Spring Cloud Alicloud SMS 中的 SMS API 基于阿里云官方 SMS SDK ,提供具备单个短信发送、多个短信批量发送、短信查询、短信消息(`短信回执消息` 和 `上行短信消息`) 类型操作API。 - -一个简单的使用 SMS API 发送短信的应用如下。 - -[source,java] ----- -@SpringBootApplication -public class SmsApplication { - - @Autowired - private ISmsService smsService; - - /** - * 短信发送 Example - * @param code - * @return - */ - @RequestMapping("/batch-sms-send.do") - - public SendBatchSmsResponse batchsendCheckCode( - @RequestParam(name = "code") String code) { - - // 组装请求对象-具体描述见控制台-文档部分内容 - SendSmsRequest request = new SendSmsRequest(); - // 必填:待发送手机号 - request.setPhoneNumbers("152******"); - // 必填:短信签名-可在短信控制台中找到 - request.setSignName("******"); - // 必填:短信模板-可在短信控制台中找到 - request.setTemplateCode("******"); - // 可选:模板中的变量替换JSON串,如模板内容为"【企业级分布式应用服务】,您的验证码为${code}"时,此处的值为 - request.setTemplateParam("{\"code\":\"" + code + "\"}"); - SendSmsResponse sendSmsResponse ; - try { - sendSmsResponse = smsService.sendSmsRequest(request); - } - catch (ClientException e) { - e.printStackTrace(); - sendSmsResponse = new SendSmsResponse(); - } - return sendSmsResponse ; - } - - public static void main(String[] args) throws URISyntaxException { - - SpringApplication.run(SmsApplication.class, args); - } - -} ----- - -在发送短信之前，首先需要 https://account.aliyun.com/register/register.htm?spm=5176.8142029.388261.26.e9396d3eaYK2sG&oauth_callback=https%3A%2F%2Fwww.aliyun.com%2F[注册阿里云账号] ，如果已经有的话，请 https://dysms.console.aliyun.com/dysms.htm?spm=5176.8195934.1283918..18924183bHPct2&accounttraceid=c8cb4243-3080-4eb1-96b0-1f2316584269#/[开通 SMS 服务]。 - -更多关于 SMS 发送短信的步骤，可以参考 SMS 官方 https://help.aliyun.com/document_detail/55284.html?spm=a2c4g.11186623.6.568.715e4f30ZiVkbI[短信发送API(SendSms)---JAVA] 文档。 - -NOTE: 由于早期的 SMS sdk 版本的问题，如果短信发送失败，请将代码中含有明确指定 MethodType 为 POST 的这行代码给删除掉。如果还有问题，请第一时间联系我们。 - - -=== SMS Api 的高级功能 - -Spring Cloud Alicloud SMS 封装的 API 接口为了降低学习的成本，尽量保持和官网提供的 API 以及 Example 保持一致。 - -* 批量短信发送 - -参考以下的 Example ，来快速开发一个具有批量短信发送的功能。在 Controller 中或者新建一个 Controler 新增如下代码： - -[source,java] ----- -/** - * 批量短信发送 Example - * @param code - * @return - */ -@RequestMapping("/batch-sms-send.do") -public SendBatchSmsResponse batchsendCheckCode( - @RequestParam(name = "code") String code) { - // 组装请求对象 - SendBatchSmsRequest request = new SendBatchSmsRequest(); - // 使用 GET 提交 - request.setMethod(MethodType.GET); - // 必填:待发送手机号。支持JSON格式的批量调用，批量上限为100个手机号码,批量调用相对于单条调用及时性稍有延迟,验证码类型的短信推荐使用单条调用的方式 - request.setPhoneNumberJson("[\"177********\",\"130********\"]"); - // 必填:短信签名-支持不同的号码发送不同的短信签名 - request.setSignNameJson("[\"*******\",\"*******\"]"); - // 必填:短信模板-可在短信控制台中找到 - request.setTemplateCode("******"); - // 必填:模板中的变量替换JSON串,如模板内容为"亲爱的${name},您的验证码为${code}"时,此处的值为 - // 友情提示:如果JSON中需要带换行符,请参照标准的JSON协议对换行符的要求,比如短信内容中包含\r\n的情况在JSON中需要表示成\\r\\n,否则会导致JSON在服务端解析失败 - request.setTemplateParamJson( - "[{\"code\":\"" + code + "\"},{\"code\":\"" + code + "\"}]"); - SendBatchSmsResponse sendSmsResponse ; - try { - sendSmsResponse = smsService - .sendSmsBatchRequest(request); - return sendSmsResponse; - } - catch (ClientException e) { - e.printStackTrace(); - sendSmsResponse = new SendBatchSmsResponse(); - } - return sendSmsResponse ; -} ----- - -NOTE: 这里设置请求的 MethodType 为 GET，和官网给出的例子还有些不一样。这是因为依赖的阿里云 POP API 版本不一致导致不兼容的问题，设置为 GET 即可。 - -更多的参数说明可 https://help.aliyun.com/document_detail/66041.html?spm=a2c4g.11186623.6.571.631315e8AauJhP[参考这里] - -* 短信查询 - -参考以下的 Example ，可以快速开发根据某个指定的号码查询短信历史发送状态。在 Controller 中或者新建一个 Controler 新增如下代码： - -[source,java] ----- -/** - * - * 短信查询 Example - * @param telephone - * @return - */ -@RequestMapping("/query.do") -public QuerySendDetailsResponse querySendDetailsResponse( - @RequestParam(name = "tel") String telephone) { - // 组装请求对象 - QuerySendDetailsRequest request = new QuerySendDetailsRequest(); - // 必填-号码 - request.setPhoneNumber(telephone); - // 必填-短信发送的日期 支持30天内记录查询（可查其中一天的发送数据），格式yyyyMMdd - request.setSendDate("20190103"); - // 必填-页大小 - request.setPageSize(10L); - // 必填-当前页码从1开始计数 - request.setCurrentPage(1L); - try { - QuerySendDetailsResponse response = smsService.querySendDetails(request); - return response; - } - catch (ClientException e) { - e.printStackTrace(); - } - - return new QuerySendDetailsResponse(); -} - ----- - -更多的参数说明，可 https://help.aliyun.com/document_detail/55289.html?spm=a2c4g.11186623.6.569.4f852c78mugEfx[参考这里] - -* 短信回执消息 - -通过订阅 SmsReport 短信状态报告，可以获知每条短信的发送情况，了解短信是否达到终端用户的状态与相关信息。这些工作已经都被 Spring Cloud AliCloud SMS 封装在内部了。你只需要完成以下两步即可。 - -1、在 `application.properties` 配置文件中(也可以是 application.yaml)配置 SmsReport 的队列名称。 - -.application.properties -[source,properties] ----- -spring.cloud.alicloud.sms.report-queue-name=Alicom-Queue-********-SmsReport ----- - -2、 实现 SmsReportMessageListener 接口，并初始化一个 Spring Bean 。 - -[source,java] ----- -/** - * 如果需要监听短信是否被对方成功接收，只需实现这个接口并初始化一个 Spring Bean 即可。 - */ -@Component -public class SmsReportMessageListener - implements org.springframework.cloud.alicloud.sms.SmsReportMessageListener { - - @Override - public boolean dealMessage(Message message) { - // 在这里添加你的处理逻辑 - - //do something - - System.err.println(this.getClass().getName() + "; " + message.toString()); - return true; - } -} ----- - -更多关于 Message 的消息体格式可 https://help.aliyun.com/document_detail/55496.html?spm=a2c4g.11186623.6.570.7f792c78rOiWXO[参考这里]。 - -* 上行短信消息 - -通过订阅SmsUp上行短信消息，可以获知终端用户回复短信的内容。这些工作也已经被 Spring Cloud AliCloud SMS 封装好了。你只需要完成以下两步即可。 - -1、 在 `application.properties` 配置文件中(也可以是 application.yaml)配置 SmsReport 的队列名称。 - -.application.properties ----- -spring.cloud.alicloud.sms.up-queue-name=Alicom-Queue-********-SmsUp ----- - -2、实现 SmsUpMessageListener 接口，并初始化一个 Spring Bean 。 - -[source,java] ----- -/** - * 如果发送的短信需要接收对方回复的状态消息，只需实现该接口并初始化一个 Spring Bean 即可。 - */ -@Component -public class SmsUpMessageListener - implements org.springframework.cloud.alicloud.sms.SmsUpMessageListener { - - @Override - public boolean dealMessage(Message message) { - // 在这里添加你的处理逻辑 - - //do something - - System.err.println(this.getClass().getName() + "; " + message.toString()); - return true; - } -} ----- - -更多关于 Message 的消息体格式可 https://help.aliyun.com/document_detail/55496.html?spm=a2c4g.11186623.6.570.7f792c78rOiWXO[参考这里]。 \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/spring-cloud-alibaba.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc-zh/spring-cloud-alibaba.adoc deleted file mode 100644 index 2ff0754f4..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc-zh/spring-cloud-alibaba.adoc +++ /dev/null @@ -1,38 +0,0 @@ -[[spring-cloud-alibaba-reference]] -= Spring Cloud Alibaba 参考文档 -Jim Fang, Jing Xiao, Mercy Ma, Xiaolong Zuo, Bingting Peng, Yuxin Wang -:doctype: book -:toc: -:toclevels: 4 -:source-highlighter: prettify -:numbered: - -include::introduction.adoc[] - -include::dependency-management.adoc[] - -include::nacos-discovery.adoc[] - -include::nacos-config.adoc[] - -include::sentinel.adoc[] - -include::rocketmq-new.adoc[] - -include::ans.adoc[] - -include::acm.adoc[] - -include::oss.adoc[] - -include::schedulerx.adoc[] - -include::sms.adoc[] - -include::sidecar.adoc[] - -include::appactive.adoc[] - -include::governance.adoc[] - - diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/acm.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/acm.adoc deleted file mode 100644 index 114681065..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/acm.adoc +++ /dev/null @@ -1,178 +0,0 @@ -== Spring Cloud Alibaba Cloud ACM - -Spring Cloud AliCloud ACM is an implementation of the commercial product Application Configuration Management(ACM) in the client side of Spring Cloud, and is free of charge. - -Use Spring Cloud AliCloud ACM to quickly access ACM configuration management capabilities based on Spring Cloud's programming model. - -NOTE: Currently EDAS already supports direct deployment of the Nacos Config app. - -=== How to Introduce Spring Cloud Alibaba Cloud ACM - -If you want to use ACM in your project, please use the starter with the group ID as `com.alibaba.cloud` and the artifact ID as `spring-cloud-starter-alicloud-acm`. - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alicloud-acm - ----- - -=== Use ACM to Manage Configurations - -When Spring Cloud Alibaba Cloud ACM Starter is introduced into the client, the application will automatically get configuration information from the configuration management server when it starts, and inject the configuration into Spring Environment. - -The following is a simple illustration. - -[source,java] ----- -@SpringBootApplication -public class ProviderApplication { - - public static void main(String[] args) { - ConfigurableApplicationContext applicationContext = SpringApplication.run(ProviderApplication.class, args); - String userName = applicationContext.getEnvironment().getProperty("user.name"); - String userAge = applicationContext.getEnvironment().getProperty("user.age"); - System.err.println("user name :" +userName+"; age: "+userAge); - } -} ----- - -As we need to obtain configuration information from the configuration server, we will need to configure the address of the server. We also need to add the following information in bootstrap.properties. - -[source,properties] ----- -# Required. The application name will be used as part of the keyword to get the configuration key from the server. -spring.application.name=acm-config -server.port=18081 -# The following is the IP and port number of the configuration server. -spring.cloud.alicloud.acm.server-list=127.0.0.1 -spring.cloud.alicloud.acm.server-port=8080 ----- - -NOTE: By now the configuration center is not started yet, so you will get an error message if your application is started. Therefore, start the configuration center before you start your application. - - -==== Start Configuration Center - -ACM uses two types of configuration centers. One is lightweight configuration center, the other is ACM which is used on Alibaba Cloud. Generally, you can use the lightweight version for application development and local testing, and use ACM for canary deployment or production. - -===== Use Lightweight Configuration Center - -Refer to the https://help.aliyun.com/document_detail/44163.html[Configure Lightweight Configuration Center] for details about how to download and install lightweight configuration center. - -NOTE: You only need to perform step 1(Download lightweight configuration center) and step 2(Start lightweight configuration center). - - -===== Use ACM on the Alibaba Cloud - -Using ACM on the cloud saves you from the tedious work of server maintenance while at the same time provides a better stability. There is no difference at the code level between using ACM on cloud and lightweight configuration center, but there are some differences in configurations. - -The following is a simple sample of using ACM. You can view configuration details on https://acm.console.aliyun.com[ACM Console] - -[source,properties] ----- -# The application name will be used as part of the keyword to obtain configuration key from the server, and is mandatory. -spring.application.name=acm-config -# Configure your own port number -server.port=18081 -# The following is the IP and port number of the configuration center. -spring.cloud.alicloud.acm.server-mode=EDAS -spring.cloud.alicloud.access-key=Your Alibaba Cloud AK -spring.cloud.alicloud.secret-key=Your Alibaba Cloud SK -spring.cloud.alicloud.acm.endpoint=acm.aliyun.com -spring.cloud.alicloud.acm.namespace=Your ACM namespace(You can find the namespace on the ACM console) ----- - -NOTE: EDAS provides application hosting service and will fill in all configurations about ACM automatically for the hosted applications. - -==== Add Configuration in the Configuration Center - -1. After you start the lightweight configuration center, add the following configuration on the console. - -[source,subs="normal"] ----- -Group: DEFAULT_GROOUP - -DataId: acm-config.properties - -Content: user.name=james - user.age=18 ----- - -NOTE: The format of dataId is `{prefix}. {file-extension}`. “prefix” is obtained from spring.application.name by default, and the value of “file-extension” is "properties” by default. - -==== Start Application Verification - -Start the following example and you can see that the value printed on the console is the value we configured in the lightweight configuration center. - -[source,subs="normal"] ----- -user name :james; age: 18 ----- - -=== Modify Configuration File Extension - -The default file extension of dataId in spring-cloud-starter-alicloud-acm is properties. In addition to properties, yaml is also supported. -You can set the file extension using spring.cloud.alicloud.acm.file-extension. Just set it to `yaml` or `yml`for yaml format. - -NOTE: After you change the file extension, you need to make corresponding format changes in the DataID and content of the configuration center. - -=== Dynamic Configuration Refresh - -spring-cloud-starter-alicloud-acm supports dynamic configuration updates. RefreshEvent in Spring is published when you update configuration in the configuration center. -All classes with @RefreshScope and @ConfigurationProperties annotations will be refreshed automatically. - -NOTE: You can disable automatic refresh by this setting: spring.cloud.alicloud.acm.refresh.enabled=false - -=== Configure Profile Granularity - -When configuration is loaded by spring-cloud-starter-alicloud-acm, configuration with DataId {spring.application.name}. {file-extension} will be loaded first. If there is content in spring.profiles.active, the content of spring.profile, and configuration with the dataid format of{spring.application.name}-{profile}. {file-extension} will also be loaded in turn, and the latter has higher priority. - -spring.profiles.active is the configuration metadata, and should also be configured in bootstrap.properties or bootstrap.yaml. For example, you can add the following content in bootstrap.properties. - -[sources,properties] ----- -spring.profiles.active={profile-name} ----- - -Note: You can also configure the granularity through JVM parameters such as -Dspring.profiles.active=develop or --spring.profiles.active=develop, which have higher priority. Just follow the specifications of Spring Boot. - - -=== Support Custom ACM Timeout - -the default timeout of ACM client get config from sever is 3000 ms . If you need to define a timeout, set configuration `spring.cloud.alicloud.acm.timeout`,the unit is millisecond. - - -=== Support Custom Group Configurations - -DEFAULT_GROUP is used by default when no `{spring.cloud.alicloud.acm.group}` configuration is defined. If you need to define your own group, you can use the following method: - -[source,properties] ----- -spring.cloud.alicloud.acm.group=DEVELOP_GROUP ----- - -NOTE: This configuration must be placed in the bootstrap.properties file, and the value of Group must be the same with the value of `spring.cloud.alicloud.acm.group`. - -==== Support Shared Configurations - -ACM provides a solution to share the same configuration across multiple applications. You can do this by adding the `spring.application.group` configuration in Bootstrap. - -[source,properties] ----- -spring.application.group=company.department.team ----- - -Then, you application will retrieve configurations from the following DataId in turn before it retrieves its own configuration: company:application.properties, company.department:application.properties, company.department.team:application.properties. -After that, it also retrieves configuration from {spring.application.group}: {spring.application.name}. {file-extension} -The later in order, the higer the priority, and the unique configuration of the application itself has the highest priority. - - -NOTE: The default suffix of DataId is properties, and you can change it using spring.cloud.alicloud.acm.file-extension. `{spring.application.group}: {spring.application.name}. {file-extension}` . - -NOTE: If you configured `spring.profiles.active` , then the DataId format of `{spring.application.group}: {spring.application.name}-{spring.profiles.active}. {file-extension}` is also supported, and has higher priority than `{spring.application.group}: {spring.application.name}. {file-extension}` - -=== Actuator Endpoint - -the Actuator endpoint of ACM is `/acm`, `config` represents the ACM metadata configuration information, `runtime.sources` corresponds to the configuration information obtained from the ACM server and the last refresh time, `runtime.refreshHistory` corresponds to the dynamic refresh history. \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/ans.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/ans.adoc deleted file mode 100644 index b386a5894..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/ans.adoc +++ /dev/null @@ -1,96 +0,0 @@ -== Spring Cloud Alibaba Cloud ANS - -ANS(Application Naming Service) is a component of EDAS. Spring Cloud Alibaba Cloud ANS provides the commercial version of service registration and discovery in conformity with the Spring Cloud specifications, so that you can develop your applications locally and run them on the cloud. - -NOTE: EDAS currently supports direct deployment of Nacos Discovery applications - -=== How to Introduce Spring Cloud Alibaba Cloud ANS - -If you want to use ANS in your project, please use the starter with the group ID as `com.alibaba.cloud` and the artifact ID as `spring-cloud-starter-alicloud-ans`. - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alicloud-ans - ----- - -=== Use ANS to Register Service - -When Spring Cloud AliCloud ANS Starter is introduced on the client, the metadata of the service such as IP, port number and weight will be registered to the registration center automatically. The client will maintain heartbeat with the server to prove that it is capable of providing service properly. - -The following is a simple illustration. - -[source,java] ----- -@SpringBootApplication -@EnableDiscoveryClient -@RestController -public class ProviderApplication { - - @RequestMapping("/") - public String home() { - return "Hello world"; - } - - public static void main(String[] args) { - SpringApplication.run(ProviderApplication.class, args); - } - -} ----- - -As the service will registered to the registration center, we will need to configure the address of the registration center. We also need to add the following address in application.properties. - -[source,properties] ----- -# The application name will be used as the service name, therefore it is mandatory. -spring.application.name=ans-provider -server.port=18081 -# The following is the IP and port number of the registration center. -spring.cloud.alicloud.ans.server-list=127.0.0.1 -spring.cloud.alicloud.ans.server-port=8080 ----- - -NOTE: By now the registration center is not started yet, so you will get an error message if your application is started. Therefore, start the registration center before you start your application. - -=== Start Registration Center - -ANS uses two types of registration centers. One is the free lightweight configuration center and the other is the registration center on cloud, which is provided through EDAS. Generally, you can use the lightweight version for application development and local testing, and use EDAS for canary deployment or production. - -==== Start Lightweight Configuration Center - -Refer to the https://help.aliyun.com/document_detail/44163.html[Configure Lightweight Configuration Center] for details about how to download and install lightweight configuration center. - -NOTE: You only need to perform step 1(Download lightweight configuration center) and step 2(Start lightweight configuration center). Step 3(Configure hosts) is not required if you use ANS at the same time. - -After you start the lightweight configuration center, start ProviderApplication directly, and you will be able to register your service to the configuration center. The default port of the lightweight configuration center is 8080, therefore you can open http://127.0.0.1:8080, click “Services” on the left and see the registered service. - -==== User Registration Center on the Cloud - -Using the registration center on the cloud saves you from the tedious work of server maintenance while at the same time provides a better stability. There is no difference at the code level between using the registration center on cloud and lightweight configuration center, but there are some differences in configurations. - -The following is a simple sample of using the registration center on the cloud. - -[source,properties] ----- -# The application name will be used the service name, and is therefore mandatory. -spring.application.name=ans-provider -# Configure your own port number -server.port=18081 -# The following is the IP and port number of the configuration center. The default value is 127.0.0.1 and 8080, so the following lines can be omitted. -spring.cloud.alicloud.ans.server-mode=EDAS -spring.cloud.alicloud.access-key=Your Alibaba Cloud AK -spring.cloud.alicloud.secret-key=Your Alibaba Cloud SK -spring.cloud.alicloud.edas.namespace=cn-xxxxx ----- - -The default value of server-mode is LOCAL. If you want to use the registration center on cloud, you need to change it to EDAS. - -Access-key and secret-key are the AK/SK of your Alibaba Cloud account. Register an Alibaba Cloud account first and log on to the Cloud Console https://usercenter.console.aliyun.com/#/manage/ak[Alibaba Cloud AK/SK] to copy your AccessKey ID and Access Key Secret. If you haven’t created one, click the “Create AccessKey” button. - -Namespace is a concept in EDAS, which is used to isolate environments, such as testing environment and production environment. To find your namespace, click to https://common-buy.aliyun.com/?spm=5176.11451019.0.0.6f5965c0Uq5tue&commodityCode=edaspostpay#/buy[Sign up for EDAS] first. You will not be charged under the pay-as-you-go mode. Then log on to the https://edas.console.aliyun.com/#/namespaces?regionNo=cn-hangzhou[EDAS Console] and you will be able to see your namespace, for example cn-hangzhou. - -NOTE: EDAS provides application hosting service and will fill in all configurations automatically for the hosted applications. - diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/appactive.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/appactive.adoc deleted file mode 100644 index e9e58010c..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/appactive.adoc +++ /dev/null @@ -1,250 +0,0 @@ -== Spring Cloud Alibaba AppActive - -=== Introduction - -AppActive is an open source middleware that builds a cloud-native, high-availability and multi-active disaster tolerance -architecture for business applications. It provides standards, implementations, and demos for applying the multi-active -disaster recovery architecture, which is suitable for rich business scenarios (single AZ, single region, single cloud, -multi AZ, multi region, multi-cloud, self-built IDC...). - -AppActive is an internal open source project of AHAS-MSHA. It is based on Alibaba's nearly 9-year production disaster -recovery practice, and combines the best practices of many external customers and communities from Alibaba Cloud's -commercial services, and has the characteristics of high reliability and scalability. - -AppActive has the following features: - -==== Unit diversion - -===== Unified traffic access -The ability to control traffic comes from the unified access of traffic. We call this layer the access layer. The access layer is the entrance of all traffic of the unit. It can parse the request protocol and correctly guide the request traffic to the corresponding application service SLB of the correct unit according to the set split mode and split granularity. If there are no special instructions below, the request protocol defaults to HTTP. The figure below is a schematic diagram of the access layer. - -===== Shunt mode -In the multi-active scenario, the traffic will be sliced ​​according to a certain latitude and distributed to different units. Multi-active supports multiple diversion modes, such as proportional diversion and diversion according to business attributes. The specific diversion mode to choose depends on the needs of the business scenario. The shunt mode is finally reflected in the routing rules. The routing rule is a configuration that defines which unit a certain flow should belong to. - -1. Diversion proportionally.In some business scenarios, you need to split traffic according to users or device numbers. Users, devices, etc. can all be abstracted into one ID, and then the ID can be divided into multiple sections, and each section belongs to a certain unit. In this shunt mode, the traffic ratio of each unit can be estimated through the ID interval. By setting the ratio of the ID interval to the unit capacity to be consistent, global load balancing can be achieved. -2. Diversion according to business attributes.In some business scenarios, it is necessary to split traffic according to traffic attributes, such as introducing crawler traffic to a specific unit, or splitting traffic by province. Crawlers, provinces, etc. can all be abstracted into one label, and then different label value traffic can be introduced into different units. This offloading mode can support physical isolation of traffic with different business attributes. - -===== Shunt granularity -With the servicing of applications, today's applications are no longer a monolithic architecture, and there may be hundreds of applications that provide user access. The access layer introduces user traffic to the correct application, and supports two granularities of domain name and URI prefix. - -1. Diversion by domain name.Different applications are distinguished according to different domain names. For example, the domain name of application app1 is app1.example.com, and the domain name of app2 is app2.example.com. -2. Diversion by URI prefix.Different applications are distinguished according to different URI prefixes. For example, the domain names of apps app1 and app2 are both app.example.com, but the traffic with the prefix /app1 in the URI is introduced into app1, and the traffic with the prefix /app2 is introduced into app2. - -===== Traffic Protocol -The access layer supports four-layer and seven-layer rich traffic request protocols to meet the needs of users in diverse scenarios such as the Internet and the Internet of Things. - -1. HTTP protocol support.The access layer supports the HTTP protocol by default, and the domain name and URI are parsed from the HTTP protocol for forwarding and routing. -2. HTTPS protocol support.The access layer supports the HTTPS protocol, provides centralized domain name certificate management, and meets the user's requirements for reliable and secure transmission. If the user configures the domain name certificate at the access layer, the application of SLB does not need to configure the certificate. -3. Other protocol support.In addition to supporting HTTP and HTTPS protocols, the access layer also supports other HTTP-based protocols, such as SOAP. The access layer has great scalability in terms of protocols, and can quickly support special protocols in the form of plug-ins, such as MQTT and COAP in the Internet of Things scenario. - -===== Route transparent transmission -In order to ensure that the flow can be closed in the cell, each layer of the access layer, application layer, and data layer will perform routing error correction or cell protection. In order to identify the traffic, it is necessary to clarify the unitized type and branch id of the traffic, which we call routing parameters, so that the correct unit of the traffic can be calculated through routing rules. Therefore, the routing parameters need to be transmitted along the request path, which we call routing Penetrate. - -1. Access layer routing transparent transmission.When a browser initiates a service request, it needs to carry routing parameters in the request. Routing parameters can be in cookie, head or body, cookie is recommended. The access layer can parse the HTTP request, get the routing parameters and route to the correct application SLB, while the application server can still get the native routing parameters from the request. -2. Application layer routing transparent transmission.When the traffic arrives at the application server, MultiLive provides a plug-in to extract routing parameters from the HTTP request and save them in the context. The next application may initiate RPC calls or asynchronous messages. Therefore, routing parameters need to be transparently transmitted at the RPC and message levels. -3. RPC routing transparent transmission.When an application initiates an RPC call, the RPC client can retrieve routing parameters from the context and follow the RPC request to the remote service provider Provider. The Provider client recognizes the routing parameters in the Request and saves them in the calling context. The process of routing parameters in RPC is transparent to users. -4. Message routing transparent transmission.When the MQ client sends a message, it will obtain routing parameters from the current context and add it to the message properties. When the MQ client consumes a message, it can retrieve routing parameters from the message attributes and save them in the calling context. The process of routing parameters in MQ is transparent to users. -5. Data layer routing transparent transmission.Dirty writing of data can cause serious consequences, so it is necessary to ensure that the data is stored in the correct unit of DB. Duohuo provides the DRIVER plug-in, and rejects requests from non-this unit. - -==== Unit collaboration -In the disaster recovery scenario, each unit in the ideal scenario is independent, but in fact there will be some business scenarios that cross-unit scenarios. In order to meet these scenarios, the product needs to provide unit collaboration capabilities. - -===== Center call -In some specific business scenarios, in order to ensure strong data consistency, specific services can only be provided in specific central units, and all calls to central services will be directly routed to the central unit for completion. Remote multi-active products use CSB components and RPC multi-active plug-ins to complete coordinated calls between service units to meet business integrity. - -==== Unit protection -The product guarantees the global correctness of the business logic, and will not cause inconsistencies in the unit business logic due to cut-flow operations. Each layer of the system from top to bottom has error correction protection capabilities for error traffic to ensure that services are flowed correctly according to the unitized rules. - -===== Access layer error correction -The traffic enters the access layer, and the access layer determines the unit of the traffic by requesting additional routing parameters, and the non-unit traffic will be proxied to the correct target unit, ensuring the correctness of the access layer ingress traffic. - -===== RPC error correction -When the RPC service is called, the RPC Multi-Live Plugin will perform the correct routing of the service call based on the requested unit information on the Consumer side, and call the wrong traffic service. The RPC Multi-Live Plugin will calculate the correct target unit and call across units. Target unit services to ensure the consistency of service circulation logic. At the same time, the RPC Multi-Live Plugin will perform a second check on the incoming request on the Provider side to ensure the correct service call. Through the double check mechanism, RPC Multi-Live Plugin realizes the error correction of RPC calls to ensure the correctness of service calls. - -==== Unit extension -===== Horizontal extension -When the business carrying capacity of the existing unit has reached the upper limit and cannot be expanded, the product provides simple and fast unit horizontal expansion capabilities: - -1. Expansion of new units nationwide without geographic restrictions -2. The number of new units to be expanded is not limited, and the stability and performance of the unit are not affected by the number of units -3. Two types of unit expansion are provided: remote unit with independent DB and same-city unit with shared DB - -=== How to use - -==== Data Plane - -**Precondition** - -- Require your application service to be implemented in Java and implement service invocation with Spring Cloud -- Load balancing supports Ribbon, but SpringCloudBalancer is not currently supported -- Support declarative Http clients: OpenFeign and RestTemplate, not support original Http clients such as OkHttp and HttpClient - -**Quick Start** -Before starting the example for demonstration, let's take a look at how Spring Cloud applications use the remote multi-active capabilities provided by AppActive. -**Note, this chapter is only for your understanding of the access method. The access work has been completed in this examples, and you do not need to modify it.** - -1. First, modify the pom.xml file to add the following maven dependencies based on the latest `spring-cloud-alibaba-dependencies` added to the provider and consumer. - - - com.alibaba.cloud - spring-cloud-starter-alibaba-appactive - - -2. Configure offload policies for specific interfaces in the `application.properties` configuration file of the Provider application. The suffix `core-path` is used to configure core services, `global-path` is used to configure global services, and `general-path` is used to configure general services. For example, the product application distribution strategy in the demo is configured as follows： - - spring.cloud.appactive.filter.core-path=/detailHidden/*,/detail/* - spring.cloud.appactive.filter.global-path=/buy/* - spring.cloud.appactive.filter.general-path=/* - -3. In the `application.properties` of the Consumer application, configure the client load balancing as the load balancing algorithm provided by AppActive. The configuration method is 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.appactive.consumer.AppactiveRule - -**Presentation preparation** - -1. Start Nacos, MySQL, and push multi-active rules to Nacos: - -- In the `appactive-example` directory, execute: `docker-compose -f component-quickstart.yml up -d` to start Nacos, MySQL. -- Execute the following command: `curl -X POST 'http://127.0.0.1:8848/nacos/v1/console/namespaces' -d 'customNamespaceId=appactiveDemoNamespaceId&namespaceName=appactiveDemoNamespaceName&namespaceDesc=appactiveDemoNamespaceDesc'` Create a demo named in Nacos configuration center Space appactiveDemoNamespaceId. -- Execute the following command: `sh baseline.sh 2 NACOS appactiveDemoNamespaceId` to push the multi-active rule to the namespace. The multi-live rules are described as follows: -- `appactive.dataId.idSourceRulePath`: Describes how to extract routing tokens from http traffic -- `appactive.dataId.transformerRulePath`: Describes how to parse routing tokens -- `appactive.dataId.trafficRouteRulePath`: Describes the mapping between routing labels and units -- `appactive.dataId.dataScopeRuleDirectoryPath_mysql-product`: Properties that describe the database - -2. Start five sets of applications, the startup parameters are: - -- frontend -``` --Dappactive.channelTypeEnum=NACOS --Dappactive.namespaceId=appactiveDemoNamespaceId --Dappactive.unit=unit --Dappactive.app=frontend --Dio.appactive.demo.unitlist=center,unit --Dio.appactive.demo.applist=frontend,product,storage --Dserver.port=8875 -``` -- product -``` --Dappactive.channelTypeEnum=NACOS --Dappactive.namespaceId=appactiveDemoNamespaceId --Dappactive.unit=center --Dappactive.app=product --Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/product?characterEncoding=utf8&useSSL=false&serverTimezone=GMT&activeInstanceId=mysql&activeDbName=product --Dserver.port=8883 -``` -``` --Dappactive.channelTypeEnum=NACOS --Dappactive.namespaceId=appactiveDemoNamespaceId --Dappactive.unit=unit --Dappactive.app=product --Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/product?characterEncoding=utf8&useSSL=false&serverTimezone=GMT&activeInstanceId=mysql&activeDbName=product --Dserver.port=8873 -``` -- storage -``` --Dappactive.channelTypeEnum=NACOS --Dappactive.namespaceId=appactiveDemoNamespaceId --Dappactive.unit=center --Dappactive.app=storage --Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/product?characterEncoding=utf8&useSSL=false&serverTimezone=GMT --Dserver.port=8881 -``` -``` --Dappactive.channelTypeEnum=NACOS --Dappactive.namespaceId=appactiveDemoNamespaceId --Dappactive.unit=unit --Dappactive.app=storage --Dspring.datasource.url=jdbc:mysql://127.0.0.1:3306/product?characterEncoding=utf8&useSSL=false&serverTimezone=GMT --Dserver.port=8871 -``` - -**Demonstration process** - -1. Demonstration of general service calls belonging to the normal unit. Typing: `http://127.0.0.1:8079/listProduct` address in the browser, it can be seen that the request is sent to the product through the frontend application. - -image::pic/image-2022-09-15-16-16-25-989.png[] - - Since `/listProduct` in the above path matches the `/*` path rule in the product application, which corresponds to the normal unit, frontend does not have a tendency in the product address list obtained from the registry, and will randomly select an address for request sending. So requesting the above path multiple times will see the request switch back and forth between the normal and center units of the product. - -2. Demonstration of core service calls belonging to the different unit by request information. Typing: `http://127.0.0.1:8079/detailProduct` in the browser, because the `/detailProduct` in the above path matches the `/detail/*` path rule in the product application, corresponding to the normal(unit) unit, it will be based on the request The specific value of the variable in the Header, Cookie or request parameter is used to determine the downstream unit type of the request, because the following flow switching rules are configured in advance (for details, see the content of the idUnitMapping.json file in the rule directory): - - { - "itemType": "UnitRuleItem", - "items": [ - { - "name": "unit", - "conditions": [ - { - "@userIdBetween": [ - "0~1999" - ] - } - ] - }, - { - "name": "center", - "conditions": [ - { - "@userIdBetween": [ - "2000~9999" - ] - } - ] - } - ] - } - - The above rules mean that requests with user IDs of 0 ~ 1999 will be sent to the noraml(unit) in the downstream provider, and requests with user IDs of 2000 ~ 9999 will be sent to the center unit of the downstream provider. - As shown in the figure below, a request with a user ID of 1999 is simulated. It can be seen that the request is sent to the normal unit of product in the downstream through the frontend. - -image::pic/image-2022-09-15-16-15-39-851.png[] - - As shown in the figure below, a request with a user ID of 2000 is simulated. It can be seen that the request is sent to the center unit node of the product in the downstream through the frontend. - -image::pic/image-2022-09-15-16-14-50-461.png[] - -3. Demonstration of global service invocation belonging to the center unit. Typing: `http://127.0.0.1:8079/buyProduct` path in the browser, because the `/buyProduct` in the above path matches the `/buy/*` path rule in the product and storage applications, corresponding to the center unit, it will directly send the request to the downstream center unit node. - -image::pic/image-2022-09-15-16-14-02-388.png[] - - -4. Cut flow demo. The main things to do when cutting flow are as follows: -- Build new mapping relationship rules and write prohibition rules (manually). -- Push the write prohibition rules to the application. -- Push the new mapping relationship rules to the application after waiting for the data to equalize. -The streaming rule demonstrated next will send requests with user IDs 0 ~ 2999 to the normal(called unit) unit in the downstream provider, and requests with user IDs 3000 ~ 9999 will be sent to the center(called center) unit in the downstream provider. For specific rules, see idUnitMappingNext.json: - - { - "itemType": "UnitRuleItem", - "items": [ - { - "name": "unit", - "conditions": [ - { - "@userIdBetween": [ - "0~2999" - ] - } - ] - }, - { - "name": "center", - "conditions": [ - { - "@userIdBetween": [ - "3000~9999" - ] - } - ] - } - ] - } - -As shown in the figure below, a request with a user ID of 2999 is simulated. It can be seen that the request is sent to the unit node of the product in the downstream through the frontend, and the flow switching rule takes effect. - -image::pic/image-2022-09-15-16-12-58-177.png[] - -As shown in the figure below, a request with a user ID of 3000 is simulated. It can be seen that the request is sent to the center unit node of the product in the downstream through the frontend, and the cut flow rule takes effect. - -image::pic/image-2022-09-15-16-12-26-461.png[] \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/circuitbreaker-sentinel.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/circuitbreaker-sentinel.adoc deleted file mode 100644 index b2695e723..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/circuitbreaker-sentinel.adoc +++ /dev/null @@ -1,73 +0,0 @@ -=== Circuit Breaker: Spring Cloud Circuit Breaker With Sentinel & Configuring Sentinel Circuit Breakers - -==== Default Configuration - -To provide a default configuration for all of your circuit breakers create a `Customizer` bean that is passed a -`SentinelCircuitBreakerFactory` or `ReactiveSentinelCircuitBreakerFactory`. -The `configureDefault` method can be used to provide a default configuration. - -==== -[source,java] ----- -@Bean -public Customizer defaultCustomizer() { - return factory -> factory.configureDefault(id -> new SentinelConfigBuilder(id) - .build()); -} ----- -==== - -You can choose to provide default circuit breaking rules via `SentinelConfigBuilder#rules(rules)`. -You can also choose to load circuit breaking rules later elsewhere using -`DegradeRuleManager.loadRules(rules)` API of Sentinel, or via Sentinel dashboard. - -===== Reactive Example - -==== -[source,java] ----- -@Bean -public Customizer defaultCustomizer() { - return factory -> factory.configureDefault(id -> new SentinelConfigBuilder(id) - .build()); -} ----- -==== - -==== Specific Circuit Breaker Configuration - -Similarly to providing a default configuration, you can create a `Customizer` bean this is passed a -`SentinelCircuitBreakerFactory`. - -==== -[source,java] ----- -@Bean -public Customizer slowCustomizer() { - String slowId = "slow"; - List rules = Collections.singletonList( - new DegradeRule(slowId).setGrade(RuleConstant.DEGRADE_GRADE_RT) - .setCount(100) - .setTimeWindow(10) - ); - return factory -> factory.configure(builder -> builder.rules(rules), slowId); -} ----- -==== - -===== Reactive Example - -==== -[source,java] ----- -@Bean -public Customizer customizer() { - List rules = Collections.singletonList( - new DegradeRule().setGrade(RuleConstant.DEGRADE_GRADE_RT) - .setCount(100) - .setTimeWindow(10) - ); - return factory -> factory.configure(builder -> builder.rules(rules), "foo", "bar"); -} ----- -==== \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/dependency-management.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/dependency-management.adoc deleted file mode 100644 index f710c5d3c..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/dependency-management.adoc +++ /dev/null @@ -1,20 +0,0 @@ -== Dependency Management - -If you’re a Maven Central user, add our BOM to your pom.xml section. This will allow you to omit versions for any of the Maven dependencies and instead delegate versioning to the BOM. - -```xml - - - - com.alibaba.cloud - spring-cloud-alibaba-dependencies - 2.2.10-RC1 - pom - import - - - -``` - -In the following sections, it will be assumed you are using the Spring Cloud Alibaba BOM and the dependency snippets will not contain versions. - diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/governance.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/governance.adoc deleted file mode 100644 index 09760feb1..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/governance.adoc +++ /dev/null @@ -1,126 +0,0 @@ -== Spring Cloud Alibaba Governance - -image::pic/governance-module.png[] - -Spring Cloud Alibaba Governance is a Microservices governance capabilities provided by Spring Cloud Alibaba, which provides various types of microservices governance capabilities, including label routing, service authentication, etc. Moreover, it supports various control planes, such as https://istio.io/[Istio] and http://opensergo.io/[OpenSergo], so that users can get the governance rules in real time just adding relevant dependency, and apply these rules to applications to govern the Spring Cloud Alibaba application. - - -=== Resource Transform -image::pic/resource-transform.png[] - -The resource-transform adapter of Microservices Governance will uniformly transform the rules published by different control planes, like Istio and OperSergo, into the unified abstract data structure of Spring Cloud Alibaba for subsequent use. - -If you use Istio in your project to transform the rule, first of all, note that you need to build a Kubernetes cluster and deploy Istio in it. For details, refer to https://istio.io/latest/zh/docs/setup/install[Istio installation], you need to add a following starter dependency application(Generally added to service consumer application): -[source,xml,indent=0] ----- - - com.alibaba.cloud - spring-cloud-starter-xds-adapter - ----- -If you want to use OpenSergo, you can refer to https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/governance-example/label-routing-example[Spring Cloud Alibaba Routing Examples] - -After that, configure the following configuration in the application.yml: - -[source,yaml,indent=0] ----- -server: - port: ${SERVER_PORT:80} -spring: - cloud: - governance: - auth: - enabled: ${ISTIO_AUTH_ENABLE:true} - istio: - config: - enabled: ${ISTIO_CONFIG_ENABLE:true} - host: ${ISTIOD_ADDR:127.0.0.1} - port: ${ISTIOD_PORT:15010} - polling-pool-size: ${POLLING_POOL_SIZE:10} - polling-time: ${POLLING_TIMEOUT:10} - istiod-token: ${ISTIOD_TOKEN:} - log-xds: ${LOG_XDS:true} ----- - -Here's an explanation of each field: -|=== -|Configuration Item|key|Default Value|Description -|Whether to enable authentication| spring.cloud.governance.auth.enabled|true| -|Whether to connect to Istio to obtain authentication configuration| spring.cloud.istio.config.enabled|true| -|Host of Istiod| spring.cloud.istio.config.host|127.0.0.1| -|Port of Istiod| spring.cloud.istio.config.port|15012|15010 port does not need TLS，but 15012 does -|Thread pool size for application to pull the config| spring.cloud.istio.config.polling-pool-size|10| -|Time interval for application to pull the config| spring.cloud.istio.config.polling-time|30|The unit is second -|JWT token for application to connect to 15012 port| spring.cloud.istio.config.istiod-token|Content of file `/var/run/secrets/tokens/istio-token` in the pod of application| -|Whether to print logs about xDS| spring.cloud.istio.config.log-xds|true| -|=== - -Note that the application runs in the K8s environment, and the application in the non-default namespace needs to receive the rules issued by Istiod, and needs to inject the meta information of the running application Kubernetes into the following environment variables. For the specific operation method, please refer to https://kubernetes.io/zh-cn/docs/tasks/inject-data-application/environment-variable-expose-pod-information[Kubernetes documentation] - -|=== -|Environment variable name|K8s pod metadata name -|POD_NAME|metadata.name -|NAMESPACE_NAME|metadata.namespace -|=== - -=== Routing -==== Component support description - -Currently, the routing module only supports some components: - -Remote call Component: Spring Cloud OpenFeign - -Load balance Component: Ribbon - -In the future, more components such as RestTemplate, Spring Cloud LoadBalancer and so on will be supported. - -==== Using Routing capacity -With the introduction of the transformation adapter of rule, we can obtain the governance rules to give the Spring Cloud application some governance capabilities. Label routing module can route the Spring Cloud application according to the request header, request parameters and other tags to route to different services. - -If you use Microservices Governance Label Routing in your project, You need to use a following starter dependency(Generally added to service consumer application): -[source,xml,indent=0] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-governance-routing - ----- - -2.Configure a load balance algorithm when there are routing rules (RandomRule algorithm as an example) -If no configuration,use default ribbon load balance algorithm ZoneAvoidanceRule. ----- -spring.cloud.governance.routing.rule=RandomRule ----- - -With the introduction of Istio Resource Transform adapter, the label routing module supports routing of the following types of request meta-information: - -* Request Path -* Request Header -* Request Param - -We use Istio to publish corresponding `DestinationRule` and `VirtualService` to configure corresponding labeled routing rules. For details, see the following documents and examples: - -* https://istio.io/latest/zh/docs/reference/config/networking/virtual-service/#VirtualService[Istio VirtualService] -* https://istio.io/latest/zh/docs/concepts/traffic-management/#destination-rules[Istio Destination Rule] -* https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/governance-example/label-routing-example[Spring Cloud Alibaba Routing Examples] - -=== Authentication -image::pic/auth-process.png[] - -With the introduction of the transformation adapter of rule, we can obtain the governance rules to give the Spring Cloud application some governance capabilities. The Authentication module provides various authentication modes for Spring Cloud applications, such as IP blacklist and whitelist and JWT authentication. - -Add following Microservices Authentication starter: - -[source,xml,indent=0] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-governance-auth - ----- - -We use Istio to publish corresponding `AuthorizationPolicy` and `RequestAuthentication` to configure corresponding Authentication rules. For details, see the following documents and examples - -* https://istio.io/latest/zh/docs/reference/config/security/request_authentication/[Istio RequestAuthentication] -* https://istio.io/latest/zh/docs/reference/config/security/authorization-policy/[Authorization Policy] -* https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/governance-example/authentication-example[Spring Cloud Alibaba Authorization Examples] diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/introduction.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/introduction.adoc deleted file mode 100644 index 84a83c1f7..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/introduction.adoc +++ /dev/null @@ -1,19 +0,0 @@ -== Introduction - -Spring Cloud Alibaba aims to provide a one-stop solution for microservices development. This project includes the required components for developing distributed applications and services, so that developers can develop distributed applications easily with the Spring Cloud programming models. - -With Spring Cloud Alibaba, you only need to add a few annotations and configurations, and you will be able to use the distributed solutions of Alibaba for your applications, and build a distributed system of your own with Alibaba middleware. - -The features of Spring Cloud Alibaba: - -1. **Flow control and service degradation**：support WebServlet, WebFlux, OpenFeign, RestTemplate, Dubbo access to the function of limiting and degrading flow. It can modify the rules of limiting and degrading flow in real time through the console at run time, and it also supports the monitoring of limiting and degrading Metrics. -2. **Service registration and discovery**：Service can be registered and clients can discover the instances using Spring-managed beans, auto integration Ribbon. -3. **Distributed configuration**：support for externalized configuration in a distributed system, auto refresh when configuration changes. -4. **Rpc Service**：extend Spring Cloud client RestTemplate and OpenFeign to support calling Dubbo RPC services. -5. **Event-driven**：support for building highly scalable event-driven microservices connected with shared messaging systems. -6. **Distributed Transaction**：support for distributed transaction solution with high performance and ease of use. -7. **Alibaba Cloud Object Storage**：massive, secure, low-cost, and highly reliable cloud storage services. Support for storing and accessing any type of data in any application, anytime, anywhere. -8. **Alibaba Cloud SchedulerX**：accurate, highly reliable, and highly available scheduled job scheduling services with response time within seconds. -9. **Alibaba Cloud SMS**： A messaging service that covers the globe, Alibaba SMS provides convenient, efficient, and intelligent communication capabilities that help businesses quickly contact their customers. - -Spring Cloud Alibaba also provide rich https://github.com/alibaba/spring-cloud-alibaba/tree/master/spring-cloud-alibaba-examples[examples]. diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/nacos-config.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/nacos-config.adoc deleted file mode 100644 index c9f97b464..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/nacos-config.adoc +++ /dev/null @@ -1,422 +0,0 @@ -== Spring Cloud Alibaba Nacos Config - -Nacos is an easy-to-use dynamic service discovery, configuration and service management platform for building cloud native applications. - -Use Spring Cloud Alibaba Nacos Config to quickly access Nacos configuration management capabilities based on Spring Cloud's programming model. - -=== How to Introduce Nacos Config for configuration - -please use the starter with the group ID as `com.alibaba.cloud` and the artifact ID as `spring-cloud-starter-alibaba-nacos-config`. - -[source,xml,indent=0] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-config - ----- - -=== Quickstart - -Nacos Config uses DataId and GROUP to determine a configuration. - -The following figure shows that the DataId uses `myDataid`, GROUP uses `DEFAULT_GROUP`, and configures a configuration item of the format Properties: - -.Nacos Config Item -image::https://img.alicdn.com/tfs/TB1N2nxbRr0gK0jSZFnXXbRRXXa-2448-1194.png[] - -==== Initialize Nacos Server - -For specific startup methods, refer to the "Nacos Server Startup" section of the Spring Cloud Alibaba Nacos Discovery section. - -After the Nacos Server is started, add how to configure it: - -[source,subs="normal"] ----- -Data ID: nacos-config.properties - -Group : DEFAULT_GROUP - -Configuration format: Properties - -Configuration content: user.name=nacos-config-properties - user.age=90 ----- - -NOTE: The default file extension of DataId is properties. - -===== Usage on the Client - -If you want to use Nacos to manage externalized configurations for your applications, please use the starter with the group ID as `com.alibaba.cloud` and the artifact ID as `spring-cloud-starter-alibaba-nacos-config`. - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-config - ----- - -Now we can create a standard Spring Boot application. - -[source,java] ----- -@SpringBootApplication -public class NacosConfigApplication { - - public static void main(String[] args) { - ConfigurableApplicationContext applicationContext = SpringApplication.run(NacosConfigApplication.class, args); - String userName = applicationContext.getEnvironment().getProperty("user.name"); - String userAge = applicationContext.getEnvironment().getProperty("user.age"); - System.err.println("user name :" +userName+"; age: "+userAge); - } -} ----- - -Before running this example, we need to configure the address of the Nacos server in bootstrap.properties. For example: - -.bootstrap.properties -[source,properties] ----- -# DataId By default, the `spring.application.name` configuration is combined with the file extension (the configuration format uses properties by default), and the GROUP is not configured to use DEFAULT_GROUP by default. Therefore, the Nacos Config configuration corresponding to the configuration file has a DataId of nacos-config.properties and a GROUP of DEFAULT_GROUP -spring.application.name=nacos-config -spring.cloud.nacos.config.server-addr=127.0.0.1:8848 ----- - -NOTE: If you use domain name to access Nacos, the format of `spring.cloud.nacos.config.server-addr` should be `Domain name:port`. -For example, if the Nacos domain name is abc.com.nacos, and the listerner port is 80, then the configuration should be `spring.cloud.nacos.config.server-addr=abc.com.nacos:80`. -Port 80 cannot be omitted. - -Run this example and you can see the following output: - -[source,subs="normal"] ----- -2018-11-02 14:24:51.638 INFO 32700 --- [main] c.a.demo.provider.NacosConfigApplication : Started NacosConfigApplication in 14.645 seconds (JVM running for 15.139) -user name :nacos-config-properties; age: 90 -2018-11-02 14:24:51.688 INFO 32700 --- [-127.0.0.1:8848] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@a8c5e74: startup date [Fri Nov 02 14:24:51 CST 2018]; root of context hierarchy ----- - -=== Add Configurations with DataId in YAML Format - -Nacos Config supports yaml format as well. You only need to complete the following 2 steps. - -1、In the bootstrap.properties file, add the following line to claim that the format of DataId is yaml. As follows: - -.bootstrap.properties -[source,yaml] ----- -spring.cloud.nacos.config.file-extension=yaml ----- - -2、Add a configuration with the DataId in yaml format on the Nacos console, as shown below: - -[source,subs="normal"] ----- -Data ID: nacos-config.yaml - -Group : DEFAULT_GROUP - -Configuration format: YAML - -Configuration content: user.name: nacos-config-yaml - user.age: 68 ----- - -After completing the preivous two steps, restart the testing program and you will see the following result. - -[source,subs="normal"] ----- -2018-11-02 14:59:00.484 INFO 32928 --- [main] c.a.demo.provider.NacosConfigApplication:Started NacosConfigApplication in 14.183 seconds (JVM running for 14.671) -user name :nacos-config-yaml; age: 68 -2018-11-02 14:59:00.529 INFO 32928 --- [-127.0.0.1:8848] s.c.a.AnnotationConfigApplicationContext : Refreshing org.springframework.context.annotation.AnnotationConfigApplicationContext@265a478e: startup date [Fri Nov 02 14:59:00 CST 2018]; root of context hierarchy ----- - -=== Support Dynamic Configuration Udpates - -Nacos Config also supports dynamic configuration updates. The code for starting Spring Boot application testing is as follows: - -[source,java] ----- -@SpringBootApplication -public class NacosConfigApplication { - - public static void main(String[] args) { - ConfigurableApplicationContext applicationContext = SpringApplication.run(NacosConfigApplication.class, args); - while(true) { - //When configurations are refreshed dynamically, they will be updated in the Enviroment, therefore here we retrieve configurations from Environment every other second. - String userName = applicationContext.getEnvironment().getProperty("user.name"); - String userAge = applicationContext.getEnvironment().getProperty("user.age"); - System.err.println("user name :" + userName + "; age: " + userAge); - TimeUnit.SECONDS.sleep(1); - } - } -} ----- - -When user.name is changed, the latest value can be retrieved from the application, as shown below: - -[source,subs="normal"] ----- -user name :nacos-config-yaml; age: 68 -user name :nacos-config-yaml; age: 68 -user name :nacos-config-yaml; age: 68 -2018-11-02 15:04:25.069 INFO 32957 --- [-127.0.0.1:8848] o.s.boot.SpringApplication : Started application in 0.144 seconds (JVM running for 71.752) -2018-11-02 15:04:25.070 INFO 32957 --- [-127.0.0.1:8848] s.c.a.AnnotationConfigApplicationContext : Closing org.springframework.context.annotation.AnnotationConfigApplicationContext@10c89124: startup date [Fri Nov 02 15:04:25 CST 2018]; parent: org.springframework.context.annotation.AnnotationConfigApplicationContext@6520af7 -2018-11-02 15:04:25.071 INFO 32957 --- [-127.0.0.1:8848] s.c.a.AnnotationConfigApplicationContext : Closing org.springframework.context.annotation.AnnotationConfigApplicationContext@6520af7: startup date [Fri Nov 02 15:04:24 CST 2018]; root of context hierarchy -//Read the updated value from Enviroment -user name :nacos-config-yaml-update; age: 68 -user name :nacos-config-yaml-update; age: 68 ----- - -NOTE: You can disable automatic refresh with this setting`spring.cloud.nacos.config.refresh.enabled=false`. - -=== Support configurations at the profile level - -When configurations are loaded by Nacos Config, basic configurations with DataId of `${spring.application.name}. ${file-extension:properties}` , and DataId of `${spring.application.name}-${profile}. ${file-extension:properties}` are also loaded. If you need to use different configurations from different environments, you can use the `${spring.profiles.active}` configuration provided by Spring. - -[source,properties] ----- -spring.profiles.active=develop ----- - -NOTE: When specified in configuration files, ${spring.profiles.active} must be placed in bootstrap.properties. - -Add a basic configuration in Nacos, with a DataId of nacos-config-develop.yaml, as shown below: - -[source,subs="normal"] ----- -Data ID: nacos-config-develop.yaml - -Group : DEFAULT_GROUP - -Configuration format: YAML - -Configuration content: current.env: develop-env ----- - -Run the following Spring Boot application testing code: - -[source,java] ----- -@SpringBootApplication -public class NacosConfigApplication { - - public static void main(String[] args) { - ConfigurableApplicationContext applicationContext = SpringApplication.run(NacosConfigApplication.class, args); - while(true) { - String userName = applicationContext.getEnvironment().getProperty("user.name"); - String userAge = applicationContext.getEnvironment().getProperty("user.age"); - //Get the current deployment environment - String currentEnv = applicationContext.getEnvironment().getProperty("current.env"); - System.err.println("in "+currentEnv+" enviroment; "+"user name :" + userName + "; age: " + userAge); - TimeUnit.SECONDS.sleep(1); - } - } -} ----- -After started, you can see the output as follows in the console: - -[source,subs="normal"] ----- -in develop-env enviroment; user name :nacos-config-yaml-update; age: 68 -2018-11-02 15:34:25.013 INFO 33014 --- [ Thread-11] ConfigServletWebServerApplicationContext : Closing org.springframework.boot.web.servlet.context.AnnotationConfigServletWebServerApplicationContext@6f1c29b7: startup date [Fri Nov 02 15:33:57 CST 2018]; parent: org.springframework.context.annotation.AnnotationConfigApplicationContext@63355449 ----- - -To switch to the production environment, you only need to change the parameter of `${spring.profiles.active}`. As show below: - -[source,properties] ----- -spring.profiles.active=product ----- - -At the same time, add the basic configuration with the DataId in the Nacos of your production environment. For example, you can add the configuration with the DataId of nacos-config-product.yaml in Nacos of your production environment: - -[source,subs="normal"] ----- -Data ID: nacos-config-product.yaml - -Group : DEFAULT_GROUP - -Configuration format: YAML - -Configuration content: current.env: product-env ----- - -Start the testing program and you will see the following result: - -[source,subs="normal"] ----- -in product-env enviroment; user name :nacos-config-yaml-update; age: 68 -2018-11-02 15:42:14.628 INFO 33024 --- [Thread-11] ConfigServletWebServerApplicationContext : Closing org.springframework.boot.web.servlet.context.AnnotationConfigServletWebServerApplicationContext@6aa8e115: startup date [Fri Nov 02 15:42:03 CST 2018]; parent: org.springframework.context.annotation.AnnotationConfigApplicationContext@19bb07ed ----- - - -NOTE: In this example, we coded the configuration in the configuration file by using the `spring.profiles.active=` method. In real scenarios, this variable needs to be different in different environment. You can use the `-Dspring.profiles.active=` parameter to specify the configuration so that you can switch between different environments easily. - -=== Support Custom Namespaces -For details about namespaces in Nacos, refer to https://nacos.io/zh-cn/docs/concepts.html[Nacos Concepts] - -[quote] -Namespaces are used to isolate configurations for different tenants. Groups and Data IDs can be the same across different namespaces. Typical scenarios of namespaces is the isolation of configurations for different environments, for example, isolation between development/testing environments and production environments(configurations and services and so on). - -The “Public” namespace of Nacos is used if no namespace is specified in `${spring.cloud.nacos.config.namespace}`. You can also specify a custom namespace in the following way： -[source,properties] ----- -spring.cloud.nacos.config.namespace=b3404bc0-d7dc-4855-b519-570ed34b62d7 ----- - -NOTE: This configuration must be in the bootstrap.properties file. The value of `spring.cloud.nacos.config.namespace` is the id of the namespace, and the value of id can be retrieved from the Nacos console. Do not select other namespaces when adding configurations. Otherwise configurations cannot be retrieved properly. - -=== Support Custom Groups - -DEFAULT_GROUP is used by default when no `{spring.cloud.nacos.config.group}` configuration is defined. If you need to define your own group, you can define it in the following property: - -[source,properties] ----- -spring.cloud.nacos.config.group=DEVELOP_GROUP ----- - -NOTE: This configuration must be in the bootstrap.properties file, and the value of Group must be the same with the value of `spring.cloud.nacos.config.group`. - -=== Support Custom Data Id - -As of Spring Cloud Alibaba Nacos Config, data id can be self-defined. For detailed design of this part, refer to https://github.com/alibaba/spring-cloud-alibaba/issues/141[Github issue]. -The following is a complete sample: - -[source,properties] ----- -spring.application.name=opensource-service-provider -spring.cloud.nacos.config.server-addr=127.0.0.1:8848 - -# config external configuration -# 1. Data Id is in the default group of DEFAULT_GROUP, and dynamic refresh of configurations is not supported. -spring.cloud.nacos.config.ext-config[0].data-id=ext-config-common01.properties - -# 2. Data Id is not in the default group, and dynamic refresh of configurations is not supported. -spring.cloud.nacos.config.ext-config[1].data-id=ext-config-common02.properties -spring.cloud.nacos.config.ext-config[1].group=GLOBALE_GROUP - -# 3. Data Id is not in the default group and dynamic referesh of configurations is supported. -spring.cloud.nacos.config.ext-config[2].data-id=ext-config-common03.properties -spring.cloud.nacos.config.ext-config[2].group=REFRESH_GROUP -spring.cloud.nacos.config.ext-config[2].refresh=true ----- - -We can see that: - -* Support multiple data ids by configuring `spring.cloud.nacos.config.ext-config[n].data-id`. -* Customize the group of data id by configuring `spring.cloud.nacos.config.ext-config[n].group`. If not specified, DEFAULT_GROUP is used. -* Control whether this data id supports dynamic refresh of configurations is supported when configurations are changed by configuring `spring.cloud.nacos.config.ext-config[n].refresh`. - It’s not supported by default. - - -NOTE: When multiple Data Ids are configured at the same time, the priority is defined by the value of “n” in `spring.cloud.nacos.config.ext-config[n].data-id`. The bigger the value, the higher the priority. - -NOTE: The value of `spring.cloud.nacos.config.ext-config[n].data-id` must have a file extension, and it could be properties or yaml/yml. -The setting in `spring.cloud.nacos.config.file-extension` does not have any impact on the custom Data Id file extension. - -The configuration of custom Data Id allows the sharing of configurations among multiple applications, and also enables support of multiple configurations for one application. - -To share the data id among multiple applications in a clearer manner, you can also use the following method: - -[source,properties] ----- -spring.cloud.nacos.config.shared-dataids=bootstrap-common.properties,all-common.properties -spring.cloud.nacos.config.refreshable-dataids=bootstrap-common.properties ----- - -We can see that: - -* Multiple shared data ids can be configured using `spring.cloud.nacos.config.shared-dataids` , and the data ids are separted by commas. -* `spring.cloud.nacos.config.refreshable-dataids` is used to control which data ids will be refreshed dynamically when configurations are updated, and that the latest configuration values can be retrieved by applications. Data ids are separated with commas. - If not specified, all shared data ids will not be dynamically refreshed. - -NOTE: When using `spring.cloud.nacos.config.shared-dataids` to configure multiple shared data ids, -we agree on the following priority between the shared configurations: Priorities are decided based on the order in which the configurations appear. The one that occurs later is higher in priority than the one that appears first. - -NOTE: When using `spring.cloud.nacos.config.shared-dataids`, the data Id must have a file extension, and it could be properties or yaml/yml. -And the configuration in `spring.cloud.nacos.config.file-extension` does not have any impact on the customized Data Id file extension. - -NOTE: When `spring.cloud.nacos.config.refreshable-dataids` specifies the data ids that support dynamic refresh, the corresponding values of the data ids should also specify file extensions. - -=== Nacos Config Endpoint - -Nacos Config provides an Endpoint internally with a corresponding endpoint id of `nacos-config`. - -Endpoint exposed json contains three properties: - -1. Sources: Current application configuration data information - -2. RefreshHistory: Configuration refresh history - -3. NacosConfigProperties: Shows the current basic Nacos configurations of the current service - -The followings shows how a service instance accesses the Endpoint: - -[source,json,indent=0] ----- -{ - "NacosConfigProperties": { - "serverAddr": "127.0.0.1:8848", - "encode": null, - "group": "DEFAULT_GROUP", - "prefix": null, - "fileExtension": "properties", - "timeout": 3000, - "endpoint": null, - "namespace": null, - "accessKey": null, - "secretKey": null, - "contextPath": null, - "clusterName": null, - "name": null, - "sharedDataids": "base-common.properties,common.properties", - "refreshableDataids": "common.properties", - "extConfig": null - }, - "RefreshHistory": [{ - "timestamp": "2019-07-29 11:20:04", - "dataId": "nacos-config-example.properties", - "md5": "7d5d7f1051ff6571e2ec9f90887d9d91" - }], - "Sources": [{ - "lastSynced": "2019-07-29 11:19:04", - "dataId": "common.properties" - }, { - "lastSynced": "2019-07-29 11:19:04", - "dataId": "base-common.properties" - }, { - "lastSynced": "2019-07-29 11:19:04", - "dataId": "nacos-config-example.properties" - }] -} ----- - - -=== Disable Nacos Config AutoConfiguration - -set spring.cloud.nacos.config.enabled = false to disable Spring Cloud Nacos Config AutoConfiguration. - -=== More Information about Nacos Config Starter Configurations - -The following shows the other configurations of the starter of Nacos Config: - -|=== -|Configuration |Key |Default Value |Description -|Server address|`spring.cloud.nacos.config.server-addr`|| IP and port of the Nacos Server listener -|Dataid from nacos config|`spring.cloud.nacos.config.name`|| First take the prefix, then go to the name, and finally take spring.application.name -|Dataid from nacos config|`spring.cloud.nacos.config.prefix`|| First take the prefix, then go to the name, and finally take spring.application.name -|Encode for nacos config content|`spring.cloud.nacos.config.encode`||Encode for nacos config content -|GROUP for nacos config|`spring.cloud.nacos.config.group`|`DEFAULT_GROUP`|GROUP for nacos config -|The suffix of nacos config dataId, also the file extension of config content.|`spring.cloud.nacos.config.fileExtension`|`properties`|The suffix of nacos config dataId, also the file extension of config content(now support properties or yaml(yml)) -|Timeout for get config from nacos|`spring.cloud.nacos.config.timeout`|`3000`|Timeout for get config from nacos -|Endpoint|`spring.cloud.nacos.config.endpoint`||Endpoint -|Namespace|`spring.cloud.nacos.config.namespace`||Namespace -|AccessKey|`spring.cloud.nacos.config.accessKey`||Alibaba Cloud account accesskey -|SecretKey|`spring.cloud.nacos.config.secretKey`||Alibaba Cloud account secretkey -|The context path of Nacos Server|`spring.cloud.nacos.config.contextPath`||The context path of Nacos Server -|Cluster name|`spring.cloud.nacos.config.clusterName`||Cluster name -|Dataid for Shared Configuration|`spring.cloud.nacos.config.sharedDataids`||Dataid for Shared Configuration, split by "," -|Dynamic refresh dataid for Shared Configuration|`spring.cloud.nacos.config.refreshableDataids`||Dynamic refresh dataid for Shared Configuration, split by "," -|custom dataid|`spring.cloud.nacos.config.extConfig`||It's a List，build up by `Config` POJO. `Config` has 3 attributes, `dataId`, `group` and `refresh` -|=== diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/nacos-discovery.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/nacos-discovery.adoc deleted file mode 100644 index 2464f8f5b..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/nacos-discovery.adoc +++ /dev/null @@ -1,357 +0,0 @@ -== Spring Cloud Alibaba Nacos Discovery - -Nacos is an easy-to-use dynamic service discovery, configuration and service management platform for building cloud native applications. - -With Spring Cloud Alibaba Nacos Discovery, you can quickly access the Nacos service registration feature based on Spring Cloud's programming model. - -=== Service Registration/Discovery: Nacos Discovery - -Service discovery is one of the key components in the microservices architecture. In such a architecture, configuring a service list for every client manually could be a daunting task, and makes dynamic scaling extremely difficult. - Nacos Discovery helps you to register your service to the Nacos server automatically, and the Nacos server keeps track of the services and refreshes the service list dynamically. In addition, Nacos -Discovery registers some of the metadata of the service instance, such as host, port, health check URL, homepage to Nacos. For details about how to download and start Nacos, refer to the https://nacos.io/zh-cn/docs/quick-start.html[Nacos Website]. - -=== How to Introduce Nacos Discovery for service registration/discovery - -please use the starter with the group ID as `com.alibaba.cloud` and the artifact ID as `spring-cloud-starter-alibaba-nacos-discovery`. - -[source,xml,indent=0] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-discovery - ----- - -=== An example of using Nacos Discovery for service registration/discovery and call - -Nacos Discovery integrate with the Netflix Ribbon, RestTemplate or OpenFeign can be used for service-to-service calls. - -==== Nacos Server Startup - -For details about how to download and start Nacos, refer to the https://nacos.io/zh-cn/docs/quick-start.html[Nacos Website]. - -After Nacos Server starts, go to http://ip:8848 to view the console (default account name/password is nacos/nacos): - -.Nacos Dashboard -image::https://img.alicdn.com/tfs/TB1XEfwbQH0gK0jSZPiXXavapXa-2790-1060.png[] - -For more Nacos Server versions, you can download the latest version from https://github.com/alibaba/nacos/releases[release page]. - -==== Start a Provider Application - -The following sample illustrates how to register a service to Nacos. - -* Configuration of pom.xml The following is a complete example of pom.xml： - -.pom.xml -[source,xml] ----- - - - 4.0.0 - - open.source.test - nacos-discovery-test - 1.0-SNAPSHOT - nacos-discovery-test - - - org.springframework.boot - spring-boot-starter-parent - ${spring.boot.version} - - - - - UTF-8 - UTF-8 - 1.8 - - - - - - org.springframework.cloud - spring-cloud-dependencies - ${spring.cloud.version} - pom - import - - - com.alibaba.cloud - spring-cloud-alibaba-dependencies - ${spring.cloud.alibaba.version} - pom - import - - - - - - - org.springframework.boot - spring-boot-starter-web - - - - org.springframework.boot - spring-boot-starter-actuator - - - - com.alibaba.cloud - spring-cloud-starter-alibaba-nacos-discovery - - - - - - - org.springframework.boot - spring-boot-maven-plugin - - - - ----- - -* Configuration of application.properties Some of the basic configurations of Nacos must be included in application.properties(or application.yaml), as shown below： - -.application.properties -[source,properties] ----- -server.port=8081 -spring.application.name=nacos-provider -spring.cloud.nacos.discovery.server-addr=127.0.0.1:8848 -management.endpoints.web.exposure.include=* ----- - - -NOTE: If you do not want to use Nacos for service registration and discovery, you can set `spring.cloud.nacos.discovery` to `false`. - -* The following is a sample for starting Provider: - -[source,java,indent=0] ----- -@SpringBootApplication -@EnableDiscoveryClient -public class NacosProviderDemoApplication { - - public static void main(String[] args) { - SpringApplication.run(NacosProviderDemoApplication.class, args); - } - - @RestController - public class EchoController { - @GetMapping(value = "/echo/{string}") - public String echo(@PathVariable String string) { - return "Hello Nacos Discovery " + string; - } - } -} ----- - -Now you can see the registered services on the Nacos console. - -NOTE: Before you start the provider application, please start Nacos first. Refer to https://nacos.io/zh-cn/docs/quick-start.html[Naco Website] for more details. - -==== Start a Consumer Application - -It might not be as easy as starting a provider application, because the consumer needs to call the RESTful service of the provider. In this example, we will use the most primitive way, that is, -combining the LoadBalanceClient and RestTemplate explicitly to access the RESTful service. -You can refer to section 1.2 for pom.xml and application.properties configurations. The following is the sample code for starting a consumer application. - -NOTE: You can also access the service by using RestTemplate and FeignClient with load balancing. - -[source, java] ----- -@SpringBootApplication -@EnableDiscoveryClient -public class NacosConsumerApp { - - @RestController - public class NacosController{ - - @Autowired - private LoadBalancerClient loadBalancerClient; - @Autowired - private RestTemplate restTemplate; - - @Value("${spring.application.name}") - private String appName; - - @GetMapping("/echo/app-name") - public String echoAppName(){ - //Access through the combination of LoadBalanceClient and RestTemplate - ServiceInstance serviceInstance = loadBalancerClient.choose("nacos-provider"); - String path = String.format("http://%s:%s/echo/%s",serviceInstance.getHost(),serviceInstance.getPort(),appName); - System.out.println("request path:" +path); - return restTemplate.getForObject(path,String.class); - } - - } - - //Instantiate RestTemplate Instance - @Bean - public RestTemplate restTemplate(){ - - return new RestTemplate(); - } - - public static void main(String[] args) { - - SpringApplication.run(NacosConsumerApp.class,args); - } -} ----- - -In this example, we injected a LoadBalancerClient instance, and instantiated a RestTemplate manually. At the same time, we injected the configuration value of `spring.application.name` into the application, -so that the current application name can be displayed when calling the service of the provider. - -NOTE: Please start Nacos before you start the consumer application. For details, please refer to https://nacos.io/zh-cn/docs/quick-start.html[Nacos Website]. - -Next, access the `http://ip:port/echo/app-name` interface provided by the consumer. Here we started the port of 8082. The access result is shown below： - - Address：http://127.0.0.1:8082/echo/app-name - Access result： Hello Nacos Discovery nacos-consumer - - -=== Nacos Discovery Endpoint - -Nacos Discovery provides an Endpoint internally with a corresponding endpoint id of `nacos-discovery`. - -Endpoint exposed json contains two properties: - -1. subscribe: Shows the current service subscribers - -2. NacosDiscoveryProperties: Shows the current basic Nacos configurations of the current service - -The followings shows how a service instance accesses the Endpoint: - -[source, json] ----- -{ - "subscribe": [ - { - "jsonFromServer": "", - "name": "nacos-provider", - "clusters": "", - "cacheMillis": 10000, - "hosts": [ - { - "instanceId": "30.5.124.156#8081#DEFAULT#nacos-provider", - "ip": "30.5.124.156", - "port": 8081, - "weight": 1.0, - "healthy": true, - "enabled": true, - "cluster": { - "serviceName": null, - "name": null, - "healthChecker": { - "type": "TCP" - }, - "defaultPort": 80, - "defaultCheckPort": 80, - "useIPPort4Check": true, - "metadata": { - - } - }, - "service": null, - "metadata": { - - } - } - ], - "lastRefTime": 1541755293119, - "checksum": "e5a699c9201f5328241c178e804657e11541755293119", - "allIPs": false, - "key": "nacos-provider", - "valid": true - } - ], - "NacosDiscoveryProperties": { - "serverAddr": "127.0.0.1:8848", - "endpoint": "", - "namespace": "", - "logName": "", - "service": "nacos-provider", - "weight": 1.0, - "clusterName": "DEFAULT", - "metadata": { - - }, - "registerEnabled": true, - "ip": "30.5.124.201", - "networkInterface": "", - "port": 8082, - "secure": false, - "accessKey": "", - "secretKey": "" - } -} ----- - -=== Weight Route - -==== Ribbon - -.application.properties -[source,properties] ----- -[service_name].ribbon.NFLoadBalancerRuleClassName=com.alibaba.cloud.nacos.ribbon.NacosRule ----- - -=== 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: -[source,properties] ----- -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: -[source,properties] ----- -spring.cloud.nacos.discovery.ip-type=IPv6 ----- - -=== More Information about Nacos Discovery Starter Configurations - -The following shows the other configurations of the starter of Nacos Discovery: - -|=== -|Configuration |Key |Default Value |Description -|Server address|`spring.cloud.nacos.discovery.server-addr`||IP and port of the Nacos Server listener -|Service name|`spring.cloud.nacos.discovery.service`|`${spring.application.name}`|Name the current service -|Weight|`spring.cloud.nacos.discovery.weight`|`1`|Value range: 1 to 100. The bigger the value, the greater the weight -|Network card name|`spring.cloud.nacos.discovery.network-interface`||If the IP address is not specified, the registered IP address is the IP address of the network card. If this is not specified either, the IP address of the first network card will be used by default. -|Registered IP address|`spring.cloud.nacos.discovery.ip`||Highest priority -|Registered IP address 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 -|Registered port|`spring.cloud.nacos.discovery.port`|`-1`|Will be detected automatically by default. Do not need to be configured. -|Namespace|`spring.cloud.nacos.discovery.namespace`||A typical scenario is to isolate the service registration for different environment, such as resource (configurations, services etc.) isolation between testing and production environment -|AccessKey|`spring.cloud.nacos.discovery.access-key`||Alibaba Cloud account accesskey -|SecretKey|`spring.cloud.nacos.discovery.secret-key`||Alibaba Cloud account secretkey -|Metadata|`spring.cloud.nacos.discovery.metadata`||You can define some of the metadata for your services in the Map format -|Log file name|`spring.cloud.nacos.discovery.log-name`|| -|Cluster Name|`spring.cloud.nacos.discovery.cluster-name`|`DEFAULT`|Cluster name of Nacos -|Endpoint|`spring.cloud.nacos.discovery.endpoint`||The domain name of a certain service in a specific region. You can retrieve the server address dynamically with this domain name -|Integrate Ribbon or not|`ribbon.nacos.enabled`|`true`|Set to true in most cases -|Enable Nacos Watch|`spring.cloud.nacos.discovery.watch.enabled`|`false`|set to true to enable watch -|Enable Nacos Discovery HeartBeat|`spring.cloud.nacos.discovery.heart-beat.enabled`|`false`|set to true to enable heart beat -|=== - diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/oss.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/oss.adoc deleted file mode 100644 index a44fd72df..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/oss.adoc +++ /dev/null @@ -1,157 +0,0 @@ -== Spring Cloud Alibaba Cloud OSS - -OSS（Object Storage Service）is a storage product on Alibaba Cloud. Spring Cloud Alibaba Cloud OSS provides the commercialized storage service in conformity with Spring Cloud specifications. We provide easy-to-use APIs and supports the integration of Resource in the Spring framework. - -=== How to Introduce Spring Cloud Alibaba Cloud OSS - -We’ve released Spring Cloud Alibaba version 0.2.1. You will need to add dependency management POM first. - -[source,xml] ----- - - - - com.alibaba.cloud - spring-cloud-alibaba-dependencies - 0.2.2.BUILD-SNAPSHOT - pom - import - - - ----- - -Next we need to introduce Spring Cloud Alibaba Cloud OSS Starter. - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alicloud-oss - ----- - -=== How to Use OSS API - -==== Configure OSS - -Before you start to use Spring Cloud Alibaba Cloud OSS, please add the following configurations in application.properties. - -[source,properties] ----- -spring.cloud.alicloud.access-key=Your Alibaba Cloud AK -spring.cloud.alicloud.secret-key=Your Alibaba Cloud SK -spring.cloud.alicloud.oss.endpoint=***.aliyuncs.com ----- - -access-key and secret-key is the AK/SK of your Alibaba Cloud account. If you don’t have one, please register an account first, and log on to https://usercenter.console.aliyun.com/#/manage/ak[Alibaba Cloud AK/SK Management] to get your AccessKey ID and Access Key Secret . If you haven’t create the AccessKeys, click “Create AccessKey” to create one. - -For endpoint information, please refer to the OSS https://help.aliyun.com/document_detail/31837.html[Documentation] and get the endpoint for your region. - - -==== Introduce OSS API - -The OSS API of Spring Cloud Alibaba Cloud OSS is based on the official OSS SDK, and includes APIs for uploading, downloading, viewing files. - -Here is a simple application that uses the OSS API. - -[source,java] ----- -@SpringBootApplication -public class OssApplication { - - @Autowired - private OSS ossClient; - - @RequestMapping("/") - public String home() { - ossClient.putObject("bucketName", "fileName", new FileInputStream("/your/local/file/path")); - return "upload success"; - } - - public static void main(String[] args) throws URISyntaxException { - SpringApplication.run(OssApplication.class, args); - } - -} ----- - -Before you upload your files, please https://account.aliyun.com/register/register.htm?spm=5176.8142029.388261.26.e9396d3eaYK2sG&oauth_callback=https%3A%2F%2Fwww.aliyun.com%2F[Register an Alibaba Cloud Account]. If you already have one, please https://common-buy.aliyun.com/?spm=5176.8465980.unusable.dopen.4cdf1450rg8Ujb&commodityCode=oss#/open[Sign up for OSS]. - -Log on to the https://oss.console.aliyun.com/overview[OSS Console], click “Create New Bucket” and create a bucket as instructed. Replace the bucket name in the “bucketname” of the previous code with your new bucket name. "fileName” can be any name you like, and "/your/local/file/path” can be any local file path. Next you can run `curl http://127.0.0.1:port number/ to upload your files, and you will see your file on the https://oss.console.aliyun.com/overview[OSS Console]. - -For more instructions on OSS APIs, please refer to https://help.aliyun.com/document_detail/32008.html[OSS SDK Documentation]. - -=== Integrate with the Resource Specifications of Spring - -Spring Cloud Alibaba Cloud OSS integrates the Resource of the Spring framework, which allows you to use the OSS resources easily. - -The following is a simple example of how to use Resource. - -[source,java] ----- -@SpringBootApplication -public class OssApplication { - - @Value("oss://bucketName/fileName") - private Resource file; - - @GetMapping("/file") - public String fileResource() { - try { - return "get file resource success. content: " + StreamUtils.copyToString( - file.getInputStream(), Charset.forName(CharEncoding.UTF_8)); - } catch (Exception e) { - return "get resource fail: " + e.getMessage(); - } - } - - public static void main(String[] args) throws URISyntaxException { - SpringApplication.run(OssApplication.class, args); - } - -} ----- - -NOTE: A prerequisite for the above sample is that you need to have a bucket named “bucketName” on OSS, and you have a file named “fileName” in this bucket. - -=== Use STS Authentication - -In addition to AccessKeys, Spring Cloud Alibaba Cloud OSS also supports STS authentication. STS is an authentication method with temporary security tokens, and is usually used for a third party to access its resources temporarily. - -For a third party to access resources temporarily, it only needs to complete the following configurations. - -[source,properties] ----- -spring.cloud.alicloud.oss.authorization-mode=STS -spring.cloud.alicloud.oss.endpoint=***.aliyuncs.com -spring.cloud.alicloud.oss.sts.access-key=Your authenticated AK -spring.cloud.alicloud.oss.sts.secret-key=Your authenticated SK -spring.cloud.alicloud.oss.sts.security-token=Your authenticated ST ----- - -Among which, spring.cloud.alicloud.oss.authorization-mode is the enumeration type. Fill in STS here means that STS authentication is used. For endpoint information, refer to the https://help.aliyun.com/document_detail/31837.html[OSS Documentation] and fill in the endpoint for your region. - -Access-key, secret-key and the security-token need to be issued by the authentication side. For more information about STS, refer to https://help.aliyun.com/document_detail/31867.html[STS Documentation]. - -=== More Configurations for the Client - -In addition to basic configurations, Spring Cloud Alibaba Cloud OSS also supports many other configurations, which are also included in the application.properties file. - -Here are some examples. - -[source,properties] ----- -spring.cloud.alicloud.oss.authorization-mode=STS -spring.cloud.alicloud.oss.endpoint=***.aliyuncs.com -spring.cloud.alicloud.oss.sts.access-key=Your authenticated AK -spring.cloud.alicloud.oss.sts.secret-key=Your authenticated SK -spring.cloud.alicloud.oss.sts.security-token=Your authenticated ST - -spring.cloud.alicloud.oss.config.connection-timeout=3000 -spring.cloud.alicloud.oss.config.max-connections=1000 ----- - -For more configurations, refer to the table at the bottom of https://help.aliyun.com/document_detail/32010.html[OSSClient Configurations]. - -NOTE: In most cases, you need to connect the parameter names with “-” for the parameters in the table of https://help.aliyun.com/document_detail/32010.html[OSSClient Configurations] with “-”, and all letters should be in lowercase. For example, ConnectionTimeout should be changed to connection-timeout. diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/auth-process.png b/spring-cloud-alibaba-docs/src/main/asciidoc/pic/auth-process.png deleted file mode 100644 index 29638a551..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/auth-process.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/governance-module.png b/spring-cloud-alibaba-docs/src/main/asciidoc/pic/governance-module.png deleted file mode 100644 index 0b37e3536..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/governance-module.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-12-26-461.png b/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-12-26-461.png deleted file mode 100644 index c888c29a9..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-12-26-461.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-12-58-177.png b/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-12-58-177.png deleted file mode 100644 index 158803eed..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-12-58-177.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-14-02-388.png b/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-14-02-388.png deleted file mode 100644 index 68c0432ac..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-14-02-388.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-14-50-461.png b/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-14-50-461.png deleted file mode 100644 index 246eea025..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-14-50-461.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-15-39-851.png b/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-15-39-851.png deleted file mode 100644 index 3a3d5d271..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-15-39-851.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-16-25-989.png b/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-16-25-989.png deleted file mode 100644 index 5089084bc..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/image-2022-09-15-16-16-25-989.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/resource-transform.png b/spring-cloud-alibaba-docs/src/main/asciidoc/pic/resource-transform.png deleted file mode 100644 index 3865e9458..000000000 Binary files a/spring-cloud-alibaba-docs/src/main/asciidoc/pic/resource-transform.png and /dev/null differ diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/rocketmq.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/rocketmq.adoc deleted file mode 100644 index 4362375d9..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/rocketmq.adoc +++ /dev/null @@ -1,338 +0,0 @@ -== Spring Cloud Alibaba RocketMQ Binder - -=== Introduction of RocketMQ - -https://rocketmq.apache.org[RocketMQ] is an open-source distributed message system. It is based on highly available distributed cluster technologies and provides message publishing and subscription service with low latency and high stability. RocketMQ is widely used in a variety of industries, such as decoupling of asynchronous communication, enterprise sulotions, financial settlements, telecommunication, e-commerce, logistics, marketing, social media, instant messaging, mobile applications, mobile games, vedios, IoT, and Internet of Vehicles. - -It has the following features: - -* Strict order of message sending and consumption - -* Rich modes of message pulling - -* Horizontal scalability of consumers - -* Real-time message subscription - -* Billion-level message accumulation capability - -=== RocketMQ Usages - -* Download RocketMQ - -Download https://www.apache.org/dyn/closer.cgi?path=rocketmq/4.3.2/rocketmq-all-4.3.2-bin-release.zip[Latest Binary File of RocketMQ], and decompress it. - -The decompressed directory is as follows: - -``` -apache-rocketmq -├── LICENSE -├── NOTICE -├── README.md -├── benchmark -├── bin -├── conf -└── lib -``` - -* Start NameServer - -```bash -nohup sh bin/mqnamesrv & -tail -f ~/logs/rocketmqlogs/namesrv.log -``` - -* Start Broker - -```bash -nohup sh bin/mqbroker -n localhost:9876 & -tail -f ~/logs/rocketmqlogs/broker.log -``` - -* Send and Receive Messages - -Send messages: - -```bash -sh bin/tools.sh org.apache.rocketmq.example.quickstart.Producer -``` - -Output when the message is successfully sent: `SendResult [sendStatus=SEND_OK, msgId= ...` - -Receive messages: - -```bash -sh bin/tools.sh org.apache.rocketmq.example.quickstart.Consumer -``` - -Output when the message is successfully received： `ConsumeMessageThread_%d Receive New Messages: [MessageExt...` - -* Disable Server - -```bash -sh bin/mqshutdown broker -sh bin/mqshutdown namesrv -``` - -=== Introduction of Spring Cloud Stream - -Spring Cloud Stream is a microservice framework used to build architectures based on messages. It helps you to create production-ready single-server Spring applications based on SpringBoot, and connects with Broker using `Spring Integration`. - -Spring Cloud Stream provides unified abstractions of message middleware configurations, and puts forward concepts such as publish-subscribe, consumer groups and partition. - -There are two concepts in Spring Cloud Stream: Binder and Binding - -* Binder: A component used to integrate with external message middleware, and is used to create binding. Different message middleware products have their own binder implementations. - -For example, `Kafka` uses `KafkaMessageChannelBinder`, `RabbitMQ` uses `RabbitMessageChannelBinder`, while `RocketMQ` uses `RocketMQMessageChannelBinder`. - -* Binding: Includes Input Binding and Output Binding. - -Binding serves as a bridge between message middleware and the provider and consumer of the applications. Developers only need to use the Provider or Consumer to produce or consume data, and do not need to worry about the interactions with the message middleware. - -.Spring Cloud Stream -image::https://docs.spring.io/spring-cloud-stream/docs/current/reference/htmlsingle/images/SCSt-overview.png[] - -Now let’s use Spring Cloud Stream to write a simple code for sending and receiving messages: - -```java -MessageChannel messageChannel = new DirectChannel(); - -// Message subscription -((SubscribableChannel) messageChannel).subscribe(new MessageHandler() { - @Override - public void handleMessage(Message message) throws MessagingException { - System.out.println("receive msg: " + message.getPayload()); - } -}); - -// Message sending -messageChannel.send(MessageBuilder.withPayload("simple msg").build()); -``` - -All the message types in this code are provided by the `spring-messaging`module. It shields the lower-layer implementations of message middleware. If you would like to change the message middleware, you only need to configure the related message middleware information in the configuration file and modify the binder dependency. - -**The lower layer of Spring Cloud Stream also implements various code abstractions based on the previous code.** - -=== How to use Spring Cloud Alibaba RocketMQ Binder - -For using the Spring Cloud Alibaba RocketMQ Binder, you just need to add it to your Spring Cloud Stream application, using the following Maven coordinates: - -```xml - - com.alibaba.cloud - spring-cloud-stream-binder-rocketmq - -``` - -Alternatively, you can also use the Spring Cloud Stream RocketMQ Starter: - -```xml - - com.alibaba.cloud - spring-cloud-starter-stream-rocketmq - -``` - -=== How Spring Cloud Alibaba RocketMQ Binder Works - -This is the implementation architecture of Spring Cloud Stream RocketMQ Binder: - -.SCS RocketMQ Binder -image::https://img.alicdn.com/tfs/TB1v8rcbUY1gK0jSZFCXXcwqXXa-1236-773.png[] - -The implementation of RocketMQ Binder depend on the https://github.com/apache/rocketmq-spring[RocketMQ-Spring] framework. - -RocketMQ Spring framework is an integration of RocketMQ and Spring Boot. It provides three main features: - -1. `RocketMQTemplate`: Sending messages, including synchronous, asynchronous, and transactional messages. -2. `@RocketMQTransactionListener`: Listen and check for transaction messages. -3. `@RocketMQMessageListener`: Consume messages. - -`RocketMQMessageChannelBinder` is a standard implementation of Binder, it will build `RocketMQInboundChannelAdapter` and `RocketMQMessageHandler` internally. - -`RocketMQMessageHandler` will construct `RocketMQTemplate` based on the Binding configuration. `RocketMQTemplate` will convert the `org.springframework.messaging.Message` message class of `spring-messaging` module to the RocketMQ message class `org.apache.rocketmq.common .message.Message` internally, then send it out. - -`RocketMQInboundChannelAdapter` will also construct `RocketMQListenerBindingContainer` based on the Binding configuration, and `RocketMQListenerBindingContainer` will start the RocketMQ `Consumer` to receive the messages. - -NOTE: RocketMQ Binder Application can also be used to configure rocketmq.** to trigger RocketMQ Spring related AutoConfiguration - -Currently Binder supports setting the relevant key in `Header` to set the properties of the RocketMQ message. - -For example, `TAGS`, `DELAY`, `TRANSACTIONAL_ARG`, `KEYS`, `WAIT_STORE_MSG_OK`, `FLAG` represent the labels corresponding to the RocketMQ message. - -```java -MessageBuilder builder = MessageBuilder.withPayload(msg) - .setHeader(RocketMQHeaders.TAGS, "binder") - .setHeader(RocketMQHeaders.KEYS, "my-key") - .setHeader(MessageConst.PROPERTY_DELAY_TIME_LEVEL, "1"); -Message message = builder.build(); -output().send(message); -``` - -=== Support MessageSource - -SCS RocketMQ Binder support `MessageSource`，which can receive messages by pull mode： - -```java -@SpringBootApplication -@EnableBinding(MQApplication.PolledProcessor.class) -public class MQApplication { - - private final Logger logger = - LoggerFactory.getLogger(MQApplication.class); - - public static void main(String[] args) { - SpringApplication.run(MQApplication.class, args); - } - - @Bean - public ApplicationRunner runner(PollableMessageSource source, - MessageChannel dest) { - return args -> { - while (true) { - boolean result = source.poll(m -> { - String payload = (String) m.getPayload(); - logger.info("Received: " + payload); - dest.send(MessageBuilder.withPayload(payload.toUpperCase()) - .copyHeaders(m.getHeaders()) - .build()); - }, new ParameterizedTypeReference() { }); - if (result) { - logger.info("Processed a message"); - } - else { - logger.info("Nothing to do"); - } - Thread.sleep(5_000); - } - }; - } - - public static interface PolledProcessor { - - @Input - PollableMessageSource source(); - - @Output - MessageChannel dest(); - - } - -} -``` - -=== Configuration Options - -==== RocketMQ Binder Properties - -spring.cloud.stream.rocketmq.binder.name-server:: -The name server of RocketMQ Server(Older versions use the namesrv-addr configuration item). -+ -Default: `127.0.0.1:9876`. -spring.cloud.stream.rocketmq.binder.access-key:: -The AccessKey of Alibaba Cloud Account. -+ -Default: null. -spring.cloud.stream.rocketmq.binder.secret-key:: -The SecretKey of Alibaba Cloud Account. -+ -Default: null. -spring.cloud.stream.rocketmq.binder.enable-msg-trace:: -Enable Message Trace feature for all producers and consumers. -+ -Default: `true`. -spring.cloud.stream.rocketmq.binder.customized-trace-topic:: -The trace topic for message trace. -+ -Default: `RMQ_SYS_TRACE_TOPIC`. -+ -spring.cloud.stream.rocketmq.binder.access-channel:: -The commercial version of rocketmq message trajectory topic is adaptive,the value is CLOUD -+ -Default: null. - -==== RocketMQ Consumer Properties - -The following properties are available for RocketMQ producers only and must be prefixed with `spring.cloud.stream.rocketmq.bindings..consumer.`. - -enable:: -Enable Consumer Binding. -+ -Default: `true`. -tags:: -Consumer subscription tags expression, tags split by `||`. -+ -Default: empty. -sql:: -Consumer subscription sql expression. -+ -Default: empty. -broadcasting:: -Control message mode, if you want all subscribers receive message all message, broadcasting is a good choice. -+ -Default: `false`. -orderly:: -Receiving message concurrently or orderly. -+ -Default: `false`. -delayLevelWhenNextConsume:: -Message consume retry strategy for concurrently consume: -* -1,no retry,put into DLQ directly -* 0,broker control retry frequency -* >0,client control retry frequency -+ -Default: `0`. -suspendCurrentQueueTimeMillis:: -Time interval of message consume retry for orderly consume. -+ -Default: `1000`. - -==== RocketMQ Provider Properties - -The following properties are available for RocketMQ producers only and must be prefixed with `spring.cloud.stream.rocketmq.bindings..producer.`. - -enable:: -Enable Producer Binding. -+ -Default: `true`. -group:: -Producer group name. -+ -Default: empty. -maxMessageSize:: -Maximum allowed message size in bytes. -+ -Default: `8249344`. -transactional:: -Send Transactional Message. -+ -Default: `false`. -sync:: -Send message in synchronous mode. -+ -Default: `false`. -vipChannelEnabled:: -Send message with vip channel. -+ -Default: `true`. -sendMessageTimeout:: -Millis of send message timeout. -+ -Default: `3000`. -compressMessageBodyThreshold:: -Compress message body threshold, namely, message body larger than 4k will be compressed on default. -+ -Default: `4096`. -retryTimesWhenSendFailed:: -Maximum number of retry to perform internally before claiming sending failure in synchronous mode. -+ -Default: `2`. -retryTimesWhenSendAsyncFailed:: -Maximum number of retry to perform internally before claiming sending failure in asynchronous mode. -+ -Default: `2`. -retryNextServer:: -Indicate whether to retry another broker on sending failure internally. -+ -Default: `false`. \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/schedulerx.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/schedulerx.adoc deleted file mode 100644 index ea68fd8a9..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/schedulerx.adoc +++ /dev/null @@ -1,114 +0,0 @@ -== Spring Cloud Alibaba Cloud SchedulerX - -SchedulerX（Distributed job scheduling） is a component of EDAS, an Alibaba Cloud product. Spring Cloud Alibaba Cloud SchedulerX provides distributed job scheduling in conformity with the Spring Cloud specifications. SchedulerX provides timed job scheduling service with high accuracy with seconds, high stability and high availabiliy, and supports multiple job types, such as simple single-server jobs, simple multi-host jobs, script jobs, and grid jobs. - -=== How to Introduce Spring Cloud Alibaba Cloud SchedulerX - -If you want to use SchedulerX in your project, please use the starter with the group ID as `com.alibaba.cloud` and the artifact ID as `spring-cloud-starter-alicloud-schedulerX`. - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alicloud-schedulerX - ----- - -=== Start SchedulerX - -After Spring Cloud Alibaba Cloud SchedulerX Starter is introduced into the client, you only need to complete a few simple configurations and you will be able to initialize the SchedulerX service automatically. - -The following is a simple example. - -[source,java] ----- -@SpringBootApplication -public class ScxApplication { - - public static void main(String[] args) { - SpringApplication.run(ScxApplication.class, args); - } - -} ----- - -Add the following configurations in the application.properties file. - -[source,properties] ----- -server.port=18033 -# cn-test is the test region of SchedulerX -spring.cloud.alicloud.scx.group-id=*** -spring.cloud.alicloud.edas.namespace=cn-test ----- - -Before getting the group-id, please https://account.aliyun.com/register/register.htm?spm=5176.8142029.388261.26.e9396d3eEIv28g&oauth_callback=https%3A%2F%2Fwww.aliyun.com%2F[Register an Alibaba Cloud account], and then https://common-buy.aliyun.com/?spm=5176.11451019.0.0.6f5965c0Uq5tue&commodityCode=edaspostpay#/buy[Sign up for EDAS] and https://edas.console.aliyun.com/#/edasTools[Sign up for SchedulerX] as well. - -To get the group-id, refer to the https://help.aliyun.com/document_detail/98784.html[SchedulerX Documentation]. - -NOTE: When you create a group, please select the “test” region. - -=== Compile a simple job - -Simple job is the most commonly used job type. You only need to implement the ScxSimpleJobProcessor interface. - -The following is a sample of a simple single-server job. - -[source,java] ----- -public class SimpleTask implements ScxSimpleJobProcessor { - - @Override - public ProcessResult process(ScxSimpleJobContext context) { - System.out.println("-----------Hello world---------------"); - ProcessResult processResult = new ProcessResult(true); - return processResult; - } - -} ----- - -=== Job Scheduling - -Go to the https://edas.console.aliyun.com/#/edasSchedulerXJob?regionNo=cn-test[SchedulerX Jobs] page, select the “Test” region, and click “Create Job” on the upper-right corner to create a job, as shown below. - -[source,text] ----- -Job Group： Test——***-*-*-**** -Job process interface：SimpleTask -Type： Simple Single-Server Job -Quartz Cron Expression： Default Option——0 * * * * ? -Job Description： Empty -Custom Parameters： Empty ----- - -The job above is a “Simple Single-Server Job”, and specified a Cron expression of "0 * * * * ?" . This means that the job will be executed once and once only in every minute. - -For more job types, refer to https://help.aliyun.com/document_detail/43136.html[SchedulerX Documentation]. - -=== Usage in Production Environment - -The previous examples shows how to use SchedulerX in the “Test” region, which is mainly used for local testing. - -At the production level, you need to complete some other configurations in addition to the group-id and namespace as mentioned above. See examples below: - -[source,properties] ----- -server.port=18033 -# cn-test is the test region of SchedulerX -spring.cloud.alicloud.scx.group-id=*** -spring.cloud.alicloud.edas.namespace=*** -# If your application runs on EDAS, you do not need to configure the following. -spring.cloud.alicloud.access-key=*** -spring.cloud.alicloud.secret-key=*** -# The following configurations are not mandatory. You can refer to the SchedulerX documentation for details. -spring.cloud.alicloud.scx.domain-name=*** ----- - -The way to get the group-id is the same as described in the previous examples, and you can get the namespace by clicking “Namespaces” in the left-side navigation pane of the EDAS console. - -NOTE: Group-id must be created within a namespace. - -Access-key and secret-key are the AK/SK of your Alibaba Cloud account. If you deploy you applications on EDAS, then you do not need to fill in this information. Otherwise please go to https://usercenter.console.aliyun.com/#/manage/ak[Security Information] to get your AccessKeys. - -Domain-name is not mandatory. You can refer to https://help.aliyun.com/document_detail/35359.html[SchedulerX Documentation] for details. diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/seata.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/seata.adoc deleted file mode 100644 index d28a76d9e..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/seata.adoc +++ /dev/null @@ -1,87 +0,0 @@ -== Spring Cloud Alibaba Seata - -=== Introducing Seata - -Seata is a distributed transaction framework to ensure the data consistency of each service under the microservice architecture. - - -=== How to use seata - - -To include Seata in your project, use the starter with group ID `com.alibaba.cloud` and artifact ID `spring-cloud-starter-alibaba-seata`. - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alibaba-seata - ----- - -The project provides relevant https://github.com/alibaba/spring-cloud-alibaba/tree/2.2.x/spring-cloud-alibaba-examples/seata-example[Example], before running it, you need to complete the following steps: - -1. Ensure that `nacos-server` is running locally on the `8848` port. -2. Configuration database, will application in the resources directory of the `account-server`, `order-service`, `storage-service` three applications. The following configuration in the yml file is modified to the actual configuration in your running environment. - - base: - config: - mdb: - hostname: 127.0.0.1 #your mysql server ip address - dbname: seata #your database name for test - port: 3306 #your mysql server listening port - username: root #your mysql server username - password: root #your mysql server password - -3. Create the database tables, you can refer to `all.sql` under `spring-cloud-alibaba-examples/seata-example` for a quick operation. - - According to the selected transaction mode, create a https://github.com/seata/seata/tree/develop/script/client[transaction log table]. For example, the default is AT mode, then enter at/db and select the corresponding database script executes - - Create a https://github.com/seata/seata/tree/develop/script/server/db[status record table] related to seata transactions, including `global_table` , `branch_table` , `lock_table` , `distributed_lock`. - - Create the database tables required by `spring-cloud-alibaba-examples/seata-example` . -4. Create the Nacos configuration in `spring-cloud-alibaba-examples/seata-example` . - - data id: seata.properties, - Group: SEATA_ Group(Seata 1.5.1 default group) - - Configuration Content: - service.vgroupMapping.order-service-tx-group=default - service.vgroupMapping.account-service-tx-group=default - service.vgroupMapping.business-service-tx-group=default - service.vgroupMapping.storage-service-tx-group=default - -5. Start Seata Server This describes SpringBoot and download server in two ways. - - Run seata-server from `spring-cloud-alibaba-examples/seata-example` to start Seata server. - - Run https://seata.io/zh-cn/docs/ops/deploy-guide-beginner.html[seata-server.jar] provided by official website to start Seata server. -6. Start the sub-services under the `spring-cloud-alibaba-examples/seata-example` including `account-service` , `order-service` , `storage-service` , and finally start the global transaction control service `business-service`。 -7. After launching the example, the following URLs are accessed through the GET method of HTTP to validate scenarios where other services are invoked through RestTemplate and FeignClient in `business-service` respectively. - - http://127.0.0.1:18081/seata/feign - http://127.0.0.1:18081/seata/rest - -=== Seata Dashboard - -- Seata 1.5.1 supports Seata console local access console address: `http://127.0.0.1:7091`。 -- Through the Seata console, you can observe the executing transaction information and global lock information, and delete the relevant information when the transaction is completed. - - -=== How do I verify the success of a distributed transaction? -==== Whether Xid information was successfully transmitted - -In the Controller of the three services `account-server`, `order-service` and `storage-service`, the first logic executed is to output the Xid information in the RootContext. If you see that the correct Xid information is output, it changes every time and the Xid of all services in the same call is consistent. This indicates that the transfer and restore of Seata's Xid are normal. - -==== Consistency of data in database - -In this example, we simulate a scenario where a user purchases goods, StorageService is responsible for deducting the inventory quantity, OrderService is responsible for saving the order, and AccountService is responsible for deducting the user account balance. - -To demonstrate the sample, we used Random in OrderService and AcountService. NextBoolean () randomly throws exceptions, simulating a scenario in which exceptions occur randomly when a service is invoked. - -If the distributed transaction is valid, then the following equation should be true - -- User Original Amount (1000) = User Existing Amount + Goods Unit Price (2) * Order Quantity * Goods Quantity per Order (2) -- Initial Quantity of Goods (100) = Existing Quantity of Goods + Order Quantity * Quantity of Goods per Order (2) - -=== Support points for Spring Cloud - -- Service providers that provide services through Spring MVC can automatically restore the Seata context when they receive HTTP requests with Seata information in the header. -- Support for automatic delivery of Seata context when service callers invoke through RestTemplate. -- Supports automatic delivery of the Seata context when a service caller invokes through a FeignClient. -- Supports scenarios where both SeataClient and Hystrix are used. -- Supports scenarios used by both SeataClient and Sentinel. \ No newline at end of file diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/sentinel.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/sentinel.adoc deleted file mode 100644 index e0a5622a1..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/sentinel.adoc +++ /dev/null @@ -1,452 +0,0 @@ -== Spring Cloud Alibaba Sentinel - -=== Introduction of Sentinel - -As microservices become popular, the stability of service calls is becoming increasingly important. https://github.com/alibaba/Sentinel[Sentinel] takes "flow" as the breakthrough point, and works on multiple fields including flow control, circuit breaking and load protection to protect service reliability. - -https://github.com/alibaba/Sentinel[Sentinel] has the following features: - - -* *Rich Scenarios*： Sentinel has supported the key scenarios of Alibaba’s Double 11 Shopping Festivals for over 10 years, such as second kill(i.e., controlling sudden bursts of traffic flow so that it’s within the acceptable range of the system capacity), message load shifting, circuit breaking of unreliable downstream applications. -* *Comprehensive Real-Time Monitoring*： Sentinel provides real-time monitoring capability. You can see the monitoring data of your servers at the accuracy of seconds, and even the overall runtime status of a cluster with less than 500 nodes. -* *Extensive Open-Source Ecosystem*： Sentinel provides out-of-box modules that can be easily integrated with other open-source frameworks/libraries, such as Spring Cloud, Dubbo, and gRPC. To use Sentinel, you only need to introduce the related dependency and make a few simple configurations. -* *Sound SPI Extensions*： Sentinel provides easy-to-use and sound SPI extension interfaces. You can customize logics with the SPI extensions quickly, for example, you can define your own rule management, or adapt to specific data sources. - -=== How to Use Sentinel - -If you want to use Sentinel in your project, please use the starter with the group ID as `com.alibaba.cloud` and the artifact ID as `spring-cloud-starter-alibaba-sentinel`. - -```xml - - com.alibaba.cloud - spring-cloud-starter-alibaba-sentinel - -``` - -The following is a simple example of how to use Sentinel: - -```java -@SpringBootApplication -public class Application { - - public static void main(String[] args) { - SpringApplication.run(ServiceApplication.class, args); - } - -} - -@RestController -public class TestController { - - @GetMapping(value = "/hello") - @SentinelResource("hello") - public String hello() { - return "Hello Sentinel"; - } - -} -``` - -The @SentinelResource annotation is used to identify if a resource is rate limited or degraded. In the above sample, the 'hello' attribute of the annotation refers to the resource name. - -@SentinelResource also provides attributes such as `blockHandler`, `blockHandlerClass`, and `fallback` to identify rate limiting or degradation operations. For more details, refer to https://github.com/alibaba/Sentinel/wiki/%E6%B3%A8%E8%A7%A3%E6%94%AF%E6%8C%81[Sentinel Annotation Support]. - -The above examples are all used in the WebServlet environment. Sentinel currently supports WebFlux and needs to cooperate with the `spring-boot-starter-webflux` dependency to trigger the WebFlux-related automation configuration in sentinel starter. - -```java -@SpringBootApplication -public class Application { - - public static void main(String[] args) { - SpringApplication.run(ServiceApplication.class, args); - } - -} - -@RestController -public class TestController { - - @GetMapping("/mono") - @SentinelResource("hello") - public Mono mono() { - return Mono.just("simple string") - .transform(new SentinelReactorTransformer<>("otherResourceName")); - } - -} -``` - -===== Sentinel Dashboard - -Sentinel dashboard is a lightweight console that provides functions such as machine discovery, single-server resource monitoring, overview of cluster resource data, as well as rule management. To use these features, you only need to complete a few steps. - -*Note*: The statistics overview for clusters only supports clusters with less than 500 nodes, and has a latency of about 1 to 2 seconds. - -.Sentinel Dashboard -image::https://github.com/alibaba/Sentinel/wiki/image/dashboard.png[] - -To use the Sentinel dashboard, simply complete the following 3 steps. - -====== Get the Dashboard - -You can download the latest dashboard JAR file from the https://github.com/alibaba/Sentinel/releases[Release Page]. - -You can also get the latest source code to build your own Sentinel dashboard： - -* Download the https://github.com/alibaba/Sentinel/tree/master/sentinel-dashboard[Dashboard] project. -* Run the following command to package the code into a FatJar: `mvn clean package` - - -====== Start the Dashboard - -Sentinel dashboard is a standard SpringBoot application, and you can run the JAR file in the Spring Boot mode. - -```shell -java -Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080 -Dproject.name=sentinel-dashboard -jar sentinel-dashboard.jar -``` - -If there is conflict with the 8080 port, you can use `-Dserver.port=new port` to define a new port. - -==== Configure the Dashboard - -.application.yml -[source,yaml] ----- -spring: - cloud: - sentinel: - transport: - port: 8719 - dashboard: localhost:8080 ----- - -The port number specified in `spring.cloud.sentinel.transport.port` will start an HTTP Server on the corresponding server of the application, and this server will interact with the Sentinel dashboard. For example, if a rate limiting rule is added in the Sentinel dashboard, the the rule data will be pushed to and recieved by the HTTP Server, which in turn registers the rule to Sentinel. - -For more information about Sentinel dashboard, please refer to https://github.com/alibaba/Sentinel/wiki/%E6%8E%A7%E5%88%B6%E5%8F%B0[Sentinel Dashboard]. - -=== OpenFeign Support - -Sentinel is compatible with the https://github.com/OpenFeign/feign[OpenFeign] component. To use it, in addition to introducing the `sentinel-starter` dependency, complete the following 2 steps: - -* Enable the Sentinel support for feign in the properties file. `feign.sentinel.enabled=true` -* Add the `openfeign starter` dependency to trigger and enable `sentinel starter`: -```xml - - org.springframework.cloud - spring-cloud-starter-openfeign - -``` - -This is a simple usage of `FeignClient`: - -```java -@FeignClient(name = "service-provider", fallback = EchoServiceFallback.class, configuration = FeignConfiguration.class) -public interface EchoService { - @GetMapping(value = "/echo/{str}") - String echo(@PathVariable("str") String str); -} - -class FeignConfiguration { - @Bean - public EchoServiceFallback echoServiceFallback() { - return new EchoServiceFallback(); - } -} - -class EchoServiceFallback implements EchoService { - @Override - public String echo(@PathVariable("str") String str) { - return "echo fallback"; - } -} -``` - -NOTE: The resource name policy in the corresponding interface of Feign is：httpmethod:protocol://requesturl. All the attributes in the `@FeignClient` annotation is supported by Sentinel. - -The corresponding resource name of the `echo` method in the `EchoService` interface is `GET:http://service-provider/echo/{str}`. - -=== RestTemplate Support - -Spring Cloud Alibaba Sentinel supports the protection of `RestTemplate` service calls using Sentinel. To do this, you need to add the `@SentinelRestTemplate` annotation when constructing the `RestTemplate` bean. - -```java -@Bean -@SentinelRestTemplate(blockHandler = "handleException", blockHandlerClass = ExceptionUtil.class) -public RestTemplate restTemplate() { - return new RestTemplate(); -} -``` - -The attribute of the `@SentinelRestTemplate` annotation support flow control(`blockHandler`, `blockHandlerClass`) and circuit breaking(`fallback`, `fallbackClass`). - -== - -The `blockHandler` or `fallback` is the static method of `blockHandlerClass` or `fallbackClass`. - -The parameter and return value of method in `@SentinelRestTemplate` is same as `org.springframework.http.client.ClientHttpRequestInterceptor#interceptor`, but it has one more parameter `BlockException` to catch the exception by Sentinel. - -The method signature of `handleException` in `ExceptionUtil` above should be like this: - -```java -public class ExceptionUtil { - public static ClientHttpResponse handleException(HttpRequest request, byte[] body, ClientHttpRequestExecution execution, BlockException exception) { - ... - } -} -``` - -NOTE: When the application starts, it will check if the `@SentinelRestTemplate` annotation corresponding to the flow control or circuit breaking method exists, if it does not exist, it will throw an exception. - -The attribute of the `@SentinelRestTemplate` annotation is optional. - -It will return `RestTemplate request block by sentinel` when you using `RestTemplate` blocked by Sentinel. You can override it by your own logic. We provide `SentinelClientHttpResponse` to handle the response. - -Sentinel RestTemplate provides two granularities for resource rate limiting: - -* `httpmethod:schema://host:port/path`： Protocol, host, port and path - -* `httpmethod:schema://host:port`： Protocol, host and port - -NOTE: Take Http GET `https://www.taobao.com/test` as an example. The corresponding resource names have two levels of granularities, `GET:https://www.taobao.com` and `GET:https://www.taobao.com/test`. - -=== Dynamic Data Source Support - -`SentinelProperties` provide `datasource` attribute to configure datasource. - -For example, 4 data sources are configures： - -[source,properties] ----- -spring.cloud.sentinel.datasource.ds1.file.file=classpath: degraderule.json -spring.cloud.sentinel.datasource.ds1.file.rule-type=flow - -#spring.cloud.sentinel.datasource.ds1.file.file=classpath: flowrule.json -#spring.cloud.sentinel.datasource.ds1.file.data-type=custom -#spring.cloud.sentinel.datasource.ds1.file.converter-class=JsonFlowRuleListConverter -#spring.cloud.sentinel.datasource.ds1.file.rule-type=flow - -spring.cloud.sentinel.datasource.ds2.nacos.server-addr=localhost:8848 -spring.cloud.sentinel.datasource.ds2.nacos.data-id=sentinel -spring.cloud.sentinel.datasource.ds2.nacos.group-id=DEFAULT_GROUP -spring.cloud.sentinel.datasource.ds2.nacos.data-type=json -spring.cloud.sentinel.datasource.ds2.nacos.rule-type=degrade - -spring.cloud.sentinel.datasource.ds3.zk.path = /Sentinel-Demo/SYSTEM-CODE-DEMO-FLOW -spring.cloud.sentinel.datasource.ds3.zk.server-addr = localhost:2181 -spring.cloud.sentinel.datasource.ds3.zk.rule-type=authority - -spring.cloud.sentinel.datasource.ds4.apollo.namespace-name = application -spring.cloud.sentinel.datasource.ds4.apollo.flow-rules-key = sentinel -spring.cloud.sentinel.datasource.ds4.apollo.default-flow-rule-value = test -spring.cloud.sentinel.datasource.ds4.apollo.rule-type=param-flow ----- - -This method follows the configuration of Spring Cloud Stream Binder. `TreeMap` is used for storage internally, and comparator is `String.CASE_INSENSITIVE_ORDER`. - -NOTE: d1, ds2, ds3, ds4 are the names of `ReadableDataSource`, and can be coded as you like. The `file`, `zk`, `nacos` , `apollo` refer to the specific data sources. The configurations following them are the specific configurations of these data sources respecitively. - -Every data source has 3 common configuration items: `data-type`, `converter-class` and `rule-type`. - -`data-type` refers to `Converter`. Spring Cloud Alibaba Sentinel provides two embedded values by default: `json` and `xml` (the default is json if not specified). If you do not want to use the embedded `json` or `xml` `Converter`, you can also fill in `custom` to indicate that you will define your own `Converter`, and then configure the `converter-class`. You need to specify the full path of the class for this configuration. - -`rule-type` refers to the rule type in datasource(`flow`，`degrade`，`authority`，`system`, `param-flow`, `gw-flow`, `gw-api-group`). - -NOTE: XML format is not supported by default. To make it effective, you need to add the `jackson-dataformat-xml` dependency. - -To learn more about how dynamic data sources work in Sentinel, refer to https://github.com/alibaba/Sentinel/wiki/%E5%8A%A8%E6%80%81%E8%A7%84%E5%88%99%E6%89%A9%E5%B1%95[Dynamic Rule Extension]. - -=== Support Zuul - -Refer https://github.com/alibaba/Sentinel/wiki/API-Gateway-Flow-Control[API Gateway Flow Control] - -If you want to use Sentinel Starter with Zuul, you need to add the `spring-cloud-alibaba-sentinel-gateway` dependency, and you need to add the `spring-cloud-starter-netflix-zuul` dependency to let Zuul AutoConfiguration class in the gateway module takes effect: - -```xml - - com.alibaba.cloud - spring-cloud-starter-alibaba-sentinel - - - - com.alibaba.cloud - spring-cloud-alibaba-sentinel-gateway - - - - org.springframework.cloud - spring-cloud-starter-netflix-zuul - -``` - -=== Support Spring Cloud Gateway - -Refer https://github.com/alibaba/Sentinel/wiki/API-Gateway-Flow-Control[API Gateway Flow Control] - -If you want to use Sentinel Starter with Spring Cloud Gateway, you need to add the `spring-cloud-alibaba-sentinel-gateway` dependency and add the `spring-cloud-starter-gateway` dependency to let Spring Cloud Gateway AutoConfiguration class in the module takes effect: - -```xml - - com.alibaba.cloud - spring-cloud-starter-alibaba-sentinel - - - - com.alibaba.cloud - spring-cloud-alibaba-sentinel-gateway - - - - org.springframework.cloud - spring-cloud-starter-gateway - -``` - -include::circuitbreaker-sentinel.adoc[] - -=== Sentinel Endpoint - -Sentinel provides an Endpoint internally with a corresponding endpoint id of `sentinel`. - -Endpoint exposed json contains multi properties: - -1. appName: application name -2. logDir: the directory of log -3. logUsePid: log name with pid ot not -4. blockPage: redirect page after sentinel block -5. metricsFileSize: the size of metrics file -6. metricsFileCharset: metrics file charset -7. totalMetricsFileCount: the total file count of of metrics file -8. consoleServer: sentinel dashboard address -9. clientIp: client ip -10. heartbeatIntervalMs: client heartbeat interval with dashboard -11. clientPort: the client needs to expose the port to interact with the dashboard -12. coldFactor: cold factor -13. filter: CommonFilter related properties, such as order, urlPatterns and enable -14. datasource: datasource configuration info by client -15. rules: the rule that the client takes effect internally contains flowRules, degradeRules, systemRules, authorityRule, paramFlowRule - -The followings shows how a service instance accesses the Endpoint: - -[source,json,indent=0] ----- -{ - "blockPage": null, - "appName": "sentinel-example", - "consoleServer": "localhost:8080", - "coldFactor": "3", - "rules": { - "flowRules": [{ - "resource": "GET:http://www.taobao.com", - "limitApp": "default", - "grade": 1, - "count": 0.0, - "strategy": 0, - "refResource": null, - "controlBehavior": 0, - "warmUpPeriodSec": 10, - "maxQueueingTimeMs": 500, - "clusterMode": false, - "clusterConfig": null - }, { - "resource": "/test", - "limitApp": "default", - "grade": 1, - "count": 0.0, - "strategy": 0, - "refResource": null, - "controlBehavior": 0, - "warmUpPeriodSec": 10, - "maxQueueingTimeMs": 500, - "clusterMode": false, - "clusterConfig": null - }, { - "resource": "/hello", - "limitApp": "default", - "grade": 1, - "count": 1.0, - "strategy": 0, - "refResource": null, - "controlBehavior": 0, - "warmUpPeriodSec": 10, - "maxQueueingTimeMs": 500, - "clusterMode": false, - "clusterConfig": null - }] - }, - "metricsFileCharset": "UTF-8", - "filter": { - "order": -2147483648, - "urlPatterns": ["/*"], - "enabled": true - }, - "totalMetricsFileCount": 6, - "datasource": { - "ds1": { - "file": { - "dataType": "json", - "ruleType": "FLOW", - "converterClass": null, - "file": "...", - "charset": "utf-8", - "recommendRefreshMs": 3000, - "bufSize": 1048576 - }, - "nacos": null, - "zk": null, - "apollo": null, - "redis": null - } - }, - "clientIp": "30.5.121.91", - "clientPort": "8719", - "logUsePid": false, - "metricsFileSize": 52428800, - "logDir": "...", - "heartbeatIntervalMs": 10000 -} ----- - -=== Configuration - -The following table shows that when there are corresponding bean types in `ApplicationContext`, some actions will be taken: - -|=== -|Existing Bean Type |Action |Function -|`UrlCleaner`|`WebCallbackManager.setUrlCleaner(urlCleaner)`|Resource cleaning(resource(for example, classify all URLs of /foo/:id to the /foo/* resource)) -|`UrlBlockHandler`|`WebCallbackManager.setUrlBlockHandler(urlBlockHandler)`|Customize rate limiting logic -|`RequestOriginParser`|`WebCallbackManager.setRequestOriginParser(requestOriginParser)`|Setting the origin -|=== - -The following table shows all the configurations of Spring Cloud Alibaba Sentinel: - -|=== -|Configuration |Description |Default Value -|`spring.application.name` or `project.name`|Project Name Of Sentinel| -|`spring.cloud.sentinel.enabled`|Whether Sentinel automatic configuration takes effect|true -|`spring.cloud.sentinel.eager`|Whether to trigger Sentinel initialization in advance|false -|`spring.cloud.sentinel.transport.port`|Port for the application to interact with Sentinel dashboard. An HTTP Server which uses this port will be started in the application|8719 -|`spring.cloud.sentinel.transport.dashboard`|Sentinel dashboard address| -|`spring.cloud.sentinel.transport.heartbeatIntervalMs`|Hearbeat interval between the application and Sentinel dashboard| -|`spring.cloud.sentinel.transport.client-ip`|The client IP of this configuration will be registered to the Sentinel Server side.| -|`spring.cloud.sentinel.filter.order`|Loading order of Servlet Filter. The filter will be constructed in the Starter|Integer.MIN_VALUE -|`spring.cloud.sentinel.filter.url-patterns`|Data type is array. Refers to the collection of Servlet Filter ULR patterns|/* -|`spring.cloud.sentinel.filter.enabled`|Enable to instance CommonFilter|true -|`spring.cloud.sentinel.metric.charset`|metric file character set|UTF-8 -|`spring.cloud.sentinel.metric.fileSingleSize`|Sentinel metric single file size| -|`spring.cloud.sentinel.metric.fileTotalCount`|Sentinel metric total file number| -|`spring.cloud.sentinel.log.dir`|Directory of Sentinel log files| -|`spring.cloud.sentinel.log.switch-pid`|If PID is required for Sentinel log file names|false -|`spring.cloud.sentinel.servlet.blockPage`| Customized redirection URL. When rate limited, the request will be redirected to the pre-defined URL | -|`spring.cloud.sentinel.flow.coldFactor`| https://github.com/alibaba/Sentinel/wiki/%E9%99%90%E6%B5%81---%E5%86%B7%E5%90%AF%E5%8A%A8[ColdFactor] |3 -|`spring.cloud.sentinel.zuul.order.pre`| The order of SentinelZuulPreFilter | 10000 -|`spring.cloud.sentinel.zuul.order.post`| The order of SentinelZuulPostFilter | 1000 -|`spring.cloud.sentinel.zuul.order.error`| The order of SentinelZuulErrorFilter | -1 -|`spring.cloud.sentinel.scg.fallback.mode`| Response mode after Spring Cloud Gateway circuit break (select `redirect` or `response`) | -|`spring.cloud.sentinel.scg.fallback.redirect`| Spring Cloud Gateway response mode is the redirect URL corresponding to 'redirect' mode | -|`spring.cloud.sentinel.scg.fallback.response-body`| Spring Cloud Gateway response mode is response content corresponding to 'response' mode | -|`spring.cloud.sentinel.scg.fallback.response-status`| Spring Cloud Gateway response mode is the response code corresponding to 'response' mode | 429 -|`spring.cloud.sentinel.scg.fallback.content-type`| The Spring Cloud Gateway response mode is the content-type corresponding to the 'response' mode. | application/json -|=== - - -NOTE: These configurations will only take effect in servlet environment. RestTemplate and Feign will not take effect for these configurations. diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/sms.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/sms.adoc deleted file mode 100644 index f6308fb03..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/sms.adoc +++ /dev/null @@ -1,210 +0,0 @@ -== Spring Cloud Alibaba Cloud SMS - -SMS（Short Message Service）is a messaging service that covers the globe, Alibaba SMS provides convenient, efficient, and intelligent communication capabilities that help businesses quickly contact their customers. - -Spring Cloud Alibaba Cloud SMS provide an easier-to-use API for quick access to Alibaba Cloud's SMS service based on Spring Cloud Alibaba SMS. - -=== How to Introduce Spring Cloud Alibaba Cloud SMS - -If you want to use SMS in your project, please use the starter with the group ID as `com.alibaba.cloud` and the artifact ID as `spring-cloud-starter-alicloud-sms`. - -[source,xml] ----- - - com.alibaba.cloud - spring-cloud-starter-alicloud-sms - ----- - -=== How to use SMS API - -==== Configure SMS - -Before you start to use Spring Cloud Alibaba Cloud SMS, please add the following configurations in application.properties. - -[source,properties] ----- -spring.cloud.alicloud.access-key=AK -spring.cloud.alicloud.secret-key=SK ----- - -access-key and secret-key is the AK/SK of your Alibaba Cloud account. If you don’t have one, please register an account first, and log on to https://usercenter.console.aliyun.com/#/manage/ak[Alibaba Cloud AK/SK Management] to get your AccessKey ID and Access Key Secret . If you haven’t create the AccessKeys, click “Create AccessKey” to create one. - -==== Introduce SMS API - -The SMS API in Spring Cloud Alicloud SMS is based on Alibaba Cloud SMS SDK. It has a single SMS sending, multiple SMS bulk sending, SMS query, SMS message (SMS receipt message and Upstream SMS message) class operation API. - -The following is a simple example of how to use SMS api to send short message: - -[source,java] ----- -@SpringBootApplication -public class SmsApplication { - - @Autowired - private ISmsService smsService; - - @RequestMapping("/batch-sms-send.do") - public SendBatchSmsResponse batchsendCheckCode( - @RequestParam(name = "code") String code) { - - SendSmsRequest request = new SendSmsRequest(); - // Required:the mobile number - request.setPhoneNumbers("152******"); - // Required:SMS-SignName-could be found in sms console - request.setSignName("******"); - // Required:Template-could be found in sms console - request.setTemplateCode("******"); - // Required:The param of sms template.For exmaple, if the template is "Hello,your verification code is ${code}". The param should be like following value - request.setTemplateParam("{\"code\":\"" + code + "\"}"); - SendSmsResponse sendSmsResponse ; - try { - sendSmsResponse = smsService.sendSmsRequest(request); - } - catch (ClientException e) { - e.printStackTrace(); - sendSmsResponse = new SendSmsResponse(); - } - return sendSmsResponse ; - } - - public static void main(String[] args) throws URISyntaxException { - SpringApplication.run(SmsApplication.class, args); - } - -} ----- - -Before you send your messages, please https://account.aliyun.com/register/register.htm?spm=5176.8142029.388261.26.e9396d3eaYK2sG&oauth_callback=https%3A%2F%2Fwww.aliyun.com%2F[Register an Alibaba Cloud Account]. If you already have one, please https://dysms.console.aliyun.com/dysms.htm?spm=5176.8195934.1283918..18924183bHPct2&accounttraceid=c8cb4243-3080-4eb1-96b0-1f2316584269#/[Turn on SMS Service]. - -For more information about SMS , please refer to the SMS official https://help.aliyun.com/document_detail/55284.html?spm=a2c4g.11186623.6.568.715e4f30ZiVkbI[SMS] (SendSms)---JAVA] docs . - -NOTE: Due to an issue with the earlier SMS sdk version, if the text message fails to be sent, please delete the line of code that contains the explicit MethodType as POST. If you still have problems, please contact us as soon as possible. - -=== The Advanced Features of SMS Api - -In order to reduce the cost of learning, the API interface of the Spring Cloud Alicloud SMS package is kept as consistent as the API and Example provided by the official website. - -* Batch SMS sending - -Refer to the following example to quickly develop a feature with bulk SMS sending. Add the following code in the Controller or create a new Controller: - -[source,java] ----- -@RequestMapping("/batch-sms-send.do") -public SendBatchSmsResponse batchsendCheckCode( - @RequestParam(name = "code") String code) { - SendBatchSmsRequest request = new SendBatchSmsRequest(); - request.setMethod(MethodType.GET); - request.setPhoneNumberJson("[\"177********\",\"130********\"]"); - request.setSignNameJson("[\"*******\",\"*******\"]"); - request.setTemplateCode("******"); - request.setTemplateParamJson( - "[{\"code\":\"" + code + "\"},{\"code\":\"" + code + "\"}]"); - SendBatchSmsResponse sendSmsResponse ; - try { - sendSmsResponse = smsService - .sendSmsBatchRequest(request); - return sendSmsResponse; - } - catch (ClientException e) { - e.printStackTrace(); - sendSmsResponse = new SendBatchSmsResponse(); - } - return sendSmsResponse ; -} ----- - -NOTE: The MethodType of the request is set to GET, which is somewhat different from the example given by the official website. This is because the inconsistent version of the dependent Alibaba Cloud POP API version causes incompatibility issues, set to GET. - -More parameter descriptions can be https://help.aliyun.com/document_detail/66041.html?spm=a2c4g.11186623.6.571.631315e8AauJhP[reference here] - -* SMS Query - -Refer to the following example to quickly develop a history of sending SMS messages based on a specified number. Add the following code in the Controller or create a new Controller: - -[source,java] ----- -@RequestMapping("/query.do") -public QuerySendDetailsResponse querySendDetailsResponse( - @RequestParam(name = "tel") String telephone) { - QuerySendDetailsRequest request = new QuerySendDetailsRequest(); - request.setPhoneNumber(telephone); - request.setSendDate("20190103"); - request.setPageSize(10L); - request.setCurrentPage(1L); - try { - QuerySendDetailsResponse response = smsService.querySendDetails(request); - return response; - } - catch (ClientException e) { - e.printStackTrace(); - } - - return new QuerySendDetailsResponse(); -} - ----- - -More parameter descriptions can be found at https://help.aliyun.com/document_detail/55289.html?spm=a2c4g.11186623.6.569.4f852c78mugEfx[reference here] - -* SMS receipt message - -By subscribing to the SmsReport SMS status report, you can know the status of each SMS message and whether it knows the status and related information of the terminal user. These efforts have been encapsulated internally by Spring Cloud AliCloud SMS. You only need to complete the following two steps. - -1、Configure the queue name for SmsReport in the `application.properties` configuration file (which can also be application.yaml). - -.application.properties ----- -spring.cloud.alicloud.sms.report-queue-name=Alicom-Queue-********-SmsReport ----- - -2、Implement the SmsReportMessageListener interface and initialize a Spring Bean. - -[source,java] ----- -@Component -public class SmsReportMessageListener - implements SmsReportMessageListener { - - @Override - public boolean dealMessage(Message message) { - //do something - System.err.println(this.getClass().getName() + "; " + message.toString()); - return true; - } -} ----- - -More message body format for Message can be https://help.aliyun.com/document_detail/55496.html?spm=a2c4g.11186623.6.570.7f792c78rOiWXO[reference here]. - -* Upstream SMS message - -By subscribing to the SmsUp upstream SMS message, you can know the content of the end user replying to the SMS. These efforts have also been packaged by Spring Cloud AliCloud SMS. You only need to complete the following two steps. - -1、Configure the queue name for SmsReport in the `application.properties` configuration file (which can also be application.yaml). - -.application.properties -[source,properties] ----- -spring.cloud.alicloud.sms.up-queue-name=Alicom-Queue-********-SmsUp ----- - -2、Implement the SmsUpMessageListener interface and initialize a Spring Bean. - -[source,java] ----- -@Component -public class SmsUpMessageListener - implements org.springframework.cloud.alicloud.sms.SmsUpMessageListener { - - @Override - public boolean dealMessage(Message message) { - //do something - System.err.println(this.getClass().getName() + "; " + message.toString()); - return true; - } -} ----- - -More message body format for Message can be https://help.aliyun.com/document_detail/55496.html?spm=a2c4g.11186623.6.570.7f792c78rOiWXO[reference here]. diff --git a/spring-cloud-alibaba-docs/src/main/asciidoc/spring-cloud-alibaba.adoc b/spring-cloud-alibaba-docs/src/main/asciidoc/spring-cloud-alibaba.adoc deleted file mode 100644 index 84c7a0a3a..000000000 --- a/spring-cloud-alibaba-docs/src/main/asciidoc/spring-cloud-alibaba.adoc +++ /dev/null @@ -1,34 +0,0 @@ -[[spring-cloud-alibaba-reference]] -= Spring Cloud Alibaba Reference Documentation -Jim Fang, Jing Xiao, Mercy Ma, Xiaolong Zuo, Bingting Peng, Yuxin Wang -:doctype: book -:toc: -:toclevels: 4 -:source-highlighter: prettify -:numbered: - -include::introduction.adoc[] - -include::dependency-management.adoc[] - -include::nacos-discovery.adoc[] - -include::nacos-config.adoc[] - -include::sentinel.adoc[] - -include::rocketmq.adoc[] - -include::ans.adoc[] - -include::acm.adoc[] - -include::oss.adoc[] - -include::schedulerx.adoc[] - -include::sms.adoc[] - -include::appactive.adoc[] - -include::governance.adoc[] \ No newline at end of file