You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by GitBox <gi...@apache.org> on 2018/08/27 09:01:38 UTC
[GitHub] liubao68 closed pull request #53: Build consumer dir translation
liubao68 closed pull request #53: Build consumer dir translation
URL: https://github.com/apache/incubator-servicecomb-docs/pull/53
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/java-chassis-reference/en_US/build-consumer/circuit-breaker.md b/java-chassis-reference/en_US/build-consumer/circuit-breaker.md
index b9c727d..543e140 100644
--- a/java-chassis-reference/en_US/build-consumer/circuit-breaker.md
+++ b/java-chassis-reference/en_US/build-consumer/circuit-breaker.md
@@ -1,9 +1,8 @@
-# 熔断策略
+## Circuit Break Policy
+### Scenario
-## 场景描述
+Circuit brake policy can configure ServiceComb fallback capability, you can configure conditions under which service will stop send request after circuit break policy configured.
-熔断策略是对ServiceComb熔断功能的设置，用户通过配置熔断策略可以指定在何种条件下ServiceComb框架将终止发送请求。
+### Configuration
-## 配置说明
-
-熔断作为异常反应机制是降级策略的一部分，相关概念还有隔离和容错。三者的关系以及配置方式参见[降级策略](/build-provider/configuration/downgrade-strategy.md)。
\ No newline at end of file
+Circuit break is part of fallback policy when a service request is abnormal, relevant concept such as isolation and fault tolerance please refer to [fallback policy](/build-provider/configuration/downgrade-strategy.md)。
diff --git a/java-chassis-reference/en_US/build-consumer/code-first.md b/java-chassis-reference/en_US/build-consumer/code-first.md
old mode 100644
new mode 100755
index d87d7ae..d590f5b
--- a/java-chassis-reference/en_US/build-consumer/code-first.md
+++ b/java-chassis-reference/en_US/build-consumer/code-first.md
@@ -1,16 +1,16 @@
-## 场景描述
+## Scene Description
-服务消费者可以不用显式地将契约存放在项目目录中，当程序启动时，ServiceComb框架会自动根据microservice.yaml文件中配置的服务提供者的微服务名称和版本号，从服务中心拉取契约信息。
+Service consumers can store contracts in the project directory without having to explicitly do so, and when the program starts, the ServiceComb framework automatically pulls the contract information from the service center based on the microservice name and version number of the service provider configured in the microservice.yaml file.
-## 涉及API
+## Involving API
-使用隐式契约可用于RestTemplate、透明RPC两种服务消费者开发模式，使用RestTemplate的开发方式参见4.3 使用RestTemplate开发服务消费者。
+The use of implicit contracts can be used for both RestTemplate and transparent RPC service development models. For the development method using RestTemplate, see 4.3 Developing Service Consumers with RestTemplate.
-## 示例代码
+## Sample Code
-本小节以透明RPC开发模式为例展示如何使用隐式契约开发服务消费者。
+This section shows how to develop service consumers using implicit contracts, using transparent RPC development patterns as an example.
-服务消费者的示例代码如下：
+The sample code for the service consumer is as follows:
```java
import org.springframework.stereotype.Component;
@@ -24,7 +24,7 @@ import org.apache.servicecomb.samples.common.schema.models.Person;
public class CodeFirstConsumerMain {
@RpcReference(microserviceName = "codefirst", schemaId = "codeFirstHello")
private static Hello hello;
-
+
public static void main(String[] args) throws Exception {
init();
System.out.println(hello.sayHi("Java Chassis"));
@@ -40,4 +40,5 @@ public class CodeFirstConsumerMain {
}
```
-在以上代码中，服务消费者已经取得了服务提供者的服务接口Hello，并在代码中声明一个Hello类型的成员。通过在hello上使用RPCReference注解指明微服务名称和schemaId，ServiceComb框架可以在程序启动时从服务中心获取到对应的服务提供者实例信息，并且生成一个代理注入到hello中，用户可以像调用本地类一样调用远程服务。
+In the code above, the service consumer has taken the service interface Hello of the service provider and declared a Hello type member in the code. By using the RPCReference annotation on hello to specify the microservice name and schemaId, the ServiceComb framework can be in
+When the program starts, the corresponding service provider instance information is obtained from the service center and a proxy is generated to be injected into the hello. The user can invoke the remote service as if it were a local class.
diff --git a/java-chassis-reference/en_US/build-consumer/develop-consumer-using-rpc.md b/java-chassis-reference/en_US/build-consumer/develop-consumer-using-rpc.md
index b308390..941eacf 100644
--- a/java-chassis-reference/en_US/build-consumer/develop-consumer-using-rpc.md
+++ b/java-chassis-reference/en_US/build-consumer/develop-consumer-using-rpc.md
@@ -1,47 +1,79 @@
-# 使用透明RPC方式开发服务消费者
+# Develop with RPC
+## Concept Description
-## 概念阐述
+The RPC development mode allows you to add annotations on the microservice APIs to generate the service provider agent. In this case, you can call microservices.
-透明RPC开发模式允许用户通过简单的java interface像本地调用一样进行服务调用。
-透明RPC仅仅是一种开发模式：
-* 与使用highway还是RESTful传输没有关联
-* 与producer使用透明RPC/Jax-RS还是SpringMVC模式开发没有关联
-* 也与producer代码是否实现这个interface没有关联。
-
-透明RPC开发模式与spring cloud的feign类似，不过更简单，因为不必在这个interface中增加任何RESTful annotation。
+## Sample Code
+
+To call a microservice, you only need to declare a member of a service API type and add the @RpcReference annotation for the member, the microservice that depends on the declaration, and the schemaID. The sample code is as follows.
-## 在spring bean中通过@RpcReference声明
```java
+import org.springframework.stereotype.Component;
+
+import org.apache.servicecomb.foundation.common.utils.BeanUtils;
+import org.apache.servicecomb.foundation.common.utils.Log4jUtils;
+import org.apache.servicecomb.provider.pojo.RpcReference;
+import org.apache.servicecomb.samples.common.schema.Hello;
+import org.apache.servicecomb.samples.common.schema.models.Person;
+
@Component
-public class SomeBean {
- ......
-
- @RpcReference(microserviceName = "helloService", schemaId = "helloSchema")
- private Hello hello;
-
- ......
+public class CodeFirstConsumerMain {
+ @RpcReference(microserviceName = "codefirst", schemaId = "codeFirstHello")
+ private static Hello hello;
+
+ public static void main(String[] args) throws Exception {
+ init();
+ System.out.println(hello.sayHi("Java Chassis"));
+ Person person = new Person();
+ person.setName("ServiceComb/Java Chassis");
+ System.out.println(hello.sayHello(person));
+ }
+
+ public static void init() throws Exception {
+ Log4jUtils.init();
+ BeanUtils.init();
+ }
}
```
-## 脱离spring bean，直接通过api声明
+
+In the preceding code, the microservice consumers have obtained the microservice API Hello of the microservice provider and declared a member of the Hello type. The annotation `@RPCReference` on `Hello` specifies the microservice name and schemaId, The ServiceComb framework can obtain information about isntances from a certain provider during program startup and generate an agent to insert to Hello. This allows you to call a remote service in the same way as you call a local class.
+
+### Additional explanation for consumer invocation
+In above example, in order to direct use `hello` in main function, we mark it as `static`. As a local field of `CodeFirstConsumerMain`, we recommend get it use these two way :
+
+#### First way: define cse:rpc-reference
+In your bean.xml, add `cse:rpc-reference` configuration:
+
+```xml
+<cse:rpc-reference id="hello" microservice-name="codefirst"
+ schema-id="codeFirstHello" interface="org.apache.servicecomb.samples.common.schema.Hello"></cse:rpc-reference>
+```
+
+Then use `BeanUtils.getBean` to get `Hello` provider:
+
```java
-Hello hello = Invoker.createProxy("helloService", "helloSchema", Hello.class);
+Hello hello = BeanUtils.getBean("hello");
```
-## reactive
-只需要使用jdk的CompletableFuture对返回值进行包装即可
+#### Second way: get Bean, then use field
+First use `BeanUtils.getBean` to get Bean of `CodeFirstConsumerMain`:
+
```java
-interface Hello {
- CompletableFuture<String> sayHi(String name);
-}
+//Default instance name of Spring Bean is same as class name with first char low-cased
+CodeFirstConsumerMain consumer = BeanUtils.getBean("codeFirstConsumerMain");
```
-同一个interface中，可以同时声明同一个方法的reactive和同步原型
-因为要求方法名与契约中的operationId一一对应，而仅有返回值类型不同，在java中是非法的，所以需要修改方法名，并通过swagger annotation来声明真正的operationId
+Then get `hello` via Getter：
+
```java
-interface Hello {
- String sayHi(String name);
-
- @ApiOperation(nickname = "sayHi", value = "reactive method for sayHi")
- CompletableFuture<String> asyncSayHi(String name);
+public Hello getHello() {
+ return hello;
}
```
+
+```java
+Hello hello = consumer.getHello()
+```
+
+> NOTE:
+> `BeanUtils.getBean` has inner lock so performacen is low , we recommend use once and cache return as local field for future use(such as in constructor).
\ No newline at end of file
diff --git a/java-chassis-reference/en_US/build-consumer/fault-injection.md b/java-chassis-reference/en_US/build-consumer/fault-injection.md
old mode 100644
new mode 100755
index 7daf407..75fcc86
--- a/java-chassis-reference/en_US/build-consumer/fault-injection.md
+++ b/java-chassis-reference/en_US/build-consumer/fault-injection.md
@@ -1,14 +1,14 @@
-## 场景描述
+## Fault Injection
+### Scenario
+The user via fault injection on the consumer side to set the delay and error of the request to the specified microservice and its trigger probability.
-用户在consumer端使用故障注入，可以设置发往指定微服务的请求的时延和错误及其触发概率。
+## Precautions
-## 注意事项
+The delay time for delay injection requests is unified to the millisecond level.
-延迟注入请求的延迟时间统一为毫秒级别
+## Configuration instructions
-## 配置说明
-
-故障注入配置在microservice.yaml文件中，相关配置项见下表。要开启服务消费者端的故障注入，还需要在处理链中配置消费端故障注入handler，配置示例如下：
+The fault injection configuration is in the microservice.yaml file. The related configuration items are shown in the following table. To enable fault injection in the service consumer, you need to configure the consumer fault injection handler in the processing chain. The configuration example is as follows:
```yaml
servicecomb:
@@ -18,28 +18,28 @@ servicecomb:
default: loadbalance,fault-injection-consumer
```
-故障注入配置项说明
+Fault injection configuration item description
-\[scope\]代表故障注入的生效范围，可配置值包括全局配置\_global，或指定微服务的服务名\[ServiceName\]。
+\[scope\] represents the effective scope of the fault injection. The configurable value includes the global configuration \_global or the service name of the microservice \[ServiceName\].
-\[protocol\]代表使用的通信协议，可配置值包括rest或highway。
+\[protocol\] represents the communication protocol used, and configurable values include rest or highway.
-| 配置项 | 默认值 | 取值范围 | 是否必选 | 含义 | 注意 |
+| Configuration Item | Default Value | Range of Value | Required | Meaning |
| :--- | :--- | :--- | :--- | :--- | :--- |
-| servicecomb.governance.Consumer.\[scope\].policy.fault.protocols.\[protocol\].delay.fixedDelay | 无 | \(0,9223372036854775807\]，长整形 | 否 | Consumer端发送延迟注入请求的延迟时间 | 目前时间单位是毫秒 |
-| servicecomb.governance.Consumer.\[scope\].policy.fault.protocols.\[protocol\].delay.percent | 100 | \(0,100\]，整形 | 否 | Consumer端发送延迟注入请求的触发概率 | |
-| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].policy.fault.protocols.\[protocol\].delay.fixedDelay | 无 | \(0,9223372036854775807\]，长整形 | 否 | Consumer端发送到对应schema的延迟注入请求的延迟时间 | 支持schema级别的配置 |
-| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].policy.fault.protocols.\[protocol\].delay.percent | 100 | \(0,100\]，整形 | 否 | Consumer端发送到对应schema的延迟注入请求的触发概率 | 支持schema级别的配置 |
-| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].operations.\[operation\].policy.fault.protocols.\[protocol\].delay.fixedDelay | 无 | \(0,9223372036854775807\]，长整形 | 否 | Consumer端发送到对应operation的延迟注入请求的延迟时间 | 支持operation级别的配置 |
-| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].operations.\[operation\].policy.fault.protocols.\[protocol\].delay.percent | 100 | \(0,100\]，整形 | 否 | Consumer端发送到对应operation的延迟注入请求的触发概率 | 支持operation级别的配置 |
-| servicecomb.governance.Consumer.\[scope\].policy.fault.protocols.\[protocol\].abort.httpStatus | 无 | \(100,999\]，整形 | 否 | Consumer端发送错误注入请求的http错误码 | |
-| servicecomb.governance.Consumer.\[scope\].policy.fault.protocols.\[protocol\].abort.percent | 100 | \(0,100\]，整形 | 否 | Consumer端发送错误注入请求的触发概率 | |
-| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].policy.fault.protocols.\[protocol\].abort.httpStatus | 无 | \(100,999\]，整形 | 否 | Consumer端发送到对应schema的错误注入请求的http错误码 | 支持schema级别的配置 |
-| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].policy.fault.protocols.\[protocol\].abort.percent | 100 | \(0,100\]，整形 | 否 | Consumer端发送到对应schema的错误注入请求的触发概率 | 支持schema级别的配置 |
-| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].operations.\[operation\].policy.fault.protocols.\[protocol\].abort.httpStatus | 无 | \(100,999\]，整形 | 否 | Consumer端发送到对应operation的错误注入请求的http错误码 | 支持operation级别的配置 |
-| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].operations.\[operation\].policy.fault.protocols.\[protocol\].abort.percent | 100 | \(0,100\]，整形 | 否 | Consumer端发送到对应operation的错误注入请求的触发概率 | 支持operation级别的配置 |
-
-## 示例代码
+| servicecomb.governance.Consumer.\[scope\].policy.fault.protocols.\[protocol\].delay.fixedDelay | None | \(0,9223372036854775807\], Long Shaping | No | Consumer Send Delay Injection Request Delay time | current time unit is milliseconds |
+| servicecomb.governance.Consumer.\[scope\].policy.fault.protocols.\[protocol\].delay.percent | 100 | \(0,100\], Shaping | No | Trigger Probability of Sending Delay Injection Requests by Consumers | |
+| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].policy.fault.protocols.\[protocol\].delay.fixedDelay | None | \(0,9223372036854775807\], Long Shaping| No | Delay time for delay injection request sent by the consumer to the corresponding schema | Support for schema level configuration |
+| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].policy.fault.protocols.\[protocol\].delay.percent | 100 | \(0,100\],Plastic| No| Consumer Trigger probability of a delayed injection request sent by the end to the corresponding schema | Support for schema level configuration |
+| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].operations.\[operation\].policy.fault.protocols.\[protocol\].delay.fixedDelay | None | \(0 ,9223372036854775807\],long shaping| no|delay time of delay injection request sent by the consumer to the corresponding operation | support operation level configuration |
+| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].operations.\[operation\].policy.fault.protocols.\[protocol\].delay.percent | 100 | \(0,100 \], shaping|no| trigger probability of delay injection request sent by the consumer to the corresponding operation | support operation level configuration |
+| servicecomb.governance.Consumer.\[scope\].policy.fault.protocols.\[protocol\].abort.httpStatus | None | \(100,999\], Shaping | No | The http error sent by the Consumer to send an error injection request Code| |
+| servicecomb.governance.Consumer.\[scope\].policy.fault.protocols.\[protocol\].abort.percent | 100 | \(0,100\], Shaping | No | Trigger Probability of Sending Error Injection Requests by Consumers | |
+| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].policy.fault.protocols.\[protocol\].abort.httpStatus | None | \(100,999\],Plastic| No| Consumer Http error code sent by the end to the corresponding schema error injection request | Support schema level configuration |
+| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].policy.fault.protocols.\[protocol\].abort.percent | 100 | \(0,100\],Plastic| No| Consumer Trigger probability of error injection request sent by the end to the corresponding schema | Support schema level configuration |
+| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].operations.\[operation\].policy.fault.protocols.\[protocol\].abort.httpStatus | None | \(100,999 \], shaping | No | http error code sent by the consumer to the error injection request of the corresponding operation | Support operation level configuration |
+| servicecomb.governance.Consumer.\[ServiceName\].schemas.\[schema\].operations.\[operation\].policy.fault.protocols.\[protocol\].abort.percent | 100 | \(0,100 \], shaping | No | Trigger probability of error injection request sent by the consumer to the corresponding operation | Support operation level configuration |
+
+## Sample Code
```
servicecomb:
@@ -72,6 +72,3 @@ servicecomb:
httpStatus: 421
percent: 100
```
-
-
-
diff --git a/java-chassis-reference/en_US/build-consumer/flow-control.md b/java-chassis-reference/en_US/build-consumer/flow-control.md
index bba55b4..7e01a04 100644
--- a/java-chassis-reference/en_US/build-consumer/flow-control.md
+++ b/java-chassis-reference/en_US/build-consumer/flow-control.md
@@ -1,14 +1,15 @@
-## 场景描述
+## Flow Control Policy
+### Scenario
-用户在consumer端使用限流策略，可以限制发往指定微服务的请求的频率。
+You can limit the frequency of request send to specific microservice when flow control was enables in consumer service.
-## 注意事项
+### Precaution
-参考3.7.2-限流策略。
+See detail info at [Service Configurations](/users/service-configurations/#限流策略)。
-## 配置说明
+### Configuration
-限流策略配置在microservice.yaml文件中，相关配置项见下表。要开启服务消费者端的限流策略，还需要在处理链中配置消费端限流handler，配置示例如下：
+Flow control policy configuration is in microservice.yaml file. You need to configure consumer handler in chain of service. See example blow:
```yaml
servicecomb:
@@ -18,12 +19,9 @@ servicecomb:
default: qps-flowcontrol-consumer
```
-QPS流控配置项说明
-
-| 配置项 | 默认值 | 取值范围 | 是否必选 | 含义 | 注意 |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| servicecomb.flowcontrol.Consumer.qps.enabled | true | Boolean | 否 | 是否启用Consumer流控 | - |
-| servicecomb.flowcontrol.Consumer.qps.limit.\[ServiceName\].\[Schema\].\[operation\] | 2147483647 \(max int\) | \(0,2147483647\]，整形 | 否 | 每秒钟允许的请求数 | 支持microservice、schema、operation三个级别的配置 |
-
-
+Configuration items of QPS:
+| Configuration Item | Default Value | Value Range | Mandatory | Description | Remark |
+| :--------------------------------------- | :-------------------- | :---------------------- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| servicecomb.flowcontrol.Consumer.qps.enabled | true | Boolean | No | Specifies whether consumers flowcontrol enables. | - |
+| servicecomb.flowcontrol.Consumer.qps.limit.[ServiceName].[Schema].[operation] | 2147483647 (max int) | (0,2147483647], Integer | No | Specifies number of requests per second. | Support three level configurations: microservice、schema、operation. |
\ No newline at end of file
diff --git a/java-chassis-reference/en_US/build-consumer/invoke-control.md b/java-chassis-reference/en_US/build-consumer/invoke-control.md
index e69de29..362191a 100644
--- a/java-chassis-reference/en_US/build-consumer/invoke-control.md
+++ b/java-chassis-reference/en_US/build-consumer/invoke-control.md
@@ -0,0 +1,9 @@
+## Circuit Break Policy
+Circuit brake policy can configure ServiceComb fallback capability, you can configure conditions under which service will stop send request after circuit break policy configured.
+
+## Flow Control Policy
+You can limit the frequency of request send to specific microservice when flow control was enables in consumer service.
+
+## Fault Injection
+
+The user via fault injection on the consumer side to set the delay and error of the request to the specified microservice and its trigger probability.
diff --git a/java-chassis-reference/en_US/build-consumer/using-resttemplate.md b/java-chassis-reference/en_US/build-consumer/using-resttemplate.md
index 8f4528b..879ec94 100644
--- a/java-chassis-reference/en_US/build-consumer/using-resttemplate.md
+++ b/java-chassis-reference/en_US/build-consumer/using-resttemplate.md
@@ -1,20 +1,25 @@
-# 使用RestTemplate开发服务消费者
+# Develop with Rest Template
+## Concept Description
-## 概念阐述
+ Rest Template is a RESTful API provide by the Spring framework. ServiceComb provides the API for service calling
-RestTemplate是Spring提供的RESTful访问接口，ServiceComb提供该接口的实现类用于服务的调用。
+## Scenario
-## 场景描述
+ You can call microservices using your customized URL and the RestTemplate instance provided by ServiceComb regardless of the specific address of the service.
-用户使用ServiceComb提供的RestTemplate实例，可以使用自定义的URL进行服务调用，而不用关心服务的具体地址。
+## Sample Code
-## 示例代码
+ Obtain RestTemplate by calling `RestTemplateBuilder.create()`. Then, use the instance and the customized URL to call microservices. The code is as follows:
-RestTemplate实例通过调用`RestTemplateBuilder.create()`方法获取，再使用该实例通过自定义的URL进行服务调用，代码如下：
+```java
+import org.springframework.stereotype.Component;
+import org.springframework.web.client.RestTemplate;
-* Spring MVC 客户端示例代码：
+import org.apache.servicecomb.foundation.common.utils.BeanUtils;
+import org.apache.servicecomb.foundation.common.utils.Log4jUtils;
+import org.apache.servicecomb.provider.springmvc.reference.RestTemplateBuilder;
+import org.apache.servicecomb.samples.common.schema.models.Person;
-```java
@Component
public class SpringmvcConsumerMain {
private static RestTemplate restTemplate = RestTemplateBuilder.create();
@@ -38,36 +43,10 @@ public class SpringmvcConsumerMain {
}
```
-* JAX RS 客户端示例代码：
-
-```java
-
-@Component
-public class JaxrsConsumerMain {
-
- public static void main(String[] args) throws Exception {
- init();
- //其他都类似spring MVC示例的客户端代码，注意如果服务端只接收 GET 请求，要使用方法 getForObject()
- RestTemplate restTemplate = RestTemplateBuilder.create();
- String result = restTemplate.getForObject("cse://jaxrs/jaxrshello/saybye", String.class);
- }
-
- public static void init() throws Exception {
- Log4jUtils.init();
- BeanUtils.init();
- }
-}
-```
-
-> 说明：
->
-> * URL格式为：`cse://microserviceName/path?querystring`。以[用SpringMVC开发微服务](/用SpringMVC开发微服务)中定义的服务提供者为例，其微服务名称是springmvc，basePath是`/springmvchello`，那么URL中的microserviceName=`springmvc`，请求sayhi时的path=`springmvchello/sayhi`，所以示例代码中请求sayhi的URL是`cse://springmvc/springmvchello/sayhi?name=Java Chassis`。具体代码示例如下 ：
-
-
```java
@RestSchema(schemaId = "springmvcHello")
@RequestMapping(path = "/springmvchello", produces = MediaType.APPLICATION_JSON)
-//这里 path = “/springmvchello” 中的 springmvchello 就是 上述的basePath
+//Here, springmvchello in path = "/springmvchello" is the above basePath.
public class SpringmvcHelloImpl implements Hello {
@Override
@RequestMapping(path = "/sayhi", method = RequestMethod.POST)
@@ -82,7 +61,7 @@ public class SpringmvcHelloImpl implements Hello {
}
}
```
-> 下述代码是示例项目 [ SpringMVC ](https://github.com/apache/incubator-servicecomb-java-chassis/tree/master/samples/springmvc-sample)的 springmvc-provider 模块 中 resources 目录下 microservice.yaml
+> The following code is microservice.yaml in the resources directory of the springmvc-provider module of the sample project [Spring MVC] (https://github.com/apache/incubator-service comb-java-chassis/tree/master/samples/springmvc-sample)
```yaml
APPLICATION_ID: springmvc-sample
@@ -107,7 +86,6 @@ cse:
address: http://127.0.0.1:30100 #service center address
```
-
-
-
-> * 使用上述这种URL格式，ServiceComb框架会在内部进行服务发现、熔断容错等处理并最终将请求发送到服务提供者。
+> NOTE:
+- The URL must be in format of ServiceComb: `cse://microserviceName/path?querystring`. Use the provider defined in [Develop Microservice with SpringMVC](/users/develop-with-springmvc/) as an example. The microservice name is `springmvc`, and its base path is `/springmvchello`, so you should set microserviceName in the URL to `springmvchello/sayhi` when requesting sayhi. Therefore, the URL for requesting sayhi is `cse://springmvc/springmvchello/sayhi?name=Java Chassis`.
+- During use of this URL format, the ServiceComb framework will perform internal microservice descovery, fallbreak, and fault tolerance and send the requests to the microservice providers.
diff --git a/java-chassis-reference/en_US/build-consumer/with-contract.md b/java-chassis-reference/en_US/build-consumer/with-contract.md
index 3cf5eaa..8e72c10 100644
--- a/java-chassis-reference/en_US/build-consumer/with-contract.md
+++ b/java-chassis-reference/en_US/build-consumer/with-contract.md
@@ -1,16 +1,13 @@
-# 使用服务契约
+# Service Using API Definitions
+## Scenario
-## 场景描述
+When a consumer calls a service from a provider, you need to register a service API definition. You can obtain service API definition from your provider for your consumer in two ways. One is to obtain the service API definition from the provider off-line and manually configure the API definition to the project. Another is to automatically download the service API definition from the service center.
-当服务消费者调用服务提供者的服务时，需要注册服务契约。消费者有两种方式获取提供者的服务契约，一种是从服务的提供方离线获取契约文件，手工配置到项目中；另一种是从服务中心自动下载契约。
+## Configuration
-## 配置说明
+> You can obtain service API definition in either way, regardless of the development mode of service consumers.
-> 说明：服务契约的获取方式与服务消费者的开发方式是无关的，用户可以任意组合使用。
-
-### 配置依赖服务
-
-服务消费者需要在microservice.yaml文件中配置依赖的provider，示例配置如下：
+In the microservice.yaml file, configure a provider for the consumer. The following is an example of the configuration:
```yaml
servicecomb:
@@ -20,33 +17,31 @@ servicecomb:
version-rule: 0.0.1
```
-> version-rule是版本匹配规则，有四种格式：
+> There are four kind of rule for version-rule:
>
-> * 精确版本匹配：例如`version-rule: 0.0.1`，表示只匹配版本号为0.0.1的服务提供者
-> * 后续版本匹配：例如`version-rule: 1.0.0+`，表示匹配版本号大于或等于1.0.0的服务提供者
-> * 最新版本：`version-rule: latest`，表示匹配最新版本的服务提供者
-> * 版本范围：例如`1.0.0-2.0.2`，表示匹配版本号在1.0.0至2.0.2之间的服务提供者，包含1.0.0和2.0.2
+> * Accurate Matching Rule: such as `version-rule: 0.0.1`, it indicates that only those providers whose version is 0.0.1 can be matched.
+> * Later Matching Rule: such as `version-rule: 1.0.0+`, it indicates that those providers whose version is later that 1.0.0 can be matched.
+> * Latest Matching Rule: such as `version-rule: latest`, it indicates that only those providers whose version number is latest can be matched.
+> * Range Matching Rule: such as`1.0.0-2.0.2`, it indicates that those provider whose version number is between 1.0.0 and 2.0.2 can be matched, including 1.0.0 and 2.0.2
>
-> 此配置项默认为`latest`
-
-### 手工配置服务契约
+> The default version rule of version-rule is `latest`.
-服务消费者的开发者在线下拿到服务提供者的契约，配置到消费者工程的特定目录下。服务契约在项目中的存放目录与[定义服务契约](/build-provider/define-contract.md)的配置说明部分相同。
+### Manually Configuring Service API Definition
-microservice目录下的每一个目录代表一个微服务，微服务目录下的每一个yaml文件代表一个schema契约，文件名就是schemaId。applications目录下存放需要指明appId的服务契约，用于跨app调用等场景。目录结构如下所示：
+After you obtained the API definition of your consumer from the provider, configure it in a specified directory of the consumer project. The directory is the one mentioned in the configuration description [Service Contract](/users/service-contract/).
-```
+Each directory under the microservices directory indecates a microservice, and each .yaml file under the jaxrs directory represents a schema API definition. The file name is the schema ID. The service API definitions whose application IDs need to be specified are stored under the applications directory for cross-application calls. The directory structure is as follows:
+```txt
resources
- microservices
- - serviceName # 微服务名
- - schemaId.yaml # schema接口的契约
+ - serviceName # Microservice name
+ - schemaId.yaml # Schema API definition
- applications
- - appId # 应用ID
- - serviceName # 微服务名
- - schemaId.yaml # schema接口的契约
+ - appId # Application ID
+ - serviceName # Microservice name
+ - schemaId.yaml # Schema API definition
```
-### 从服务中心自动下载契约
-
-服务消费者也可以不用显式地将契约存放在项目目录中，当程序启动时，ServiceComb框架会自动根据microservice.yaml文件中配置的服务提供者的微服务名称和版本号，从服务中心自动下载契约信息。
+### Automatically Downloading API Definition from Service Center
+If a consumer does not explicitly store the API definition in the project directory, when the application is started, the ServiceComb framework automatically downloads the information about the API definition from the service center based on the provider's microservices name and version configured in microservice.yaml.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services