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 2017/12/23 08:08:22 UTC
[incubator-servicecomb-website] branch master updated: SCB-110
translate developing consumer service document for website (#6)
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-website.git
The following commit(s) were added to refs/heads/master by this push:
new a33e3f9 SCB-110 translate developing consumer service document for website (#6)
a33e3f9 is described below
commit a33e3f95bd4b01f98a9d9f76e61690d21744f53c
Author: chasel168 <64...@qq.com>
AuthorDate: Sat Dec 23 16:08:20 2017 +0800
SCB-110 translate developing consumer service document for website (#6)
---
_users/develop-with-rest-template.md | 22 ++++++-------
_users/develop-with-rpc.md | 14 ++++-----
_users/invoke-control.md | 61 ++++++++++++++++++------------------
_users/use-service-contract.md | 48 ++++++++++++++--------------
4 files changed, 72 insertions(+), 73 deletions(-)
diff --git a/_users/develop-with-rest-template.md b/_users/develop-with-rest-template.md
index 4691bf1..59757d4 100644
--- a/_users/develop-with-rest-template.md
+++ b/_users/develop-with-rest-template.md
@@ -1,26 +1,26 @@
---
-title: "使用Rest Template方式开发"
+title: "Develop with Rest Template"
lang: en
ref: develop-with-rest-template
permalink: /users/develop-with-rest-template/
-excerpt: "使用Rest Template方式开发"
+excerpt: "Develop with Rest Template"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## 概念阐述
+## Concept Description
- Rest Template是Spring提供的RESTful访问接口，ServiceComb提供该接口的实现类用于服务的调用。
+ Rest Template is a RESTful API provide by the Spring framework. ServiceComb provides the API for service calling
-## 场景描述
+## Scenario
- 用户使用ServiceComb提供的Rest Template实例，可以使用自定义的URL进行服务调用，而不用关心服务的具体地址。
+ You can call microservices using your customized URL and the RestTemplate instance provided by ServiceComb regardless of the specific address of the service.
-## 示例代码
+## Sample Code
- Rest Template实例通过调用`RestTemplateBuilder.create()`方法获取，再使用该实例通过自定义的URL进行服务调用，代码如下：
+ Obtain RestTemplate by calling `RestTemplateBuilder.create()`. Then, use the instance and the customized URL to call microservices. The code is as follows:
```java
import org.springframework.stereotype.Component;
@@ -54,6 +54,6 @@ public class SpringmvcConsumerMain {
}
```
-> 说明：
-- URL格式为：`cse://microserviceName/path?querystring`。以[用SpringMVC开发微服务](/users/develop-with-springmvc/)中定义的服务提供者为例，其微服务名称是`springmvc`，basePath是`/springmvchello`，那么URL中的microserviceName是`springmvc`，请求sayhi时的path是`springmvchello/sayhi`，所以示例代码中请求sayhi的URL是`cse://springmvc/springmvchello/sayhi?name=Java Chassis`。
-- 使用这种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/_users/develop-with-rpc.md b/_users/develop-with-rpc.md
index 846c966..da439fd 100644
--- a/_users/develop-with-rpc.md
+++ b/_users/develop-with-rpc.md
@@ -1,22 +1,22 @@
---
-title: "使用RPC方式开发"
+title: "Develop with RPC"
lang: en
ref: develop-with-rpc
permalink: /users/develop-with-rpc/
-excerpt: "使用RPC方式开发"
+excerpt: "Develop with RPC"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## 概念阐述
+## Concept Description
-RPC开发方式允许用户通过在服务接口上标注注解来生成服务提供者代理，从而进行服务的调用。
+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.
-## 示例代码
+## Sample Code
-只需要声明一个服务接口类型的成员，并且使用`@RpcReference`标注该成员，声明依赖的微服务及schemaId，即可进行服务调用，示例代码如下：
+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.
```java
import org.springframework.stereotype.Component;
@@ -47,4 +47,4 @@ public class CodeFirstConsumerMain {
}
```
-在以上代码中，服务消费者已经取得了服务提供者的服务接口`Hello`，并在代码中声明一个`Hello`类型的成员。通过在`hello`上使用`@RPCReference`注解指明微服务名称和schemaId，ServiceComb框架可以在程序启动时从服务中心获取到对应的服务提供者实例信息，并且生成一个代理注入到hello中，用户可以像调用本地类一样调用远程服务。
+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.
diff --git a/_users/invoke-control.md b/_users/invoke-control.md
index 7b96e07..e7716a1 100644
--- a/_users/invoke-control.md
+++ b/_users/invoke-control.md
@@ -1,53 +1,53 @@
---
-title: "调用控制"
+title: "Invoke Control"
lang: en
ref: invoke-control
permalink: /users/invoke-control/
-excerpt: "调用控制"
+excerpt: "Invoke Control"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## 实例级故障隔离
+## Instance-Level Fault Isolation
-### 场景描述
+### Scenario
-实例级故障隔离功能允许在微服务的部分实例调用失败时，停止向故障实例发送请求，从而达到隔离故障实例的功能。
+In the scenario where some instances fail to be called, the instance-level fault isolation function stops the ServiceComb framework from sending requests to the faulty instance.
-### 配置说明
+### Configuration
-实例级故障隔离功能集成在负载均衡功能中，负载均衡策略的配置见[负载均衡策略](/users/service-configurations/#负载均衡策略)。负载均衡策略中，与实例级故障隔离相关的配置项见下表。
+This instance-level fault isolation function is integrated into the load balancing function. For configuration of the load balancing policy, see [Service Configurations](/users/service-configurations/#负载均衡策略). For parameters associated with instance-level fault isolation in the load balancing policy, see table below:
-| 配置项 | 默认值 | 取值范围 | 是否必选 | 含义 | 注意 |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| cse.loadbalance.isolation.enabled | false | Boolean | 否 | 是否开启故障实例隔离功能 | - |
-| cse.loadbalance.isolation.enableRequestThreshold | 20 | Integer | 否 | 当实例的调用总次数达到该值时开始进入隔离逻辑门槛 | - |
-| cse.loadbalance.isolation.errorThresholdPercentage | 20 | Integer，区间为\(0,100\] | 否 | 实例故障隔离错误百分比 | - |
-| cse.loadbalance.isolation.singleTestTime | 10000 | Integer | 否 | 故障实例单点测试时间 | |
+| Configuration Item | Default Value | Value Range | Mandatory | Description | Remark |
+| :--------------------------------------- | :------------ | :----------------- | :-------- | :--------------------------------------- | :----- |
+| cse.loadbalance.isolation.enabled | false | Boolean | No | Specifies whether to enable faulty instance isolation. | - |
+| cse.loadbalance.isolation.enableRequestThreshold | 20 | Integer | No | Specifies the threshold number of instance calls. If this value is reached, isolation is enabled. | - |
+| cse.loadbalance.isolation.errorThresholdPercentage | 20 | Integer, \(0,100\] | No | Specifies the error percentage. Instance fault isolation is enabled when the set value is reached. | - |
+| cse.loadbalance.isolation.singleTestTime | 10000 | Integer | No | Specifies the duration of a faulty instance test on a single node. | |
-## 熔断策略
-### 场景描述
+## Circuit Break Policy
+### Scenario
-熔断策略是对ServiceComb熔断功能的设置，用户通过配置熔断策略可以指定在何种条件下ServiceComb框架将终止发送请求。
+Circuit brake policy can configure ServiceComb fallback capability, you can configure conditions under which service will stop send request after circuit break policy configured.
-### 配置说明
+### Configuration
-熔断作为异常反应机制是降级策略的一部分，相关概念还有隔离和容错。三者的关系以及配置方式参见[降级策略](/users/service-configurations/#降级策略)。
+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](/users/service-configurations/#降级策略)。
-## 限流策略
-### 场景描述
+## 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
-参考服务提供者处[限流策略注意事项](/users/service-configurations/#限流策略)。
+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
cse:
@@ -57,9 +57,10 @@ cse:
default: qps-flowcontrol-consumer
```
-QPS流控配置项说明
+Configuration items of QPS:
+
+| Configuration Item | Default Value | Value Range | Mandatory | Description | Remark |
+| :--------------------------------------- | :-------------------- | :---------------------- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| cse.flowcontrol.Consumer.qps.enabled | true | Boolean | No | Specifies whether consumers flowcontrol enables. | - |
+| cse.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. |
-| 配置项 | 默认值 | 取值范围 | 是否必选 | 含义 | 注意 |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| cse.flowcontrol.Consumer.qps.enabled | true | Boolean | 否 | 是否启用Consumer流控 | - |
-| cse.flowcontrol.Consumer.qps.limit.[ServiceName].[Schema].[operation] | 2147483647 (max int) | (0,2147483647]，整形 | 否 | 每秒钟允许的请求数 | 支持microservice、schema、operation三个级别的配置 |
diff --git a/_users/use-service-contract.md b/_users/use-service-contract.md
index 9acfcdd..5993c6a 100644
--- a/_users/use-service-contract.md
+++ b/_users/use-service-contract.md
@@ -1,26 +1,24 @@
---
-title: "使用服务契约"
+title: "Service Using API Definitions"
lang: en
ref: use-service-contract
permalink: /users/use-service-contract/
-excerpt: "使用服务契约"
+excerpt: "Service Using API Definitions"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## 场景描述
+## 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
cse:
@@ -30,31 +28,31 @@ cse:
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`.
-### 手工配置服务契约
+### Manually Configuring Service API Definition
-服务消费者的开发者在线下拿到服务提供者的契约，配置到消费者工程的特定目录下。服务契约在项目中的存放目录与[服务契约](/users/service-contract/)的配置说明部分相同。
+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/).
-microservice目录下的每一个目录代表一个微服务，微服务目录下的每一个yaml文件代表一个schema契约，文件名就是schemaId。applications目录下存放需要指明appId的服务契约，用于跨app调用等场景。目录结构如下所示：
+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
```
-### 从服务中心自动下载契约
+### Automatically Downloading API Definition from Service Center
-服务消费者也可以不用显式地将契约存放在项目目录中，当程序启动时，ServiceComb框架会自动根据microservice.yaml文件中配置的服务提供者的微服务名称和版本号，从服务中心自动下载契约信息。
+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.
--
To stop receiving notification emails like this one, please contact
['"commits@servicecomb.apache.org" <co...@servicecomb.apache.org>'].