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/03/09 06:57:11 UTC

[servicecomb-docs] branch master updated (d5b40ac -> 3d95779)

This is an automated email from the ASF dual-hosted git repository.

liubao pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-docs.git.


    from d5b40ac  [SCB-2196]usage of connection pools for htt1 and http2 (#227)
     new 1bf73fc  [SCB-2212]improve documents for gray release
     new 3d95779  [SCB-2211]add documents to show reactive support of java chassis

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 .../build-consumer/develop-consumer-using-rpc.md   | 10 +++-
 .../zh_CN/docs/build-provider/catalog.md           |  1 +
 .../zh_CN/docs/build-provider/reactive.md          | 55 ++++++++++++++++++++++
 .../zh_CN/docs/build-provider/thread-pool.md       | 18 ++++++-
 .../zh_CN/docs/references-handlers/router.md       | 27 ++++++-----
 java-chassis-reference/zh_CN/docs/toc.md           |  2 +-
 java-chassis-reference/zh_CN/mkdocs.yml            |  2 +-
 7 files changed, 98 insertions(+), 17 deletions(-)
 create mode 100644 java-chassis-reference/zh_CN/docs/build-provider/reactive.md

[servicecomb-docs] 01/02: [SCB-2212]improve documents for gray release

Posted by li...@apache.org.

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

commit 1bf73fca0c48393f81ee2af17ed144347847f31f
Author: libuao68 <bi...@qq.com>
AuthorDate: Tue Mar 9 11:03:32 2021 +0800

    [SCB-2212]improve documents for gray release
---
 .../zh_CN/docs/references-handlers/router.md       | 27 +++++++++++++---------
 java-chassis-reference/zh_CN/docs/toc.md           |  2 +-
 java-chassis-reference/zh_CN/mkdocs.yml            |  2 +-
 3 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/java-chassis-reference/zh_CN/docs/references-handlers/router.md b/java-chassis-reference/zh_CN/docs/references-handlers/router.md
index 943f8ee..ccb9b1c 100644
--- a/java-chassis-reference/zh_CN/docs/references-handlers/router.md
+++ b/java-chassis-reference/zh_CN/docs/references-handlers/router.md
@@ -1,8 +1,12 @@
-# 路由管理
+# 灰度发布
 
-应用可以通过使用路由管理，来进行灰度发布实现版本的平滑过渡升级。路由管理通过动态配置下发完成。 
+使用灰度发布可以实现版本的零中断升级。假设微服务A当前是v1版本，v1版本存在一个实例，现在需要升级到到v2版本。首先配置一个灰度
+发布规则，将100%的流量指向v1版本；配置规则生效后，部署v2版本；v2版本启动完毕，配置10%的流量到v2版本；当v2版本
+运行稳定，配置100%的流量到v2版本；停止v1版本的实例。
 
-使用路由管理，需要在项目中引入如下依赖：
+* 前提条件：灰度发布依赖负载均衡管理模块， 参考[负载均衡](./loadbalance.md) 。 
+
+使用灰度发布，需要在项目中引入如下依赖：
 
 ```xml
 <dependency>
@@ -13,14 +17,17 @@
 
 在配置文件中增加配置项：
 
-前提条件：配置servicecomb.handler.chain.Consumer.default，在处理链Consumer中配置loadbalance，[loadbalance处理链介绍](./loadbalance.md)。
-
 | 配置项名                                   | 描述                   |
 | ------------------------------------------ | ---------------------- |
 | servicecomb.routeRule.[targetService]      | 目标服务的路由管理规则 |
 | servicecomb.router.type                    | 填写'router'           |
+| servicecomb.router.header                  | 从HTTP请求头中提取额外的可以用于匹配HTTP Header信息。 以逗号分隔的多个 Header 名称。|
+
+* 说明：路由规则里面的 headers 来源分为如下几部分：（1）servicecomb.router.header 配置的 Header 信息；（2）Invocation Arguments，即
+  业务接口的参数列表。关于Invocation Arguments和Swagger Arguments的差异，请参考 Invocation 类。 Invocation Arguments的优先级
+  高于 servicecomb.router.header。 
 
-路由管理规则实例如下：
+灰度发布规则示例如下：
 
 ```yaml
 servicecomb:
@@ -62,14 +69,12 @@ servicecomb:
 
 #### 匹配流程
 
-对于上面的示例配置，所有访问provider服务的请求，首先尝试与优先级为2的第一个的match规则进行匹配header：header存在key为region的按照正则规则区分大小写匹配，存在key为type的进行字符串精准匹配。若匹配match成功则按照route的配置分配100%的流量到version和tags对应的实例。若匹配match失败则进入下个优先级为1的规则。不同规则优先级不能相等。
+对于上面的示例配置，所有访问provider服务的请求，首先尝试与优先级为2的第一个的match规则进行匹配
+header：header存在key为region的按照正则规则区分大小写匹配，存在key为type的进行字符串精准匹配。若匹配
+match成功则按照route的配置分配100%的流量到version和tags对应的实例。若匹配match失败则进入下个优先级为1的规则。不同规则优先级不能相等。
 
 #### 异常情况的处理
 
 如果因为规则配置错误，或者没有match到任何一条规则，流量会直接跳过灰度规则，相当于没有灰度发布配置。
 
 如果已经匹配了match，因为对应的version或者tags找不到实例，则剩余流量自动转发到目前的最新版本。
-
-#### 负载均衡算法
-
-借鉴了nginx，使用平滑加权轮询算法，流量会均匀的等比分配到对应的服务实例上。
\ No newline at end of file
diff --git a/java-chassis-reference/zh_CN/docs/toc.md b/java-chassis-reference/zh_CN/docs/toc.md
index d538447..a645d52 100644
--- a/java-chassis-reference/zh_CN/docs/toc.md
+++ b/java-chassis-reference/zh_CN/docs/toc.md
@@ -79,7 +79,7 @@
     - [处理链介绍](references-handlers/intruduction.md)
     - [负载均衡](references-handlers/loadbalance.md)
     - [限流](references-handlers/ratelimit.md)
-    - [路由管理](references-handlers/router.md)
+    - [灰度发布](references-handlers/router.md)
     - [故障注入](references-handlers/fault-injection.md)
     - [隔离熔断容错](references-handlers/bizkeeper.md)
     - [基于动态配置的流量特征治理](references-handlers/governance.md)
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml b/java-chassis-reference/zh_CN/mkdocs.yml
index 914f192..32e848b 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -26,7 +26,7 @@ nav:
       - 处理链介绍: references-handlers/intruduction.md
       - 负载均衡: references-handlers/loadbalance.md
       - 限流: references-handlers/ratelimit.md
-      - 路由管理: references-handlers/router.md
+      - 灰度发布: references-handlers/router.md
       - 故障注入: references-handlers/fault-injection.md
       - 隔离熔断容错: references-handlers/bizkeeper.md
       - 基于动态配置的流量特征治理: references-handlers/governance.md

[servicecomb-docs] 02/02: [SCB-2211]add documents to show reactive support of java chassis

Posted by li...@apache.org.

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

commit 3d95779f7f4e10548bb62e16db87a25d72f814ce
Author: libuao68 <bi...@qq.com>
AuthorDate: Tue Mar 9 14:51:25 2021 +0800

    [SCB-2211]add documents to show reactive support of java chassis
---
 .../build-consumer/develop-consumer-using-rpc.md   | 10 +++-
 .../zh_CN/docs/build-provider/catalog.md           |  1 +
 .../zh_CN/docs/build-provider/reactive.md          | 55 ++++++++++++++++++++++
 .../zh_CN/docs/build-provider/thread-pool.md       | 18 ++++++-
 4 files changed, 80 insertions(+), 4 deletions(-)

diff --git a/java-chassis-reference/zh_CN/docs/build-consumer/develop-consumer-using-rpc.md b/java-chassis-reference/zh_CN/docs/build-consumer/develop-consumer-using-rpc.md
index b308390..8f7b2bb 100644
--- a/java-chassis-reference/zh_CN/docs/build-consumer/develop-consumer-using-rpc.md
+++ b/java-chassis-reference/zh_CN/docs/build-consumer/develop-consumer-using-rpc.md
@@ -1,16 +1,18 @@
-# 使用透明RPC方式开发服务消费者
+# 使用RPC方式开发服务消费者
 
 ## 概念阐述
 
 透明RPC开发模式允许用户通过简单的java interface像本地调用一样进行服务调用。  
 透明RPC仅仅是一种开发模式：
+
 * 与使用highway还是RESTful传输没有关联
 * 与producer使用透明RPC/Jax-RS还是SpringMVC模式开发没有关联
 * 也与producer代码是否实现这个interface没有关联。  
   
-透明RPC开发模式与spring cloud的feign类似，不过更简单，因为不必在这个interface中增加任何RESTful annotation。
+透明RPC开发模式与spring boot的feign类似，不过更简单，因为不必在这个interface中增加任何RESTful annotation。
 
 ## 在spring bean中通过@RpcReference声明
+
 ```java
 @Component
 public class SomeBean {
@@ -22,13 +24,16 @@ public class SomeBean {
   ......
 }
 ```
+
 ## 脱离spring bean，直接通过api声明
 ```java
 Hello hello = Invoker.createProxy("helloService", "helloSchema", Hello.class);
 ```
 
 ## reactive
+
 只需要使用jdk的CompletableFuture对返回值进行包装即可
+
 ```java
 interface Hello {
   CompletableFuture<String> sayHi(String name);
@@ -37,6 +42,7 @@ interface Hello {
 
 同一个interface中，可以同时声明同一个方法的reactive和同步原型  
 因为要求方法名与契约中的operationId一一对应，而仅有返回值类型不同，在java中是非法的，所以需要修改方法名，并通过swagger annotation来声明真正的operationId
+
 ```java
 interface Hello {
   String sayHi(String name);
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/catalog.md b/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
index b8b7bdc..035f1c8 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
@@ -5,6 +5,7 @@
 * [用SpringMVC开发微服务](springmvc.md)
 * [用透明RPC开发微服务](transparent-rpc.md)
 * [只发布interface的方法为服务接口](use-interface.md)
+* [异步处理](reactive.md)
 * [使用 Context 参数](context-param.md)
 * [多个返回值和错误码](multi-code.md)
 * [使用Swagger注解](swagger-annotation.md)
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/reactive.md b/java-chassis-reference/zh_CN/docs/build-provider/reactive.md
new file mode 100644
index 0000000..9db2e14
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/build-provider/reactive.md
@@ -0,0 +1,55 @@
+# 异步处理
+
+异步处理可以更加充分的利用CPU，提升应用程序的性能。相对于同步处理，异步处理的开发过程更加复杂，出现的问题也更加难于定位。Java Chassis
+提供了非常灵活的异步处理机制，使得开发者能够选择性的使用同步处理和异步处理。
+
+## 定义异步处理的接口和使用异步访问
+
+在Provider端，Spring MVC、JAX RS和RPC的异步接口定义类似，都使用`CompletableFuture`来声明异步接口。以透明RPC为例，定义方法如下：
+
+```java
+  public CompletableFuture<String> sayHello(String name) {
+    CompletableFuture<String> future = new CompletableFuture<>();
+    future.complete(name);
+    return future;
+  }
+```
+
+在Consumer端，可以使用透明RPC、InvokerUtils、AsyncRestTemplate来使用异步。以透明RPC为例，首先声明接口：
+
+```java
+public interface Hello {
+  @ApiOperation(nickname = "sayHello", value = "")
+  CompletableFuture<String> sayHelloAsync(String name);
+
+  String sayHello(String name);
+}
+```
+
+上面的例子同时定义了异步访问的接口和同步访问的接口，它们可以用来访问Provider的同一个接口。 使用异步接口和使用同步接口的过程一样：
+
+```java
+  @RpcReference(microserviceName = "name", schemaId = "Hello")
+  public Hello hello;
+```
+
+## 异步逻辑执行的线程池
+
+声明为异步接口，并不会改变业务逻辑入口被执行的线程。比如在Provider端，业务逻辑的入口还是在同步线程池中执行的，Edge Service在event-loop执行。
+改变入口逻辑的执行线程，需要修改方法的默认线程池。异步接口执行完毕，回调逻辑在业务自定义的异步执行线程池执行。 
+
+详细情况参考[线程池](thread-pool.md)。 
+
+异步逻辑在更加复杂场景下的执行过程，请参考[reactive](../general-development/reactive.md)。
+
+## 有关 event-loop 线程的特殊说明
+
+在Edge Service等场景，或者在Provider使用了异步线程池的场景，所有的业务逻辑都是在event-loop执行的。在event-loop执行的业务代码，不能存在
+任何阻塞操作，否则会破坏event-loop的事件派发，导致死锁。 这些场景访问其他微服务，必须采用异步接口。 event-loop执行阻塞操作导致死锁的情况，
+或者导致性能下降的情况，需要在满足一定的并发条件才能够出现，不小心使用会给业务可靠性带来很大的风险。 Java Chassis针对常见的错误也提供了一些
+检测机制，比如在event-loop执行同步Consumer调用的时候，会报告异常，让开发者及时发现问题。 
+
+
+ 
+
+
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/thread-pool.md b/java-chassis-reference/zh_CN/docs/build-provider/thread-pool.md
index 09a99d4..862b9fd 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/thread-pool.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/thread-pool.md
@@ -19,10 +19,15 @@ Java Chassis 提供了一个全局的内置线程池， 如果业务有特殊的
   * 指定schema专用的线程池: `servicecomb.executors.Provider.${schemaId}: custom-executor`
   * 指定operation专用的线程池: `servicecomb.executors.Provider.${schemaId}.${operationId}: custom-executor`
  
-## ServiceComb内置线程池
+## Java Chassis 内置线程池
+
+Java Chassis提供了两个内置的线程池，`servicecomb.executor.groupThreadPool` 和 `servicecomb.executor.reactive`。 前者
+是同步线程池，在Consumer和Provider默认启用；后者是异步线程池，在Edge Service默认启用。 
+
+### 同步线程池
 
 一般的线程池都是所有线程共享一个任务队列，在这种情况下，所有网络线程需要向同一个队列申请请求入队，线程池中的所有线程需要从同一个队列中抢任务执行，对于高吞吐的场景，这会导致竞争冲突，形成性能瓶颈  
-所以，为了提升性能，ServiceComb内置线程池实际是真正线程池的包装，允许在其内部配置多组线程池，且每个网络线程绑定一组线程池，以减小竞争冲突  
+所以，为了提升性能，Java Chassis内置线程池实际是真正线程池的包装，允许在其内部配置多组线程池，且每个网络线程绑定一组线程池，以减小竞争冲突  
 ![](../assets/producer-default-executor.png)
 
 * 1.2.0之前的版本
@@ -44,3 +49,12 @@ Java Chassis 提供了一个全局的内置线程池， 如果业务有特殊的
 | servicecomb.executor.default.maxIdleSecond-per-group| 60                | 每组线程池中超过coreThreads-per-group的线程，如果idle超时，则会销毁该线程 |
 | servicecomb.executor.default.maxQueueSize-per-group | Integer.MAX_VALUE | 每组线程池中任务队列的最大长度                                            |
 | servicecomb.rest.server.requestWaitInPoolTimeout    | 30000             |在同步线程中排队等待执行的超时时间，单位为毫秒         |
+
+### 异步线程池
+
+所谓的异步线程池，实际上是没有提供额外的线程池。 所有的业务逻辑直接在 event-loop 线程池执行。 使用异步线程池，业务代码不能够存在阻塞操作。
+常见的阻塞操作包括
+
+* 使用同步API，调用其他微服务，比如 RestTemplate、透明RPC等。
+* 特别耗时的任务。比如等待IO、等待锁、Sleep等。
+