You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by li...@apache.org on 2021/02/01 02:39:21 UTC
[servicecomb-docs] branch master updated: governance docs
improvement and some other bug fixes (#220)
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-docs.git
The following commit(s) were added to refs/heads/master by this push:
new bd7d4b9 governance docs improvement and some other bug fixes (#220)
bd7d4b9 is described below
commit bd7d4b9abf9f609ddfeb26a0a6009612b435f8a1
Author: bao liu <bi...@qq.com>
AuthorDate: Mon Feb 1 10:39:14 2021 +0800
governance docs improvement and some other bug fixes (#220)
---
.../zh_CN/docs/build-provider/springmvc.md | 2 +-
.../zh_CN/docs/build-provider/transparent-rpc.md | 4 +
.../docs/featured-topics/upgrading/2_1_1T2_1_5.md | 41 +++++++-
.../zh_CN/docs/references-handlers/governance.md | 107 ++++++++++++++++++++-
4 files changed, 147 insertions(+), 7 deletions(-)
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md b/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md
index a236afa..0416194 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md
@@ -4,7 +4,7 @@ Spring MVC 是 spring-web 项目定义的一套注解，开发者可以使用这
支持使用这套标签定义 REST 接口。需要注意的是，servicecomb 只是使用这些注解，而注解的实现是项目自行开发的，
实现的功能集合是 Spring MVC 注解的子集。可以阅读文章后面的内容了解具体的标签集合和使用约束。
-[SpringMVC Sample](spring-mvc-sample) 提供了一些基础的代码示例，可以下载使用。
+[SpringMVC Sample][spring-mvc-sample] 提供了一些基础的代码示例，可以下载使用。
[spring-mvc-sample]: https://github.com/apache/servicecomb-samples/tree/master/java-chassis-samples/springmvc-sample
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/transparent-rpc.md b/java-chassis-reference/zh_CN/docs/build-provider/transparent-rpc.md
index ac378f7..0e1456e 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/transparent-rpc.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/transparent-rpc.md
@@ -4,6 +4,10 @@
透明RPC开发模式是一种基于接口和接口实现的开发模式，服务的开发者不需要使用Spring MVC和JAX-RS注解。
+[透明RPC例子][pojo-sample] 提供了一些基础的代码示例，可以下载使用。
+
+[pojo-sample]: https://github.com/apache/servicecomb-samples/tree/master/java-chassis-samples/pojo-sample
+
## 开发示例
透明RPC开发模式支持Spring xml配置和注解配置两种服务发布方式，通过Spring xml配置的方式如下：
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_1_1T2_1_5.md b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_1_1T2_1_5.md
index 65e6601..0b63348 100644
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_1_1T2_1_5.md
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_1_1T2_1_5.md
@@ -16,7 +16,46 @@
## `foudation-common` 调整
-这个模块提供了将时间类型数据格式化的功能。在2.1.5版本中，升级了jackson-bom版本从2.10.5到2.12.0，导致时间数据类型格式化结果
+这个模块提供了将时间类型数据格式化的功能。在2.1.5版本中，升级了jackson-bom版本从2.10.5到2.12.1，导致时间数据类型格式化结果
产生了变更。例如：升级前格式化时间为`2017-07-21T17:32:28.000+0000`，升级后为`2017-07-21T17:32:28.000+00:00`。如果产品
使用了该类型数据，需要考虑升级后数据类型的变更，对原有业务逻辑的影响。
+## `servicestage-environment` 调整
+
+这个模块只有一个 `mapping.xml` 文件，提供环境变量映射。原来的内容为：
+
+```yaml
+PAAS_CSE_ENDPOINT:
+ - servicecomb.service.registry.address
+ - servicecomb.config.client.serverUri
+PAAS_CSE_SC_ENDPOINT:
+ - servicecomb.service.registry.address
+PAAS_CSE_CC_ENDPOINT:
+ - servicecomb.config.client.serverUri
+PAAS_PROJECT_NAME:
+ - servicecomb.credentials.project
+
+CAS_APPLICATION_NAME:
+ - servicecomb.service.application
+CAS_COMPONENT_NAME:
+ - servicecomb.service.name
+CAS_INSTANCE_VERSION:
+ - servicecomb.service.version
+```
+
+调整为
+
+```yaml
+PAAS_CSE_ENDPOINT:
+ - servicecomb.service.registry.address
+ - servicecomb.config.client.serverUri
+PAAS_CSE_SC_ENDPOINT:
+ - servicecomb.service.registry.address
+PAAS_CSE_CC_ENDPOINT:
+ - servicecomb.config.client.serverUri
+PAAS_PROJECT_NAME:
+ - servicecomb.credentials.project
+```
+
+做这个调整是因为大部分业务场景，不需要覆盖应用名称、微服务名称和版本。 另外，微服务引擎还提供了 APP_MAPPING、SERVICE_MAPPING、VERSION_MAPING
+来支持应用名称、微服务名称和版本的覆盖。
diff --git a/java-chassis-reference/zh_CN/docs/references-handlers/governance.md b/java-chassis-reference/zh_CN/docs/references-handlers/governance.md
index 4ea875f..491166a 100644
--- a/java-chassis-reference/zh_CN/docs/references-handlers/governance.md
+++ b/java-chassis-reference/zh_CN/docs/references-handlers/governance.md
@@ -120,7 +120,7 @@ servicecomb:
services: helloService
```
-规则解释：限流规则借鉴了 [Resilience4j][resilience4j] 的思想，其原理为： 每隔limitRefreshPeriod的时间会加入limitForPeriod个新许可，
+规则解释：限流规则借鉴了 [Resilience4j][resilience4j] 的思想，其原理为： 每隔limitRefreshPeriod的时间会加入limitForPeriod（即rate）个新许可，
如果获取不到新的许可(已经触发限流)，当前线程会park，最多等待timeoutDuration的时间，默认单位为ms。在异步框架中，建议 timeoutDuration
设置为0，否则可能阻塞事件派发线程。
@@ -159,7 +159,7 @@ servicecomb:
userLoginAction: |
failureRateThreshold：50
slowCallRateThreshold： 100
- SlowCallDurationThreshold： 60000
+ slowCallDurationThreshold： 60000
minimumNumberOfCalls: 100
slidingWindowType: count
slidingWindowSize: 100
@@ -167,7 +167,7 @@ servicecomb:
```
规则解释：熔断规则借鉴了 [Resilience4j][resilience4j] 的思想，其原理为：达到指定 failureRateThreshold 错误率或者 slowCallRateThreshold 慢请求
-率时进行熔断，慢请求通过 SlowCallDurationThreshold 定义。minimumNumberOfCalls 是达到熔断要求的最低请求数量门槛。slidingWindowType指定滑动窗口
+率时进行熔断，慢请求通过 slowCallDurationThreshold 定义。minimumNumberOfCalls 是达到熔断要求的最低请求数量门槛。slidingWindowType指定滑动窗口
类型，默认可选 count / time 分别是基于请求数量窗口和基于时间窗口。slidingWindowSize 指定窗口大小，根据滑动窗口类型，单位可能是请求数量或者秒。
### 隔离仓
@@ -184,9 +184,106 @@ servicecomb:
规则解释：隔离仓规则借鉴了 [Resilience4j][resilience4j] 的思想，其原理为：当最大并发数超过 maxConcurrentCalls，等待 maxWaitDuration
竞争资源，如果获得资源，则继续处理，如果获取不到，则拒绝执行请求。在异步框架，建议 maxWaitDuration 设置为0，防止阻塞事件派发线程。
-### 使用 JAVA SDK
+### 基于流量标记治理使用指南
-* 待完善
+* Java Chassis
+
+Java Chassis 通过 Handler 实现了基于流量标记治理能力。其中 Provider 实现了限流、熔断和隔离仓，Consumer 实现了重试。使用流量标
+记治理能力，首先需要在代码中引入依赖：
+
+```xml
+<dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>handler-governance</artifactId>
+</dependency>
+```
+
+然后配置 Handler 链
+
+```yaml
+servicecomb:
+ handler:
+ chain:
+ Consumer:
+ default: governance-consumer,loadbalance
+ Provider:
+ default: governance-provider
+```
+
+* Spring Cloud
+
+Spring Cloud通过Aspect拦截RequestMappingHandlerAdater实现了限流、熔断和隔离仓，通过拦截RestTemplate和FeignClient实现了重试。
+使用流量标记治理能力，首先需要在代码中引入依赖：
+
+```xml
+<dependency>
+ <groupId>com.huaweicloud</groupId>
+ <artifactId>spring-cloud-starter-huawei-governance</artifactId>
+</dependency>
+```
+
+* Dubbo
+
+Dubbo的Provider通过Filter拦截请求实现了限流、熔断和隔离仓，通过拦截ClusterInvoker实现了重试。使用流量标记治理能力，首先需要在代码中引入依赖：
+
+```xml
+<dependency>
+ <groupId>com.huaweicloud.dubbo-servicecomb</groupId>
+ <artifactId>dubbo-servicecomb-governance-center</artifactId>
+ <version>${project.version}</version>
+</dependency>
+```
+
+如果要使用重试，需要修改dubbo的Spring配置文件，将dubbo默认的ClusterInvoker修改为dubbo-servicecomb：
+
+```xml
+<dubbo:consumer cluster="dubbo-servicecomb"></dubbo:consumer>
+```
+
+* 自定义
+
+服务治理的默认实现并不一定能够解决业务的所有问题。自定义治理功能可以方便的在不同的场景下使用基于流量的治理能力，比如在网关场景下进行流控。
+SDK基于Spring，使用Spring的框架都能够灵活的使用这些API，方法类似。下面以流控为例，说明如何使用API。 使用API开发的自定义代码，也
+可以通过动态配置下发治理规则。
+
+代码的基本过程包括声明RateLimitingHandler的引用，创建GovernanceRequest，拦截（包装）业务逻辑，处理治理异常。
+
+```java
+@Autowired
+private RateLimitingHandler rateLimitingHandler;
+
+GovernanceRequest governanceRequest = convert(request);
+
+CheckedFunction0<Object> next = pjp::proceed;
+DecorateCheckedSupplier<Object> dcs = Decorators.ofCheckedSupplier(next);
+
+try {
+ SpringCloudInvocationContext.setInvocationContext();
+
+ RateLimiter rateLimiter = rateLimitingHandler.getActuator(request);
+ if (rateLimiter != null) {
+ dcs.withRateLimiter(rateLimiter);
+ }
+
+ return dcs.get();
+} catch (Throwable th) {
+ if (th instanceof RequestNotPermitted) {
+ response.setStatus(429);
+ response.getWriter().print("rate limited.");
+ LOGGER.warn("the request is rate limit by policy : {}",
+ th.getMessage());
+ } else {
+ if (serverRecoverPolicy != null) {
+ return serverRecoverPolicy.apply(th);
+ }
+ throw th;
+ }
+} finally {
+ SpringCloudInvocationContext.removeInvocationContext();
+}
+```
+
+上面简单的介绍了自定义开发。对于更加深入的使用方式，也可以直接参考Java Chassis、Spring Cloud、Dubbo项目中的默认实现代码。
[java-chassis]: https://github.com/apache/servicecomb-java-chassis
[go-chassis]: https://github.com/go-chassis/go-chassis