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/24 07:18:59 UTC
[servicecomb-docs] branch master updated: [SCB-2175]transport
documents improvement (#225)
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 b4582d1 [SCB-2175]transport documents improvement (#225)
b4582d1 is described below
commit b4582d1d8fc456823c47b96bb8ec96ff43ab716a
Author: bao liu <bi...@qq.com>
AuthorDate: Wed Feb 24 15:18:49 2021 +0800
[SCB-2175]transport documents improvement (#225)
---
.../docs/config-reference/rest-transport-client.md | 2 +-
java-chassis-reference/zh_CN/docs/toc.md | 3 ++-
.../zh_CN/docs/transports/highway-rpc.md | 2 ++
.../zh_CN/docs/transports/http2.md | 13 +++--------
.../zh_CN/docs/transports/introduction.md | 21 +++++++++++++++++
.../zh_CN/docs/transports/rest-over-servlet.md | 27 ++++++++++++++--------
.../zh_CN/docs/transports/rest-over-vertx.md | 14 ++++-------
.../zh_CN/docs/transports/transport.md | 4 ----
java-chassis-reference/zh_CN/mkdocs.yml | 3 ++-
9 files changed, 53 insertions(+), 36 deletions(-)
diff --git a/java-chassis-reference/zh_CN/docs/config-reference/rest-transport-client.md b/java-chassis-reference/zh_CN/docs/config-reference/rest-transport-client.md
index e52af8f..4199564 100644
--- a/java-chassis-reference/zh_CN/docs/config-reference/rest-transport-client.md
+++ b/java-chassis-reference/zh_CN/docs/config-reference/rest-transport-client.md
@@ -18,7 +18,7 @@
|servicecomb.rest.client.maxHeaderSize||8192|HTTP 最大头部限制|
|servicecomb.rest.client.http2.enabled|2.0.2|true|是否启用Rest Transport Client，HTTP 2|
|servicecomb.rest.client.http2.useAlpnEnabled||true||
- |servicecomb.rest.client.http2.multiplexingLimit||1||
+ |servicecomb.rest.client.http2.multiplexingLimit||-1|一条连接中，同时支持的最大的stream并发量，-1表示不限制。最终以服务端的concurrentStreams和客户端的multiplexingLimit较小值为准。|
|servicecomb.rest.client.http2.maxPoolSize||1|HTTP2 客户端连接池大小|
|servicecomb.rest.client.http2.idleTimeoutInSeconds|2.0.1|0|HTTP2 连接闲置超时时间|
diff --git a/java-chassis-reference/zh_CN/docs/toc.md b/java-chassis-reference/zh_CN/docs/toc.md
index 65e8c7c..84e9188 100644
--- a/java-chassis-reference/zh_CN/docs/toc.md
+++ b/java-chassis-reference/zh_CN/docs/toc.md
@@ -66,10 +66,11 @@
* [线程模型](general-development/thread-model.md)
* [配置日志](general-development/config-logs.md)
* 多样化的通信协议功能参考:
+ * [多协议介绍](transports/introduction.md)
* [REST over Servlet](transports/rest-over-servlet.md)
* [REST over Vertx](transports/rest-over-vertx.md)
+ * [REST over HTTP2](transports/http2.md)
* [Highway](transports/highway-rpc.md)
- * [HTTP2](transports/http2.md)
* 多样化的服务注册与发现功能参考:
* [注册发现说明](registry/introduction.md)
* [使用服务中心](registry/service-center.md)
diff --git a/java-chassis-reference/zh_CN/docs/transports/highway-rpc.md b/java-chassis-reference/zh_CN/docs/transports/highway-rpc.md
index d2e60bf..52555f4 100644
--- a/java-chassis-reference/zh_CN/docs/transports/highway-rpc.md
+++ b/java-chassis-reference/zh_CN/docs/transports/highway-rpc.md
@@ -27,6 +27,8 @@ Highway通道在microservice.yaml文件中的配置项如下表所示：
| servicecomb.highway.server.verticle-count | [verticle-count](verticle-count.md) | highway server verticle实例数 |
| servicecomb.highway.client.thread-count | [verticle-count](verticle-count.md) | highway client verticle实例数(Deprecated) |
| servicecomb.highway.client.verticle-count | [verticle-count](verticle-count.md) | highway client verticle实例数 |
+| servicecomb.Provider.requestWaitInPoolTimeout${op-priority}| 30000 |在同步线程中排队等待执行的超时时间，单位为毫秒 |
+| servicecomb.highway.server.requestWaitInPoolTimeout | 30000 |同servicecomb.Provider.requestWaitInPoolTimeout${op-priority}, 该配置项优先级更高。 |
## 示例代码
diff --git a/java-chassis-reference/zh_CN/docs/transports/http2.md b/java-chassis-reference/zh_CN/docs/transports/http2.md
index cc3e109..b6ae914 100644
--- a/java-chassis-reference/zh_CN/docs/transports/http2.md
+++ b/java-chassis-reference/zh_CN/docs/transports/http2.md
@@ -1,4 +1,4 @@
-#Http2
+# REST over Http2
## 场景描述
@@ -31,13 +31,6 @@
|-----------------------------------------------|---------|---------------------------------------- |------|
|servicecomb.rest.server.http2.useAlpnEnabled | true |是否启用 ALPN | |
|servicecomb.rest.server.http2.concurrentStreams| 100 |一条连接中，同时支持的最大的stream并发量 |以server端的concurrentStreams和client端的multiplexingLimit较小值为准|
-
-## http2 client 端配置项
-
-| 配置项 | 默认值 | 含义 | 注意 |
-|---------------------------------------------------|--------|------------------------------------------------------ |------|
-|servicecomb.rest.client.http2.useAlpnEnabled |true |是否启用 ALPN | |
-|servicecomb.rest.client.http2.multiplexingLimit |-1 |一条连接中，同时支持的最大的stream并发量，-1表示不限制 |以server端的concurrentStreams和client端的multiplexingLimit较小值为准 |
-|servicecomb.rest.client.http2.maxPoolSize |1 |每个连接池中，对每一个IP：Port最多建立的连接数 | |
-|servicecomb.rest.client.http2.idleTimeoutInSeconds |0 |空闲连接的超时时间，超时后会关闭连接 | |
+|servicecomb.Provider.requestWaitInPoolTimeout${op-priority}| 30000 | 在同步线程中排队等待执行的超时时间，单位为毫秒 | |
+|servicecomb.rest.server.requestWaitInPoolTimeout | 30000 | 同servicecomb.Provider.requestWaitInPoolTimeout${op-priority}, 该配置项优先级更高。 | |
diff --git a/java-chassis-reference/zh_CN/docs/transports/introduction.md b/java-chassis-reference/zh_CN/docs/transports/introduction.md
new file mode 100644
index 0000000..d4fd981
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/transports/introduction.md
@@ -0,0 +1,21 @@
+# 多协议介绍
+
+Java Chassis提出了一些创新的概念，提供方便、简洁的多协议通信开发。首先是编程模型和通信模型的分离。编程模型指用户写代码的
+方式，Java Chassis非常灵活的编程模型:
+
+* Provider编程模型：JAX-RS、SpringMVC、透明RPC
+* Consumer编程模型：透明RPC、RestTemplate、InvokerUtils
+
+开发者可以在项目中自由组合Provider和Consumer的编程模型，即存在 3 * 3 种开发组合，最推荐的开发组合Provider采用JAX-RS，
+Consumer采用透明RPC；熟悉Spring的用户组合SpringMVC和透明RPC。
+
+编程模型和我们通常所说的多协议支持没有关系。 多协议支持一般指的是对象如何编码，比如采用Json还是采用protobuffer；通信协议
+采用什么，比如采用HTTP还是采用私有TCP协议。 对象编码方式和通信协议的组合，称为通信模型。 Java Chassis的通信模型可以分成
+两类：REST 和 Highway。
+
+* REST： 对象编码采用Json，支持接口参数与HTTP的Path， Header、Body的映射关系定义。通信协议采用HTTP协议族，比如HTTP、
+ HTTPS、HTTP2（H2和H2C）。
+* Highway： 对象编码采用protobuffer。通信协议采用Java Chassis自定义的私有TCP协议。
+
+Java Chassis的编程模型和通信模型分离，意味着业务代码开发的时候，不需要关注通信模型，可以在不修改业务代码的情况下，
+修改通信模型配置，切换为新的通信模型。
diff --git a/java-chassis-reference/zh_CN/docs/transports/rest-over-servlet.md b/java-chassis-reference/zh_CN/docs/transports/rest-over-servlet.md
index c2e58db..f0fde94 100644
--- a/java-chassis-reference/zh_CN/docs/transports/rest-over-servlet.md
+++ b/java-chassis-reference/zh_CN/docs/transports/rest-over-servlet.md
@@ -1,5 +1,11 @@
# REST over Servlet
-REST over Servlet对应使用web容器部署运行，需要新建一个servlet工程将微服务包装起来，打成war包，加载到web容器中启动运行。
+REST over Servlet的本质是将Java Chassis作为一个Servlet，部署到支持Servlet的Web容器中。 通常有两种使用场景：第一种是在
+独立的Web容器中部署运行，比如Tomcat；第二种是组合Spring Boot提供的Embedded Tomcat运行。
+
+本章节主要介绍在独立的Web容器中部署运行。在Spring Boot提供的Embedded Tomcat中运行，请参考
+[在Spring Boot中使用java chassis](../using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md)。
+
+
## 对外发布的Path
当微服务部署到web容器中时，相对于独立运行，会涉及到web root以及servlet url pattern对url的改变。
对于传统开发框架而言，需要consumer感知对方的完整url；比如web root为/mywebapp，url pattern为/rest，业务级path为/application，则consumer代码必须通过/mywebapp/rest/application来访问。
@@ -206,14 +212,15 @@ REST over Servlet在microservice.yaml文件中的配置项见表3-9。
表1-1 REST over Servlet配置项说明
-| 配置项 | 默认值 | 是否必选 | 含义 |
-| :----------------------------------------------- | :----------- | :------- | :---------------------------------------------------- |
-| servicecomb.rest.address | 0.0.0.0:8080 | 否 |服务监听地址<br>必须配置为与web容器监听地址相同的地址 |
-| servicecomb.rest.server.timeout | -1 | 否 |异步servlet超时时间, 单位为毫秒<br>建议保持默认值 |
-| servicecomb.rest.server.requestWaitInPoolTimeout | 30000 | 否 |在同步线程中排队等待执行的超时时间，单位为毫秒 |
-| servicecomb.rest.servlet.urlPattern | 无 | 否 | 用于简化servlet+servlet mapping配置<br>只有在web.xml中未配置servlet+servlet mapping时，才使用此配置项，配置格式为：/\* 或 /path/\*，其中path可以是多次目录 |
-| servicecomb.uploads.maxSize | 无 | 否 | 文件上传 form body 最大大小 |
-| servicecomb.uploads.maxFileSize | 无 | 否 | 文件上传所有文件总的大小限制 |
-| servicecomb.uploads.fileSizeThreshold | 无 | 否 | 文件上传，实际写入磁盘文件的最大大小 |
+| 配置项 | 默认值 | 含义 |
+| :----------------------------------------------- | :----------- | :---------------------------------------------------- |
+| servicecomb.rest.address | 0.0.0.0:8080 | 服务监听地址<br>必须配置为与web容器监听地址相同的地址 |
+| servicecomb.rest.server.timeout | -1 | 异步servlet超时时间, 单位为毫秒<br>建议保持默认值 |
+| servicecomb.Provider.requestWaitInPoolTimeout${op-priority}| 30000 | 在同步线程中排队等待执行的超时时间，单位为毫秒 |
+| servicecomb.rest.server.requestWaitInPoolTimeout | 30000 | 同servicecomb.Provider.requestWaitInPoolTimeout${op-priority}, 该配置项优先级更高。 |
+| servicecomb.rest.servlet.urlPattern | 无 | 用于简化servlet+servlet mapping配置<br>只有在web.xml中未配置servlet+servlet mapping时，才使用此配置项，配置格式为：/\* 或 /path/\*，其中path可以是多次目录 |
+| servicecomb.uploads.maxSize | 无 | 文件上传 form body 最大大小 |
+| servicecomb.uploads.maxFileSize | 无 | 文件上传所有文件总的大小限制 |
+| servicecomb.uploads.fileSizeThreshold | 无 | 文件上传，实际写入磁盘文件的最大大小 |
diff --git a/java-chassis-reference/zh_CN/docs/transports/rest-over-vertx.md b/java-chassis-reference/zh_CN/docs/transports/rest-over-vertx.md
index 44bd3df..f089b8f 100644
--- a/java-chassis-reference/zh_CN/docs/transports/rest-over-vertx.md
+++ b/java-chassis-reference/zh_CN/docs/transports/rest-over-vertx.md
@@ -36,13 +36,8 @@ REST over Vertx通道在microservice.yaml文件中有以下配置项：
| servicecomb.rest.server.compression | false | 服务端是否支持启用压缩 |
| servicecomb.rest.server.maxInitialLineLength | 4096 | 服务端接收请求的最大 initial line 长度，单位字节 |
| servicecomb.rest.server.maxHeaderSize | 32768 | 服务端接收请求的最大header长度，单位字节 |
-| servicecomb.rest.client.thread-count | [verticle-count](verticle-count.md) | rest client verticle实例数（Deprecated） |
-| servicecomb.rest.client.verticle-count | [verticle-count](verticle-count.md) | rest client verticle实例数 |
-| servicecomb.rest.client.connection.maxPoolSize | 5 | 对一个IP:port组合，在每个连接池中的最大连接数 |
-| servicecomb.rest.client.connection.idleTimeoutInSeconds | 30 | 连接闲置时间，超时连接会被释放 |
-| servicecomb.rest.client.connection.keepAlive | true | 是否使用长连接 |
-| servicecomb.rest.client.connection.compression | false | 客户端是否支持启用压缩 |
-| servicecomb.rest.client.maxHeaderSize | 8192 | 客户端接收响应的最大header长度，单位字节 |
+| servicecomb.Provider.requestWaitInPoolTimeout${op-priority}| 30000 |在同步线程中排队等待执行的超时时间，单位为毫秒 |
+| servicecomb.rest.server.requestWaitInPoolTimeout | 30000 |同servicecomb.Provider.requestWaitInPoolTimeout${op-priority}, 该配置项优先级更高。 | | 客户端接收响应的最大header长度，单位字节 |
| servicecomb.uploads.maxSize | 无限制 | 最大 body 大小，这个配置项对文件上传，REST请求都生效|
### 补充说明
@@ -61,8 +56,9 @@ REST over Vertx通道在microservice.yaml文件中有以下配置项：
* 一个client最多向一个server建立40条连接。(`8 * 5 = 40`)
* `n`个client最多会向一个server建立`40 * n`条连接
-为了提高性能，需要尽量使用更大的连接池，但是更大的连接池又可能会导致连接数暴涨，当微服务实例规模达到百级别时，有的进程可能需要管理几万条连接，业务需要根据实际业务规模进行合理的规划。
- http1.1的规划相对复杂，并且有的场景几乎无解，建议切换为[http2](http2.md)。
+为了提高性能，需要尽量使用更大的连接池，但是更大的连接池又可能会导致连接数暴涨，当微服务实例规模达到百级别时，有的进程可能需要管理
+几万条连接，业务需要根据实际业务规模进行合理的规划。在实例规模比较小的情况下，HTTP仍然是所有应用程序的最佳选择，它具备更好的兼容性
+和可靠性。当单个实例的连接数管理规模超过1万的时候，可以考虑切换为[http2](http2.md)。
## 示例代码
diff --git a/java-chassis-reference/zh_CN/docs/transports/transport.md b/java-chassis-reference/zh_CN/docs/transports/transport.md
deleted file mode 100644
index 4476e35..0000000
--- a/java-chassis-reference/zh_CN/docs/transports/transport.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# 通信
-
-## 概念阐述
-ServiceComb实现了两种网络通道，包括REST和Highway，均支持TLS加密传输。其中，REST网络通道将服务以标准RESTful形式发布，调用端兼容直接使用http client使用标准RESTful形式进行调用。
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml b/java-chassis-reference/zh_CN/mkdocs.yml
index 14fcf78..0ef6c99 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -12,10 +12,11 @@ nav:
- 通用功能开发: general-development/catalog.md
- 多样化的通信协议功能参考:
+ - 多协议介绍: transports/introduction.md
- REST over Servlet: transports/rest-over-servlet.md
- REST over Vertx: transports/rest-over-vertx.md
+ - REST over HTTP2: transports/http2.md
- Highway: transports/highway-rpc.md
- - HTTP2: transports/http2.md
- 多样化的服务注册与发现功能参考:
- 注册发现说明: registry/introduction.md
- 使用服务中心: registry/service-center.md