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 2020/06/23 09:07:13 UTC
[servicecomb-docs] branch master updated: [SCB-2003]add documents
for supported context parameters in consumer / provider
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 2dcc49a [SCB-2003]add documents for supported context parameters in consumer / provider
2dcc49a is described below
commit 2dcc49aef988a32891fe9e6ceb625654ddc29d20
Author: liubao <bi...@qq.com>
AuthorDate: Tue Jun 23 15:53:14 2020 +0800
[SCB-2003]add documents for supported context parameters in consumer / provider
---
.../zh_CN/docs/build-provider/catalog.md | 8 +-
.../zh_CN/docs/build-provider/code-first.md | 16 --
.../zh_CN/docs/build-provider/context-param.md | 73 +++++++
.../zh_CN/docs/build-provider/define-contract.md | 61 +++---
.../definition/service-definition.md | 24 ++-
.../zh_CN/docs/build-provider/springmvc.md | 209 +++++++++++----------
.../docs/build-provider/swagger-annotation.md | 35 ++--
java-chassis-reference/zh_CN/docs/toc.md | 8 +-
8 files changed, 256 insertions(+), 178 deletions(-)
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/catalog.md b/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
index 04c02e0..f794863 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/catalog.md
@@ -1,12 +1,12 @@
# 开发服务提供者
-* [服务定义](definition/service-definition.md)
-* [定义服务契约](define-contract.md)
-* [使用隐式契约](code-first.md)
-* [使用Swagger注解](swagger-annotation.md)
+* [微服务定义](definition/service-definition.md)
+* [理解服务契约](define-contract.md)
* [用SpringMVC开发微服务](springmvc.md)
* [用JAX-RS开发微服务](jaxrs.md)
* [用透明RPC开发微服务](transparent-rpc.md)
+* [使用 Context 参数](context-param.md)
+* [使用Swagger注解](swagger-annotation.md)
* [接口定义和数据类型](interface-constraints.md)
* [服务监听地址和发布地址](listen-address-and-publish-address.md)
* [线程池](thread-pool.md)
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/code-first.md b/java-chassis-reference/zh_CN/docs/build-provider/code-first.md
deleted file mode 100644
index e1a0ea2..0000000
--- a/java-chassis-reference/zh_CN/docs/build-provider/code-first.md
+++ /dev/null
@@ -1,16 +0,0 @@
-# 使用隐式契约
-
-## 概念阐述
-
- 隐式契约是指ServiceComb根据服务实现类自动生成的服务契约。
-
-## 场景描述
-
- 用户通过隐式契约功能，可以不预先定义契约和接口，直接定义实现类，在服务启动时，根据实现类自动生成契约，并注册到服务中心。
-
-## 涉及API
-
- 隐式契约可用于Spring MVC、JAX-RS、透明RPC三种开发模式，具体使用参见3.4 用SpringMVC开发微服务、3.5 用JAX-RS开发微服务和3.6 用透明RPC开发微服务。
-
- 使用透明RPC模式开发微服务时，由于从代码上无法分辨微服务开发人员期望如何定义契约，所以生成的契约全是POST方法，所有method的入参被包装为一个class，作为body参数传递，所以建议使用隐式契约开发provider时，选择SpringMVC或JAX-RS开发模式，可以得到完整的RESTful声明。
-
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/context-param.md b/java-chassis-reference/zh_CN/docs/build-provider/context-param.md
new file mode 100644
index 0000000..38fdb65
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/build-provider/context-param.md
@@ -0,0 +1,73 @@
+# 使用 Context 参数
+
+Context 参数指在接口声明中的特殊参数，这些参数信息不会出现在最终的契约信息中，开发者可以使用 Context 参数
+获取或者传递与运行时有关的信息。
+
+* HttpServletRequest
+
+ HttpServletRequest 用于获取和HTTP请求有关的信息，比如 header 等。当 servicecomb 运行于 `Highway`
+ 协议，或者运行于 `vert.x` 服务器之上的时候，仍然可以使用。 但是需要注意，和 JSP/Servlet 协议标准的实现
+ 不同， 开发者无法通过 HttpServletRequest 操作流，只能够进行一些简单的获取 header 等操作。比如下面的例子，
+ 获取 query 参数：
+
+ ```java
+ @GetMapping(path = "/reduce")
+ @ApiImplicitParams({@ApiImplicitParam(name = "a", dataType = "integer", format = "int32", paramType = "query")})
+ public int reduce(HttpServletRequest request, @CookieValue(name = "b") int b) {
+ int a = Integer.parseInt(request.getParameter("a"));
+ return a - b;
+ }
+ ```
+
+ 特别需要注意，如果请求不是直接到达 provider， 而是经过 servicecomb 的 Edge Service 转发到 provider，
+ 上面的代码还必须使用 `@ApiImplicitParams` 显示的声明这个接口的实现通过 `HttpServletRequest` 读取了
+ query 参数 `a`， 如果不声明， Edge Service 做请求转发的时候，不会转发参数 `a`， 代码中读取的参数值为
+ null。
+
+ 还需要注意，servicecomb 不支持 `HttpServletResponse` Context 参数。
+
+* InvocationContext
+
+ InvocationContext 是 servicecomb 特有的上下文信息，可以在 `Handler`, `HttpServerFilter` 等
+ 多种场景使用。 InvocationContext 包含 local 和 context 两种数据， local 数据只在本进程的模块间
+ 传递， context 数据可以在微服务之间传递。
+
+ ```java
+ @ApiResponse(code = 202, response = User.class, message = "")
+ @ResponseHeaders({@ResponseHeader(name = "h1", response = String.class),
+ @ResponseHeader(name = "h2", response = String.class)})
+ @RequestMapping(path = "/cseResponseCorrect", method = RequestMethod.GET)
+ public Response cseResponseCorrect(InvocationContext c1) {
+ Response response = Response.createSuccess(Status.ACCEPTED, new User());
+ Headers headers = response.getHeaders();
+ headers.addHeader("h1", "h1v " + c1.getContext().get(Const.SRC_MICROSERVICE));
+
+ InvocationContext c2 = ContextUtils.getInvocationContext();
+ headers.addHeader("h2", "h2v " + c2.getContext().get(Const.SRC_MICROSERVICE));
+
+ return response;
+ }
+ ```
+
+ 上面的代码显示了 InvocationContext 参数的用法， 这个用法和代码中通过 ContextUtils.getInvocationContext()
+ 获取是等价的。
+
+ InvocationContext 还可以在 consumer 端的 RPC 接口中使用， [使用Context传递控制消息](../general-development/context.md) 描述了更多 InvocationContext 的使用
+ 场景。
+
+* Endpoint
+
+ Endpoint 描述当前请求需要发往的实例地址。 这个 context 参数只能够在 consumer 端的 PRC 接口使用。当
+ 微服务存在多个实例的时候，可以使用这种方式指定将请求发往哪个实例。
+
+ ```java
+ public interface SchemaDiscoveryService {
+ String getSchema(Endpoint endpoint, String schemaId);
+ }
+
+ SchemaDiscoveryService schemaDiscoveryService = Invoker
+ .createProxy(serviceName, SchemaDiscoveryService.SCHEMA_ID,
+ SchemaDiscoveryService.class);
+
+ schemaDiscoveryService.getSchema(EndpointUtils.parse(endpoint), schemaId);
+ ```
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/define-contract.md b/java-chassis-reference/zh_CN/docs/build-provider/define-contract.md
index e653c7e..60cbd9c 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/define-contract.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/define-contract.md
@@ -1,30 +1,31 @@
-# 定义服务契约
-``
-## 概念阐述
+# 理解服务契约
+
+servicecomb 的核心设计理念是 `以契约为中心`，契约是微服务系统运行和治理的基础。 可以将契约理解为基
+于 OpenAPI 规范的微服务接口描述。java chassis 提供了两种方式定义契约：`code first` 和
+ `contract first` 。
-服务契约，指基于OpenAPI规范的微服务接口契约，是服务端与消费端对于接口的定义。java chassis提供了两种方式定义契约：code first和contract first。
* code first
-producer使用Jax-RS或SpringMVC的RESTful annotation声明接口的输入、输出参数，或者再配合OpenAPI的annotation，增加人类可读的信息，比如样例代码、文本描述等等；ServiceComb引擎启动时，根据这些annotation生成契约描述，并自动上传到服务中心。producer也可以使用透明RPC方式开发，但是因为没有任何RESTful的annotation指导如何生成契约，所以此时自动生成的契约非常的不RESTful化，不建议使用。
-consumer使用透明RPC或RestTemplate进行调用。
-code first的开发模式下，开发人员，不必手写契约。
+ 开发者首先通过 JAVA 代码定义接口信息，servicecomb 会根据代码定义，生成以 yaml 文件描述的 OpenAPI
+ 文档。 servicecomb 支持使用 `JAX-RS`, `Sprig MVC` 等 REST Annotation 描述接口信息，还可以通过
+ swagger API 补充其他接口信息。 在使用 `RPC` 方式定义接口的时候， 系统会按照默认的规则生成接口描述，
+ 也可以使用这些标签修饰接口信息，让契约信息更加容易阅读和理解。
* contract first
-此场景下，不使用框架自动生成的契约，而是直接使用开发人员提供的契约文件，这需要由开发人员保证契约与代码的一致性。
-
-## 场景描述
+ 开发者先通过契约编辑器书写 yaml 格式的接口描述，然后通过代码生成工具，生成项目代码。这种方式通常
+ 需要定义一套标准的软件工程规范，并提供相关的工具支持。这种方式更加容易实现接口规范管理，实现测试自动化
+ 等软件工程流程。
-服务契约用于服务端和消费端的解耦，服务端围绕契约进行服务的实现，消费端根据契约进行服务的调用，可支持服务端和消费端采用不同的编程语言实现。
+由于 `contract first` 实践起来，需要配套的管理过程和工具体系支持，这里不详细描述，
+本章节简单描述如何书写契约。后续的章节会描述使用 `code first` 的开发细节。
-> _**说明:**_
-> 服务提供者在启动时会将接口契约注册到服务中心，可供服务消费者下载使用。接口契约是微服务-版本级别的信息，当多个微服务实例启动时，有一个实例将契约注册到服务中心后，服务中心就不会再用后来者注册的契约信息覆盖已有的契约。因此，仅修改服务提供者的接口信息不会让服务中心存储的契约发生变化，对于服务消费者而言，获取到的接口信息依然是旧的。若要更新服务中心中的接口契约，可以选择升级微服务版本号，或者删除已有的微服务信息（后者不建议在生产环境使用）。
+# contract first 开发步骤简要描述
-## 配置说明
+ServiceComb 使用 yaml 文件格式定义服务契约，推荐使用[Swagger Editor](http://editor.swagger.io/#/)工具来编写契约，
+可检查语法格式及自动生成API文档。详细的契约文件格式请参考[OpenAPI官方文档](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)。
-ServiceComb使用yaml文件格式定义服务契约，推荐使用[Swagger Editor](http://editor.swagger.io/#/)工具来编写契约，可检查语法格式及自动生成API文档。详细的契约文件格式请参考[OpenAPI官方文档](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)。
-
-契约文件放置在"resources/microservices"或者"resources/application"目录下，目录结构如下所示。
+契约文件放置在 `resources/microservices` 或者 `resources/application` 目录下，目录结构如下所示。
```yaml
resources
@@ -37,13 +38,12 @@ resources
- schemaId.yaml #schema接口的契约
```
-> **注意**：
->
-> * ServiceComb的Swagger契约文件应当使用UTF-8字符集保存。如果当用户使用其他字符集保存契约文件，且文件中包含中文字符时，可能会导致未知错误。
+ServiceComb的Swagger契约文件应当使用UTF-8字符集保存。如果当用户使用其他字符集保存契约文件，且文
+件中包含中文字符时，可能会导致未知错误。
## 示例代码
-`resources/microservices`目录和`resources/application`目录下的schemaId.yaml文件内容示例如下。文件中的接口定义需要与服务的实际接口相符。
+`resources/microservices`目录和`resources/application` 目录下的schemaId.yaml文件内容示例如下。
```yaml
swagger: '2.0'
@@ -102,15 +102,18 @@ definitions:
name: "Person"
```
-> **注意**：
->
-> * ServiceComb中的契约，建议basePath不要包含web container的web root，以及servlet的url pattern。
+ServiceComb中的契约，basePath不需要包含web container的web root，以及servlet的url pattern。
+因为ServiceComb支持部署解耦，既可以脱离servlet container独立部署，也可使用war的方式部署
+到servlet container中，还可以使用embedded servlet container的方式运行。
+部署方式修改导致的实际url变更，ServiceComb consumer业务代码并不需要感知，框架会自动适配。
+
+说明：
-因为ServiceComb支持部署解耦，既可以脱离servlet container独立部署，也可使用war的方式部署到servlet container中，还可以使用embedded servlet container的方式运行。
-只要base path不包含web root以及url pattern，则部署方式修改导致的实际url变更，ServiceComb consumer业务代码并不需要感知，框架会自动适配。
-> * info.x-java-interface需要标明具体的接口路径，根据项目实际情况而定。
-> * SchemaId中可以包含"."字符，但不推荐这样命名。这是由于ServiceComb使用的配置文件是yaml格式的，"."符号用于分割配置项名称，如果SchemaId中也包含了"."可能会导致一些支持契约级别的配置无法正确被识别。
-> * OperationId的命名中不可包含"."字符。
+ * info.x-java-interface需要标明具体的接口路径，根据项目实际情况而定。该信息主要是为了和老版本兼容，
+ 新版本可以不需要指定。
+ * SchemaId中可以包含"."字符，但不推荐这样命名。这是由于ServiceComb使用的配置文件是yaml格式的，
+ "."符号用于分割配置项名称，如果SchemaId中也包含了"."可能会导致一些支持契约级别的配置无法正确被识别。
+ * OperationId的命名中不可包含"."字符。
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/definition/service-definition.md b/java-chassis-reference/zh_CN/docs/build-provider/definition/service-definition.md
index c7108f6..ebd90e5 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/definition/service-definition.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/definition/service-definition.md
@@ -1,14 +1,23 @@
-### 概念阐述
+# 微服务定义
-服务定义信息是微服务的身份标识，它定义了服务从属于哪个应用，以及名字和版本。服务定义信息中也可以有扩展信息，用于定义服务的属性元数据。
+servicecomb 微服务定义包括两个基础模型 `Microservice` 和 `MicroserviceInstance`。 这些信息定义了
+微服务标识，从属于哪个应用，以及名字和版本。
-### 场景描述
+* 微服务信息
-当用户定义新的微服务或修改微服务的基本信息时，会涉及到服务定义信息的创建和修改操作。
+ servicecomb 的微服务信息在类 `Microservice` 中定义。 它主要包含应用 ID (appId)， 微服务名称 (serviceName),
+ 微服务版本(version)，环境(environment) 等信息。
-### 配置说明
+* 实例信息
-本章节介绍涉及microservice.yaml文件的以下配置项，文件在项目中的存放路径为src\main\resources\microservice.yaml。
+ servicecomb 的实例信息在类 `MicroserviceInstance` 中定义。 它主要包含网络地址(endpoints) 信息。
+
+# 场景描述
+
+开发一个微服务，需要在 `microservice.yaml` 文件中配置微服务的基本信息。 如果使用 spring boot，也可以在
+`application.yml` 文件中配置微服务的基本信息。
+
+`microservice.yaml` 文件在项目中的存放路径为 `src\main\resources\microservice.yaml`。
表1-1配置项说明
@@ -28,7 +37,7 @@
> * 服务的元数据会随服务一同注册到服务中心，如需修改，则要连同服务version一起变更。若想保持服务version不变，则需要通过服务管理中心统一变更元数据。
> * 虽然微服务名、契约名中可以使用"."字符，但是不推荐在命名中使用"."。这是由于ServiceComb使用的配置文件是yaml格式的，"."符号用于分割配置项名称，如果微服务名、契约名中也包含了"."可能会导致一些支持微服务、契约级别的配置无法正确被识别。
-### 示例代码
+下面是一个微服务信息的配置示例：
```yaml
APPLICATION_ID: helloTest # 应用名
@@ -45,3 +54,4 @@ instance_description: #实例描述
key3: value3
propertyExtentedClass: org.apache.servicecomb.serviceregistry.MicroServicePropertyExtendedStub
```
+
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md b/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md
index 2478653..a236afa 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/springmvc.md
@@ -1,14 +1,17 @@
# 用 Spring MVC 开发微服务
-## 概念阐述
+Spring MVC 是 spring-web 项目定义的一套注解，开发者可以使用这套注解定义 REST 接口。 servicecomb 也
+支持使用这套标签定义 REST 接口。需要注意的是，servicecomb 只是使用这些注解，而注解的实现是项目自行开发的，
+实现的功能集合是 Spring MVC 注解的子集。可以阅读文章后面的内容了解具体的标签集合和使用约束。
-Spring MVC 是 spring-web 项目定义的一套注解，开发者可以使用这套注解定义 REST 接口。 servicecomb 也支持使用
-这套标签定义 REST 接口。
+[SpringMVC Sample](spring-mvc-sample) 提供了一些基础的代码示例，可以下载使用。
-可以参考示例项目 [SpringMVC](https://github.com/apache/servicecomb-samples/tree/master/java-chassis-samples/springmvc-sample) 。
+[spring-mvc-sample]: https://github.com/apache/servicecomb-samples/tree/master/java-chassis-samples/springmvc-sample
## 开发步骤
+下面简单介绍使用 Spring MVC 开发 REST 服务的一些简单步骤。
+
* 定义服务接口（可选）
定义接口是一个好习惯， 它不是必须的。
@@ -22,7 +25,7 @@ Spring MVC 是 spring-web 项目定义的一套注解，开发者可以使用这
* 实现服务接口
-在服务的实现类上打上注解 `@RestSchema`，指定 `schemaId`。 注意 `schemaId` 需要保证微服务范围内唯一。
+ 在服务的实现类上打上注解 `@RestSchema`，指定 `schemaId`。 注意 `schemaId` 需要保证微服务范围内唯一。
```java
@RestSchema(schemaId = "springmvcHello")
@@ -44,7 +47,8 @@ Spring MVC 是 spring-web 项目定义的一套注解，开发者可以使用这
* 发布服务 （可选，默认会扫描 main 函数所在的 package ）
-在`resources/META-INF/spring`目录下创建`springmvcprovider.bean.xml`文件，命名规则为`\*.bean.xml`，配置spring进行服务扫描的base-package，文件内容如下：
+ 在`resources/META-INF/spring`目录下创建`springmvcprovider.bean.xml`文件，
+ 命名规则为`\*.bean.xml`，配置spring进行服务扫描的base-package，文件内容如下：
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -61,7 +65,7 @@ Spring MVC 是 spring-web 项目定义的一套注解，开发者可以使用这
* 启动 provider 服务
-servicecomb 依赖于 Spring, 只需要将 Spring 框架启动起来即可。
+ servicecomb 依赖于 Spring, 只需要将 Spring 框架启动起来即可。
```java
public class SpringmvcProviderMain {
@@ -72,6 +76,102 @@ servicecomb 依赖于 Spring, 只需要将 Spring 框架启动起来即可。
}
```
+## ServiceComb支持的 Spring MVC 注解说明
+
+servicecomb 支持使用 Spring MVC 提供的注解 `org.springframework.web.bind.annotation` 来声
+明REST接口，但是两者是独立的实现，而且有不一样的设计目标。servicecomb 的目标是提供跨语言、支持多通信协议的
+框架，因此去掉了Spring MVC中一些对跨语言支持不是很好的特性，也不支持特定运行框架强相关的特性，比
+如直接访问Servlet协议定义的`HttpServletRequest`。servicecomb 没有实现`@Controller`相关功
+能, 只实现了`@RestController`，即通过MVC模式进行页面渲染等功能都是不支持的。
+
+下面是一些具体差异。
+
+* 常用标签支持
+
+ 下面是CSE对于Spring MVC常用标签的支持情况。
+
+ ***表1-1 Spring MVC注解情况说明***
+
+| 标签名称 | 是否支持 | 说明 |
+| :--- | :--- | :--- |
+| RequestMapping | 是 | 不允许制定多个Path，一个接口只允许一个Path，必须显示的声明 method 属性，只能定义唯一一个 method |
+| GetMapping | 是 | |
+| PutMapping | 是 | |
+| PostMapping | 是 | |
+| DeleteMapping | 是 | |
+| PatchMapping | 是 | |
+| RequestParam | 是 | |
+| CookieValue | 是 | |
+| PathVariable | 是 | |
+| RequestHeader | 是 | |
+| RequestBody | 是 | 目前支持application/json，plain/text |
+| RequestPart | 是 | 用于文件上传的场景，对应的标签还有Part、MultipartFile |
+| ResponseBody | 否 | 返回值缺省都是在body返回 |
+| ResponseStatus | 否 | 可以通过ApiResponse指定返回的错误码 |
+| RequestAttribute | 否 | Servlet协议相关的标签 |
+| SessionAttribute | 否 | Servlet协议相关的标签 |
+| MatrixVariable | 否 | |
+| ModelAttribute | 否 | |
+| ControllerAdvice | 否 | |
+| CrossOrigin | 否 | |
+| ExceptionHandler | 否 | |
+| InitBinder | 否 | |
+
+* 服务声明方式
+
+ Spring MVC使用`@RestController`声明服务，而ServiceComb使用`@RestSchema`声明服务，并且需
+ 要显式地使用`@RequestMapping`声明服务路径，以区分该服务是采用Spring MVC的标签还是使用JAX RS的标签。
+
+ ```
+ @RestSchema(schemaId = "springmvcHello")
+ @RequestMapping(path = "/springmvchello", produces = MediaType.APPLICATION_JSON)
+ public class SpringmvcHelloImpl implements Hello {
+ ......
+ }
+ ```
+
+ servicecomb 也支持 `@RestController` 声明，等价于 `@RestSchma(schemaId="服务的class名称")`，这个
+ 功能可以简化用户将老的应用改造为 servicecomb 。 建议用户使用`@RestSchema`显式声明schemaId，在管理
+ 接口基本的配置项的时候，更加直观。
+
+ **注意**：如果不希望Java-Chassis扫描`@RestController`注解作为REST接口类处理，需要增加配置
+ `servicecomb.provider.rest.scanRestController=false` 以关闭此功能。
+
+* 数据类型支持
+
+ Spring 技术实现的 Spring MVC，可以在服务定义中使用多种数据类型，只要这种数据类型能够被json序列化和
+ 反序列化。比如：
+
+ ```
+ // 抽象类型
+ public void postData(@RequestBody Object data)
+ // 接口定义
+ public void postData(@RequestBody IPerson interfaceData)
+ // 没指定类型的泛型
+ public void postData(@RequestBody Map rawData)
+ ```
+
+ Spring 技术早期都是基于 JSP/Servlet 协议标准的，还可以使用相关的 context 参数，比如：
+
+ ```
+ // 具体协议相关的类型
+ public void postData(HttpServletRequest rquest, HttpServletResponse response)
+ ```
+
+ servicecomb 对于数据类型存在一定的限制，不允许使用接口、抽象类等数据类型定义参数，虽然 servicecomb
+ 支持使用 Object 这个特殊的类型来处理类型无法确定的情况，但是建议尽可能少使用，使用 Object 作为类型，
+ 运行时的类型不确定，可能给客户端代码的书写带来一定麻烦。
+
+ servicecomb 也支持一些 context 参数， 参考[使用 Context 参数](context-param.md) 。但是由于 servicecomb 默认的运行环境并不是 JSP/Servlet 协议
+ 环境，因此不能直接使用 `HttpServletRequest` 和 `HttpServletResponse`。
+
+ ServiceComb在数据类型的支持方面的更多说明，请参考： [接口定义和数据类型](interface-constraints.md)
+
+* 其他
+
+ 更多开发过程中碰到的问题，可以参考[案例](https://bbs.huaweicloud.com/blogs/8b8d8584e70d11e8bd5a7ca23e93a891)。开发过程中存在疑问，也可以在这里进行提问。
+
+
## 在响应中包含 HTTP header
可以有多种方式在响应中包含 HTTP header， 下面代码展示了使用 ResponseEntity 包含 HTTP header。 需要注意
@@ -154,9 +254,8 @@ servicecomb 依赖于 Spring, 只需要将 Spring 框架启动起来即可。
## Query参数聚合为POJO对象
-### 使用说明
-
SpringBoot支持将Java业务接口中的多个query参数聚合为一个POJO类，SpringBoot原生用法示例如下：
+
```java
@RequestMapping("/hello")
public class HelloService {
@@ -167,9 +266,11 @@ public class HelloService {
}
}
```
+
其中，作为参数的`Person`类是一个标准的JavaBean，包含属性`name`和`age`。当服务接收到的请求时，SpringBoot会将query参数`name`和`age`聚合为Person对象传入业务接口。
ServiceComb的SpringMVC开发模式现在也支持类似的用法，该用法的要求如下：
+
1. POJO参数上不能有Spring的参数注解，否则ServiceComb不会将其作为聚合的query参数对象处理。
2. 仅支持聚合query参数
3. POJO参数类中的属性名与query参数名需要保持一致
@@ -253,93 +354,3 @@ String result = restTemplate.getForObject(
String.class); // 调用效果与RPC方式相同
```
-## ServiceComb支持的 Spring MVC 注解说明
-
-ServiceComb支持使用 Spring MVC 提供的注解\(org.springframework.web.bind.annotation\)来声
-明REST接口，但是两者是独立的实现，而且有不一样的设计目标。CSE的目标是提供跨语言、支持多通信协议的
-框架，因此去掉了Spring MVC中一些对跨语言支持不是很好的特性，也不支持特定运行框架强相关的特性，比
-如直接访问Servlet协议定义的`HttpServletRequest`。ServiceComb没有实现`@Controller`相关功
-能, 只实现了`@RestController`，即通过MVC模式进行页面渲染等功能都是不支持的。
-
-下面是一些具体差异。
-
-* 常用标签支持
-
- 下面是CSE对于Spring MVC常用标签的支持情况。
-
- ### 表1-1 Spring MVC注解情况说明
-
-| 标签名称 | 是否支持 | 说明 |
-| :--- | :--- | :--- |
-| RequestMapping | 是 | 不允许制定多个Path，一个接口只允许一个Path |
-| GetMapping | 是 | |
-| PutMapping | 是 | |
-| PostMapping | 是 | |
-| DeleteMapping | 是 | |
-| PatchMapping | 是 | |
-| RequestParam | 是 | |
-| CookieValue | 是 | |
-| PathVariable | 是 | |
-| RequestHeader | 是 | |
-| RequestBody | 是 | 目前支持application/json，plain/text |
-| RequestPart | 是 | 用于文件上传的场景，对应的标签还有Part、MultipartFile |
-| ResponseBody | 否 | 返回值缺省都是在body返回 |
-| ResponseStatus | 否 | 可以通过ApiResponse指定返回的错误码 |
-| RequestAttribute | 否 | Servlet协议相关的标签 |
-| SessionAttribute | 否 | Servlet协议相关的标签 |
-| MatrixVariable | 否 | |
-| ModelAttribute | 否 | |
-| ControllerAdvice | 否 | |
-| CrossOrigin | 否 | |
-| ExceptionHandler | 否 | |
-| InitBinder | 否 | |
-
-* 服务声明方式
-
- Spring MVC使用`@RestController`声明服务，而ServiceComb使用`@RestSchema`声明服务，并且需
- 要显式地使用`@RequestMapping`声明服务路径，以区分该服务是采用Spring MVC的标签还是使用JAX RS的标签。
-
- ```
- @RestSchema(schemaId = "hello")
- @RequestMapping(path = "/")
- ```
-
- Schema 是 CSE 的服务契约，是服务运行时的基础，服务治理、编解码等都基于契约进行。在跨语言的场景，契约
- 也定义了不同语言能够同时理解的部分。
-
- servicecomb 也支持 `@RestController` 声明，等价于 `@RestSchma(schemaId="服务的class名称")`，这个
- 功能可以简化用户将老的应用改造为 servicecomb 。 建议用户使用`@RestSchema`显式声明schemaId，在管理
- 接口基本的配置项的时候，更加直观。
-
- **注意**：如果不希望Java-Chassis扫描`@RestController`注解作为REST接口类处理，需要增加配置
- `servicecomb.provider.rest.scanRestController=false` 以关闭此功能。
-
-* 数据类型支持
-
- Spring 技术实现的 Spring MVC，可以在服务定义中使用多种数据类型，只要这种数据类型能够被json序列化和
- 反序列化。比如：
-
- ```
- // 抽象类型
- public void postData(@RequestBody Object data)
- // 接口定义
- public void postData(@RequestBody IPerson interfaceData)
- // 没指定类型的泛型
- public void postData(@RequestBody Map rawData)
- // 具体协议相关的类型
- public void postData(HttpServletRequest rquest)
- ```
-
- servicecomb 对于数据类型存在一定的限制，不允许使用接口等数据类型定义参数，因为 servicecomb 会根据接口
- 定义生成契约。 例子中的接口定义，如果不结合实现代码或者额外的开发文档说明，
- 无法知道具体的参数信息。站在浏览器的 REST 视角，不知道如何在 body 里面构造消息内容。
-
- 为了支持快速开发，servicecomb 支持 HttpServletRequest，Object。但
- 是实际在使用的时候，他们与WEB服务器的语义是不一样的，比如不能直接操作流。因此建议开发者在 servicecomb 的
- 使用场景下，尽可能不要使用 HttpServletRequest，Object 作为请求参数。
-
- ServiceComb在数据类型的支持方面的更多说明，请参考： [接口定义和数据类型](interface-constraints.md)
-
-* 其他
-
- 更多开发过程中碰到的问题，可以参考[案例](https://bbs.huaweicloud.com/blogs/8b8d8584e70d11e8bd5a7ca23e93a891)。开发过程中存在疑问，也可以在这里进行提问。
diff --git a/java-chassis-reference/zh_CN/docs/build-provider/swagger-annotation.md b/java-chassis-reference/zh_CN/docs/build-provider/swagger-annotation.md
index 3ca446f..e8b9165 100644
--- a/java-chassis-reference/zh_CN/docs/build-provider/swagger-annotation.md
+++ b/java-chassis-reference/zh_CN/docs/build-provider/swagger-annotation.md
@@ -1,22 +1,19 @@
# 使用 Swagger 注解
-## 概念阐述
+采用 Spring MVC 或者 JAX RS 注解已经能够描述大部分常用的契约信息，但是仍然不足以描述所有契约信息。可以混合
+使用 Swagger 注解，进一步补充契约信息，使得契约信息更加完整。当 Spring MVC 或者 JAR RS 注解描述的信息与
+Swagger 注解描述的信息重复时，以 Swagger 注解描述的信息为准，即 Swagger 注解具有更高的优先级。
-Swagger提供了一套注解用于描述接口契约，用户使用注解，可以在代码中增加对于契约的描述信息。ServiceComb支持其中的部分注解。
+关于Swagger注解的含义，可以在[Swagger注解文档](swagger-annotation)中找到官方说明。可以对
+照该官方文档与本说明来了解如何在ServiceComb框架下使用注解指定Swagger契约的各项属性。
-## 场景描述
+[swagger-annotation]: https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X
-通过使用注解描述接口契约，用户可以利用ServiceComb的Swagger契约生成功能自动生成符合要求的契约文件，而无须手工编写和修改契约，能够有效提高开发效率。
+## `@Api`
-## 配置说明
-
-关于Swagger注解的含义，可以在[Swagger注解文档](https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X)中找到官方说明。您可以对照该官方文档与本说明来了解如何在ServiceComb框架下使用注解指定Swagger契约的各项属性。
-
-在ServiceComb中，Swagger注解不是必须使用的。当用户使用SpringMVC和JAX-RS的注解来标注微服务方法时，ServiceComb可以根据这些注解的值推断出各微服务方法的契约信息。
-
-### `@Api`
-
-> `@Api`作用于类级别，在Swagger官方描述中是用于将一个Class标注为一个Swagger资源。但该注解在ServiceComb中不是必须的，ServiceComb可以根据`@RestSchema`和`@RpcSchema`确定需要从哪些类中解析出Swagger契约。
+> `@Api`作用于类级别，在Swagger官方描述中是用于将一个Class标注为一个Swagger资源。但该注解
+> 在ServiceComb中不是必须的，ServiceComb可以根据`@RestSchema`和`@RpcSchema`确定需要从哪些
+> 类中解析出Swagger契约。
| 属性 | 类型 | 说明 |
| :--- | :------ | :--- |
@@ -24,7 +21,7 @@ Swagger提供了一套注解用于描述接口契约，用户使用注解，可
| consumes | string | 指定契约级别的请求体数据格式，可以使用逗号分隔指定多个 |
| produces | string | 指定契约级别的响应体数据格式，可以使用逗号分隔指定多个 |
-### `@SwaggerDefinition`
+## `@SwaggerDefinition`
> 作用于类级别，用于定义一个Swagger资源中的信息。
@@ -43,7 +40,7 @@ Swagger提供了一套注解用于描述接口契约，用户使用注解，可
| tags | `@Tag` | Tag定义，@Tag包含name、description、externalDocs三个属性 |
| externalDocs | `@externalDocs` | 外部说明文档链接，包含value、url两个属性 |
-### `@ApiOperation`
+## `@ApiOperation`
> 作用于方法级别，用于描述一个Swagger operation。
@@ -62,7 +59,7 @@ Swagger提供了一套注解用于描述接口契约，用户使用注解，可
| httpMethod | string | 设置HTTP方法 |
| hidden | boolean | 是否隐藏此方法 |
-### `@ApiImplicitParam`
+## `@ApiImplicitParam`
> 作用于方法级别，用于说明Swagger文档中operation的参数的属性。
>
@@ -83,7 +80,7 @@ Swagger提供了一套注解用于描述接口契约，用户使用注解，可
| example | string | 一个非body参数的示例值 |
| format | string | 允许用户自定义数据格式，详情参见Swagger官方文档 |
-### `@ApiImplicitParams`
+## `@ApiImplicitParams`
> `@ApiImplicitParams`作用于方法、类级别，用于批量指定多个`@ApiImplicitParam`。
@@ -91,7 +88,7 @@ Swagger提供了一套注解用于描述接口契约，用户使用注解，可
| :--- | :------ | :--- |
| value | `@ApiImplicitParam` | 参数定义 |
-### `@ApiResponse`
+## `@ApiResponse`
> 用于描述返回消息的HTTP状态码所表达的含义。通常`@ApiOperation`可以表示一个正常情况返回消息的HTTP状态码，其他情形下的HTTP状态码由本注解描述。根据Swagger官方文档的描述，本注解不应该直接用于方法级别，而应该被包含在`@ApiResponses`中。
@@ -103,7 +100,7 @@ Swagger提供了一套注解用于描述接口契约，用户使用注解，可
| responseContainer | string | 返回值的包装容器，可选值为`List/Set/Map` |
| responseHeaders | @ResponseHeader | 描述一组返回消息的HTTP头，ServiceComb支持的`@ResponseHeader`的属性有`name`、`description`、`response`、`responseContainer` |
-### `@ApiResponses`
+## `@ApiResponses`
> 作用于方法、类级别，用于指定和说明一组返回值。
diff --git a/java-chassis-reference/zh_CN/docs/toc.md b/java-chassis-reference/zh_CN/docs/toc.md
index 5564b93..154a2ae 100644
--- a/java-chassis-reference/zh_CN/docs/toc.md
+++ b/java-chassis-reference/zh_CN/docs/toc.md
@@ -16,13 +16,13 @@
* [Java Chassis 微服务技术选型](start/design.md#h4)
* [Java Chassis 与 Spring Cloud](start/design.md#h5)
* [开发服务提供者](build-provider/catalog.md)
- * [服务定义](build-provider/definition/service-definition.md)
- * [定义服务契约](build-provider/define-contract.md)
- * [使用隐式契约](build-provider/code-first.md)
- * [使用Swagger注解](build-provider/swagger-annotation.md)
+ * [微服务定义](build-provider/definition/service-definition.md)
+ * [理解服务契约](build-provider/define-contract.md)
* [用SpringMVC开发微服务](build-provider/springmvc.md)
* [用JAX-RS开发微服务](build-provider/jaxrs.md)
* [用透明RPC开发微服务](build-provider/transparent-rpc.md)
+ * [使用 Context 参数](build-provider/context-param.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)