You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by ni...@apache.org on 2018/08/31 08:32:49 UTC
[incubator-servicecomb-docs] branch master updated: Migration
build-provider from web repo (#43)
This is an automated email from the ASF dual-hosted git repository.
ningjiang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-servicecomb-docs.git
The following commit(s) were added to refs/heads/master by this push:
new a75d346 Migration build-provider from web repo (#43)
a75d346 is described below
commit a75d3465c128f48296c752ac49c54860dcbbb01e
Author: lidian <li...@huawei.com>
AuthorDate: Fri Aug 31 16:32:47 2018 +0800
Migration build-provider from web repo (#43)
* update en_US version of build-provider
* update build-provider/
* update java-chassis-reference/en_US/build-provider/define-contract.md
* java-chassis-reference/en_US/build-provider/interface-constraints.md
* java-chassis-reference/en_US/build-provider/jaxrs.md
* java-chassis-reference/en_US/build-provider/springmvc.md
* java-chassis-reference/en_US/build-provider/transparent-rpc.md
* translate java-chassis-reference/en_US/build-provider/code-first.md
* delete .md file head for build issue
* fix java-chassis-reference/en_US/build-provider/bootup.md issue
* fix java-chassis-reference/en_US/build-provider/code-first.md issue
* fix java-chassis-reference/en_US/build-provider/define-contract.md issue
* Update define-contract.md
---
.../en_US/build-provider/bootup.md | 23 +-
.../en_US/build-provider/code-first.md | 18 +-
.../en_US/build-provider/define-contract.md | 81 +++--
.../definition/service-definition.md | 64 ++--
.../en_US/build-provider/interface-constraints.md | 170 +++--------
.../en_US/build-provider/jaxrs.md | 334 +++++++++------------
.../en_US/build-provider/protocol.md | 13 +-
.../en_US/build-provider/protocol/highway-rpc.md | 46 ++-
.../build-provider/protocol/rest-over-servlet.md | 38 +--
.../build-provider/protocol/rest-over-vertx.md | 57 ++--
.../en_US/build-provider/protocol/thread-model.md | 35 ++-
.../en_US/build-provider/springmvc.md | 313 ++++++++-----------
.../en_US/build-provider/transparent-rpc.md | 239 ++++++++-------
13 files changed, 602 insertions(+), 829 deletions(-)
diff --git a/java-chassis-reference/en_US/build-provider/bootup.md b/java-chassis-reference/en_US/build-provider/bootup.md
index 9c0d9ae..50cef61 100644
--- a/java-chassis-reference/en_US/build-provider/bootup.md
+++ b/java-chassis-reference/en_US/build-provider/bootup.md
@@ -1,21 +1,18 @@
-## 概念阐述
+# Application Boot-up Process
-服务提供者的启动过程分为初始化Log4j、bean加载（包括配置加载）和服务注册三部分。
+The startup process of a service provider includes initializing Log4j, loading bean(including its parameters), and registering service.
-* 初始化Log4j
+* Initialize Log4j:
-`Log4jUtils`默认会从`classpath\*:config/base/log4j.properties`和`classpath\*:config/log4j.properties`两个路径读取log4j配置并合并，将其传递给Log4j的`PropertyConfigurator`方法初始化Log4j。如果优先级最高的配置文件是在磁盘上，且其所在目录有写权限，则将合并的配置输出到该目录，以便于维护时观察生效的参数。
+ By default, Log4jUtils merges the log4j configurations from classpath\*:config/base/log4j.properties and classpath\*:config/log4j.properties, then transfer them to log4j's PropertyConfigurator method to initialize it. If the configuration file with the highest priority is stored on the disk directory with write permission, the combined configuration will be saved to this location to view which parameters take effect during maintenance.
-* bean加载
+* Load the bean.
-`BeanUtils`默认会从`classpath\*:META-INF/spring/\*.bean.xml`路径加载配置文件，并将其传递给Spring框架的`ClassPathXmlApplicationContext`完成应用上下文加载。在这个过程中会加载foundation-config模块的bean，完成配置加载。
-
-* 服务注册
-
-在Spring context加载完成后，`org.apache.servicecomb.core.CseApplicationListener`会加载handler配置、加载provider的schema信息，最后将微服务信息注册到服务中心。
-
-> **说明：**
-> ServiceComb的配置项分为三个层次：配置中心、环境变量、本地文件，三者优先级依次递减，高优先级中的配置项覆盖低优先级同名配置项。存放在配置中心的配置项可以在运行时修改。
+ By default `BeanUtils` loads the configuration file from the `classpath\*:META-INF/spring/\*.bean.xml` Path and transfer the configuration to `ClassPathXmlApplicationContext` of the Spring framework to load the context. In this process, ```BeanUtils``` loads the bean of the foundation-config module.
+* Register the microservice.
+ When Spring context is loaded, 'org.apache.servicecomb.core.CseApplicationListener' will load the handlers configurations and providers' schema info, then register the microservice in the Service Center.
+> **NOTE:**
+> ServiceComb have three level of configuration items: configuration center, environment variables, and local files, listed in descending order by priority. If configuration items with the same name exist, the one in the highest level overwrites others. Configuration items stored in the configuration center can be modified during running.
diff --git a/java-chassis-reference/en_US/build-provider/code-first.md b/java-chassis-reference/en_US/build-provider/code-first.md
index e1a0ea2..ed8e3f9 100644
--- a/java-chassis-reference/en_US/build-provider/code-first.md
+++ b/java-chassis-reference/en_US/build-provider/code-first.md
@@ -1,16 +1,14 @@
-# 使用隐式契约
+## Implicit Contract
+### Concept Description
-## 概念阐述
+ The Implicit Contract definition is ServiceComb automatically generate a contract of service based on the service implementation class.
- 隐式契约是指ServiceComb根据服务实现类自动生成的服务契约。
+### Scenario
-## 场景描述
+ By using the implicit API definition you can define the implementation class without pre-defining APIs. When the service is started, an API is automatically generated and registered to the service center.
- 用户通过隐式契约功能，可以不预先定义契约和接口，直接定义实现类，在服务启动时，根据实现类自动生成契约，并注册到服务中心。
+### Involved API
-## 涉及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声明。
+ Implicit API definitions can be used for Spring MVC, JAX-RS, and transparent RPC development modes, For details, see [Development Style-SpringMVC](/users/develop-with-springmvc/), [Development Stype-JAX-RS](/users/develop-with-jax-rs/) and [Development Style-Transparent RPC](/users/develop-with-transparent-rpc/).
+ When you develop a microservice in transparent RPC mode, the code does not show how you want to define an API, and all generated APIs are POST methods, The input parameters of all the methods will be packaged as a class and transferred as body parameters. Therefore, if you develop providers using implicit APIs, you are advised to choose Spring MVC or JAX-RS mode to obtain complete RESTful statements.
diff --git a/java-chassis-reference/en_US/build-provider/define-contract.md b/java-chassis-reference/en_US/build-provider/define-contract.md
index e653c7e..210be5e 100644
--- a/java-chassis-reference/en_US/build-provider/define-contract.md
+++ b/java-chassis-reference/en_US/build-provider/define-contract.md
@@ -1,49 +1,46 @@
-# 定义服务契约
-``
-## 概念阐述
+# Service Contract Definition
+## Concept Description
+The Service Contract refers to the micro-service interface contract based on the OpenAPI specification. The interface definition between the server and the consumer. The java chassis provides two ways to define the contract: 'code first' and '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的开发模式下，开发人员，不必手写契约。
+* Code first
+The Producer use of Jax-RS or SpringMVC's RESTful annotation declares the input and output parameters of the interface, or with the OpenAPI annotations, to add human-readable information, such as sample code, text descriptions, etc.; when the ServiceComb engine starts, according to these annotations generate a contract description and automatically upload it to the service center.
+The producer can also be developed using the transparent RPC model, but since there is no RESTful annotation to guide how to generate the contract, at this time, the automatically generated contract very non-standard and not recommended. The consumer is called with a transparent RPC or RestTemplate.
+Under the code first development model, developers do not have to handwritten contracts.
-* contract first
+* Contract first
+In this scenario, instead of using the contract automatically generated by the framework, the contract file provided by the developer is directly used, which requires the developer to ensure the consistency of the contract and the code.
-此场景下，不使用框架自动生成的契约，而是直接使用开发人员提供的契约文件，这需要由开发人员保证契约与代码的一致性。
+## Scenario
-## 场景描述
+The service contract is used for decoupling between the server and the consumer. The server implements the service around the contract. The consumer invokes the service according to the contract, which can support the server and the consumer to implement in different programming languages.
-服务契约用于服务端和消费端的解耦，服务端围绕契约进行服务的实现，消费端根据契约进行服务的调用，可支持服务端和消费端采用不同的编程语言实现。
+> _** Description: **_
+> The service provider registers the interface contract with the service center at startup, which can be downloaded and used by the service consumer. The interface contract is micro-service-version level information. When multiple micro-service instances are started, if an instance registers the contract with the service center, the service center will not overwrite the existing contract with the contract information registered by the latecomer. Therefore, only modifying the service prov [...]
-> _**说明:**_
-> 服务提供者在启动时会将接口契约注册到服务中心，可供服务消费者下载使用。接口契约是微服务-版本级别的信息，当多个微服务实例启动时，有一个实例将契约注册到服务中心后，服务中心就不会再用后来者注册的契约信息覆盖已有的契约。因此，仅修改服务提供者的接口信息不会让服务中心存储的契约发生变化，对于服务消费者而言，获取到的接口信息依然是旧的。若要更新服务中心中的接口契约，可以选择升级微服务版本号，或者删除已有的微服务信息（后者不建议在生产环境使用）。
+### Configuration
-## 配置说明
+ServiceComb defines API in a .yaml file. It's recommended to use [Swagger Editor](http://editor.swagger.io/#/) to define the APIs. This tool can check syntax and automaticlly generate an API document. For details about the API definition file format, see [ Official OpenAPI documentation](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"目录下，目录结构如下所示。
+The API definition file is located in "resources/microservices" or "resources/applications" directory. The directory structure is as follows:
```yaml
resources
- - microservices
- - serviceName #微服务名
- - schemaId.yaml #schema接口的契约
- - applications
- - appId #应用ID
- - serviceName #微服务名
- - schemaId.yaml #schema接口的契约
+ - microservices
+ - serviceName #Microservice name
+ - schemaId.yaml #schema ID
+ - applications
+ - appId #Application ID
+ - serviceName #Service name
+ - schemaId.yaml #Schema ID
```
-
-> **注意**：
+> **Note**:
>
-> * ServiceComb的Swagger契约文件应当使用UTF-8字符集保存。如果当用户使用其他字符集保存契约文件，且文件中包含中文字符时，可能会导致未知错误。
+> * ServiceComb's Swagger contract file should be saved using the UTF-8 character set. If the user saves the contract file with a different character set and the file contains Chinese characters, it may cause an unknown error.
-## 示例代码
+### Sample Code
-`resources/microservices`目录和`resources/application`目录下的schemaId.yaml文件内容示例如下。文件中的接口定义需要与服务的实际接口相符。
+The contents of the schemaId.yaml file in the `resources/microservices` directory and the `resources/application` directory are as follows. The interface definitions in the file need to match the actual interface of the service.
```yaml
swagger: '2.0'
@@ -66,11 +63,11 @@ paths:
type: string
responses:
200:
- description: 正确返回
+ description: return value
schema:
type: string
default:
- description: 默认返回
+ description: return a default result
schema:
type: string
/sayhello:
@@ -84,11 +81,11 @@ paths:
$ref: "#/definitions/Person"
responses:
200:
- description: 正确返回
+ description: return value
schema:
type: string
default:
- description: 默认返回
+ description: return a default result
schema:
type: string
definitions:
@@ -102,15 +99,15 @@ definitions:
name: "Person"
```
-> **注意**：
->
-> * ServiceComb中的契约，建议basePath不要包含web container的web root，以及servlet的url pattern。
+> **NOTE**：
+> * Contract in ServiceComb, it is recommended that basePath not include the web root of the web container, and the url pattern of the servlet.
+
+Because ServiceComb supports deployment decoupling, it can be deployed independently from the servlet container, or deployed to the servlet container using the war, or it can be run using the embedded servlet container.
+As long as the base path does not contain the web root and the url pattern, the actual url changes caused by the deployment mode modification, the ServiceComb consumer business code does not need to be perceived, and the framework will automatically adapt.
+> * info.x-java-interface needs to indicate the specific interface path, depending on the actual situation of the project.
+> * SchemaId can contain "." characters, but it is not recommended. This is because the configuration file used by ServiceComb is in yaml format. The "." symbol is used to split the configuration item name. If the SchemaId also contains ".", some configurations that support the contract level may not be recognized correctly.
+> * The "." character cannot be included in the naming of the OperationId.
-因为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的命名中不可包含"."字符。
diff --git a/java-chassis-reference/en_US/build-provider/definition/service-definition.md b/java-chassis-reference/en_US/build-provider/definition/service-definition.md
index c7108f6..390d48d 100644
--- a/java-chassis-reference/en_US/build-provider/definition/service-definition.md
+++ b/java-chassis-reference/en_US/build-provider/definition/service-definition.md
@@ -1,47 +1,45 @@
-### 概念阐述
+# Service Definition
-服务定义信息是微服务的身份标识，它定义了服务从属于哪个应用，以及名字和版本。服务定义信息中也可以有扩展信息，用于定义服务的属性元数据。
+## Concept Description
-### 场景描述
+A service definition identifies a microservice. It defines the service name, version, and the application that the service belongs to. The service definition can also contain extended information defining the attribute metadata of a service.
-当用户定义新的微服务或修改微服务的基本信息时，会涉及到服务定义信息的创建和修改操作。
+## Scenario
-### 配置说明
+To define a new microservice or modify its basic information, you may need to create and modify service definitions.
-本章节介绍涉及microservice.yaml文件的以下配置项，文件在项目中的存放路径为src\main\resources\microservice.yaml。
+## Configuration
-表1-1配置项说明
+This section describe the following configration items related to the microservice.yaml file in the src\main\resources\ directory.
-| 配置项 | 默认值 | 取值范围 | 是否必选 | 含义 | 注意 |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| APPLICATION\_ID | - | - | 是 | 应用名 | - |
-| service\_description.name | - | - | 是 | 微服务名 | 应确保app内部唯一。微服务名支持数字、大小写字母和"-"、"\_"、"."三个特殊字符，但是不能以特殊字符作为首尾字符，命名规范为：^\[a-zA-Z0-9\]+$|^\[a-zA-Z0-9\]\[a-zA-Z0-9\_-.\]\*\[a-zA-Z0-9\]$。 |
-| service\_description.version | - | - | 是 | 微服务版本号 | - |
-| service\_description.description | - | - | 否 | 微服务描述 | |
-| service\_description.properties | - | - | 否 | 微服务元数据配置（通过microservice.yaml文件进行配置） | - |
-| service\_description.propertyExtendedClass | - | - | 否 | 微服务元数据配置（通过实现接口PropertyExtended进行配置） | 接口返回的配置会覆盖配置文件中key相同的配置。 |
-| instance\_description.properties | - | - | 否 | 服务实例元数据配置（通过microservice.yaml文件进行配置） | |
-| instance\_description.propertyExtendedClass | - | - | 否 | 微服务元数据配置（通过实现接口PropertyExtended进行配置） | 同service\_description.propertyExtendedClass |
+| Configuration on Item | Default | Range | Mandatory | Description | Remarks |
+| :--------------------------------------- | :------ | :---- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| APPLICATION\_ID | - | - | Yes | Indicates an application name. | - |
+| service\_description.name | - | - | Yes | Indicates a microservice name | The microservice name should be unique within an application. The name can contain digits, uppercase and lowercase letters, hyphens(-), underscores(_), and periods(.); and can neither start nor end with punctuations. The naming rule is as follows: ^\[a-zA-Z0-9\]+$|^\[a-zA-Z0-9\]\[a-zA-Z0-9\_-.\]\*\[a-zA-Z0-9\]$. |
+| service\_description.version | - | - | Yes | Indicates a service version. | - |
+| service\_description.properties | - | - | No | Configures microservice metadata(in the microservice.yaml file). | - |
+| service\_description.propertyExtendedClass | - | - | No | Configures microservice metadata(through the PropertyExtended API). | The configurations returned through the API will overwrite those with the same keys in the configuration file. |
+| instance\_description.properties | - | - | No | Configures instance metadata(in the microservice.yaml file) | |
+| instance\_description.propertyExtendedClass | - | - | No | Configures microservice metadata(through the PropertyExtended API). | The configurations returned through the API will overwrite thos with the same keys in the configuration file. |
-> 说明：
->
-> * 服务的元数据会随服务一同注册到服务中心，如需修改，则要连同服务version一起变更。若想保持服务version不变，则需要通过服务管理中心统一变更元数据。
-> * 虽然微服务名、契约名中可以使用"."字符，但是不推荐在命名中使用"."。这是由于ServiceComb使用的配置文件是yaml格式的，"."符号用于分割配置项名称，如果微服务名、契约名中也包含了"."可能会导致一些支持微服务、契约级别的配置无法正确被识别。
+> NOTE：
+- The metadata of a service is registered to the service center with the service. It is changed together with the service version. Changing metadata in the service center will keep the version unchanged.
+- By default, one microservice can be called by only one APPLICATION_ID. You can set allowCrossApp=true in microservice properties to access a microservice acroos APPLICATION_ID.
-### 示例代码
+## Sample Code
```yaml
-APPLICATION_ID: helloTest # 应用名
-service_description: # 服务描述
- name: helloServer # 微服务名称
- version: 0.0.1 # 服务版本号
- properties: # 元数据
- key1: value1
+APPLICATION_ID: helloTest #Application name
+service_description: #Service description
+ name: helloServer #Microservice name
+ version: 0.0.1 #Service version
+ properties: #Metadata
+ allowCrossApp: false
+ key1: value1
key2: value2
- description: This is a description about the microservice # 微服务描述
- propertyExtentedClass: org.apache.servicecomb.serviceregistry.MicroServicePropertyExtendedStub
-instance_description: #实例描述
- properties: #元数据
+ propertyExtendedClass: org.apache.servicecomb.serviceregistry.MicroServicePropertyExtendedStub
+instance_description: #Instance description
+ properties: #Metadata
key3: value3
- propertyExtentedClass: org.apache.servicecomb.serviceregistry.MicroServicePropertyExtendedStub
+ propertyExtendedClass: org.apache.servicecomb.serviceregistry.MicroServicePropertyExtendedStub
```
diff --git a/java-chassis-reference/en_US/build-provider/interface-constraints.md b/java-chassis-reference/en_US/build-provider/interface-constraints.md
index 48a693d..c00e402 100644
--- a/java-chassis-reference/en_US/build-provider/interface-constraints.md
+++ b/java-chassis-reference/en_US/build-provider/interface-constraints.md
@@ -1,10 +1,9 @@
-# 接口定义和数据类型
+# API Constraints
+A Java Chassis API constraints is that an API definition should describe its usage. You can identify how to call the API without checking the code.
-## 接口定义的要求
+As developers, we aim at making our APIs easy to be called. However, developers have different understanding about this aim.
-ServiceComb-Java-Chassis建议接口定义遵循一个简单的原则：接口定义即接口使用说明，不用通过查看代码实现，就能识别如何调用这个接口。可以看出，这个原则站在使用者这边，以更容易被使用作为参考。ServiceComb会根据接口定义生成接口契约，符合这个原则的接口，生成的契约也是用户容易阅读的。
-
-举个例子：
+For example:
```java
public Person query(String id);
@@ -12,149 +11,50 @@ public Object query(String id);
public class Person {String name;}
```
-显然调用接口一，我们知道要传递一个String类型的id参数，返回值是一个Person类型，Person里面存在String类型的name参数。调用接口二，我们不知道怎么处理返回值，必须参考服务提供者的文档说明。这个视角是熟练的RPC开发者的视角。
+Obviously, if API 1 is called, we know that an ID parameter of String type needs to be transferred. The returned value is of Person type, which contains a string-typed name parameter. If API 2 is called, we do not know how to process the returned value, and need to refer to documents provided by the service provider. API 2 is developed in the perspective of RPC developers.
-当我们要将接口发布为REST接口的时候，可以指定接口参数和HTTP协议的映射关系，比如：
+To release an API as a REST API, we can use the swagger file; specify the ID to be transmitted using RequestParam, PathVariable, or RequestBody; or use the label provided by SpringMVC or JAX-RS.
```java
-public Person query(@RequestParam String id);
-public Person query(@PathVariable String id);
-public void save(@RequestBody Person person);
-```
-
-通常，我们会将简单的数据类型，比如String, int等在RequestParam或者PathVariable传递，而把复杂的数据类型使用JSON编码以后在RequestBody传递，以减少HTTP协议限制可能给开发者带来的各种问题。这个视角是熟练的REST开发者的视角，在RPC开发者的视角之外，REST开发者需要理解的信息更多，他们不仅需要知道RPC接口，还需要了解接口和HTTP协议的绑定关系，要理解JAVA对象如何在HTTP的消息中进行转换。
-
-ServiceComb-Java-Chassis还有一个约束：接口定义必须符合Open API的规范，从而能够更好的在不同语言之间进行协作，能够支持除了HTTP以为的其他协议和编码。熟练的SpringMVC、JAX-RS开发者会发现一些特殊的用法无法使用，比如使用HttpServletRequest来解析HTTP头信息等。再比如，按照Open API规范，每个接口都必须有唯一的ID，如果开发者需要使用重载，那么必须显示的使用@ApiOperation给重载方法赋予唯一的ID。ServiceComb-Java-Chassis接口定义要求符合下面的范式：
-
+public Person query(@RequestParam String id);
+public Person query(@PathVariable String id);
+public Person query(@RequestBody String id);
```
-@SupportedAnnotations
-ResponseType methodName(RequestType...)
-```
-
-不能定义异常、不能包含在接口原型未声明的错误码和输出（如果没声明错误码，缺省的错误码除外，比如HTTP 的200）。
-
-通常，系统约束越多，那么就更加容易对系统进行统一的管控和治理；开发方式越自由，实现业务功能则更加快速，需要在这两方面取得一些平衡。ServiceComb-Java-Chassis是比gRPC要灵活很多的框架，同时也去掉了Spring MVC的一些不常用的扩展。开发者可以在ServiceComb-Java-Chassis讨论区反馈开发过程中期望支持的场景，更好的维护这个平衡。期望这个讨论是围绕某个具体的应用场景来进行的，比如上传文件如何更好的进行，而不是具体的开发方式进行的，比如使用Object来传递参数。
-
-## 详细的约束列表
-
-开发者不能在接口定义的时候使用如下类型：
-* 抽象的数据结构: java.lang.Object, net.sf.json.JsonObject等
- **备注：** 最新版本可以使用java.lang.Object作为参数和返回值。它的运行时类型可以是int、String、Map等。尽管如此，建议开发者不要使用抽象数据结构，以及第三方提供的非POJO类作为接口的参数和返回值。这些类型包括java.math.BigDecimal、org.joda.time.JodaTime等。这些类型会给开发者带来很大的困扰。比如开发者可能以为BidDecimal会以数字传输，实际不然，并且在某些内部状态没正确计算的情况下，得到的并不是用户预期的值。
-* 接口或者抽象类
- ```java
- public interface IPerson {//...}
- public abstract class AbstractPerson {//...}
- ```
+Generally , simple data types, such as String and int, are transmitted in RequestParam or PathVariable, and complex data types are transmitted in RequestBody after being coded using JSON, to reduce problems cause by HTTP protocol restrictions on developers.
-* 上述类型的集合类型或者没有指定具体类型的集合，比如：`List<IPerson>, Map<String, PersonHolder<?>>, List, Map`等。 `List<String>, List<Person>`这些具体类型是支持的。
+## Detailed Constraint List
+Developers cannot use the following types to define APIs:
-* 包含上述类型作为属性的类型
+* Abstract data structures, such as java.lang.Object, net.sf.json.JsonObject
+* API or abstract class
+ ```java
+ public interface IPerson {...}
+ public abstract class AbstractPerson {...}
+ ```
+* Generic type
+ ```java
+ public class PersonHolder<T> {...}
+ ```
+* A collection type of the preceding types or a set without a specified type, such as `List<IPerson>, Map<String, PersonHolder<?>>, List, Map`. such as `List<String>, List<Person>` are supported.
- ```java
- public class GroupOfPerson {IPerson master //...}
- ```
+ ```java
+ public class GroupOfPerson {IPerson master ...}
+ ```
-开发者不用担心记不住这些约束，程序会在启动的时候检查不支持的类型，并给与错误提示。
-总之，数据结构需要能够使用简单的数据类型进行描述，一目了然就是最好的。这个在不同的语言，不同的协议里面都支持的很好，长期来看，可以大大减少开发者联调沟通和后期重构的成本。
+Developers do not need to worry about the constraints. The program automatically checks them when it is started, and displays types as properties.
-### 关于数据结构和接口变更
-接口名称、参数类型、参数顺序、返回值类型变更都属于接口变更。ServiceComb启动的时候，会根据版本号检测接口变化，接口变化要求修改版本号。ServiceComb识别接口是否变化是通过代码生成的契约内容，有些不规范的接口定义可能导致在代码没有变化的情况下，生成的契约不同。比如：
-
-```
-public void get(Person p)
-class Person {
- private String value;
- private boolean isOk;
- public String getName() {return value}
- public boolean isOk() {return isOK}
-}
-```
-
-这个接口通过access method定义了"name"和"ok"两个属性，和实际的字段"value"和"isOk"不同。这种情况可能导致每次启动生成的契约不一样。需要将代码调整为符合JAVA Bean规范的定义。
-```
-public void get(Person p)
-class Person {
- private String name;
- private boolean ok;
- public String getName() {return name}
- public boolean isOk() {return ok}
-}
-```
-
-或者通过JSON标注，显示的指明字段顺序。比如：
-
-```
-public void get(Person p)
-@JsonPropertyOrder({"name", "ok"})
-class Person {
- private String value;
- private boolean isOk;
- public String getName() {return value}
- public boolean isOk() {return isOK}
-}
-```
+## Protocol Difference
+Although ServiceComb-Java-Chassis implements transparent transmission between protocols, there are slight differences between protocols due to the limitations of the underlying protocols:
-考虑到接口变更的影响，建议在进行对外接口定义的时候，尽可能不要使用第三方软件提供的类作为接口参数，而是使用自定义的POJO类。一方面升级三方件的时候，可能感知不到接口变化；另外一方面，如果出现问题，无法通过修改第三方代码进行规避。比如：java.lang.Timestamp, org.joda.time.JodaTime等。
+* Map, The key supports only string.
-## 协议上的差异
+* highway (protobuf restriction)
+ 1. Null values cannot be transmitted over the network, including elements in Collection and array, and value in map.
+ 2. The array and list with the length of 0 are not transmitted over the network. The receiver obtains the default value after decoding them.
-尽管ServiceComb-Java-Chassis实现了不同协议之间开发方式的透明，受限于底层协议的限制，不同的协议存在少量差异。
-
-* map，key只支持string
-
-* highway \(protobuf限制\)
- 1. 不支持在网络上传递null，包括Collection、array中的元素，map的value
- 2. 长度为0的数组、list，不会在网络上传递，接收端解码出来就是默认值
-
-* springmvc
- 1. 不支持Date作为path、query参数。 因为springmvc直接将Date做toString放在path、query中，与swagger的标准不匹配。
-
-## 泛型支持
-
-ServiceComb-Java-Chassis 支持REST传输方式下的泛型请求参数和返回值。例如使用一个泛型的数据类型:
-```java
-public class Generic<T>{
- public T value;
-}
-```
-其中的泛型属性T可以是一个实体类、java.util.Date、枚举，也可以嵌套泛型数据类型。
-
-当用户使用隐式契约功能自动生成微服务契约时，需要在provider接口方法的返回消息中明确指定泛型类型，以保证 ServiceComb-Java-Chassis 生成的契约中包含足够的接口信息。例如，当provider端接口方法代码为
-```java
-public Generic<List<Person>> getHolderListArea() {
- Holder<List<Person>> response = new Holder<>();
- // ommited
- return response;
-}
-```
-时， ServiceComb-Java-Chassis 能够识别出泛型返回对象的确切信息，以保证consumer端接收到的应答消息能够被正确地反序列化。
-而如果provider端接口方法的代码为
-```java
-public Generic getHolderListArea() {
- Holder<List<Person>> response = new Holder<>();
- // ommited
- return response;
-}
-```
-时，由于契约中缺少List元素的类型信息，就会出现consumer端无法正确反序列化应答的情况，比如consumer接收到的参数类型可能会变为`Holder<List<Map<String,String>>>`，`Person`对象退化为Map类型。
-
-> ***说明:***
-> 虽然 ServiceComb-Java-Chassis 支持REST泛型参数，但是我们更加推荐用户使用实体类作为参数，以获得更加明确的接口语义。
-
-## 其他常见问题
-
-* 使用RestTemplate传递raw json
-假设服务端定义了接口
-```
-Person test(Person input)
-```
-用户期望使用RestTemplate自行拼接json字符串，然后进行传递:
-```
- String personStr = JsonUtils.writeValueAsString(input);
- result = template.postForObject(cseUrlPrefix + "sayhello", personStr, Person.class);
-```
-ServiceComb不推荐开发者这样使用，里面的处理逻辑存在大量歧义。如果必须使用，需要满足几个约束：Person必须包含带String类型的构造函数；provider/consumer都必须存在这个Person类型。
\ No newline at end of file
+* springmvc
+ 1. Date cannot be used for the path or query parameter. Spring MVC stores toString in path and query, which does not match the swagger standard.
diff --git a/java-chassis-reference/en_US/build-provider/jaxrs.md b/java-chassis-reference/en_US/build-provider/jaxrs.md
index b004e33..f1ce76a 100644
--- a/java-chassis-reference/en_US/build-provider/jaxrs.md
+++ b/java-chassis-reference/en_US/build-provider/jaxrs.md
@@ -1,198 +1,136 @@
-# 用JAX-RS开发微服务
-## 概念阐述
-
-ServiceComb支持开发者使用JAX-RS注解，使用[JAX-RS](https://github.com/apache/incubator-servicecomb-java-chassis/tree/master/samples/jaxrs-sample)模式开发服务。
-
-## 开发示例
-
-### 步骤 1定义服务接口。
-
-根据开发之前定义好的契约，编写Java业务接口，代码如下。定义接口不是必须的，但是 一个好习惯，可以简化客户端使用RPC方式编写代码。
-
-```java
-public interface Hello {
- String sayHi(String name);
- String sayHello(Person person);
-}
-```
-
-
-
-### 步骤 2实现服务。
-
-使用JAX-RS注解开发业务代码，Hello的服务实现如下：
-
-```java
-@RestSchema(schemaId = "jaxrsHello")
-@Path("/jaxrshello")
-@Produces(MediaType.APPLICATION_JSON)
-public class JaxrsHelloImpl implements Hello {
- @Path("/sayhi")
- @POST
- @Override
- public String sayHi(String name) {
- return "Hello " + name;
- }
-
- @Path("/sayhello")
- @POST
- @Override
- public String sayHello(Person person) {
- return "Hello person " + person.getName();
- }
- /**
- * 这个方法是实现类特有的,因此对它的远程调用会有所不同.
- * 具体可以参考 jaxrs-consumer
- */
- @Path("/saybye")
- @GET
- public String sayBye() {
- return "Bye !";
- }
-}
-```
-
-### 步骤 3发布服务。
-
-在resources/META-INF/spring目录下创建jaxrsHello.bean.xml文件，配置spring进行服务扫描的base-package，文件内容如下。（注意修改package名称为正确名称）
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<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:cse=" http://www.huawei.com/schema/paas/cse/rpc "
- xmlns:context=" http://www.springframework.org/schema/context "
- xsi:schemaLocation=" http://www.springframework.org/schema/beans classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd http://www.huawei.com/schema/paas/cse/rpc classpath:META-INF/spring/spring-paas-cse-rpc.xsd">
-
- <context:component-scan base-package="org.apache.servicecomb.samples.jaxrs.provider"/>
-</beans>
-```
-
-### 步骤 4启动服务。
-
-```
-public class JaxrsProviderMain{
-
- public static void main(String[] args) throws Exception {
- Log4jUtils.init();
- BeanUtils.init();
- }
-}
-```
-
-## 涉及API
-
-JAX-RS开发模式当前支持如下注解，所有注解的使用方法参考[JAX-RS官方文档](https://jax-rs-spec.java.net/nonav/2.0-rev-a/apidocs/index.html)。
-
-### 表1-1JAX-RS注解支持汇总
-
-| 注解 | 位置 | 描述 |
-| :--- | :--- | :--- |
-| javax.ws.rs.Path | schema/operation | URL路径 |
-| javax.ws.rs.Produces | schema/operation | 方法支持的编解码能力 |
-| javax.ws.rs.DELETE | operation | http method |
-| javax.ws.rs.GET | operation | http method |
-| javax.ws.rs.POST | operation | http method |
-| javax.ws.rs.PUT | operation | http method |
-| javax.ws.rs.QueryParam | parameter | 从query string中获取参数 |
-| javax.ws.rs.PathParam | parameter | 从path中获取参数，必须在path中定义该参数 |
-| javax.ws.rs.HeaderParam | parameter | 从header中获取参数 |
-| javax.ws.rs.CookieParam | parameter | 从cookie中获取参数 |
-| javax.ws.rs.FormParam | parameter | 从form中获取参数 |
-| javax.ws.rs.BeanParam | parameter | 用于参数聚合，允许在一个JavaBean的属性上打上参数标记以将多个参数聚合为一个JavaBean |
-
-> **说明:**
->
-> * 当方法参数没有注解，且不为`HttpServletRequest`、`InvocationContext`类型参数时，默认为body类型参数，一个方法最多只支持一个body类型参数。
-
-## 使用@BeanParam聚合参数
-
-### 使用说明
-
-用户可以使用@BeanParam注解将多个参数聚合到一个JavaBean中，通过将@QueryParam等参数注解打在此JavaBean的属性或setter方法上来声明参数，从而简化业务接口的参数表。可以参考JAX-RS的官方说明：https://docs.oracle.com/javaee/7/api/javax/ws/rs/BeanParam.html
-
-ServiceComb现在也支持类似的用法，该用法的要求如下：
-1. 聚合参数所用的类型必须是标准的JavaBean，即类型的属性与getter、setter方法名称匹配，setter方法的返回类型为`void`
-2. 参数注解可以打在JavaBean的属性或setter方法上
-3. 允许通过@FormParam将多个上传文件参数聚合到JavaBean中
-4. 作为BeanParam的JavaBean内部如果有多余的属性，需要打上`@JsonIgnore`忽略掉
-5. body参数无法聚合进BeanParam
-6. Consumer端不支持将参数聚合为JavaBean发送，即仍然需要按照接口契约单独填写各个参数
-
-### 代码示例
-
-#### Provider端开发服务
-
-- Provider端业务接口代码：
-```java
- @RestSchema(schemaId = "helloService")
- @Path("/hello")
- public class HelloService {
- @Path("/sayHello/{name}")
- @GET
- public String sayHello(@BeanParam Person person) {
- System.out.println("sayHello is called, person = [" + person + "]");
- return "Hello, your name is " + person.getName() + ", and age is " + person.getAge();
- }
- }
-```
-- BeanParam参数定义：
-```java
- public class Person {
- private String name;
- @QueryParam("age")
- private int age;
- @PathParam("name")
- public void setName(String name) {
- this.name = name;
- }
- @JsonIgnore // 忽略复杂属性
- private List<Person> children;
-
- // 其他方法忽略
- }
-```
-- 接口契约：
-```yaml
-# 忽略契约的其他部分
-basePath: "/hello"
-paths:
- /sayHello/{name}:
- get:
- operationId: "sayHello"
- parameters:
- - name: "name"
- in: "path"
- required: true
- type: "string"
- - name: "age"
- in: "query"
- required: false
- type: "integer"
- format: "int32"
- responses:
- 200:
- description: "response of 200"
- schema:
- type: "string"
-```
-
-#### Consumer端调用服务
-
-- consumer端RPC开发模式：
- - Provider接口定义
- ```java
- public interface HelloServiceIntf {
- String sayHello(String name, int age);
- }
- ```
- - 调用代码
- ```java
- String result = helloService.sayHello("Bob", 22); // result的值为"Hello, your name is Bob, and age is 22"
- ```
-- consumer端RestTemplate开发模式：
- ```java
- String result = restTemplate.getForObject(
- "cse://provider-service/hello/sayHello/Bob?age=22",
- String.class); // 调用效果与RPC方式相同
- ```
+# Develop Microservice with JAX-RS
+## Concept Description
+
+ServiceComb supports developers in developing services in JAX-RS mode by using JAX-RS.
+
+## Development Example
+
+* **Step 1** Import dependencies into your maven project:
+
+ ```xml
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>java-chassis-dependencies</artifactId>
+ <version>1.0.0-m1</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+ <dependencies>
+ <!--transport can optional import through endpoint setting in microservice.yaml, we import both rest and highway as example-->
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>transport-rest-vertx</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>transport-highway</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>provider-jaxrs</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-log4j12</artifactId>
+ </dependency>
+ </dependencies>
+ ```
+
+* **Step 2** Implement the service. JAX-RS is used to describe the development of service code. The implementation of the Hello service is as follows:
+
+ ```java
+ import javax.ws.rs.POST;
+ import javax.ws.rs.Path;
+ import javax.ws.rs.Produces;
+ import javax.ws.rs.core.MediaType;
+ import org.apache.servicecomb.samples.common.schema.models.Person;
+
+ @Path("/jaxrshello")
+ @Produces(MediaType.APPLICATION_JSON)
+ public class JaxrsHelloImpl {
+ @Path("/sayhi")
+ @POST
+ public String sayHi(String name) {
+ return "Hello " + name;
+ }
+
+ @Path("/sayhello")
+ @POST
+ public String sayHello(Person person) {
+ return "Hello person " + person.getName();
+ }
+ }
+ ```
+
+ **Note: PLEASE MAKE SURE TO MARK @Path ON YOUR PRODUCER(JaxrsHelloImpl), OR THE PATH AND METHOD OF PUBLISHED WILL BE INCORRECT!**
+
+ In this sample the Path of sayHi is `/jaxrshello/sayhi`, and the Path of sayHello is `/jaxrshello/sayhello`, if you wish them `/sayhi` and `/sayhello`, please change the setting of `@Path` on the JaxrsHelloImpl to `@Path("/")`.
+
+* **Step 3** Release the service. Add ```@RestSchema``` as the annotation of the service implementation class and specify schemaID, which indicates that the implementation is released as a schema of the current microservice. The code is as follows:
+
+ ```java
+ import org.apache.servicecomb.provider.rest.common.RestSchema;
+ // other code omitted
+ @RestSchema(schemaId = "jaxrsHello")
+ public class JaxrsHelloImpl implements Hello {
+ // other code omitted
+ }
+ ```
+
+ Create the jaxrsHello.bean.xml file in the resources/META-INF/spring directory and configure base-package that performs scanning. The content of the file is as follows:
+
+ ```xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <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:cse="http://www.huawei.com/schema/paas/cse/rpc"
+ xmlns:context="http://www.springframework.org/schema/context"
+ xsi:schemaLocation="http://www.springframework.org/schema/beans classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd http://www.huawei.com/schema/paas/cse/rpc classpath:META-INF/spring/spring-paas-cse-rpc.xsd">
+
+ <context:component-scan base-package="org.apache.servicecomb.samples.jaxrs.provider"/>
+ </beans>
+ ```
+
+* **Step 4** Add service definition file:
+
+ Add [microservice.yaml](http://servicecomb.incubator.apache.org/cn/users/service-definition/) file into resources folder of your project.
+
+* **Step 5** Add Main class:
+
+ ```java
+ import org.apache.servicecomb.foundation.common.utils.BeanUtils;
+ import org.apache.servicecomb.foundation.common.utils.Log4jUtils;
+
+ public class Application {
+ public static void main(String[] args) throws Exception {
+ //initializing log, loading bean(including its parameters), and registering service, more detail can be found here : http://servicecomb.incubator.apache.org/users/application-boot-process/
+ Log4jUtils.init();
+ BeanUtils.init();
+ }
+ }
+ ```
+
+## Involved APIs
+
+Currently, the JAX-RS development mode supports the following annotation. For details about how to use JAX-RS, see [JAX-RS official documentation](https://jax-rs-spec.java.net/nonav/2.0-rev-a/apidocs/index.html)。
+
+| Remarks | Location | Description |
+| :---------------------- | :--------------- | :--------------------------------------- |
+| javax.ws.rs.Path | schema/operation | URL path |
+| javax.ws.rs.Produces | schema/operation | Coding/decoding capability supported by the method |
+| javax.ws.rs.DELETE | operation | http method |
+| javax.ws.rs.GET | operation | http method |
+| javax.ws.rs.POST | operation | http method |
+| javax.ws.rs.PUT | operation | http method |
+| javax.ws.rs.QueryParam | parameter | Obtain parameters from query string |
+| javax.ws.rs.PathParam | parameter | Obtain parameters from path, This parameter must be defined in path. |
+| javax.ws.rs.HeaderParam | parameter | Obtain parameters from header. |
+| javax.ws.rs.CookieParam | parameter | Obtain parameters from cookie. |
+
+> **NOTE**：
+- When the method parameter has no annotation and is not an HttpServletRequest parameter, the parameter is of the body type by default. One method supports a maximum of one body-typed parameter.
+- You are advised to explicitly define the value of the parameter. Otherwise, the parameter name in the API definition is used, such as `@QueryParam\("name"\) String name` String name instead of `@QueryParam String name`.
diff --git a/java-chassis-reference/en_US/build-provider/protocol.md b/java-chassis-reference/en_US/build-provider/protocol.md
index 6e28c80..fddcd8b 100644
--- a/java-chassis-reference/en_US/build-provider/protocol.md
+++ b/java-chassis-reference/en_US/build-provider/protocol.md
@@ -1,5 +1,12 @@
-# 通信协议
+# Communication Protocol
+### Concept Description
-### 概念阐述
+ServiceComb uses two network channels, REST and Highway, both supporting encrypted Transport Layer Security (TLS) transmission. The REST channel releases services in the standard RESTful form. The consumer can send requests using http client.
-ServiceComb实现了两种网络通道，包括REST和Highway，均支持TLS加密传输。其中，REST网络通道将服务以标准RESTful形式发布，调用端兼容直接使用http client使用标准RESTful形式进行调用。
+### Precautions
+
+Serialization of parameters and the returned values:
+
+Currently, the body parameters of the REST channel support only the application/json serialization. To send form-type parameters to the server, construct a body of the application/json format at the consumer end. Do not send the form type parameters in multipart/form-data format.
+
+Currently, the REST channel supports the application/json and text/plain serialization. A provider uses produces to declare that it has the serialization capability. The consumer specifies the serialization mode of the returned values by setting parameters regarding the requested Accept header. Data serialized in application/json serialization mode is returned by default.
diff --git a/java-chassis-reference/en_US/build-provider/protocol/highway-rpc.md b/java-chassis-reference/en_US/build-provider/protocol/highway-rpc.md
index d536036..ee003d2 100644
--- a/java-chassis-reference/en_US/build-provider/protocol/highway-rpc.md
+++ b/java-chassis-reference/en_US/build-provider/protocol/highway-rpc.md
@@ -1,41 +1,39 @@
-## 概念阐述
+## Highway RPC Protocol
+### Concept Description
-Highway是ServiceComb的高性能私有协议，用户可在有特殊性能需求的场景下选用。
+Highway is a high-performance proprietary protocol of ServiceComb, and you can use it in scenarios having special performance requirements.
-## 配置说明
+### Configuration
-使用Highway网络通道需要在maven pom文件中添加如下依赖：
+To use the Highway communication channel, you need to add the following dependencies in the maven pom.xml file:
```xml
- <dependency>
- <groupId>org.apache.servicecomb</groupId>
- <artifactId>transport-highway</artifactId>
- </dependency>
+<dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>transport-highway</artifactId>
+</dependency>
```
-Highway通道在microservice.yaml文件中的配置项如下表所示：
+Configuration items that need to be set in the microservice.yaml file are described as follows:
-表1-1Highway配置项说明
+Table 3 Configuration items of Highway
-| 配置项 | 默认值 | 取值范围 | 是否必选 | 含义 | 注意 |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| servicecomb.highway.address | 0.0.0.0:7070 | - | 否 | 服务监听地址 | - |
-| servicecomb.highway.server.thread-count | 1 | - | 否 | 服务端网络线程个数 | - |
-| servicecomb.highway.server.connection-limit | Integer.MAX_VALUE | - | 否 | 允许客户端最大连接数 | - |
-| servicecomb.highway.client.thread-count | 1 | - | 否 | 客户端网络线程个数 | - |
-| servicecomb.request.timeout | 30000 | - | 否 | 请求超时时间 | 同REST over Vertx的配置 |
-| servicecomb.references.\[服务名\].transport | rest | | 否 | 访问的transport类型 | 同REST over Vertx的配置 |
-| servicecomb.references.\[服务名\].version-rule | latest | - | 否 | 访问实例的版本号 | 同REST over Vertx的配置 |
+| Configuration Item | Default Value | Value Range | Mandatory | Description | Remark |
+| :--------------------------------------- | :------------ | :---------- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| servicecomb.highway.address | 0.0.0.0:7070 | - | No | Specifies the server listening IP address. | - |
+| servicecomb.highway.server.thread-count | 1 | - | No | Specifies the number of server network threads. | - |
+| servicecomb.highway.client.thread-count | 1 | - | No | Specifies the number of client network threads. | - |
+| servicecomb.highway.client.connection-pool-per-thread | 1 | - | No | Specifies the number of connection pools in each client thread. | - |
+| servicecomb.request.timeout | 30000 | - | No | Specifies the request timeout duration. | The configuration of this parameter for Highway is the same as that for REST over Vertx. |
+| servicecomb.references.\[服务名\].transport | rest | | No | Specifies the accessed transport type. | The configuration of this parameter for Highway is the same as that for REST over Vertx. |
+| servicecomb.references.\[服务名\].version-rule | latest | - | No | Specifies the version of the accessed instance. | The configuration of this parameter for Highway is the same as that for REST over Vertx. |
-## 示例代码
+###
-microservice.yaml文件中的配置示例：
+An example of the configuration in the microservice.yaml file for Highway is as follows:
```yaml
servicecomb:
highway:
address: 0.0.0.0:7070
```
-
-
-
diff --git a/java-chassis-reference/en_US/build-provider/protocol/rest-over-servlet.md b/java-chassis-reference/en_US/build-provider/protocol/rest-over-servlet.md
index a451b01..e4ddb09 100644
--- a/java-chassis-reference/en_US/build-provider/protocol/rest-over-servlet.md
+++ b/java-chassis-reference/en_US/build-provider/protocol/rest-over-servlet.md
@@ -1,27 +1,4 @@
-# REST over Servlet
-REST over Servlet对应使用web容器部署运行，需要新建一个servlet工程将微服务包装起来，打成war包，加载到web容器中启动运行。
-## 对外发布的Path
-当微服务部署到web容器中时，相对于独立运行，会涉及到web root以及servlet url pattern对url的改变。
-对于传统开发框架而言，需要consumer感知对方的完整url；比如web root为/mywebapp，url pattern为/rest，业务级path为/application，则consumer代码必须通过/mywebapp/rest/application来访问。
-这将导致一旦部署方式发生变化，比如从web容器变成standalone运行，则consumer或是producer必须修改代码来适配这个变化。
-
-建议使用ServiceComb的部署解耦特性，无论是consumer，还是producer，在代码中都不要感知web root以及url pattern，这样ServiceComb在运行时，会自动适配producer实例的web root以及url pattern。
-
-对于一些遗留系统改造，用户期望继续使用restTemplate.getForObject("cse://serviceName/mywebapp/rest/application"...)，这个时候，用户必须将接口定义的path定位为: /mywebapp/rest/application，例如：
-```
-@RestSchema(schemaId = "test")
-@RequestMapping(path = "/mywebapp/rest/application")
-```
-
-尽管如此，仍然推荐使用部署形态无关的方式来编码，可以减少后续由于部署形态变化，带来的修改代码问题。
-## maven依赖
-```xml
-<dependency>
- <groupId>org.apache.servicecomb</groupId>
- <artifactId>transport-rest-servlet</artifactId>
-</dependency>
-```
-
+## REST over Servlet
## 配置说明
与servlet机制配合，涉及到以下几个概念：
* 启动spring context
@@ -187,16 +164,3 @@ RestServlet工作于异步模式，根据servlet 3.0的标准，整条工作链
</filter>
```
-## **配置项**
-
-REST over Servlet在microservice.yaml文件中的配置项见表3-9。
-
-表1-1 REST over Servlet配置项说明
-
-| 配置项 | 默认值 | 取值范围 | 是否必选 | 含义 | 注意 |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| servicecomb.rest.address | 0.0.0.0:8080 | - | 否 | 服务监听地址 | 必须配置为与web容器监听地址相同的地址 |
-| servicecomb.rest.server.timeout | 3000 | - | 否 | 超时时间 | 单位为毫秒 |
-| servicecomb.rest.servlet.urlPattern | 无 | | 否 | 用于简化servlet+servlet mapping配置 | 只有在web.xml中未配置servlet+servlet mapping时，才使用此配置项，配置格式为：/\* 或 /path/\*，其中path可以是多次目录 |
-
-
diff --git a/java-chassis-reference/en_US/build-provider/protocol/rest-over-vertx.md b/java-chassis-reference/en_US/build-provider/protocol/rest-over-vertx.md
index 56dbfe6..1512754 100644
--- a/java-chassis-reference/en_US/build-provider/protocol/rest-over-vertx.md
+++ b/java-chassis-reference/en_US/build-provider/protocol/rest-over-vertx.md
@@ -1,46 +1,46 @@
-## 配置说明
+## REST over Vertx
+### Configuration
-REST over Vertx通信通道对应使用standalone部署运行模式，可直接通过main函数拉起。main函数中需要初始化日志和加载服务配置，代码如下：
+The REST over Vertx communication channel uses the standalone running mode that can be started using the main function. In the main function, you need to initialize logs and load service configuration. The code is as follow:
```java
+import org.apache.servicecomb.foundation.common.utils.BeanUtils;
+import org.apache.servicecomb.foundation.common.utils.Log4jUtils;
+
public class MainServer {
- public static void main(String[] args) throws Exception {
- Log4jUtils.init();//日志初始化
- BeanUtils.init(); // Spring bean初始化
- }
+ public static void main(String[] args) throws Exception {
+ Log4jUtils.init();//Log initialization
+ BeanUtils.init(); // Spring bean initialization
+ }
}
```
-使用REST over Vertx网络通道需要在maven pom文件中添加如下依赖：
+To use the REST over Vertx communication channel, you need to add the following dependencies in the maven pom.xml file:
```xml
<dependency>
- <groupId>org.apache.servicecomb</groupId>
- <artifactId>transport-rest-vertx</artifactId>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>transport-rest-vertx</artifactId>
</dependency>
```
-REST over Vertx通道在microservice.yaml文件中有以下配置项：
+Configuration items that need to be set in the microservice.yaml file are described as follows:
-表1-1 REST over Vertx配置项说明
+Table 2 Configuration items of REST over Vertx
-| 配置项 | 默认值 | 取值范围 | 是否必选 | 含义 | 注意 |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| servicecomb.rest.address | 0.0.0.0:8080 | - | 否 | 服务监听地址 | 仅服务提供者需要配置 |
-| servicecomb.rest.server.thread-count | 1 | - | 否 | 服务端线程数 | 仅服务提供者需要配置 |
-| servicecomb.rest.server.connection-limit | Integer.MAX_VALUE | - | 否 | 允许客户端最大连接数 | 仅服务提供者需要配置 |
-| servicecomb.rest.server.connection.idleTimeoutInSeconds | 60 | - | 否 | 服务端连接闲置超时时间 | 闲置连接会被回收 |
-| servicecomb.rest.client.thread-count | 1 | - | 否 | 客户端网络线程数 | 仅服务消费者需要配置 |
-| servicecomb.rest.client.connection.maxPoolSize | 5 | - | 否 | 每个连接池的最大连接数 | 连接数=网络线程数\*连接池个数\*连接池连接数 |
-| servicecomb.rest.client.connection.idleTimeoutInSeconds | 30 | - | 否 | 连接闲置时间 | 闲置连接会被回收 |
-| servicecomb.rest.client.connection.keepAlive | true | - | 否 | 是否使用长连接 | |
-| servicecomb.request.timeout | 30000 | - | 否 | 请求超时时间 | |
-| servicecomb.references.\[服务名\].transport | rest | | 否 | 访问的transport类型 | 仅服务消费者需要配置 |
-| servicecomb.references.\[服务名\].version-rule | latest | - | 否 | 访问实例的版本号 | 仅服务消费者需要配置支持latest，1.0.0+，1.0.0-2.0.2，精确版本。详细参考服务中心的接口描述。 |
+| Configuration Item | Default Value | Value Range | Mandatory | Description | Remark |
+| :--------------------------------------- | :------------ | :---------- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| servicecomb.rest.address | 0.0.0.0:8080 | - | No | Specifies the server listening IP address. | Only service providers require this parameter. |
+| servicecomb.rest.server.thread-count | 1 | - | No | Specifies the number of server threads. | Only service providers require this parameter. |
+| servicecomb.rest.client.thread-count | 1 | - | No | Specifies the number of client network threads. | Only service consumers require this parameter. |
+| servicecomb.rest.client.connection-pool-per-thread | 1 | - | No | Specifies the number of connection pools in each client thread. | Only service consumers require this parameter. |
+| servicecomb.request.timeout | 30000 | - | No | Specifies the request timeout duration. | |
+| servicecomb.references.\[服务名\].transport | rest | | No | Specifies the accessed transport type. | Only service consumers require this parameter. |
+| servicecomb.references.\[服务名\].version-rule | latest | - | No | Specifies the version of the accessed instance. | Only service consumers require this parameter. You can set it to latest, a version range such as 1.0.0+ or 1.0.0-2.0.2, or a specific version number. For details, see the API description of the service center. |
-## 示例代码
+### Sample Code
-microservice.yaml文件中的配置示例：
+An example of the configuration in the microservice.yaml file for REST over Vertx is as follows:
```yaml
servicecomb:
@@ -51,7 +51,4 @@ servicecomb:
hello:
transport: rest
version-rule: 0.0.1
-```
-
-
-
+```
\ No newline at end of file
diff --git a/java-chassis-reference/en_US/build-provider/protocol/thread-model.md b/java-chassis-reference/en_US/build-provider/protocol/thread-model.md
index c8787d2..16530e7 100644
--- a/java-chassis-reference/en_US/build-provider/protocol/thread-model.md
+++ b/java-chassis-reference/en_US/build-provider/protocol/thread-model.md
@@ -1,25 +1,28 @@
-## 概念阐述
+## Thread Model
+### Concept Description
-本小节主要介绍serviceComb微服务的完整线程模型，介绍IO线程和业务线程之间的关系
+This section describes the thread model for ServiceComb microservices and the relationship between the I/O and service threads.
-## 完整线程
+### Thread Model
-servicecComb微服务的完整线程模型如下图所示：
+The complete thread model of CSE is shown in the following figure.
-> 1. 业务线程在第一次调用时会绑定某一个网络线程,避免在不同网络线程之间切换,无谓地增加线程冲突的概率
-> 2. 业务线程绑定网络线程后,会再绑定该网络线程内部的某个连接,同样是为了避免线程冲突
+
-* 客户端和服务器都可以配置多个网络线程\(eventloop\)，默认为CPU核数的两倍，每个网络线程可以配置多个连接，默认为1，支持Rest和Highway两种网络通道，具体配置请查看如下章节：
- * [REST over Servlet](/build-provider/protocol/rest-over-servlet.md)
- * [REST over Vertx](/build-provider/protocol/rest-over-vertx.md)
- * [Highway RPC协议](/build-provider/protocol/highway-rpc.md)
-* 服务端可配置业务线程池executor，线程粒度可细化至schemaId:operation，配置如下：
+> 1. When a service thread is called for the first time, it binds to a network thread to avoid thread conflicts caused by switching among different network threads.
+> 2. After the service thread bound to a network thread, it will bind to a connection of the network to avoid thread conflicts.
-在microservice.yaml中添加executors配置，为schemaId:operation配置单独的业务线程池：
+* Multiple network threads (eventloop) can be bound to both the client and the server. The number of network threads is two times the quantity of the CPU cores by default. Multiple connections can be configured for each network thread, and the default number is 1. The Rest and Highway network channels are supported. For details about these configurations, see following sections:
+ * [REST over Servlet](/users/communicate-protocol#rest-over-servlet)
+ * [REST over Vertx](/users/communicate-protocol/#rest-over-vertx)
+ * [Highway RPC Protocol](/users/communicate-protocol/#highway-rpc协议)
+* You can configure the service thread pool executor for the client, and the thread granularity can be schemaId: operation.
+
+Add the executors in the microservice.yaml file and configure an independent service thread pool for schemaId: operation:
```yaml
-servicecomb:
- executors:
- Provider:
+servicecomb:
+ executors:
+ Provider:
[schemaId].[operation]
-```
\ No newline at end of file
+```
diff --git a/java-chassis-reference/en_US/build-provider/springmvc.md b/java-chassis-reference/en_US/build-provider/springmvc.md
index 9f24be5..91e270c 100644
--- a/java-chassis-reference/en_US/build-provider/springmvc.md
+++ b/java-chassis-reference/en_US/build-provider/springmvc.md
@@ -1,182 +1,131 @@
-# 用SpringMVC 开发微服务
-
-## 概念阐述
-
-ServiceComb支持SpringMVC注解，允许使用SpringMVC风格开发微服务。建议参照着项目 [SpringMVC](https://github.com/apache/incubator-servicecomb-java-chassis/tree/master/samples/springmvc-sample)进行详细阅读
-
-## 开发示例
-
-### 步骤 1定义服务接口。
-
-根据开发之前定义好的契约，编写Java业务接口，代码如下。定义接口不是必须的，但是 一个好习惯，可以简化客户端使用RPC方式编写代码。
-
-```java
-public interface Hello {
- String sayHi(String name);
- String sayHello(Person person);
-}
-```
-
-
-
-### 步骤 2实现服务。
-
-使用Spring MVC注解开发业务代码，Hello的服务实现如下。在服务的实现类上打上注解@RestSchema，指定schemaId，schemaId必须保证微服务范围内唯一。
-
-```java
-@RestSchema(schemaId = "springmvcHello")
-@RequestMapping(path = "/springmvchello", produces = MediaType.APPLICATION_JSON)
-public class SpringmvcHelloImpl implements Hello {
- @Override
- @RequestMapping(path = "/sayhi", method = RequestMethod.POST)
- public String sayHi(@RequestParam(name = "name") String name) {
- return "Hello " + name;
- }
-
- @Override
- @RequestMapping(path = "/sayhello", method = RequestMethod.POST)
- public String sayHello(@RequestBody Person person) {
- return "Hello person " + person.getName();
- }
-}
-```
-
-### 步骤 3发布服务
-
-在`resources/META-INF/spring`目录下创建`springmvcprovider.bean.xml`文件，命名规则为`\*.bean.xml`，配置spring进行服务扫描的base-package，文件内容如下：
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-
-<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 classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd
- http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd">
-
- <context:component-scan base-package="org.apache.servicecomb.samples.springmvc.povider"/>
-</beans>
-```
-
-### 步骤 4启动provider 服务
-
-进行主要相关配置初始化。
-
-```java
-public class SpringmvcProviderMain {
-
- public static void main(String[] args) throws Exception {
- Log4jUtils.init();
- BeanUtils.init();
- }
-}
-```
-
-## 涉及API
-
-Spring MVC开发模式当前支持org.springframework.web.bind.annotation包下的如下注解，所有注解的使用方法参考[Spring MVC官方文档](https://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html)。
-
-### 表1-1 Spring MVC注解支持汇总
-
-| 注解 | 位置 | 描述 |
-| :--- | :--- | :--- |
-| RequestMapping | schema/operation | 支持标注path/method/produces三种数据，operation默认继承schema上的produces |
-| PathVariable | parameter | 从path中获取参数 |
-| RequestParam | parameter | 从query中获取参数 |
-| RequestHeader | parameter | 从header中获取参数 |
-| RequestBody | parameter | 从body中获取参数，每个operation只能有一个body参数 |
-
-## Query参数聚合为POJO对象
-
-### 使用说明
-
-SpringBoot支持将Java业务接口中的多个query参数聚合为一个POJO类，SpringBoot原生用法示例如下：
-```java
-@RequestMapping("/hello")
-public class HelloService {
- @RequestMapping(value = "/sayHello", method = RequestMethod.GET)
- public String sayHello(Person person) {
- System.out.println("sayHello is called, person = [" + person + "]");
- return "Hello, your name is " + person.getName() + ", and age is " + person.getAge();
- }
-}
-```
-其中，作为参数的`Person`类是一个标准的JavaBean，包含属性`name`和`age`。当服务接收到的请求时，SpringBoot会将query参数`name`和`age`聚合为Person对象传入业务接口。
-
-ServiceComb的SpringMVC开发模式现在也支持类似的用法，该用法的要求如下：
-1. POJO参数上不能有Spring的参数注解，否则ServiceComb不会将其作为聚合的query参数对象处理。
-2. 仅支持聚合query参数
-3. POJO参数类中的属性名与query参数名需要保持一致
-4. POJO参数中不支持复杂的属性，如其他POJO对象、List等。用户可以在这些复杂类型打上`@JsonIgnore`注解来让ServiceComb忽略这些复杂属性。
-5. consumer端不支持query参数聚合为POJO对象，调用服务时依然要按照契约发送请求。即provider端被聚合的POJO参数在契约中会被展开成一系列的query参数，consumer端需要在provider接口方法中依次定义这些query参数（RPC开发模式），或在发送请求时填入这些query参数（RestTemplate开发模式）。
-
-### 代码示例
-
-#### Provider端开发服务
-
-- Provider端业务接口代码：
-```java
- @RestSchema(schemaId = "helloService")
- @RequestMapping("/hello")
- public class HelloService {
- @RequestMapping(value = "/sayHello", method = RequestMethod.GET)
- public String sayHello(Person person) {
- System.out.println("sayHello is called, person = [" + person + "]");
- return "Hello, your name is " + person.getName() + ", and age is " + person.getAge();
- }
- }
-```
-- POJO参数对象定义：
-```java
- public class Person {
- private String name;
- private int age;
- @JsonIgnore // 复杂属性需要标记@JsonIgnore，否则启动时会报错
- private List<Person> children;
- }
-```
-- 接口契约：
-```yaml
-# 忽略契约的其他部分
-basePath: "/hello"
-paths:
- /sayHello:
- get:
- operationId: "sayHello"
- parameters:
- # Person类的name属性和age属性作为契约中的query参数
- - name: "name"
- in: "query"
- required: false
- type: "string"
- - name: "age"
- in: "query"
- required: false
- type: "integer"
- format: "int32"
- responses:
- 200:
- description: "response of 200"
- schema:
- type: "string"
-```
-
-#### Consumer端调用服务
-
-- consumer端RPC开发模式：
- - Provider接口定义
- ```java
- public interface HelloServiceIntf {
- String sayHello(String name, int age);
- }
- ```
- - 调用代码
- ```java
- String result = helloService.sayHello("Bob", 22); // result的值为"Hello, your name is Bob, and age is 22"
- ```
-- consumer端RestTemplate开发模式：
- ```java
- String result = restTemplate.getForObject(
- "cse://provider-service/hello/sayHello?name=Bob&age=22",
- String.class); // 调用效果与RPC方式相同
- ```
+# Develop Microservice with SpringMVC
+## Concept Description
+
+ServiceComb supports Spring MVC remark and allows you to develop microservices in Spring MVC mode.
+
+## Development Example
+
+* **Step 1** Import dependencies into your maven project:
+
+ ```xml
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>java-chassis-dependencies</artifactId>
+ <version>1.0.0-m1</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+ <dependencies>
+ <!--transport can optional import through endpoint setting in microservice.yaml, we import both rest and highway as example-->
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>transport-rest-vertx</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>transport-highway</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>provider-springmvc</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-log4j12</artifactId>
+ </dependency>
+ </dependencies>
+ ```
+
+* **Step 2** Implement the services. Spring MVC is used to describe the development of service code. The implementation of the Hello service is as follow:
+
+ ```java
+ import javax.ws.rs.core.MediaType;
+ import org.springframework.web.bind.annotation.RequestBody;
+ import org.springframework.web.bind.annotation.RequestMapping;
+ import org.springframework.web.bind.annotation.RequestMethod;
+ import org.springframework.web.bind.annotation.RequestParam;
+ import org.apache.servicecomb.samples.common.schema.models.Person;
+
+ @RequestMapping(path = "/springmvchello", produces = MediaType.APPLICATION_JSON)
+ public class SpringmvcHelloImpl {
+ @RequestMapping(path = "/sayhi", method = RequestMethod.POST)
+ public String sayHi(@RequestParam(name = "name") String name) {
+ return "Hello " + name;
+ }
+
+ @RequestMapping(path = "/sayhello", method = RequestMethod.POST)
+ public String sayHello(@RequestBody Person person) {
+ return "Hello person " + person.getName();
+ }
+ }
+ ```
+
+ **Note: PLEASE MAKE SURE TO MARK @RequestMapping ON YOUR PRODUCER(SpringmvcHelloImpl), OR THE PATH AND METHOD OF PUBLISHED WILL BE INCORRECT!**
+
+ In this sample the Path of sayHi is `/springmvchello/sayhi`, and the Path of sayHello is `/springmvchello/sayhello`, if you wish them `/sayhi` and `/sayhello`, please change the setting of `@RequestMapping` on the SpringmvcHelloImpl to `@RequestMapping("/")`.
+
+* **Step 3** Release the service. Add @RestSchema as the annotation of the service implementation class and specify schemaId, which indicates that the implementation is released as a schema of the current microservice. The code is as follows:
+
+ ```java
+ import org.apache.servicecomb.provider.rest.common.RestSchema;
+ // other code omitted
+ @RestSchema(schemaId = "springmvcHello")
+ public class SpringmvcHelloImpl {
+ // other code omitted
+ }
+ ```
+
+ Create the ```springmvcHello.bean.xml``` file(the file name format is *.bean.xml) in the ``` resources/META-INF/spring``` directory and configure base-package that performs scanning. The content of the file is as follows:
+
+ ```xml
+ <?xml version="1.0" encoding="UTF-8"?>
+
+ <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 classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd
+ http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd">
+
+ <context:component-scan base-package="org.apache.servicecomb.samples.springmvc.provider"/>
+ </beans>
+ ```
+
+* **Step 4** Add service definition file:
+
+ Add [microservice.yaml](http://servicecomb.incubator.apache.org/cn/users/service-definition/) file into resources folder of your project.
+
+* **Step 5** Add Main class:
+
+ ```java
+ import org.apache.servicecomb.foundation.common.utils.BeanUtils;
+ import org.apache.servicecomb.foundation.common.utils.Log4jUtils;
+
+ public class Application {
+ public static void main(String[] args) throws Exception {
+ //initializing log, loading bean(including its parameters), and registering service, more detail can be found here : http://servicecomb.incubator.apache.org/users/application-boot-process/
+ Log4jUtils.init();
+ BeanUtils.init();
+ }
+ }
+ ```
+
+## Involved APIs
+
+Currently, the Spring MVC development mode supports the following annotations in the org.springframework.web.bind.annotation package. For details about how to use the annotations, see [Spring MVC official documentation](https://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html)。
+
+| Remarks | Location | Description |
+| :------------- | :--------------- | :--------------------------------------- |
+| RequestMapping | schema/operation | Data of path, method or produces is allowed. By default, an operation inherits produces from a schema. |
+| GetMapping | schema/operation | Data of path or produces is allowed. By default, an operation inherits produces from a schema. |
+| PutMapping | schema/operation | Data of path or produces is allowed, an operation inherits produces from a schema. |
+| PostMapping | schema/operation | Data of path or produces is allowed, an operation inherits produces from a schema. |
+| DeleteMapping | schema/operation | Data of path or produces is allowed, an operation inherits produces from a schema. |
+| PatchMapping | schema/operation | Data of path or produces is allowed, an operation inherits produces from a schema. |
+| PathVariable | parameter | Obtain parameters from path. |
+| RequestParam | parameter | Obtain parameters from query. |
+| RequestHeader | parameter | Obtain parameters from header. |
+| RequestBody | parameter | Obtain parameters from body. Each operation can have only one body parameter. |
diff --git a/java-chassis-reference/en_US/build-provider/transparent-rpc.md b/java-chassis-reference/en_US/build-provider/transparent-rpc.md
index ac378f7..9611363 100644
--- a/java-chassis-reference/en_US/build-provider/transparent-rpc.md
+++ b/java-chassis-reference/en_US/build-provider/transparent-rpc.md
@@ -1,118 +1,145 @@
-# 用透明RPC开发微服务
-
-## 概念阐述
-
-透明RPC开发模式是一种基于接口和接口实现的开发模式，服务的开发者不需要使用Spring MVC和JAX-RS注解。
-
-## 开发示例
-
-透明RPC开发模式支持Spring xml配置和注解配置两种服务发布方式，通过Spring xml配置的方式如下：
-
-### 步骤 1定义服务接口。
-
-根据开发之前定义好的契约，编写Java业务接口，代码如下：
-
-```java
-public interface Hello {
- String sayHi(String name);
- String sayHello(Person person);
-}
-
-public interface Compute {
- int add(int a, int b);
- int multi(int a, int b);
- int sub(int a, int b);
- int divide(int a, int b);
-}
-
-```
-
-
-
-### 步骤 2实现服务
-
-Hello的服务实现如下：
-
-> **说明**：
-> 每一个服务接口都需要定义一个schema声明。
-
-* 在接口Hello 和 Compute 的实现类上使用@RpcSchema注解定义schema，代码如下：
-
-```java
-@RpcSchema(schemaId = "hello")
-public class HelloImpl implements Hello {
- @Override
- public String sayHi(String name) {
+# Develop Microservice with Transparent RPC
+## Concept Description
+
+The transparent remote procedure call(RPC) development mode is a development mode based on API and API implementation. The service developer does not need to use the description of Spring MVC and JAX-RS.
+
+## Development Example
+
+* **Step 1** Import dependencies into your maven project:
+
+ ```xml
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>java-chassis-dependencies</artifactId>
+ <version>1.0.0-m1</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+ <dependencies>
+ <!--transport can optional import through endpoint setting in microservice.yaml, we import both rest and highway as example-->
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>transport-rest-vertx</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>transport-highway</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>provider-pojo</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-log4j12</artifactId>
+ </dependency>
+ </dependencies>
+ ```
+
+* **Step 2** Define a service API. Compile the Java API definition based on the API definition defined before development. The code is as follows:
+
+ ```java
+ public interface Hello {
+ String sayHi(String name);
+ String sayHello(Person person);
+ }
+ ```
+
+* **Step 3** implement the service. The implementation of the Hello service is as follows:
+
+ ```java
+ import org.apache.servicecomb.samples.common.schema.Hello;
+ import org.apache.servicecomb.samples.common.schema.models.Person;
+
+ public class HelloImpl implements Hello {
+ @Override
+ public String sayHi(String name) {
+ return "Hello " + name;
+ }
+
+ @Override
+ public String sayHello(Person person) {
+ return "Hello person " + person.getName();
+ }
+ }
+ ```
+
+* **Step 4** Release the service.
+ The transparent RPC development mode supports two service release mode: Spring XML configuration and Annotation configuration:
+1. Spring XML configuration Mode:
+ Create the pojoHello.bean.xml file in the resources/META-INF/spring directory and declare the schema in the file. The content of the file is as follows:
+
+ ```xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <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:cse="http://www.huawei.com/schema/paas/cse/rpc"
+ xmlns:context="http://www.springframework.org/schema/context"
+ xsi:schemaLocation="http://www.springframework.org/schema/beans classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd http://www.huawei.com/schema/paas/cse/rpc classpath:META-INF/spring/spring-paas-cse-rpc.xsd">
+
+ <cse:rpc-schema schema-id="pojoHello" implementation="org.apache.servicecomb.samples.pojo.provider.PojoHelloImpl"/>
+ </beans>
+ ```
+
+2. Annotation configuration Mode:
+ @RpcSchema is used to define schema during the API Hello implementation. The code is as follows:
+
+ ```java
+ import org.apache.servicecomb.provider.pojo.RpcSchema;
+ @RpcSchema(schemaId = "pojoHello")
+ public class HelloImpl implements Hello {
+ @Override
+ public String sayHi(String name) {
return "Hello " + name;
- }
-
- @Override
- public String sayHello(Person person) {
+ }
+
+ @Override
+ public String sayHello(Person person) {
return "Hello person " + person.getName();
- }
-}
-
-@RpcSchema(schemaId = "codeFirstCompute")
-public class CodeFirstComputeImpl implements Compute {
- @Override
- public int add(int a, int b) {
- return a + b;
- }
-
- @Override
- public int multi(int a, int b) {
- return a * b;
- }
-
- @Override
- public int sub(int a, int b) {
- return a - b;
- }
-
- @Override
- public int divide(int a, int b) {
- if (b != 0) {
- return a / b;
- }
- return 0;
- }
-}
-```
-
-### 步骤 3发布服务
-
-* 通过配置文件方式
-
-在resources/META-INF/spring目录下的pojoHello.bean.xml文件中，配置Spring进行服务扫描的base-package，文件内容如下：
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<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:cse=" http://www.huawei.com/schema/paas/cse/rpc "
- xmlns:context=" http://www.springframework.org/schema/context "
- xsi:schemaLocation=" http://www.springframework.org/schema/beans classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd http://www.huawei.com/schema/paas/cse/rpc classpath:META-INF/spring/spring-paas-cse-rpc.xsd">
+ }
+ }
+ ```
- <context:component-scan base-package="org.apache.servicecomb.samples.pojo.provider"/>
-</beans>
-```
+ In the pojoHello.bean.xml file of resources/META-INF/spring directory, configure base-package that performs scanning. The content of the file is as follows:
+ ```xml
+ <?xml version="1.0" encoding="UTF-8"?>
+ <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:cse="http://www.huawei.com/schema/paas/cse/rpc"
+ xmlns:context="http://www.springframework.org/schema/context"
+ xsi:schemaLocation="http://www.springframework.org/schema/beans classpath:org/springframework/beans/factory/xml/spring-beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd http://www.huawei.com/schema/paas/cse/rpc classpath:META-INF/spring/spring-paas-cse-rpc.xsd">
+ <context:component-scan base-package="org.apache.servicecomb.samples.pojo.provider"/>
+ </beans>
+ ```
-### 步骤 4 启动服务
+**Note: THE PATH FOR RPC IS `ClassName/MethodName`, AND THE METHOD IS `POST`.**
-```java
-public class PojoProviderMain {
+In this sample the Path of sayHi is `/HelloImpl/sayHi`, and the Path of sayHello is `/HelloImpl/sayHello`.
- public static void main(String[] args) throws Exception {
- Log4jUtils.init();
- BeanUtils.init();
- }
-}
-```
+> **NOTE**：
+Different from the Spring MVC and JAX-RS development modes, the transparent RPC development mode used `@RpcSchema` instead of `@RestSchema`.
-> **说明**：
-> 与Spring MVC开发模式和JAX-RS开发模式不同的是，透明RPC开发模式使用的注解是`@RpcSchema`而非`@RestSchema`。
+* **Step 5** Add service definition file:
+ Add [microservice.yaml](http://servicecomb.incubator.apache.org/cn/users/service-definition/) file into resources folder of your project.
+
+* **Step 6** Add Main class:
+ ```java
+ import org.apache.servicecomb.foundation.common.utils.BeanUtils;
+ import org.apache.servicecomb.foundation.common.utils.Log4jUtils;
+ public class Application {
+ public static void main(String[] args) throws Exception {
+ //initializing log, loading bean(including its parameters), and registering service, more detail can be found here : http://servicecomb.incubator.apache.org/users/application-boot-process/
+ Log4jUtils.init();
+ BeanUtils.init();
+ }
+ }
+ ```