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 36b3f36 docs improvement (#306)
36b3f36 is described below
commit 36b3f361cb11654d1d95042efd1b57476f56808f
Author: liubao68 <[email protected]>
AuthorDate: Wed Dec 13 12:07:16 2023 +0800
docs improvement (#306)
---
java-chassis-reference/zh_CN/docs/book.json | 5 -
.../zh_CN/docs/build-consumer/catalog.md | 9 -
.../docs/build-consumer/using-AsyncRestTemplate.md | 79 ------
.../zh_CN/docs/build-provider/catalog.md | 19 --
.../zh_CN/docs/featured-topics/features.md | 4 +-
.../featured-topics/features/weak-type-contrast.md | 206 --------------
.../zh_CN/docs/featured-topics/upgrading.md | 6 -
.../docs/featured-topics/upgrading/1_3_0T2_0_0.md | 314 ---------------------
.../docs/featured-topics/upgrading/2_0_0T2_0_1.md | 13 -
.../docs/featured-topics/upgrading/2_0_1T2_1_0.md | 106 -------
.../docs/featured-topics/upgrading/2_1_0T2_1_1.md | 16 --
.../docs/featured-topics/upgrading/2_1_1T2_1_5.md | 61 ----
.../docs/featured-topics/upgrading/2_1_5T2_6_0.md | 45 ---
.../docs/featured-topics/upgrading/2_6_0T2_8_0.md | 12 -
java-chassis-reference/zh_CN/docs/index.md | 36 ++-
.../zh_CN/docs/introduce3.x.x.md | 8 +-
.../zh_CN/docs/start/architecture.md | 16 --
.../zh_CN/docs/start/architecture.png | Bin 18771 -> 0 bytes
java-chassis-reference/zh_CN/mkdocs.yml | 66 +++--
19 files changed, 78 insertions(+), 943 deletions(-)
diff --git a/java-chassis-reference/zh_CN/docs/book.json
b/java-chassis-reference/zh_CN/docs/book.json
deleted file mode 100644
index d1b948c..0000000
--- a/java-chassis-reference/zh_CN/docs/book.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
- "structure": {
- "readme": "introduction.md"
- }
-}
\ No newline at end of file
diff --git a/java-chassis-reference/zh_CN/docs/build-consumer/catalog.md
b/java-chassis-reference/zh_CN/docs/build-consumer/catalog.md
deleted file mode 100644
index 9321518..0000000
--- a/java-chassis-reference/zh_CN/docs/build-consumer/catalog.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# 开发服务消费者
-
-* [消费者通用配置项](common-configuration.md)
-* [使用RestTemplate开发服务消费者](using-resttemplate.md)
-* [使用AsyncRestTemplate开发服务消费者](using-AsyncRestTemplate.md)
-* [使用RPC方式开发服务消费者](develop-consumer-using-rpc.md)
-* [泛化调用](../featured-topics/features/invoker.md)
-* [使用服务契约](with-contract.md)
-* [调用第三方REST服务](3rd-party-service-invoke.md)
\ No newline at end of file
diff --git
a/java-chassis-reference/zh_CN/docs/build-consumer/using-AsyncRestTemplate.md
b/java-chassis-reference/zh_CN/docs/build-consumer/using-AsyncRestTemplate.md
deleted file mode 100644
index a5816f8..0000000
---
a/java-chassis-reference/zh_CN/docs/build-consumer/using-AsyncRestTemplate.md
+++ /dev/null
@@ -1,79 +0,0 @@
-# 使用AsyncRestTemplate开发服务消费者
-
-***注意***: AsyncRestTemplate 接口在新版本的 Spring 接口中已经废弃。 建议使用异步 RPC 接口访问， 例如：
-
-```
-interface Hello {
- CompletableFuture<String> sayHi(String name);
-}
-
-@Component
-public class SomeBean {
- ......
-
- @RpcReference(microserviceName = "helloService", schemaId = "helloSchema")
- private Hello hello;
-
- ......
-}
-```
-
-## 概念阐述
-
-AsyncRestTemplate 开发方式允许用户异步的进行服务调用。具体的业务流程和 RestTemplate 类似，只是这里以异步的形式进行服务的调用。
-
-## 示例代码
-
-AsyncRestTemplate 实例通过 new CseAsyncRestTemplate（）来创建和获取，再使用该实例通过自定义的 URL
进行服务调用。
-
-* Spring MVC 客户端代码示例
-
-```java
-
-@Component
-public class SpringmvcConsumerMain {
- private static final Logger LOG =
LoggerFactory.getLogger(SpringmvcConsumerMain.class);
-
- public static void main(String[] args) throws Exception {
- init();
- Person person = new Person();
- person.setName("ServiceComb/Java Chassis");
- //AsyncRestTemplate Consumer
- CseAsyncRestTemplate cseAsyncRestTemplate = new CseAsyncRestTemplate();
- ListenableFuture<ResponseEntity<String>> responseEntityListenableFuture =
cseAsyncRestTemplate
- .postForEntity("cse://springmvc/springmvchello/sayhi?name=Java
Chassis", null, String.class);
- ResponseEntity<String> responseEntity =
responseEntityListenableFuture.get();
- System.out.println("AsyncRestTemplate Consumer sayHi services: " +
responseEntity.getBody());
-
- HttpEntity<Person> entity = new HttpEntity<>(person);
- ListenableFuture<ResponseEntity<String>> listenableFuture =
cseAsyncRestTemplate
- .exchange("cse://springmvc/springmvchello/sayhello", HttpMethod.POST,
entity, String.class);
- // ResponseEntity<String> responseEntity1 = listenableFuture.get();
- // System.out.println("AsyncRestTemplate Consumer sayHello services: "
+ responseEntity1.getBody());
- //设置回调函数
- listenableFuture.addCallback(
- new ListenableFutureCallback<ResponseEntity<String>>() {
- @Override
- public void onFailure(Throwable ex) {
- LOG.error("AsyncResTemplate Consumer catched exception when
sayHello, ", ex);
- }
-
- @Override
- public void onSuccess(ResponseEntity<String> result) {
- System.out.println("AsyncRestTemplate Consumer sayHello services:
" + result.getBody());
- }
- });
- }
-
- public static void init() throws Exception {
- Log4jUtils.init();
- BeanUtils.init();
- }
-}
-
-```
-
-> 说明 ：
->
-> * URL 的格式和 RestTemplate 一样，具体可以参考 restTemplate
-> * 这里用自定义的 ListenableFuture
类来作为占位符，获取远程调用结束后可能获取的结果。同时也可以自定义回调函数，对可能返回的结果进行分批处理。
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
b/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
deleted file mode 100644
index 6edd2b5..0000000
--- a/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# 开发服务提供者
-
-* [理解服务契约](define-contract.md)
-* [用JAX-RS开发微服务](jaxrs.md)
-* [用SpringMVC开发微服务](springmvc.md)
-* [用透明RPC开发微服务](transparent-rpc.md)
-* [只发布interface的方法为服务接口](use-interface.md)
-* [异步处理](reactive.md)
-* [使用 Context 参数](context-param.md)
-* [多个返回值和错误码](multi-code.md)
-* [使用Swagger注解](swagger-annotation.md)
-* [接口定义和数据类型](interface-constraints.md)
-* [服务监听地址和发布地址](listen-address-and-publish-address.md)
-* [线程池](thread-pool.md)
-* [服务启动事件](event-listener.md)
-* [参数效验](parameter-validator.md)
-* [程序启动逻辑](bootup.md)
-* [IPV6配置和使用](ipv6-configuration.md)
-* [Access Log配置](access-log-configuration.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
index 3297c12..d53a390 100644
--- a/java-chassis-reference/zh_CN/docs/featured-topics/features.md
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/features.md
@@ -1,8 +1,8 @@
# 新功能介绍系列文章
-* [2.0.0 新特性介绍： 弱类型契约](features/weak-type-contrast.md)
* [2.0.0 新特性介绍： 多配置中心支持](features/configuration-sources.md)
* [2.0.1 新特性介绍： date和date-time](features/date-time.md)
* [2.0.1 新特性介绍： 在日志中记录trace id](features/trace-id.md)
* [2.0.1 新特性介绍： 泛化调用](features/invoker.md)
-* [2.0.2 新特性介绍： Edge Service 通用的 HTTP 转发器
CommonHttpEdgeDispatcher](features/http-dispatcher.md)
\ No newline at end of file
+* [2.0.2 新特性介绍： Edge Service 通用的 HTTP 转发器
CommonHttpEdgeDispatcher](features/http-dispatcher.md)
+*
\ No newline at end of file
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/features/weak-type-contrast.md
b/java-chassis-reference/zh_CN/docs/featured-topics/features/weak-type-contrast.md
deleted file mode 100644
index d286f99..0000000
---
a/java-chassis-reference/zh_CN/docs/featured-topics/features/weak-type-contrast.md
+++ /dev/null
@@ -1,206 +0,0 @@
-# 2.0.0 新特性介绍： 弱类型契约
-
-"以契约为中心" 是 Java Chassis 的核心设计理念。 “契约” 扮演着用户与开发者，开发者与开发者之间的沟通桥梁。
-举几个简单的例子。
-
-开发者发布了一个微服务A，同时发布了一份契约文件：
-
-```yaml
-swagger: '2.0'
-info:
- title: rest api
- version: 1.0.0
-
-basePath: /controller
-produces:
- - application/json
-
-paths:
- /add:
- get:
- operationId: add
- parameters:
- - name: a
- in: query
- required: true
- type: integer
- format: int32
- - name: b
- in: query
- required: true
- type: integer
- format: int32
- responses:
- "200":
- description: add numer
- schema:
- type: integer
- format: int32
-```
-
-微服务A的用户可以基于这份契约，使用浏览器访问`add`接口，也可以在自己的微服务B中，使用`RestTemplate`
-调用`add`接口，用户不需要知道微服务A的实现细节，也不需要依赖任何微服务A提供的接口，微服务B保持完全
-与微服务A独立。只要契约不变，微服务B就可以保持不变。
-
-作为微服务A的其他开发者，可以基于契约开发治理功能，不需要知道`add`接口的实现细节。比如可以给`add`
-接口增加流量控制
`servicecomb.flowcontrol.Provider.qps.limit.[ServiceA].[Controller].[add]=1000`，
-限制其流量为1000 TPS；还可以基于 `add` 接口的参数做灰度发布，在灰度发布代码里面可能会存在下面的代码片段：
-`invocation.getSwaggerArgument("a")` 来获取参数值。
-
-"以契约为中心"是保持微服务"独立性"非常重要的手段，“独立开发、独立交付”是微服务被引入，提升软件工程能力
-最重要的价值。
-
-本文重点介绍2.0.0版本引入的“弱类型契约”，以及它与之前“强类型契约”之间的差别与联系。
-
-## 弱类型契约 vs 强类型契约
-
-弱类型契约和强类型契约的共同点都是"以契约为中心"，因此弱类型契约并没有改变 Java Chassis 的整体设计理念，
-而是在实现层面发生了一些变化，进而影响到部分开发体验。2.0.0之前的版本是强类型契约。产生强类型契约和一些技术背景
-有关系，讨论的起点可以从 Java Chassis Highway 的 ProtoBuffer 讲起。
-
-熟悉 ProtoBuffer 的开发者都知道， ProtoBuffer 主要被用于 gRPC， 其他处理 ProtoBuffer 编解码的库还有
ProtoStuff。
-gRPC 需要写 IDL 文件， 然后根据 IDL 生成运行时的代码，在gRPC的运行过程中，处理编解码的类在编译时间就已经确定，无法
-更改。ProtoStuff 提供的类库比 gRPC 更加灵活，对于同样的 IDL 文件，可以在运行时指定不同的类进行序列化和反序列化。
-无论如何，在一个微服务里面，如果存在一个契约（IDL文件），那么必须在编译时就确定这个契约对应的类是什么。这个类可以
-有一个，也可以有多个，但是必须在编译的时候确定类的类型。
-
-强类型契约可以定义为：在一个微服务里面，契约必须存在一个或者多个编译时确定的类型与它对应。在2.0.0版本之前，这个对应
-的类型是在契约文件里面指定的，比如`x-java-interface:
org.apache.servicecomb.demo.controller.Controller` 。 开发者
-可能注意到在消费端代码，可以不依赖任何提供端的类，这是因为消费端的代码会根据契约描述，采用 `javassist` 工具动态生成
-一个类型与契约对应，不同版本的契约需要生成不一样的类型，如果灰度环境版本过多，就可能导致内存过大的问题，特别是在边缘
-(Edge Service）服务里面。
-
-强类型契约的一个外在体现就是下面的代码：
-
-```java
-Person result = restTemplate.postForObject("/getPerson", null, Person.class);
-```
-
-可能抛出 `ClassCastException` 异常。 因为 `getPerson` 的返回值的类型在编译时已经确定， 如果返回值 Person 类型
-与编译时的类型不一样，就会报告 `ClassCastException` 异常。
-
-了解了强类型契约后，弱类型契约的定义就很明显了： 在一个微服务里面，契约可以存在一个或者多个编译时确定的类型与它对应，
-也可以不存在编译时确定的类型与它对应。 引入弱类型契约后，下面的代码：
-
-```java
-Person1 result = restTemplate.postForObject("/getPerson", null, Person1.class);
-Person2 result = restTemplate.postForObject("/getPerson", null, Person2.class);
-```
-
-都不会报告 `ClassCastException` 异常，只需要 `Person1` 和 `Person2` 的定义都能够和契约对应。 由此可以看出，弱类型
-契约在使用方式上更加灵活，去掉了动态创建类的过程，降低了内存占用，缩短了微服务启动时间。
-
-## 利用弱类型契约增强写代码的灵活性
-
-弱类型契约不要求提供者与消费者使用一样的类型，在代码书写上提供了很大的方便。比如提供者有如下接口：
-
-```java
-@RestSchema(schemaId = "weakSpringmvc")
-@RequestMapping(path = "/weakSpringmvc", produces =
MediaType.APPLICATION_JSON_VALUE)
-public class WeakSpringmvc {
- @GetMapping(path = "/diffNames")
- @ApiOperation(value = "differentName", nickname = "differentName")
- public int diffNames(@RequestParam("x") int a, @RequestParam("y") int b) {
- return a * 2 + b;
- }
-
- @GetMapping(path = "/genericParams")
- @ApiOperation(value = "genericParams", nickname = "genericParams")
- public List<List<String>> genericParams(@RequestParam("code") int code,
@RequestBody List<List<String>> names) {
- return names;
- }
-
- @GetMapping(path = "/genericParamsModel")
- @ApiOperation(value = "genericParamsModel", nickname = "genericParamsModel")
- public GenericsModel genericParamsModel(@RequestParam("code") int code,
@RequestBody GenericsModel model) {
- return model;
- }
-
- @GetMapping(path = "/specialNameModel")
- @ApiOperation(value = "specialNameModel", nickname = "specialNameModel")
- public SpecialNameModel specialNameModel(@RequestParam("code") int code,
@RequestBody SpecialNameModel model) {
- return model;
- }
-}
-```
-
-而消费者只需要访问其中一个接口diffNames，只需要定义一个非常简单的接口：
-
-```java
-interface DiffNames {
- int differentName(int x, int y);
-}
-
-@RpcReference(microserviceName = "springmvc", schemaId = "weakSpringmvc")
-private DiffNames diffNames;
-```
-
-其中接口名称是和契约里面的接口名称一致 `differentName`， 而不是和服务端的代码一致 `diffNames`。 契约包含 `x` 和
-`y` 两个参数， 并且契约的参数是顺序无关的， 下面的代码也是可以访问同一个接口的：
-
-```java
-interface DiffNames2 {
- int differentName(int y, int x);
-}
-
-@RpcReference(microserviceName = "springmvc", schemaId = "weakSpringmvc")
-private DiffNames2 diffNames2;
-```
-
-需要注意的是，2.0.0 版本要求保留参数名称， 在编译代码的时候，需要加上 -parameters 编译参数。
-
-开发者还可以通过 RestTemplate 调用这个接口：
-
-```java
-restTemplate.getForObject("cse://springmvc/weakSpringmvc/diffNames?x=2&y=3",
Integer.class)
-```
-
-或者采用 `InvokerUtils` 调用：
-
-```java
-Map<String, Object> args = new HashMap<>();
-args.put("x", 2);
-args.put("y", 3);
-InvokerUtils.syncInvoke("springmvc", "weakSpringmvc", "differentName", args);
-```
-
-## 弱类型契约的治理功能
-
-弱类型契约在 `Invocation` 里面提供了独立的方法，让开发者开发治理功能更加容易。
-
-```java
- public Map<String, Object> getInvocationArguments() {
- return this.invocationArguments;
- }
-
- public Map<String, Object> getSwaggerArguments() {
- return this.swaggerArguments;
- }
-
- public Object getInvocationArgument(String name) {
- return this.invocationArguments.get(name);
- }
-
- public Object getSwaggerArgument(String name) {
- return this.swaggerArguments.get(name);
- }
-```
-
-`getSwaggerArguments` 始终获取的是和契约对应的参数，如果契约为 `x` 和 `y` 两个 query 参数， 那么得到的参数就是
-包含 `x` 和 `y` 的 Map 。 `getInvocationArgument` 获取的是实际类型参数， 在服务提供者，这个参数列表的个数和类型
-和实际的 Method 的列表对应， 比如可能包含 `InvocationContext` , `HttpServletRequest` 等注入参数。
还有很多情况，
-契约参数和类型参数不对应，比如聚合参数的情况，契约参数是多个 query 参数， 而类型参数是一个 POJO； 再比如 POJO 接口
-定义的时候， 类型参数可能是多个， 而契约参数只有一个 body 参数。 在服务消费者，如果用户采用 POJO 方式调用服务提供者，
-两个接口的返回的值与服务提供者类似，存在语义差别；如果采用 RestTemplate 或者 InvokerUtils 调用， 那么两个接口返回的
-内容一样，都是契约参数。在边缘服务， 两个接口返回的都是契约参数。 这种行为体现了弱类型契约的语义： 是否存在编译时
-类型与契约对应。
-
-## 弱类型契约带来的一些变更
-
-总体而言，对于 `REST` 通信模式， 弱类型契约不仅增强了写代码的灵活性， 还完整保留了强类型契约的写代码方式，几乎不
-存在用户需要感知的变更。 对于 `HIGHWAY` 通信模式， 由于底层采用 ProtoBuffer 编码， 而 ProtoBuffer 天然就是一种
-强类型契约的编解码过程， java-chassis 为了支持弱类型契约， 做了大量努力， 在一些边界条件处理上与弱类型契约存在
-变更，两个版本的编解码是不兼容的，需要同时升级提供者和消费者。 在编码方式上，差异主要体现在对于缺省值的处理，对于
-`null` 的处理等问题上， 详细参考[1.3.0 升级 2.0.0指导](../upgrading/1_3_0T2_0_0.md) 。
-
-
\ No newline at end of file
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md
b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md
index 55e3080..fc8d479 100644
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading.md
@@ -1,9 +1,3 @@
# 升级指导系列文章
-* [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.x 升级 3.0.0指导](upgrading/2_8_0T3_0_0.md)
diff --git
a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/1_3_0T2_0_0.md
b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/1_3_0T2_0_0.md
deleted file mode 100644
index eaa3f97..0000000
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/1_3_0T2_0_0.md
+++ /dev/null
@@ -1,314 +0,0 @@
-# 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/featured-topics/upgrading/2_0_0T2_0_1.md
b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_0T2_0_1.md
deleted file mode 100644
index 49689e7..0000000
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_0T2_0_1.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# 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/featured-topics/upgrading/2_0_1T2_1_0.md
b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_1T2_1_0.md
deleted file mode 100644
index bf4c21e..0000000
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_0_1T2_1_0.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# 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/featured-topics/upgrading/2_1_0T2_1_1.md
b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_1_0T2_1_1.md
deleted file mode 100644
index 6b37f42..0000000
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_1_0T2_1_1.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# 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/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
deleted file mode 100644
index 0b63348..0000000
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_1_1T2_1_5.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# 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/featured-topics/upgrading/2_1_5T2_6_0.md
b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_1_5T2_6_0.md
deleted file mode 100644
index a4f6bd4..0000000
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_1_5T2_6_0.md
+++ /dev/null
@@ -1,45 +0,0 @@
-# 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/featured-topics/upgrading/2_6_0T2_8_0.md
b/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_6_0T2_8_0.md
deleted file mode 100644
index 35d97c8..0000000
--- a/java-chassis-reference/zh_CN/docs/featured-topics/upgrading/2_6_0T2_8_0.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# 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/index.md
b/java-chassis-reference/zh_CN/docs/index.md
index 4dc2430..dc298ae 100644
--- a/java-chassis-reference/zh_CN/docs/index.md
+++ b/java-chassis-reference/zh_CN/docs/index.md
@@ -9,13 +9,12 @@ Java Chassis 给开发者提供一个快速构建微服务的 JAVA SDK 。它包
开发者可以通过下面的链接获取其他版本的帮助文档。
-| 适用版本 | 正式发布地址 | 预览版本地址
|
-|:------|:--------------------------------------------------------|:----------------------------------------------------------|
-| 3.x.x | [中文][apache.zh_CN], [English][apache.en_US] |
[中文][preview.zh_CN], [English][preview.en_US] |
-| 2.8.x | [中文][apache.zh_CN.2.8.x], [English][apache.en_US.2.8.x] |
[中文][preview.zh_CN.2.8.x], [English][preview.en_US.2.8.x] |
-| 1.3.x | [中文][apache.zh_CN.1.3.x], [English][apache.en_US.1.3.x] |
[中文][preview.zh_CN.1.3.x], [English][preview.en_US.1.3.x] |
+| 适用版本 | 正式发布地址 |
预览版本地址 |
+|:---------------|:--------------------------------------------------------|:----------------------------------------------------------|
+| Java Chassis 3 | [中文][apache.zh_CN], [English][apache.en_US] |
[中文][preview.zh_CN], [English][preview.en_US] |
+| Java Chassis 2 | [中文][apache.zh_CN.2.8.x], [English][apache.en_US.2.8.x] |
[中文][preview.zh_CN.2.8.x], [English][preview.en_US.2.8.x] |
+| Java Chassis 1 | [中文][apache.zh_CN.1.3.x], [English][apache.en_US.1.3.x] |
[中文][preview.zh_CN.1.3.x], [English][preview.en_US.1.3.x] |
->>> 备注：当前Java Chassis 2.8.x 和 3.x.x 英文文档缺少翻译，非常期待您的帮助支持。
[apache.zh_CN]: https://servicecomb.apache.org/references/java-chassis/zh_CN/
[apache.en_US]: https://servicecomb.apache.org/references/java-chassis/en_US/
@@ -31,6 +30,29 @@ Java Chassis 给开发者提供一个快速构建微服务的 JAVA SDK 。它包
[preview.zh_CN.1.3.x]:
https://huaweicse.github.io/servicecomb-java-chassis-doc/java-chassis/1.x/zh_CN/
[preview.en_US.1.3.x]:
https://huaweicse.github.io/servicecomb-java-chassis-doc/java-chassis/1.x/en_US/
+## 术语表
+
+| 缩略语 | 英文词汇 | 中文词汇 | 解释
|
+|:------------------:|:------------------:|:-----:|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Application | Application | 应用 |
应用代表一个软件应用的逻辑实体，表示一个有业务功能呈现给用户的计算机软件应用。一个以微服务化架构构建的应用通常由多个微服务组成。
|
+| Service | Service | 微服务 |
微服务是一种轻量级SOA架构，通常用来描述广泛用于云应用、互联网应用的一种松耦合分布式架构。
|
+| Instance | Instance | 微服务实例 |
一个微服务的最小运行和部署单元，通常对应一个应用进程。
|
+| Provider | Provider | 服务提供者 | 在微服务调用关系中处于被调用一方的服务。
|
+| Consumer | Consumer | 服务消费者 | 在微服务调用关系中处于调用发起方的服务。
|
+| Schema | Schema | 微服务契约 |
微服务契约是对外接口的OpenAPI表示。OpenAPI增强了微服务的可见性，方便服务的分发、使用和治理。
|
+| Code Style | Code Style | 编程模型 | 编程模型指如何进行服务接口开发和调用，Java
Chassis提供了Spring Web MVC、JAX RS等编程模型。编程模型独立于处理链和通信模型
|
+| Filter | Filter | 处理链 |
处理链定义了一个请求的处理流程，包括编解码、服务治理、网络发送等。
|
+| Transport | Transport | 通信模型 |
通信模型定义了对象如何编解码，使用什么协议传输等。Java Chassis提供了REST、HIGHWAY等通信模型。
|
+| Load Balance | Load Balance | 负载均衡 |
当应用访问一个具有多个实例的微服务时，会涉及到路由负载均衡。可以通过配置文件配置负载均衡策略，支持随机，轮询、会话保持和基于响应时间的权值等多种负载均衡路由策略。
|
+| Rate Limiting | Rate Limiting | 限流 |
当资源成为瓶颈时，服务框架需要对消费者的访问请求做限流，启动流控保护机制。在服务消费者端和提供者端均可进行流量控制。在服务消费端，可以限制发往某个微服务提供者的请求频率；在服务提供端，可以限制每个微服务消费端发过来的请求频率，也可以根据服务提供端资源消耗情况确定总的请求频率限制，防止服务因资源耗尽而崩溃。
|
+| Service Degrade | Service Degrade | 降级 |
服务降级主要包括屏蔽降级和容错降级两种策略：屏蔽降级是指当外界的触发条件达到某个临界值时，由运维人员/开发人员决策，对某类或者某个服务进行强制降级。容错降级是指当非核心服务不可用时，可以对故障服务做业务逻辑放通，以保障核心服务的运行。
|
+| Fault Tolerance | Fault Tolerance | 容错 |
容错是消费者访问服务时出现异常的场景下的一种处理策略，出现异常后由服务框架自动选择新的服务路由进行调用。
|
+| Circuit Breaker | Circuit Breaker | 熔断 |
微服务之间通常存在依赖关系，服务调用链路可能包含多个微服务，如果链路中一个或多个服务访问延迟过高，会导致入口服务的请求不断堆积，持续消耗更多的线程、io资源，最终由于资源累积使系统出现瓶颈，造成更多服务不可用，产生雪崩效应。熔断机制就是针对上述场景设计的，当某个目标服务响应缓慢或者有大量超时情况发生时，熔断该服务的调用，对于后续调用请求，不再继续调用目标服务，直接返回，快速释放资源，等到该目标服务情况好转再恢复调用。
|
+| Bulkhead | Bulkhead | 隔离仓 |
隔离仓是一种异常检测机制，常用的检测方法是请求超时、流量过大等。一般的设置参数包括超时时间、最大并发请求数等，当超过超时时间或最大并发请求数时，记录一次异常，在熔断、实例隔离机制中，用于计算错误率。
|
+| Instance Isolation | Instance Isolation | 实例隔离 |
实例隔离通过检测实例的错误率、超时请求数等指标，短暂的屏蔽故障实例的访问，降低错误率以及防止发生雪崩效应。
|
+
## 帮助改善
-* Java Chassis的
[文档源代码](https://github.com/apache/servicecomb-docs/tree/master/java-chassis-reference)
托管在Github， 可以下载后 ，采用 MkDocs 本地使用。 也可以在
[issue](https://github.com/apache/servicecomb-docs/issues) 提交改进建议。
+* Java Chassis的
[文档源代码](https://github.com/apache/servicecomb-docs/tree/master/java-chassis-reference)
托管在Github， 可以下载后 ，采用 MkDocs 本地使用。 也可以在
[Issues](https://github.com/apache/servicecomb-docs/issues) 提交改进建议。
+
+>>> 备注：Java Chassis 2和Java Chassis 3缺少英文翻译，非常期待您的帮助支持。
diff --git a/java-chassis-reference/zh_CN/docs/introduce3.x.x.md
b/java-chassis-reference/zh_CN/docs/introduce3.x.x.md
index 165b662..261f731 100644
--- a/java-chassis-reference/zh_CN/docs/introduce3.x.x.md
+++ b/java-chassis-reference/zh_CN/docs/introduce3.x.x.md
@@ -1,9 +1,9 @@
-# 3.x.x 版本介绍
+# Java Chassis 3版本介绍
-相对于2.x.x版本，3.x.x版本在业务连续性、开发易用性、性能可靠性等方面做了大量工作。主要包括：
+相对于Java Chassis 2，Java Chassis 3在业务连续性、开发易用性、性能可靠性等方面做了大量工作。主要包括：
-* 支持 JDK 17 和 Spring Boot 3。 3.x.x完全使用JDK 17进行编译，并根据JDK
17的新特性，重构了部分代码，调整了配套的三方软件选型，使得代码更加简洁，运行更加高效。3.x.x在底层依赖上面，彻底拥抱 Spring Boot
3，并依赖于Spring
Boot特性，重构了处理链（Filter）、注册（Registration）、发现(Discovery)、配置（DynamicPropertiesSource)、负载均衡（DiscoveryTree、DiscoveryFilter)等核心组件，以支持更加丰富的应用开发生态，降低扩展实现的难度。
-* 支持OpenAPI 3.0.x。 3.x.x更新升级了OpenAPI 3.0.x，并在此基础上，提供了 Content-Type 为
application/protobuf，
application/text等支持。这样可以在HTTP/HTTP2等协议基础之上，提供更多的序列化协议支持，以提升序列化的性能。
+* 支持 JDK 17 和 Spring Boot 3。 Java Chassis 3完全使用JDK 17进行编译，并根据JDK
17的新特性，重构了部分代码，调整了配套的三方软件选型，使得代码更加简洁，运行更加高效。Java Chassis 3在底层依赖上面，彻底拥抱 Spring
Boot 3，并依赖于Spring
Boot特性，重构了处理链（Filter）、注册（Registration）、发现(Discovery)、配置（DynamicPropertiesSource)、负载均衡（DiscoveryTree、DiscoveryFilter)等核心组件，以支持更加丰富的应用开发生态，降低扩展实现的难度。
+* 支持OpenAPI 3.0.x。 Java Chassis 3更新升级了OpenAPI 3.0.x，并在此基础上，提供了 Content-Type 为
application/protobuf，
application/text等支持。这样可以在HTTP/HTTP2等协议基础之上，提供更多的序列化协议支持，以提升序列化的性能。
*
使用新的处理链机制（Filter）取代旧的处理链机制(Handler)，以提供更好的异步处理支持。统一了Handler/HttServerFilter/HttpClientFilter等机制，都使用Filter来表达。
将Handler的配置文件编排，修改为Spring Boot的依赖注入，简化用户开发和使用Filter。
*
简化了注册发现（Discovery、Registration）接口，使得开发者能够更加简单的适配不同的注册中心，提供了本地注册（Local）、广播（zero-config）、ServiceComb
注册中心（SC)、Nacos注册中心等默认实现。
*
提供了全新的实例管理和负载均衡机制，以保证注册中心网络分区故障等场景下的可靠性。该机制能够在注册中心不同的故障场景下保障微服务自身运行的可靠性，降低了注册中心可靠性对于应用本身运行可靠性的影响，为选择不同的注册中心实现提供了更多的可能性。
diff --git a/java-chassis-reference/zh_CN/docs/start/architecture.md
b/java-chassis-reference/zh_CN/docs/start/architecture.md
deleted file mode 100644
index 1311737..0000000
--- a/java-chassis-reference/zh_CN/docs/start/architecture.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# 微服务系统架构
-
-## 框架概述
-
-## **主要设计意图**
-
-1. 编程模型和通信模型分离，不同的编程模型可以灵活组合不同的通信模型。应用开发者在开发阶段只关注接口开发，部署阶段灵活切换通信方式, 不需要修改代码。
-
-2. 内建 API-First 支持,
通过契约规范化微服务开发，实现跨语言的通信，并支持配套的软件工具链（契约生成代码、代码生成契约等），构建完整的开发生态。
-
-3. 定义了常用的微服务运行模型，将微服务从发现到交互过程中的各种容错手段都封装起来, 实现开箱即用，并支持灵活定制扩展。
-
-4. 生态开放。支持多种注册发现方式： servivcecomb service center, nacos, 本地发现、广播发现等；支持多种配置管理方式：
servicecomb kie, nacos, apollo等。 满足跨云、跨地域场景的需求。
-
-5. 高性能和低时延。 灵活的通信协议、编码协议组合，以及异步编码支持，满足高性能和低时延场景的开发需求。
-
diff --git a/java-chassis-reference/zh_CN/docs/start/architecture.png
b/java-chassis-reference/zh_CN/docs/start/architecture.png
deleted file mode 100644
index 9229e44..0000000
Binary files a/java-chassis-reference/zh_CN/docs/start/architecture.png and
/dev/null differ
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml
b/java-chassis-reference/zh_CN/mkdocs.yml
index b655a3f..22c476c 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -1,4 +1,4 @@
-site_name: ServiceComb Java Chassis 开发指南
+site_name: Java Chassis 3 开发指南
use_directory_urls: false
nav:
@@ -7,8 +7,6 @@ nav:
- Java Chassis设计参考: start/design.md
- 3.x.x 版本介绍 : introduce3.x.x.md
- 快速入门:
- - 术语表: start/terminology.md
- - 微服务系统架构: start/architecture.md
- 安装本地开发环境: start/development-environment.md
- 开发第一个微服务应用: start/first-sample.md
- BMI应用-使用服务治理: featured-topics/application-bmi.md
@@ -17,17 +15,39 @@ nav:
- Spring Boot集成Java Chassis:
- Spring Boot集成Java Chassis介绍: spring-boot/introduction.md
- 与Spring Web MVC开发习惯的差异: spring-boot/diff-spring-mvc.md
-- 开发服务提供者: build-provider/catalog.md
-- 开发服务消费者: build-consumer/catalog.md
+- 开发服务提供者:
+ - 用JAX-RS开发微服务: build-provider/jaxrs.md
+ - 用SpringMVC开发微服务: build-provider/springmvc.md
+ - 用透明RPC开发微服务: build-provider/transparent-rpc.md
+ - 只发布interface的方法为服务接口: build-provider/use-interface.md
+ - 异步处理: build-provider/reactive.md
+ - 使用 Context 参数: build-provider/context-param.md
+ - 多个返回值和错误码: build-provider/multi-code.md
+ - 使用Swagger注解: build-provider/swagger-annotation.md
+ - 接口定义和数据类型: build-provider/interface-constraints.md
+ - 服务监听地址和发布地址: build-provider/listen-address-and-publish-address.md
+ - 线程池: build-provider/thread-pool.md
+ - 服务启动事件: build-provider/event-listener.md
+ - 参数效验: build-provider/parameter-validator.md
+ - 程序启动逻辑: build-provider/bootup.md
+ - IPV6配置和使用: build-provider/ipv6-configuration.md
+ - Access Log配置: build-provider/access-log-configuration.md
+- 开发服务消费者:
+ - 消费者通用配置项: build-consumer/common-configuration.md
+ - 使用RestTemplate开发服务消费者: build-consumer/using-resttemplate.md
+ - 使用RPC方式开发服务消费者: build-consumer/develop-consumer-using-rpc.md
+ - 泛化调用: featured-topics/features/invoker.md
+ - 使用服务契约: build-consumer/with-contract.md
+ - 调用第三方REST服务: build-consumer/3rd-party-service-invoke.md
- 定制请求处理流程:
- 处理链介绍: references-handlers/intruduction.md
- 通用功能开发: general-development/catalog.md
- 多样化的通信协议功能:
- 多协议介绍: transports/introduction.md
- - REST over HTTP(Vert.x): transports/rest-over-vertx.md
- - REST over HTTP2(Vert.x): transports/http2.md
- - REST over Servlet(Spring Boot Embedded):
transports/rest-over-servlet-embedded.md
- - REST over Servlet(WAR): transports/rest-over-servlet.md
+ - REST over HTTP(Vert.x: transports/rest-over-vertx.md
+ - REST over HTTP2(Vert.x: transports/http2.md
+ - REST over Servlet(Spring Boot Embedded:
transports/rest-over-servlet-embedded.md
+ - REST over Servlet(WAR: transports/rest-over-servlet.md
- Highway: transports/highway-rpc.md
- 多样化的服务注册与发现功能:
- 注册发现介绍: registry/introduction.md
@@ -40,25 +60,25 @@ nav:
- 在程序中读取配置信息: config/read-config.md
- 配置中心参考: config/config-service.md
- 服务治理功能参考:
- - 负载均衡: references-handlers/loadbalance.md
- - 限流: references-handlers/ratelimit.md
- - 灰度发布: references-handlers/router.md
- - 故障注入: references-handlers/fault-injection.md
- - 流量特征治理: references-handlers/governance.md
- - 快速失败和重试: references-handlers/fail-retry.md
+ - 负载均衡: references-handlers/loadbalance.md
+ - 限流: references-handlers/ratelimit.md
+ - 灰度发布: references-handlers/router.md
+ - 故障注入: references-handlers/fault-injection.md
+ - 流量特征治理: references-handlers/governance.md
+ - 快速失败和重试: references-handlers/fail-retry.md
- 网关功能参考:
- - 介绍: edge/open-service.md
- - 使用 Edge Service 做网关: edge/by-servicecomb-sdk.md
- - 使用 `zuul` 和 `spring cloud gateway` 做网关: edge/zuul.md
- - nginx 网关简单介绍: edge/nginx.md
+ - 介绍: edge/open-service.md
+ - 使用 Edge Service 做网关: edge/by-servicecomb-sdk.md
+ - 使用 `zuul` 和 `spring cloud gateway` 做网关: edge/zuul.md
+ - nginx 网关简单介绍: edge/nginx.md
- 安全特性参考:
- - 公钥认证: references-handlers/publickey.md
- - 使用TLS通信: security/tls.md
- - 使用RSA认证: security/shi-yong-rsa-ren-zheng.md
+ - 公钥认证: references-handlers/publickey.md
+ - 使用TLS通信: security/tls.md
+ - 使用RSA认证: security/shi-yong-rsa-ren-zheng.md
- 专题文章:
- 新功能介绍系列文章: featured-topics/features.md
- - 兼容问题和兼容性策略: featured-topics/compatibility.md
- 升级指导系列文章: featured-topics/upgrading.md
+ - 兼容问题和兼容性策略: featured-topics/compatibility.md
- 性能问题分析和调优: featured-topics/performance.md
- 常用配置项参考:
- REST Transport Client 配置项: config-reference/rest-transport-client.md
