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 330602c update some contents structure (#348)
330602c is described below
commit 330602cca8a0dba06462a873483c31bed180dc20
Author: liubao68 <[email protected]>
AuthorDate: Sat Jul 27 16:14:05 2024 +0800
update some contents structure (#348)
---
.../featured-topics/{features => }/date-time.md | 0
.../zh_CN/docs/featured-topics/features.md | 4 -
.../{features => }/http-dispatcher.md | 2 +-
.../zh_CN/docs/featured-topics/secrets.md | 16 --
.../zh_CN/docs/featured-topics/upgrading.md | 3 -
.../secrets/api-first-flow.png | Bin
.../{featured-topics => }/secrets/api-first.md | 0
.../secrets/applied-config.md | 0
.../secrets/circuit-breaker.md | 0
.../secrets/fail-fast-rate-limiting.png | Bin
.../{featured-topics => }/secrets/fail-fast.md | 0
.../secrets/interoperability-scen.png | Bin
.../secrets/interoperability.md | 0
.../secrets/load-balancer-operation.md | 0
.../secrets/load-balancer-selector-empty.png | Bin
.../secrets/load-balancer-selector-normal.png | Bin
.../secrets/load-balancer-selector.png | Bin
.../{featured-topics => }/secrets/load-balancer.md | 0
.../secrets/load-blancer-operation.png | Bin
.../{featured-topics => }/secrets/observability.md | 0
.../secrets/observability.png | Bin
.../{featured-topics => }/secrets/registries.md | 0
.../secrets/serialization-arch.png | Bin
.../secrets/serialization-case.png | Bin
.../{featured-topics => }/secrets/serialization.md | 0
.../docs/{featured-topics => }/secrets/sse.md | 0
.../{featured-topics => }/secrets/websocket.md | 0
.../secrets/zone-isolation-az.png | Bin
.../secrets/zone-isolation-ping.png | Bin
.../secrets/zone-isolation-status.png | Bin
.../secrets/zone-isolation.md | 0
.../secrets/zookeeper-scale.png | Bin
.../{featured-topics => }/secrets/zookeeper.md | 0
.../zh_CN/docs/upgrading/1_3_0T2_0_0.md | 314 +++++++++++++++++++++
.../zh_CN/docs/upgrading/2_0_0T2_0_1.md | 13 +
.../zh_CN/docs/upgrading/2_0_1T2_1_0.md | 106 +++++++
.../zh_CN/docs/upgrading/2_1_0T2_1_1.md | 16 ++
.../zh_CN/docs/upgrading/2_1_1T2_1_5.md | 61 ++++
.../zh_CN/docs/upgrading/2_1_5T2_6_0.md | 45 +++
.../zh_CN/docs/upgrading/2_6_0T2_8_0.md | 12 +
.../{featured-topics => }/upgrading/2_8_0T3_0_0.md | 0
java-chassis-reference/zh_CN/mkdocs.yml | 29 +-
42 files changed, 593 insertions(+), 28 deletions(-)
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/features/date-time.md
b/java-chassis-reference/zh_CN/docs/featured-topics/date-time.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/features/date-time.md
rename to java-chassis-reference/zh_CN/docs/featured-topics/date-time.md
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/features.md
b/java-chassis-reference/zh_CN/docs/featured-topics/features.md
deleted file mode 100644
index 15a6e0a..0000000
--- a/java-chassis-reference/zh_CN/docs/featured-topics/features.md
+++ /dev/null
@@ -1,4 +0,0 @@
-# 特性介绍
-
-* [特性介绍： date和date-time](features/date-time.md)
-* [特性介绍： Edge Service 通用的 HTTP 转发器
CommonHttpEdgeDispatcher](features/http-dispatcher.md)
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/features/http-dispatcher.md
b/java-chassis-reference/zh_CN/docs/featured-topics/http-dispatcher.md
similarity index 96%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/features/http-dispatcher.md
rename to java-chassis-reference/zh_CN/docs/featured-topics/http-dispatcher.md
index b741d46..8979b40 100644
---
a/java-chassis-reference/zh_CN/docs/featured-topics/features/http-dispatcher.md
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/http-dispatcher.md
@@ -44,7 +44,7 @@ servicecomb:
## CommonHttpEdgeDispatcher 的治理
-CommonHttpEdgeDispatcher 集成了 loadbalance 模块提供的治理能力， 在
[负载均衡](../../references-handlers/loadbalance.md) 里面的治理
+CommonHttpEdgeDispatcher 集成了 loadbalance 模块提供的治理能力， 在
[负载均衡](../references-handlers/loadbalance.md) 里面的治理
能力都可以使用，除了 `设置重试策略` 。 这个转发器通常被用于转发 UI 请求到后端的静态页面服务，以及遗留的使用 spring
boot 开发的微服务， 或者采用 spring-cloud-huawei 接入服务中心的 spring cloud 微服务应用。
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/secrets.md
b/java-chassis-reference/zh_CN/docs/featured-topics/secrets.md
deleted file mode 100644
index 84c317b..0000000
--- a/java-chassis-reference/zh_CN/docs/featured-topics/secrets.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# 技术解密
-
-* [Java Chassis 3技术解密：负载均衡选择器](secrets/load-balancer.md)
-* [Java Chassis 3技术解密：注册中心分区隔离](secrets/zone-isolation.md)
-* [Java Chassis 3技术解密：多种序列化方式支持](secrets/serialization.md)
-* [Java Chassis 3技术解密：熔断机制的改进路程](secrets/circuit-breaker.md)
-* [Java Chassis 3技术解密：过载状态下的快速失败](secrets/fail-fast.md)
-* [Java Chassis 3技术解密：应用视角的配置管理](secrets/applied-config.md)
-* [Java Chassis 3技术解密：易扩展的多种注册中心支持](secrets/registries.md)
-* [Java Chassis 3技术解密：与Spring Cloud的互操作](secrets/interoperability.md)
-* [Java Chassis 3技术解密：ZooKeeper注册和配置中心](secrets/zookeeper.md)
-* [Java Chassis 3技术解密：契约优先（API First）开发](secrets/api-first.md)
-* [Java Chassis 3技术解密：接口维度负载均衡](secrets/load-balancer-operation.md)
-* [Java Chassis 3技术解密：实用的可观测性](secrets/observability.md)
-* [Java Chassis 3技术解密：流式响应和人工智能应用开发](secrets/sse.md)
-* [Java Chassis 3技术解密：WebSocket和人工智能应用开发](secrets/websocket.md)
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md
b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md
deleted file mode 100644
index aa9442d..0000000
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# 升级指导
-
-* [2.8.x 升级 3.0.0指导](upgrading/2_8_0T3_0_0.md)
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/api-first-flow.png
b/java-chassis-reference/zh_CN/docs/secrets/api-first-flow.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/api-first-flow.png
rename to java-chassis-reference/zh_CN/docs/secrets/api-first-flow.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/api-first.md
b/java-chassis-reference/zh_CN/docs/secrets/api-first.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/api-first.md
rename to java-chassis-reference/zh_CN/docs/secrets/api-first.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/applied-config.md
b/java-chassis-reference/zh_CN/docs/secrets/applied-config.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/applied-config.md
rename to java-chassis-reference/zh_CN/docs/secrets/applied-config.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/circuit-breaker.md
b/java-chassis-reference/zh_CN/docs/secrets/circuit-breaker.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/circuit-breaker.md
rename to java-chassis-reference/zh_CN/docs/secrets/circuit-breaker.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/fail-fast-rate-limiting.png
b/java-chassis-reference/zh_CN/docs/secrets/fail-fast-rate-limiting.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/fail-fast-rate-limiting.png
rename to java-chassis-reference/zh_CN/docs/secrets/fail-fast-rate-limiting.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/fail-fast.md
b/java-chassis-reference/zh_CN/docs/secrets/fail-fast.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/fail-fast.md
rename to java-chassis-reference/zh_CN/docs/secrets/fail-fast.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/interoperability-scen.png
b/java-chassis-reference/zh_CN/docs/secrets/interoperability-scen.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/interoperability-scen.png
rename to java-chassis-reference/zh_CN/docs/secrets/interoperability-scen.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/interoperability.md
b/java-chassis-reference/zh_CN/docs/secrets/interoperability.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/interoperability.md
rename to java-chassis-reference/zh_CN/docs/secrets/interoperability.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-balancer-operation.md
b/java-chassis-reference/zh_CN/docs/secrets/load-balancer-operation.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-balancer-operation.md
rename to java-chassis-reference/zh_CN/docs/secrets/load-balancer-operation.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-balancer-selector-empty.png
b/java-chassis-reference/zh_CN/docs/secrets/load-balancer-selector-empty.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-balancer-selector-empty.png
rename to
java-chassis-reference/zh_CN/docs/secrets/load-balancer-selector-empty.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-balancer-selector-normal.png
b/java-chassis-reference/zh_CN/docs/secrets/load-balancer-selector-normal.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-balancer-selector-normal.png
rename to
java-chassis-reference/zh_CN/docs/secrets/load-balancer-selector-normal.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-balancer-selector.png
b/java-chassis-reference/zh_CN/docs/secrets/load-balancer-selector.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-balancer-selector.png
rename to java-chassis-reference/zh_CN/docs/secrets/load-balancer-selector.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-balancer.md
b/java-chassis-reference/zh_CN/docs/secrets/load-balancer.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-balancer.md
rename to java-chassis-reference/zh_CN/docs/secrets/load-balancer.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-blancer-operation.png
b/java-chassis-reference/zh_CN/docs/secrets/load-blancer-operation.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/load-blancer-operation.png
rename to java-chassis-reference/zh_CN/docs/secrets/load-blancer-operation.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/observability.md
b/java-chassis-reference/zh_CN/docs/secrets/observability.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/observability.md
rename to java-chassis-reference/zh_CN/docs/secrets/observability.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/observability.png
b/java-chassis-reference/zh_CN/docs/secrets/observability.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/observability.png
rename to java-chassis-reference/zh_CN/docs/secrets/observability.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/registries.md
b/java-chassis-reference/zh_CN/docs/secrets/registries.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/registries.md
rename to java-chassis-reference/zh_CN/docs/secrets/registries.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/serialization-arch.png
b/java-chassis-reference/zh_CN/docs/secrets/serialization-arch.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/serialization-arch.png
rename to java-chassis-reference/zh_CN/docs/secrets/serialization-arch.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/serialization-case.png
b/java-chassis-reference/zh_CN/docs/secrets/serialization-case.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/serialization-case.png
rename to java-chassis-reference/zh_CN/docs/secrets/serialization-case.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/serialization.md
b/java-chassis-reference/zh_CN/docs/secrets/serialization.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/serialization.md
rename to java-chassis-reference/zh_CN/docs/secrets/serialization.md
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/sse.md
b/java-chassis-reference/zh_CN/docs/secrets/sse.md
similarity index 100%
rename from java-chassis-reference/zh_CN/docs/featured-topics/secrets/sse.md
rename to java-chassis-reference/zh_CN/docs/secrets/sse.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/websocket.md
b/java-chassis-reference/zh_CN/docs/secrets/websocket.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/websocket.md
rename to java-chassis-reference/zh_CN/docs/secrets/websocket.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/zone-isolation-az.png
b/java-chassis-reference/zh_CN/docs/secrets/zone-isolation-az.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/zone-isolation-az.png
rename to java-chassis-reference/zh_CN/docs/secrets/zone-isolation-az.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/zone-isolation-ping.png
b/java-chassis-reference/zh_CN/docs/secrets/zone-isolation-ping.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/zone-isolation-ping.png
rename to java-chassis-reference/zh_CN/docs/secrets/zone-isolation-ping.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/zone-isolation-status.png
b/java-chassis-reference/zh_CN/docs/secrets/zone-isolation-status.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/zone-isolation-status.png
rename to java-chassis-reference/zh_CN/docs/secrets/zone-isolation-status.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/zone-isolation.md
b/java-chassis-reference/zh_CN/docs/secrets/zone-isolation.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/zone-isolation.md
rename to java-chassis-reference/zh_CN/docs/secrets/zone-isolation.md
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/zookeeper-scale.png
b/java-chassis-reference/zh_CN/docs/secrets/zookeeper-scale.png
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/zookeeper-scale.png
rename to java-chassis-reference/zh_CN/docs/secrets/zookeeper-scale.png
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/secrets/zookeeper.md
b/java-chassis-reference/zh_CN/docs/secrets/zookeeper.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/secrets/zookeeper.md
rename to java-chassis-reference/zh_CN/docs/secrets/zookeeper.md
diff --git a/java-chassis-reference/zh_CN/docs/upgrading/1_3_0T2_0_0.md
b/java-chassis-reference/zh_CN/docs/upgrading/1_3_0T2_0_0.md
new file mode 100644
index 0000000..eaa3f97
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/upgrading/1_3_0T2_0_0.md
@@ -0,0 +1,314 @@
+# 1.3.0 升级 2.0.0指导
+
+2.0.0 版本实现了 [弱类型契约](../features/weak-type-contrast.md)。
+总体而言，对于 `REST` 通信模式， 弱类型契约不仅增强了写代码的灵活性， 还完整保留了强类型契约的写代码方式，几乎不
+存在用户需要感知的变更。 对于 `HIGHWAY` 通信模式， 由于底层采用 ProtoBuffer 编码， 而 ProtoBuffer 天然就是一种
+强类型契约的编解码过程， java-chassis 为了支持弱类型契约， 做了大量努力， 在一些边界条件处理上与弱类型契约存在
+变更，两个版本的编解码是不兼容的，需要同时升级提供者和消费者。 在编码方式上，差异主要体现在对于缺省值的处理，对于
+`null` 的处理等问题上。
+
+## Highway通信协议的变更
+
+Highway通信协议是2.0.0最大的变更点。如果业务采用了Highway通信协议，需要确保所有相关的consumer
+和provider都必须升级，低版本的consumer和高版本的provider之间无法直接通信。此外，从代码风格的层面，
+还有如下一些变更。
+
+ 1. 空字符串和null的传输：protoBuffer 协议对空字符串和null都序列化为空，反序列化的结果都是null。
+ 应用程序的业务逻辑不应该使用空字符串和null表达不同语义。尽管对于REST，程序底层支持这样的区分，
+ 仍然不建议将业务逻辑构筑在这个假设之上，避免后期升级和兼容陷阱。
+ 2. 如果请求参数或者返回值是一个POJO，假设Person，REST可以返回null，但是HIGHWAY始终会创建一个
+ Person 对象返回。业务逻辑尽可能不要依赖于null对象提供语义。
+ 3. 在contrast first编程模式情况下，用户先写契约，然后通过契约生成代码，并将契约文件放
+ 到 `microservices/{microservice name}/{schema id}.yaml` 文件中，这种情况下不会通过代码生成
+ 契约。通常通过工具生成代码，工具生成的数据类型和契约的数据类型匹配，但是如果这种场景的代码经过
+ 修改，并且yaml中的数据类型是number，而代码中的类型是Integer，在HIGHWAY通信模式下会报告错误。
+ HIGHWAY 会将 number 类型解析为 protoBuffer 的 double 类型， 对应的 JAVA 类型为 double。
+ protoBuffer 不支持将Integer类型采用Double的方式序列化。在contract first编程模式下，建议通过
+ 生成工具生成代码，这样用户就不用了解swagger数据类型和JAVA数据类型映射的细节，避免一些陷阱。
+ 4. HIGHWAY 的数据类型定义不支持一些特殊字符串，比如 `H.264` 和 `MPEG-2` 在OPEN API里面是合法的
+ 参数名称，但是在 protoBuffer 里面是不合法的参数名称。带有"."和"-"的参数名字不能用于 HIGHWAY。
+ 如果存在，第一次访问这个接口的时候，会报告:
+ `io.protostuff.compiler.parser.ParserException: Could not parse syntax`
异常。
+ 5. 对于 ENUM 有一个需要特别注意的地方，protoBuffer 采用int来序列化 ENUM ，int的默认值(即0）不会序列化，那么反
+ 序列化的时候，ENUM 的缺省值必须为第一个值。应用程序需要将null和第一个缺省值当成一样的语义对待。比
+ 较好的做法是在程序里面显示的给 ENUM 字段赋缺省值。
+ 6. HIGHWAY 不支持数组参数存在 null 值的情况。如果一个接口的参数是String[]，那么里面的元素不能
+ 为 null，否则序列化和反序列化会失败。
+ 7. 对于 primitive 类型，并且接口声明为 @Required，由于 HIGHWAY 并不会序列化缺省值，比如 0 等，
+ 在Consumer端传递的参数值为 0 的时候，Provider 端并不能区分这个值是传递了0，还是没有传递。因
+ 此 HIGHWAY 会忽略 @Required 声明，使用缺省值0。
+ 8. 如果一个属性的名称采用一个小写字母开头，并且只有一个小写字母，即使生成的getter/setter是合法
+ 的， swagger 生成的属性名称还是会出现错误。应该尽可能避免使用这样的属性名称。必须使用的场景，需要
+ 显示的使用 @JsonProperty 声明。
+
+ ```java
+ public class SpecialNameModel {
+ // names starts with only one lower case , although
getter/setter generated by IDE is correct,
+ // will cause jackson generate incorrect swagger names.
+ // @JsonProperty must be used to make json work in a predictable
way.
+ @JsonProperty("aIntName")
+ private int aIntName;
+
+ public int getaIntName() {
+ return aIntName;
+ }
+
+ public void setaIntName(int aIntName) {
+ this.aIntName = aIntName;
+ }
+ }
+ ```
+
+ 9. 返回多种类型或者通过 ContextUtils 设置状态码 HIGHWAY 不再支持。 尽管 1.3.0 之前用户也不会在 HIGHWAY 模式下
+ 使用类似下面的代码， 但是在 1.3.0 之前的版本， 这些代码部分确实能够工作。
+
+ ```java
+ @PUT
+ public String sayHi(@PathParam("name") String name) {
+ ContextUtils.getInvocationContext().setStatus(202);
+ return name + " sayhi";
+ }
+ ```
+
+
+***优秀实践***:
+
+如果项目中需要同时使用 REST 和 HIGHWAY 对外提供服务， 并且会使用到一些 HIGHWAY 协议有差异的用法，
+可以将这些接口定义到不同的类中， 使用不一样的 Schema ID 进行区分，比如 `MySchemaHighwayOnly` ,
+`MySchemaRestOnly` , `MySchema` 。
+
+## 使用 Edge Service 场景下 Model 的缺省值
+
+假设业务应用采用 Edge Service 转发请求。 并且定义了一个接口， 有如下 Model 作为参数：
+
+```java
+public class Person {
+ private Integer age = 30;
+ private List<String> items;
+}
+```
+
+用户从浏览器调用这个接口， JSON 内容为 `{}` ， 不传递任何内容， 1.3.0 版本得到的 age = null， items = null 。
+2.0.0 版本 age = 30, items 为空表， 不为 null 。 这个行为是由于 1.3.0 版本 Edge Service 会自动生成一个
Person
+类， 这个类没有缺省值， Edge Service 重新序列化， 造成服务端取到了 null。 弱类型契约没有中间类型， 序列化的结果
+和用户从浏览器传递过来的值一样。
+
+
+## RestTemplate的使用
+
+对于下面的 consumer 和 provider 代码：
+
+```
+// provider
+@PostMapping(path = "/object")
+public Object testObject(@RequestBody Object input)
+
+// consumer
+Object result = restTemplate.postForObject(prefix + "/object",
+ new EmptyObject(), EmptyObject.class);
+```
+
+1.3.0 版本返回的 result 类型为 Map。 2.0.0 版本返回的类型和 postForObject 指定的类型一致，上面的示例
+中，result 类型为 EmptyObject。
+
+下面的代码，1.3.0 和 2.0.0 版本运行的结果是一样的：
+
+```
+List<GenericObjectParam<List<RecursiveObjectParam>>> response =
consumers.getSCBRestTemplate()
+ postForObject("/testListObjectParam", request, List.class);
+```
+
+前提条件是 GenericObjectParam 和 RecursiveObjectParam 在 consumer 的 classpath 中存在对应的
+类，并且 package 和服务端定义的类一样。如果不一样， 则 response 类型为 List<Map>，上面的代码会
+抛出类型转换异常。2.0.0 没有相同 package 的约束，并且在保持兼容的情况下，支持下面的用法：
+
+```
+HttpEntity<SpringmvcBasicRequestModel> requestEntity = new
HttpEntity<>(requestModel, null);
+List<SpringmvcBasicResponseModel> responseModelList =
+ template.exchange("/postListObject", HttpMethod.POST, requestEntity,
+ new ParameterizedTypeReference<List<SpringmvcBasicResponseModel>>() {
+ }).getBody();
+```
+
+这种方式的语义根据清晰，在使用泛型的时候，建议采用这种用法。
+
+在1.3.0版本支持如下用法：
+
+```java
+template.postForEntity(url,
+ "{\"time\":3073113710456,\"date\":3073113710456,\"holder\":\"test\"}",
+ DateTimeModel.class)
+```
+
+即通过 JSON String 的方式传递参数给后台的 DateTimeModel 对象。 由于这种用法在解析的时候存在二义性， 2.0.0
+不再支持这种用法。 可以使用 Map 或者 JsonObject 来传递。
+
+## AsyncRestTemplate的使用
+
+1.3.0 和 2.0.0 中 AsyncRestTemplate 的使用方式一样，没有变化。但是由于 2.0.0 只支持spring 5版
+本，而 spring 5 将 AsyncRestTemplate 标记为废弃状态，开发者在后续开发过程中尽可能不要使
+用 AsyncRestTemplate 。可以使用 CompletableFuture 来替代，可以参考这
+个[例子](https://github.com/apache/servicecomb-samples/pull/41/files)。
+
+## Spring Boot 集成的变化
+
+2.0.0 不再支持 spring 4 和 spring boot 1， 缺省使用 spring 5 和 spring boot 2， 并修改了相
+关 starters 的名称。 可以通过阅
+读 [在Spring Boot中使用java
chassis](../../using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md)
了解
+相关变化。
+
+## 支持 JDK 11
+
+2.0.0 版本可以在 JDK 11 下运行，并进行了简单的集成测试。 2.0.0 支持的核心 JDK 版本仍然是 8， 并没有采用 JDK 11 编译。
+JDK 11 的一个主要变化是后续可能不再支持通过反射改变类的封装性。 这个特性目前有很多地方使用， 2.0.0 版本为了适配 JDK 11，
+某些特性的使用会发生变化。 具体有如下几个特性 ：
+
+* 使用 EventManager 注册事件
+
+在 1.3.0 版本， 允许采用 private 类 或者 内部匿名类作为事件监听对象， 比如：
+
+```java
+public void myMethod() {
+ Object receiveEvent = new Object() {
+ @Subscribe
+ public void onEvent(AlarmEvent circutBreakerEvent) {
+ taskList.add(circutBreakerEvent);
+ }
+ };
+ EventManager.getEventBus().register(receiveEvent);
+}
+```
+
+在 2.0.0 版本不允许，启动的时候会报告异常。 2.0.0 版本注册的事件监听器，必须保证对于 EventManager 类具有可访问性。 通常
+定义的类和 EventManager 不属于同一个 package ， 因此这个类必须是 public 的， 事件处理方法也必须是 public 的。
+
+* 定义接口的 Model 使用匿名内部类
+
+在 1.3.0 版本， 使用匿名内部类作为 REST 接口的 Model 是允许的， 但是 2.0.0 版本不允许。 如果采用这样的类型作为接口参数，
+启动的时候会报告异常。
+
+* 其他方面的影响
+
+由于 JDK 11 不允许通过反射破坏封装， 早期通过反射修改 private 字段的值，来规避一些三方软件的 bug， 以及做一些额外
+定制变得不可行， 使用这些特性 JDK 11 暂时只是打印警告， 在 JDK 13 等更高版本会彻底禁止。 因此业务开发的时候， 尽可能
+不要使用破坏封装的特性。
+
+## 常见问题
+
+* java-chassis运行时依赖于接口定义里面的名字
+
+为了更好的基于swagger对服务进行治理，以及提高客户端代码书写的灵活性，java-chassis要求书写的接口定义代码在编译的时候，带上参数名称信息，否则会报告如下错误：
+
+```
+Caused by: java.lang.IllegalStateException: parameter name is not present,
method=org.apache.servicecomb.samples.porter.file.api.InternalAccessEndpoint:localAccess
+solution:
+ change pom.xml, add compiler argument: -parameters, for example:
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <compilerArgument>-parameters</compilerArgument>
+ </configuration>
+ </plugin>
+```
+
+解决该问题可以通过配置maven compiler plugin， 加上-parameters参数。如果在IDE下面运行，需要设置 build ->
java compilers 在编译参数里面增加-parameters。
+
+* spring 5变更
+
+cse.bean.xml文件如果采用了classpath查找定义文件
+
+```
+<beans xmlns="http://www.springframework.org/schema/beans";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xmlns:p="http://www.springframework.org/schema/p";
+ xmlns:util="http://www.springframework.org/schema/util";
+ xmlns:context="http://www.springframework.org/schema/context";
+ xmlns:tx="http://www.springframework.org/schema/tx";
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans
classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd
+ http://www.springframework.org/schema/tx
http://www.springframework.org/schema/tx/spring-tx-4.1.xsd
http://www.springframework.org/schema/data/jpa
http://www.springframework.org/schema/data/jpa/spring-jpa.xsd
+ http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context-3.0.xsd";>
+```
+
+会报告下面的错误：
+
+```
+[main][WARN][org.springframework.beans.factory.xml.XmlBeanDefinitionReader:48]
Ignored XML validation warning
+org.xml.sax.SAXParseException: schema_reference.4: 无法读取方案文档
'classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd', 原因为 1)
无法找到文档; 2) 无法读取文档; 3) 文档的根元素不是 <xsd:schema>。
+ at
com.sun.org.apache.xerces.internal.util.ErrorHandlerWrapper.createSAXParseException(ErrorHandlerWrapper.java:203)
~[?:1.8.0_131]
+ at
com.sun.org.apache.xerces.internal.util.ErrorHandlerWrapper.warning(ErrorHandlerWrapper.java:99)
[?:1.8.0_131]
+ at
com.sun.org.apache.xerces.internal.impl.XMLErrorReporter.reportError(XMLErrorReporter.java:392)
[?:1.8.0_131]
+```
+
+修改为:
+
+```
+<beans xmlns="http://www.springframework.org/schema/beans";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xmlns:context="http://www.springframework.org/schema/context";
+ xsi:schemaLocation="
+ http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
+ http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd";>
+```
+
+* SCBEngine使用时机
+
+代码
+
+```
+@RestSchema(schemaId = "inspector")
+@Path("/inspector")
+public class InspectorEndpoint {
+ private InspectorConfig inspectorConfig;
+
+ public InspectorEndpoint() {
+ this.inspectorConfig =
SCBEngine.getInstance().getPriorityPropertyManager().createConfigObject(InspectorConfig.class);
+ }
+```
+
+```
+Caused by: java.lang.NullPointerException
+ at org.apache.servicecomb.core.SCBEngine.<init>(SCBEngine.java:126)
+ at org.apache.servicecomb.core.SCBEngine.getInstance(SCBEngine.java:159)
+ at
org.apache.servicecomb.samples.porter.file.api.InspectorEndpoint.<init>(InspectorEndpoint.java:82)
+ at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
+ at
sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62)
+ at
sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
+ at java.lang.reflect.Constructor.newInstance(Constructor.java:423)
+```
+
+不能够在bean的初始化里面使用SCBEngine的实例。这个实例业务需要在事件AFTER_REGISTRY等处理函数中使用。
+
+## 编译错误
+
+2.0.0 相对于 1.0.0 升级了大量三方件，包括netty, vert.x, spring, spring
boot等，直接引用这些组件的代码可能编译失败。同时还对代码进行了一定重构，有些代码使用了java-chassis未公开接口，使用这些接口可能编译失败。下面是一些常见的问题。下面一些PR的修改可以参考：
+
+ *
[升级netty&vertx](https://github.com/apache/servicecomb-java-chassis/pull/1394)
+ * [升级jackson](https://github.com/apache/servicecomb-java-chassis/pull/1381)
+ * [删除spring 4和spring boot
1的支持](https://github.com/apache/servicecomb-java-chassis/pull/1415)
+ * [调整2.x版本spring boot
starter名字](https://github.com/apache/servicecomb-java-chassis/pull/1439)
+
+下面是一些场景的问题：
+
+ * `router.routeWithRegex(regex).handler(CookieHandler.create())` 提示
CookieHandler deprecated，删除这行代码
+ 即可，新版本的vert.x已经默认提供了cookie处理。
+ * io.vertx.ext.web中的 `io.vertx.ext.web.Cookie已过时` ， 修改
+ 为 `io.vertx.core.http.Cookie`
+
+2.0.0 一些可能被外部使用的内部接口调整：
+
+ * `Invocation` 类删除了 `getArgs` 接口， 替换为 `getSwaggerArguments` ， 同时新增了
`getInvocationArguments`，
+ 关于这个变更的说明，请参考新特性介绍文章[弱类型契约](../features/weak-type-contrast.md)。
+ * 删除 `DynamicSchemaLoader` ， 这个类早期版本提供出来是方便注册契约， 最新版本客户端契约发现可以通过服务中心
+ 完成，不再需要这样的功能。
+ *
`CseContext.getInstance().getTransportManager().findTransport(Const.RESTFUL)` 修改
+ 为
`SCBEngine.getInstance().getTransportManager().findTransport(Const.RESTFUL)`
+ * 测试代码可能使用
`CseContext.getInstance().getConsumerProviderManager().setTransport(microserviceName,
transport)` ， 修改
+ 为 `ArchaiusUtils.setProperty("servicecomb.references.transport." +
microserviceName, transport);`
+
+## 已知缺陷
+
+ * 2.0.0 版本将 `servicecomb.service.registry.registerUrlPrefix` 弄丢了。
这个配置项是为一个特殊场景服务的的，
+ 默认值为 false。 在使用 WEB 容器（比如 tomcat） java-chassis的场景下， 如果设置了 context-path， 使用
java-chassis
+ 提供的 RestTemplate 访问服务的时候， 不需要指定 context-path，以保证用户不用关注微服务的部署方式，提供了很大的便利。
+ 但是有些用户的代码是历史遗留代码改造过来的，期望 URL 包含完整的 context-path。 使用 2.0.0 版本如果存在这个特殊要
+ 求， 程序会运行错误，访问接口提示 NOT FOUND。这个问题在 2.0.1 修复。
diff --git a/java-chassis-reference/zh_CN/docs/upgrading/2_0_0T2_0_1.md
b/java-chassis-reference/zh_CN/docs/upgrading/2_0_0T2_0_1.md
new file mode 100644
index 0000000..49689e7
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/upgrading/2_0_0T2_0_1.md
@@ -0,0 +1,13 @@
+# 2.0.0 升级 2.0.1指导
+
+## trace id 记录的变更说明
+
+2.0.0 采用 %marker 记录 trace id， 由于 Marker 被设计为 Filtering 场景， 不适用于记录 trace id，
否则可能导致有些 logger 系统
+产生 OOM。 2.0.1 将 Marker 调整为了 MDC 。 使用指导参考 [2.0.1 新特性介绍： 在日志中记录trace
id](../features/trace-id.md)
+
+## 独立 tomcat (或者其他 web container ) 运行的场景
+
+在使用独立 tomcat 运行的场景， RestServletContextListener 在会在 contextInitialized 环节调用
Log4jUtils.init 初始化 log4j ,
+由于 log4j 目前已经被 log4j2 或者 logback 等替换， 从 2.0.1 开始， 不会调用 Log4jUtils 初始化 log4j 。
如果应用系统需要继续
+使用 log4j， 可以自定义 ServletContextListener ，调用 Log4jUtils.init 初始化 log4j。
+
diff --git a/java-chassis-reference/zh_CN/docs/upgrading/2_0_1T2_1_0.md
b/java-chassis-reference/zh_CN/docs/upgrading/2_0_1T2_1_0.md
new file mode 100644
index 0000000..bf4c21e
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/upgrading/2_0_1T2_1_0.md
@@ -0,0 +1,106 @@
+# 2.0.1 升级 2.1.0指导
+
+## 服务注册发现的变化
+
+2.1.0 对服务注册发现进行了重构，提供了更好的接口 `Discovery` 和 `Registration` 方便开发者提供不同的实现。
+
+在2.0.1及其之前的版本，服务中心(servicecomb-service-center)作为唯一的服务注册发现，不支持扩展，服务中心
+还提供了一个本地版本的实现。具体有如下两种场景：
+
+* 使用服务中心： 这种场景不需要额外配置和引入依赖。
+* 使用本地注册发现
+
+ 需要调用
+
+
System.setProperty(LocalServiceRegistryClientImpl.LOCAL_REGISTRY_FILE_KEY,
"registry.yaml");
+
+ 启用本地注册发现，不需要额外配置依赖。
+
+升级到 2.1.0 版本后， 这两种常见的使用方式调整如下：
+
+* 使用服务中心
+
+ 引入依赖
+
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>registry-service-center</artifactId>
+ </dependency>
+
+* 使用本地注册发现
+
+ 引入依赖
+
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>registry-local</artifactId>
+ </dependency>
+
+ 不需要设置 `LOCAL_REGISTRY_FILE_KEY` 变量。
+
+2.1.0 需要显示的提供 pom 依赖，否则不依赖任何模块， 启动会失败。 同时引入服务中心和本地注册发现也是允许
+的，可以通过配置项关闭其中的部分功能。
+
+```yaml
+servicecomb.local.registry.enabled: true
+servicecomb.service.registry.enabled: true
+```
+
+详细开发指南参考[注册发现说明](../../registry/introduction.md)
+
+## 服务注册发现 API 的变化
+
+如果直接使用了 `RegistryUtils` 接口， 建议切换到 `DiscoveryManager` 或者 `RegistrationManager`，
+尽管 `RegistryUtils` 接口仍然可以使用。
+
+如果直接使用了 `DiscoveryTreee` 接口，2.1. 将服务发现的接口移动到了
`org.apache.servicecomb.registry`，
+当出现编译错误的时候，重新 import 对应的新 package 类即可。
+
+如果直接使用了 `ServiceRegistry` 接口， 2.1 将对应接口移动到了 `RegistrationManager`。
+
+## 参数校验的变化
+
+参数校验失败，早期版本采用 `ResourceBundleMessageInterpolator` 来生成错误消息。 由于这个类依赖于
+`Expression Language` 库，而这个库 JAVA 慢慢的不再提供支持，从 2.1.0 版本开始，切换为
`ParameterMessageInterpolator`
+来生成错误消息。 然后系统删除来对于 `jakarta.el` 的依赖。
+
+开发者仍然可以继续使用`ResourceBundleMessageInterpolator` 来生成错误消息。需要额外的做下面的配置：
+
+* 项目中引入依赖
+
+```xml
+ <dependency>
+ <groupId>org.glassfish</groupId>
+ <artifactId>jakarta.el</artifactId>
+ </dependency>
+```
+
+* 增加配置项
+
+```yaml
+servicecomb:
+ filters:
+ validation:
+ useResourceBundleMessageInterpolator: true
+```
+
+## Logger 系统的变化
+
+servicecomb 默认使用 Slf4j 记录日志，不集成具体实现，开发者可以通过引入具体的实现依赖使用不同的 Logger。
+早期的版本 `solution-basic` 包含了 log4j2 的依赖， 2.1.0 移除了这部分依赖， 开发者如果通过这种方式
+使用 log4j2 ， 可能需要显示的增加 log4j2 的依赖， 比如：
+
+```xml
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-slf4j-impl</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-api</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.logging.log4j</groupId>
+ <artifactId>log4j-core</artifactId>
+ </dependency>
+```
\ No newline at end of file
diff --git a/java-chassis-reference/zh_CN/docs/upgrading/2_1_0T2_1_1.md
b/java-chassis-reference/zh_CN/docs/upgrading/2_1_0T2_1_1.md
new file mode 100644
index 0000000..6b37f42
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/upgrading/2_1_0T2_1_1.md
@@ -0,0 +1,16 @@
+# 2.1.0 升级 2.1.1指导
+
+## 使用 zero config 服务发现的场景
+
+zero config 服务发现是 2.1.0 新增的功能， 2.1.1 对发现过程中交换的报文格式进行了优化。 如果使用了 zero config
+功能， 升级到 2.1.1 的时候，需要对相关服务也同时做升级， 否则无法发现实例。
+
+
+## 使用 `swagger-generator-spring-data` 扩展，支持 `Page` 接口参数的场景
+
+由于 `spring-data` 不同的版本的接口差异很大， 这个模块支持的扩展对应的 `spring-data` 版本为
+`2.1.9.RELEASE`， 并且对于 `Sort` 接口的序列化没完整支持。 开发者如果使用 `spring-data`
+的不同版本， 或者需要对 `spring-data` 的不同接口提供扩展支持， 需要在项目中引入需要的
+版本， 并参考 `swagger-generator-spring-data` 实现自己的扩展，而不是直接依赖于
+`swagger-generator-spring-data` 模块。
+
diff --git a/java-chassis-reference/zh_CN/docs/upgrading/2_1_1T2_1_5.md
b/java-chassis-reference/zh_CN/docs/upgrading/2_1_1T2_1_5.md
new file mode 100644
index 0000000..0b63348
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/upgrading/2_1_1T2_1_5.md
@@ -0,0 +1,61 @@
+# 2.1.1 升级 2.1.5 指导
+
+## `org.apache.servicecomb.swagger.invocation.Response` 属性 headers 类型调整
+
+为了更好的和 HTTP 协议标准保持兼容， 将 Response 的 headers 类型由
+`org.apache.servicecomb.swagger.invocation.response.Headers` 修改为
+`io.vertx.core.MultiMap`， 同时删除了类
`org.apache.servicecomb.swagger.invocation.response.Headers`
+以支持大小写无关的 HTTP header。 修改前 header 的 key 是区分大小写的，
+修改后， 不区分大小写。 该调整也涉及到和 header 操作有关的 getter， setter 方法的调整，使用了老方法的地方会编译出错，
+修改为对应的新方法即可。
+
+## `swagger-generator-spring-data` 调整
+
+这个模块提供了 `Page`、`Pagable`、`Order` 等接口的序列化支持。2.1.5 升级了 spring boot 版本，
这些接口存在变更，因此序列化
+结果发生了改变。 如果产品使用了这些类作为外部接口，需要考虑前端返回的 json 格式的变化对产品功能的影响。
+
+## `foudation-common` 调整
+
+这个模块提供了将时间类型数据格式化的功能。在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/upgrading/2_1_5T2_6_0.md
b/java-chassis-reference/zh_CN/docs/upgrading/2_1_5T2_6_0.md
new file mode 100644
index 0000000..a4f6bd4
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/upgrading/2_1_5T2_6_0.md
@@ -0,0 +1,45 @@
+# 2.1.5 升级 2.6.0 指导
+
+## 支持`@NotBlank`和`@NotEmpty`
+
+参考下面的例子。这个新的特性在一些特殊的情况下可能导致业务故障，比如业务错误的加上了这些标签，但是实际上不会做参数校验，现在变更为校验。
+
+```java
+public class Teacher {
+
+ @NotBlank
+ private String name;
+
+ private String age;
+
+ // getters, setters
+}
+```
+
+## `servicecomb.rest.client.connection.idleTimeoutInSeconds` 缺省值修改为 30s
+
+因为服务端HTTP连接的Idle Timeout时间设置通常是60s（包括Vert.x、Tomcat等），为了尽可能降低客户端使用已经关闭了连接
+的概率，调整了这个参数的默认值。如果业务系统中没有设置这个参数，并且有些场景将 `servicecomb.request.timeout` 设置
+为大于30s， 那么可能导致这些请求提前超时。
+
+更多详细信息可以[参考案例](https://github.com/apache/servicecomb-java-chassis/issues/2603)。
+
+## `netty`和`vert.x` 升级
+
+2.6.0目前使用了最新的 `netty` 和 `vert.x` 版本， 这两个软件最新版本做了较多的重构，需要保证版本匹配才能够正常工作。
+业务尽可能不要自行单独调整单个软件的版本，保持和java-chassis使用一致，否则容易导致一些兼容性问题。 未来的版本，两个软件
+的兼容情况应该会有所改善，建议业务升级后，及时调整这两个软件的废弃用法。
+
+这两个软件升级目前已知的可能影响业务功能的点包括：
+
+* `servicecomb.rest.server.maxFormAttributeSize` 的缺省值为 8192。
java-chassis的缺省值使用了 `vert.x`
+ 的缺省值。这个值在最近的几个版本中，发生过几次变更，从无限制变更为1024， 变更为2048，到现在的8192。 如果业务需要
+ 依赖比较大的值，建议在配置文件设置适合应用场景的限制，不跟随这个缺省值。
+
+## `Spring` 和 `Spring Boot` 升级
+
+2.6.0目前使用了最新的 `Spring` 和 `Spring Boot` 版本，这个版本存在少量的变更，可能在某些特殊场景下影响业务功能。已知的情况包括：
+
+* 对URL进行了更加严格的校验，以符合HTTP协议标准。早期一些不符合标准的URL可能会报告错误。
+* `StringUtils`的`isEmpty`方法废弃了，这个方法容易造成误用，建议切换使用其他接口或者使用Commons Lang组件的接口。
+
diff --git a/java-chassis-reference/zh_CN/docs/upgrading/2_6_0T2_8_0.md
b/java-chassis-reference/zh_CN/docs/upgrading/2_6_0T2_8_0.md
new file mode 100644
index 0000000..35d97c8
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/upgrading/2_6_0T2_8_0.md
@@ -0,0 +1,12 @@
+# 2.6.0 升级 2.8.0 指导
+
+## `netty`和`vert.x` 升级
+
+2.8.0目前使用了最新的 `netty` 和 `vert.x` 版本。
+
+* `servicecomb.rest.server.http2.maxHeaderListSize` 的缺省值由`Integer.MAX_VALUE`
改为 8192。
+ java-chassis的缺省值使用了 `vert.x`的缺省值。 如果业务需要依赖比较大的值，建议在配置文件设置适合应用场景的限制，不跟随这个缺省值。
+
+## `Spring` 和 `Spring Boot` 升级
+
+2.8.0目前使用了最新的 `Spring` 和 `Spring Boot` 版本。
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_8_0T3_0_0.md
b/java-chassis-reference/zh_CN/docs/upgrading/2_8_0T3_0_0.md
similarity index 100%
rename from
java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_8_0T3_0_0.md
rename to java-chassis-reference/zh_CN/docs/upgrading/2_8_0T3_0_0.md
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml
b/java-chassis-reference/zh_CN/mkdocs.yml
index 6483eb8..2a70aa7 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -100,13 +100,34 @@ nav:
- 应用性能监控: general-development/metrics.md
- 微服务调用链: general-development/microservice-invocation-chain.md
- Access Log配置: build-provider/access-log-configuration.md
-
- 专题文章:
- - 特性介绍: featured-topics/features.md
- - 技术解密: featured-topics/secrets.md
- - 升级指导: featured-topics/upgrading.md
+ - 特性介绍： Edge Service 通用的 HTTP 转发器 CommonHttpEdgeDispatcher:
featured-topics/http-dispatcher.md
+ - 特性介绍： date和date-time: featured-topics/date-time.md
- 兼容问题和兼容性策略: featured-topics/compatibility.md
- 性能问题分析和调优: featured-topics/performance.md
+- 技术解密:
+ - Java Chassis 3技术解密：负载均衡选择器: secrets/load-balancer.md
+ - Java Chassis 3技术解密：注册中心分区隔离: secrets/zone-isolation.md
+ - Java Chassis 3技术解密：多种序列化方式支持: secrets/serialization.md
+ - Java Chassis 3技术解密：熔断机制的改进路程: secrets/circuit-breaker.md
+ - Java Chassis 3技术解密：过载状态下的快速失败: secrets/fail-fast.md
+ - Java Chassis 3技术解密：应用视角的配置管理: secrets/applied-config.md
+ - Java Chassis 3技术解密：易扩展的多种注册中心支持: secrets/registries.md
+ - Java Chassis 3技术解密：与Spring Cloud的互操作: secrets/interoperability.md
+ - Java Chassis 3技术解密：ZooKeeper注册和配置中心: secrets/zookeeper.md
+ - Java Chassis 3技术解密：契约优先（API First）开发: secrets/api-first.md
+ - Java Chassis 3技术解密：接口维度负载均衡: secrets/load-balancer-operation.md
+ - Java Chassis 3技术解密：实用的可观测性: secrets/observability.md
+ - Java Chassis 3技术解密：流式响应和人工智能应用开发: secrets/sse.md
+ - Java Chassis 3技术解密：WebSocket和人工智能应用开发: secrets/websocket.md
+- 升级指导:
+ - 1.3.0 升级 2.0.0指导: upgrading/1_3_0T2_0_0.md
+ - 2.0.0 升级 2.0.1指导: upgrading/2_0_0T2_0_1.md
+ - 2.0.1 升级 2.1.0指导: upgrading/2_0_1T2_1_0.md
+ - 2.1.0 升级 2.1.1指导: upgrading/2_1_0T2_1_1.md
+ - 2.1.1 升级 2.1.5指导: upgrading/2_1_1T2_1_5.md
+ - 2.1.5 升级 2.6.0指导: upgrading/2_1_5T2_6_0.md
+ - 2.8.0 升级 3.0.0指导: upgrading/2_8_0T3_0_0.md
- 常用配置项参考:
- REST Transport Client 配置项: config-reference/rest-transport-client.md
- 常见问题:
