You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@servicecomb.apache.org by GitBox <gi...@apache.org> on 2017/12/25 01:15:51 UTC
[GitHub] WillemJiang closed pull request #5: translate develop service provider document for servicecomb document website
WillemJiang closed pull request #5: translate develop service provider document for servicecomb document website
URL: https://github.com/apache/incubator-servicecomb-website/pull/5
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/_users/application-boot-process.md b/_users/application-boot-process.md
index c379dcf..3917ee3 100644
--- a/_users/application-boot-process.md
+++ b/_users/application-boot-process.md
@@ -1,27 +1,27 @@
---
-title: "??????"
+title: "Application Boot-up Process"
lang: en
ref: application-boot-process
permalink: /users/application-boot-process/
-excerpt: "??????"
+excerpt: "Application Boot-up Process"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
-???????????????Log4j?bean???????????????????
+The starup 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` obtains the configuration of log4j from the `classpath\*:config/base/log4j.properties` and `classpath\*:config/log4j.properties` files. combines them, and transfer them to PropertyConfigurator of log4j to initialize log4j. If the configuration file having the highest priority is stored on the disk and its directory has write permission, save the combined configuration to this directory to view which parameters take effect during maintenance.
-* bean??
+* Load the bean.
- `BeanUtils`????`classpath\*:META-INF/spring/\*.bean.xml`???????????????Spring???`ClassPathXmlApplicationContext`???????????????????foundation-config???bean????????
+ 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 foundation-config module.
-* ????
+* Register the microservice.
- ?Spring context??????`io.servicecomb.core.CseApplicationListener`???handler?????provider?schema???????????????????
+ After Spring context has been loaded, `io.servicecomb.core.CseApplicationListener` will configure the handler, load the information about the provider schema, and the register microservice to service center.
-> **???**
-> ServiceComb?????????????????????????????????????????????????????????????????????????????
+> **NOTE:**
+> The three level of configuration items for ServiceComb are the configuration center, environment variables, and local files, listed in a 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/_users/communicate-protocol.md b/_users/communicate-protocol.md
index 136f882..30d3934 100644
--- a/_users/communicate-protocol.md
+++ b/_users/communicate-protocol.md
@@ -1,49 +1,49 @@
---
-title: "????"
+title: "Communication Protocol"
lang: en
ref: communicate-protocol
permalink: /users/communicate-protocol/
-excerpt: "????"
+excerpt: "Communication Protocol"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## ????
-### ????
+## Communication Protocol
+### Concept Description
-ServiceComb????????????REST?Highway????TLS????????REST??????????RESTful??????????????http client????RESTful???????
+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.
-### ????
+### Precautions
-???????????
+Serialization of parameters and the returned values:
-??REST???body?????application/json???????????????form?????????????????application/json???body??????multipart/form-data????form?????
+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.
-??REST???????application/json?text/plain????????????produces?????????????????????Accept????????????????application/json??????
+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.
-## ????
-### ????
+## 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
-ServiceComb????????????????
+The complete thread model of CSE is shown in the following figure.
-
+
-> 1. ?????????????????????,?????????????,????????????
-> 2. ???????????,????????????????,???????????
+> 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.
-* ??????????????????\(eventloop\)????CPU????????????????????????1???Rest?Highway???????????????????
+* 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??](/users/communicate-protocol/#highway-rpc??)
-* ???????????executor?????????schemaId:operation??????
+ * [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.
-?microservice.yaml???executors????schemaId:operation???????????
+Add the executors in the microservice.yaml file and configure an independent service thread pool for schemaId: operation:
```yaml
cse:
@@ -53,13 +53,13 @@ cse:
```
## REST over Servlet
-### ????
+### Configuration
-??REST over Servlet????web???????????????servlet??????????????web??????????????????????????web.xml????????????web.xml?????listener??microservice.yaml?????urlPattern??????????
+??REST over Servlet is deployed and runs using a web container. You need to create a servlet project to pack the microservice, load it to the web container, and then start it. To pack a microservice, you can either fully configure it in the web.xml, or configure its listener and urlPattern in the web.xml and microservice.yaml files, respectively.
-* ?web.xml?????????
+* Configure the microservice in the web.xml file.
- web.xml????????src/main/webapp/WEB\_INF??????????
+ The web.xml file is under the src/main/webapp/WEB\_INF directory of the project, and its content is as follows:
```xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0">
@@ -83,7 +83,7 @@ cse:
</web-app>
```
-* ?web.xml??????listener??microservice.yaml?????urlPattern
+* Configure the listener in the web.xml file and urlPattern in the microservice.yaml file.
```xml
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0">
@@ -97,13 +97,13 @@ cse:
</web-app>
```
- ?microservice.yaml??????????????urlPattern?
+ In the microservice.yaml file, add a row to specify the urlPattern?
```yaml
servicecomb.rest.servlet.urlPattern: /rest/*
```
-???????????????????maven pom??????????
+The two method are equivalent, and they both require that the following dependencies be added in the pox.xml file:
```xml
<dependency>
@@ -112,21 +112,21 @@ cse:
</dependency>
```
-REST over Servlet?microservice.yaml???????????
+Configuration items that need to be set in the microservice.yaml file are described in Table 1:
-?1 REST over Servlet?????
+Table 1 Configuration items of REST over Servlet
-| ??? | ??? | ???? | ???? | ?? | ?? |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| cse.rest.address | 0.0.0.0:8080 | - | ? | ?????? | - |
-| cse.rest.timeout | 3000 | - | ? | ???? | ????? |
-| cse.request.timeout | 30000 | - | ? | ?????? | ?REST over Vertx??? |
-| cse.references.\[???\].transport | rest | | ? | ???transport?? | ?REST over Vertx??? |
-| cse.references.\[???\].version-rule | latest | - | ? | ???????? | ?REST over Vertx??? |
+| Configuration Item | Default Value | Value Range | Mandatory | Description | Remark |
+| :---------------------------------- | :------------ | :---------- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| cse.rest.address | 0.0.0.0:8080 | - | No | Specifies the server listening IP address. | - |
+| cse.rest.timeout | 3000 | - | No | Specifies the timeout duration | The unit is ms. |
+| cse.request.timeout | 30000 | - | No | Specifies the request timeout duration. | The configuration of this parameter for REST over Servlet is the same as that for REST over Vertx. |
+| cse.references.\[???\].transport | rest | | No | Specifies the accessed transport type. | The configuration of this parameter for REST over Servlet is the same as that for REST over Vertx. |
+| cse.references.\[???\].version-rule | latest | - | No | Specifies the version of the accessed instance. | The configuration of this parameter for REST over Servlet is the same as that for REST over Vertx. |
-### ????
+### Sample Code
-microservice.yaml???????????
+The following is an example of the configuration in the microservice.yaml file for REST over Servlet:
```yaml
cse:
@@ -136,9 +136,9 @@ cse:
```
## 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 io.servicecomb.foundation.common.utils.BeanUtils;
@@ -146,13 +146,13 @@ import io.servicecomb.foundation.common.utils.Log4jUtils;
public class MainServer {
public static void main(String[] args) throws Exception {
- ?Log4jUtils.init();//?????
- ?BeanUtils.init(); // Spring bean???
+ ?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>
@@ -161,23 +161,23 @@ public class MainServer {
</dependency>
```
-REST over Vertx???microservice.yaml??????????
+Configuration items that need to be set in the microservice.yaml file are described as follows:
-?2 REST over Vertx?????
+Table 2 Configuration items of REST over Vertx
-| ??? | ??? | ???? | ???? | ?? | ?? |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| cse.rest.address | 0.0.0.0:8080 | - | ? | ?????? | ?????????? |
-| cse.rest.server.thread-count | 1 | - | ? | ?????? | ?????????? |
-| cse.rest.client.thread-count | 1 | - | ? | ???????? | ?????????? |
-| cse.rest.client.connection-pool-per-thread | 1 | - | ? | ????????????????? | ?????????? |
-| cse.request.timeout | 30000 | - | ? | ?????? | |
-| cse.references.\[???\].transport | rest | | ? | ???transport?? | ?????????? |
-| cse.references.\[???\].version-rule | latest | - | ? | ???????? | ????????????latest?1.0.0+?1.0.0-2.0.2???????????????????? |
+| Configuration Item | Default Value | Value Range | Mandatory | Description | Remark |
+| :--------------------------------------- | :------------ | :---------- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| cse.rest.address | 0.0.0.0:8080 | - | No | Specifies the server listening IP address. | Only service providers require this parameter. |
+| cse.rest.server.thread-count | 1 | - | No | Specifies the number of server threads. | Only service providers require this parameter. |
+| cse.rest.client.thread-count | 1 | - | No | Specifies the number of client network threads. | Only service consumers require this parameter. |
+| cse.rest.client.connection-pool-per-thread | 1 | - | No | Specifies the number of connection pools in each client thread. | Only service consumers require this parameter. |
+| cse.request.timeout | 30000 | - | No | Specifies the request timeout duration. | |
+| cse.references.\[???\].transport | rest | | No | Specifies the accessed transport type. | Only service consumers require this parameter. |
+| cse.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
cse:
@@ -190,14 +190,14 @@ cse:
version-rule: 0.0.1
```
-## Highway RPC??
-### ????
+## 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>
@@ -206,23 +206,23 @@ Highway?ServiceComb???????????????????
</dependency>
```
-Highway???microservice.yaml?????????????
+Configuration items that need to be set in the microservice.yaml file are described as follows:
-?3 Highway?????
+Table 3 Configuration items of Highway
-| ??? | ??? | ???? | ???? | ?? | ?? |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| cse.highway.address | 0.0.0.0:7070 | - | ? | ?????? | - |
-| cse.highway.server.thread-count | 1 | - | ? | ????????? | - |
-| cse.highway.client.thread-count | 1 | - | ? | ????????? | - |
-| cse.highway.client.connection-pool-per-thread | 1 | - | ? | ??????????????? | - |
-| cse.request.timeout | 30000 | - | ? | ?????? | ?REST over Vertx??? |
-| cse.references.\[???\].transport | rest | | ? | ???transport?? | ?REST over Vertx??? |
-| cse.references.\[???\].version-rule | latest | - | ? | ???????? | ?REST over Vertx??? |
+| Configuration Item | Default Value | Value Range | Mandatory | Description | Remark |
+| :--------------------------------------- | :------------ | :---------- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| cse.highway.address | 0.0.0.0:7070 | - | No | Specifies the server listening IP address. | - |
+| cse.highway.server.thread-count | 1 | - | No | Specifies the number of server network threads. | - |
+| cse.highway.client.thread-count | 1 | - | No | Specifies the number of client network threads. | - |
+| cse.highway.client.connection-pool-per-thread | 1 | - | No | Specifies the number of connection pools in each client thread. | - |
+| cse.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. |
+| cse.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. |
+| cse.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
cse:
diff --git a/_users/define-service-contract.md b/_users/define-service-contract.md
index 1620492..afd5f79 100644
--- a/_users/define-service-contract.md
+++ b/_users/define-service-contract.md
@@ -1,43 +1,43 @@
---
-title: "????"
+title: "Service Contract"
lang: en
ref: service-contract
permalink: /users/service-contract/
-excerpt: "????"
+excerpt: "Service Contract"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## ????
+## Concept Description
-????????OpenAPI???????????????????????????
+The API of provider and consumer microservice is defined based on OpenAPI regulations.
-## ????
+## Scenario
-?????????????????????????????????????????????????????????????????????
+The API definition decouples providers and consumers, which allows the two parties to use different programming languages, Providers provide services and consumers call them based on the API definition.
-## ????
+## Explicit API Definition
-### ????
+### Configuration
-ServiceComb??yaml???????????????[Swagger Editor](http://editor.swagger.io/#/)????????????????????API???????????????[OpenAPI????](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)?
+ServiceComb defines API in a .yaml faile. You are advised to use [Swagger Editor](http://editor.swagger.io/#/) to write an API definition. 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)?
-???????"resources/microservices"??"resources/applications"?????????????
+The API definition file is located in "resources/microservices" or "resources/applications" directory. 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 #Service name
+ - schemaId.yaml #Schema API definition
```
-### ????
+### Sample Code
```yaml
swagger: '2.0'
@@ -60,11 +60,11 @@ paths:
type: string
responses:
200:
- description: ????
+ description: returned for a correct result
schema:
type: string
default:
- description: ????
+ description: returned for a default result
schema:
type: string
/sayhello:
@@ -78,11 +78,11 @@ paths:
$ref: "#/definitions/Person"
responses:
200:
- description: ????
+ description: returned for a correct result
schema:
type: string
default:
- description: ????
+ description: returned for a default result
schema:
type: string
definitions:
@@ -96,21 +96,21 @@ definitions:
name: "Person"
```
-> **??**?
-- ??swagger???basePath?????????web server?webroot?
-- info.x-java-interface???????????????????????
+> **NOTE**?
+- According to Swagger specifications, the path specified by basePath should contain the webroot of the web server.
+- info.x-java-interface requires a specific API path. Set it as needed.
-## ????
-### ????
+## Implicit API Definition
+### Concept Description
-????????ServiceComb?????????????????
+??The inplicit API definition is automatically generated by ServiceComb based on the service implementation class.
-### ????
+### 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.
-### ??API
+### Involved API
-?????????Spring MVC?JAX-RS???RPC?????????????[?SpringMVC?????](/users/develop-with-springmvc/)?[?JAX-RS?????](/users/develop-with-jax-rs/)?[???RPC?????](/users/develop-with-transparent-rpc/)?
+??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/).
-??????RPC????????????????????????????????????????????POST?????method?????????class???body?????????????????provider????SpringMVC?JAX-RS????????????RESTful???
+??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.
\ No newline at end of file
diff --git a/_users/develop-with-jax-rs.md b/_users/develop-with-jax-rs.md
index ff6b374..0e16f84 100644
--- a/_users/develop-with-jax-rs.md
+++ b/_users/develop-with-jax-rs.md
@@ -1,9 +1,9 @@
---
-title: "?JAX-RS?????"
+title: "Development Style-JAX-RS"
lang: en
ref: develop-with-jax-rs
permalink: /users/develop-with-jax-rs/
-excerpt: "?JAX-RS?????"
+excerpt: "Development Style-JAX-RS"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
@@ -11,15 +11,13 @@ redirect_from:
{% include toc %}
-## ????
+## Concept Description
-ServiceComb???????JAX-RS?????JAX-RS???????
+ServiceComb supports developers in developing services in JAX-RS mode by using JAX-RS.
-## ????
+## Development Example
-* **?? 1** ???????
-
- ???????????????Java??????????
+* **Steps 1** 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 {
@@ -28,12 +26,10 @@ ServiceComb???????JAX-RS?????JAX-RS???????
}
```
- > **??**?
- ????????????x-java-interface?????????
-
-* **?? 2** ?????
+ > **NOTE**?
+ > The location of the API must be the same as the path specified by x-java-interface in the API definition.
- ??JAX-RS?????????Hello????????
+* **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;
@@ -62,9 +58,7 @@ ServiceComb???????JAX-RS?????JAX-RS???????
}
```
-* **?? 3** ?????
-
- ????????????`@RestSchema`???schemaId????????????????schema????????
+* **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 io.servicecomb.provider.rest.common.RestSchema;
@@ -75,7 +69,7 @@ ServiceComb???????JAX-RS?????JAX-RS???????
}
```
- ???resources/META-INF/spring?????jaxrsHello.bean.xml?????spring???????base-package????????
+ 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"?>
@@ -84,28 +78,28 @@ ServiceComb???????JAX-RS?????JAX-RS???????
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="io.servicecomb.samples.jaxrs.provider"/>
</beans>
```
-## ??API
-
-JAX-RS????????????????????????[JAX-RS????](https://jax-rs-spec.java.net/nonav/2.0-rev-a/apidocs/index.html)?
-
-| ?? | ?? | ?? |
-| :--- | :--- | :--- |
-| 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????? |
-
-> **??**?
-- ?????????????HttpServletRequest?????????body????????????????body?????
-- ????????????????value???????????????????????`@QueryParam\("name"\) String name`????`@QueryParam String name`?
+## 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/_users/develop-with-springmvc.md b/_users/develop-with-springmvc.md
index 7559aa7..25cb280 100644
--- a/_users/develop-with-springmvc.md
+++ b/_users/develop-with-springmvc.md
@@ -1,24 +1,22 @@
---
-title: "?SpringMVC?????"
+title: "Development Style-Spring MVC"
lang: en
ref: develop-with-springmvc
permalink: /users/develop-with-springmvc/
-excerpt: "?SpringMVC?????"
+excerpt: "Development Style-Spring MVC"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## ????
+## Concept Description
-ServiceComb??SpringMVC???????SpringMVC????????
+ServiceComb supports Spring MVC remark and allows you to develop microservices in Spring MVC mode.
-## ????
+## Development Example
-* **?? 1** ???????
-
- ???????????????Java??????????
+* **Step 1** Define a service API., Compile the Java API definition based on the API definition defined before development. The code is as follow:
```java
public interface Hello {
@@ -27,11 +25,9 @@ ServiceComb??SpringMVC???????SpringMVC????????
}
```
- ????????????x-java-interface?????????
-
-* **?? 2** ?????
+ The location of the API must be the same as the path specified by x-java-interface in the API definition.
- ??Spring MVC?????????Hello????????
+* **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;
@@ -41,7 +37,7 @@ ServiceComb??SpringMVC???????SpringMVC????????
import org.springframework.web.bind.annotation.RequestParam;
import io.servicecomb.samples.common.schema.Hello;
import io.servicecomb.samples.common.schema.models.Person;
-
+
@RequestMapping(path = "/springmvchello", produces = MediaType.APPLICATION_JSON)
public class SpringmvcHelloImpl implements Hello {
@Override
@@ -58,9 +54,7 @@ ServiceComb??SpringMVC???????SpringMVC????????
}
```
-* **?? 3** ????
-
- ????????????@RestSchema???schemaId????????????????schema????????
+* **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 io.servicecomb.provider.rest.common.RestSchema;
@@ -71,34 +65,34 @@ ServiceComb??SpringMVC???????SpringMVC????????
}
```
- ???`resources/META-INF/spring`?????`springmvcHello.bean.xml`????????`\*.bean.xml`???spring???????base-package????????
+ 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="io.servicecomb.samples.springmvc.provider"/>
</beans>
```
-## ??API
-
-Spring MVC????????org.springframework.web.bind.annotation???????????????????[Spring MVC????](https://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html)?
-
-| ?? | ?? | ?? |
-| :--- | :--- | :--- |
-| RequestMapping | schema/operation | ????path/method/produces?????operation????schema??produces |
-| GetMapping | schema/operation | ????path/produces?????operation????schema??produces |
-| PutMapping | schema/operation | ????path/produces?????operation????schema??produces |
-| PostMapping | schema/operation | ????path/produces?????operation????schema??produces |
-| DeleteMapping | schema/operation | ????path/produces?????operation????schema??produces |
-| PatchMapping | schema/operation | ????path/produces?????operation????schema??produces |
-| PathVariable | parameter | ?path????? |
-| RequestParam | parameter | ?query????? |
-| RequestHeader | parameter | ?header????? |
-| RequestBody | parameter | ?body????????operation?????body?? |
+## 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/_users/develop-with-transparent-rpc.md b/_users/develop-with-transparent-rpc.md
index 9363409..4525dc8 100644
--- a/_users/develop-with-transparent-rpc.md
+++ b/_users/develop-with-transparent-rpc.md
@@ -1,26 +1,24 @@
---
-title: "???RPC?????"
+title: "Development Style-Transparent RPC"
lang: en
ref: develop-with-transparent-rpc
permalink: /users/develop-with-transparent-rpc/
-excerpt: "???RPC?????"
+excerpt: "Development Style-RPC"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## ????
+## Concept Description
-??RPC?????????????????????????????????Spring MVC?JAX-RS???
+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
-??RPC??????Spring xml??????????????????Spring xml????????
+The transparent RPC development mode supports two service release mode: Spring XML configuration and annotation configuration. The Spring XML configuration mode is as follows:
-* **?? 1** ???????
-
- ???????????????Java??????????
+* **Step 1** 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 {
@@ -29,12 +27,10 @@ redirect_from:
}
```
- > **??**?
- > ????????????x-java-interface?????????
-
-* **?? 2** ????
+ > **NOTE**?
+ > The location of the API must be the same as the path specified by x-java-interface in the API definition.
- Hello????????
+* **Step 2** implement the service. The implementation of the Hello service is as follows:
```java
import io.servicecomb.samples.common.schema.Hello;
@@ -53,9 +49,7 @@ redirect_from:
}
```
-* **?? 3** ????
-
- ?resources/META-INF/spring?????pojoHello.bean.xml?????????schema????????
+* **Step 3** Release the service. 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"?>
@@ -64,19 +58,21 @@ redirect_from:
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="io.servicecomb.samples.pojo.provider.PojoHelloImpl"/>
</beans>
```
- > **??**?
- > ??????????????schema???
+ > **NOTE**?
+ > A schema statement must be defined for each service API.
-## ???????????
+## The Develop Method by Configure Remarks
-1. ??????????Spring xml??????
-2. ????????Spring xml??????
-3. ????????Hello???????@RpcSchema????schema??????
+1. Define a service API, which is the same as the Spring XML mode.
+
+2. Implement the service in the same way as using Spring XML.
+
+3. Release the service. @RpcSchema is used to define schema during the API Hello implementation. The code is as followss:
```java
import io.servicecomb.provider.pojo.RpcSchema;
@@ -87,7 +83,7 @@ redirect_from:
}
```
- ?resources/META-INF/spring????pojoHello.bean.xml??????Spring???????base-package????????
+ 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"?>
@@ -96,10 +92,10 @@ redirect_from:
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="io.servicecomb.samples.pojo.provider"/>
</beans>
```
-> **??**?
-> ?Spring MVC?????JAX-RS???????????RPC??????????`@RpcSchema`??`@RestSchema`?
+> **NOTE**:
+> Different from the Spring MVC and JAX-RS development modes, the transparent RPC development mode used `@RpcSchema` instead of `@RestSchema`.
diff --git a/_users/service-configurations.md b/_users/service-configurations.md
index aafdbde..2ac3c56 100644
--- a/_users/service-configurations.md
+++ b/_users/service-configurations.md
@@ -1,46 +1,46 @@
---
-title: "????"
+title: "Service Configurations"
lang: en
ref: service-configurations
permalink: /users/service-configurations/
-excerpt: "????"
+excerpt: "Service Configurations"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## ??????
-### ????
+## Load Balancing Policy
+### Scenario
-??ServiceComb?????Ribbon??????????????????????????????????????????????????????????
+??ServiceComb provides a Ribbon-based load balancing solution. You can configure a load balancing policy in the configuration file. Currently, a load balancing routing policy can be random, sequential, or based on response time weight.
-### ????
+### Configuration
-?????????microservice.yaml??????????`cse.loadbalance.[MicroServiceName].[property name]`??????MicroServiceName???????????MicroServiceName??????????????
+??Load balancing policies are configured by setting the parameter `cse.loadbalance.[MicroServiceName].[property name]` in the microservice.yaml fiel. If MicroServiceName is not set, the configuration is set for all microservices. Otherwise, the configuration is set for a specific microservice.
-??**?1 ?????**
+??**Table 1 Configuration items of load balancing policy**
-| ??? | ??? | ???? | ???? | ?? | ?? |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| cse.loadbalance.NFLoadBalancerRuleClassName | com.netflix.loadbalancer.RoundRobinRule | com.netflix.loadbalancer.RoundRobinRule????com.netflix.loadbalancer.RandomRule????com.netflix.loadbalancer.WeightedResponseTimeRule???????????io.servicecomb.loadbalance.SessionStickinessRule?????? | ? | ???????? | - |
-| cse.loadbalance.SessionStickinessRule.sessionTimeoutInSeconds | 30 | Integer | ? | ?????????????????????? | ??????????e.g. cse.loadbalance.SessionStickinessRule.sessionTimeoutInSeconds??????cse.loadbalance.DemoService.SessionStickinessRule.sessionTimeoutInSeconds |
-| cse.loadbalance.SessionStickinessRule.successiveFailedTimes | 5 | Integer | ? | ????????????????? | ????????? |
-| cse.loadbalance.retryEnabled | FALSE | Boolean | ? | ???????????????????? | - |
-| cse.loadbalance.retryOnNext | 0 | Integer | ? | ?????????? | - |
-| cse.loadbalance.retryOnSame | 0 | Integer | ? | ??????????? | - |
-| 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 | ? | ?????????? | ???ms |
-| cse.loadbalance.transactionControl.policy | io.servicecomb.loadbalance.filter.SimpleTransactionControlFilter | - | ? | ???????? | ??????????????????????????????? |
-| cse.loadbalance.transactionControl.options | - | key/value pairs | ? | ??SimpleTransactionControlFilter??????????????????? | - |
+| Configuration Items | Default Value | Value Range | Mandatory | Description | Remarks |
+| :--------------------------------------- | :--------------------------------------- | :--------------------------------------- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| cse.loadbalance.NFLoadBalancerRuleClassName | com.netflix.loadbalancer.RoundRobinRule | com.netflix.loadbalancer.RoundRobinRule?polling?com.netflix.loadbalancer.RandomRule?random?com.netflix.loadbalancer.WeightedResponseTimeRule?server response time weight?io.servicecomb.loadbalance.SessionStickinessRule?session stickiness? | No | Specifiles the load balancing policy | - |
+| cse.loadbalance.SessionStickinessRule.sessionTimeoutInSeconds | 30 | Integer | No | Specifies the idle time of a client. If the idle time exceeds the set value, ServiceComb will select another server. | Currently, this parameter cannot be set for a certain microservice. For example, cse.loadbalance.SessionStickinessRule.sessionTimeoutInSeconds cannot be set to cse.loadbalance.DemoService.SessionStickinessRule.sessionTimeoutInSeconds |
+| cse.loadbalance.SessionStickinessRule.successiveFailedTimes | 5 | Integer | No | Specifies the number of failed requests from the client. If the number exceeds the set value, ServiceComb will switch to another server | Currently, this parameter cannot be set for a certain microservice. |
+| cse.loadbalance.retryEnabled | FALSE | Boolean | No | Specifies whether to call a service again when a exception is captured by the load balance. | - |
+| cse.loadbalance.retryOnNext | 0 | Integer | No | Specifies the number of attempts to connect to another server. | - |
+| cse.loadbalance.retryOnSame | 0 | Integer | No | Specifies the number of attempts to connect to the same server. | - |
+| 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. | This unit is ms. |
+| cse.loadbalance.transactionControl.policy | io.servicecomb.loadbalance.filter.SimpleTransactionControlFilter | - | No | Specifies the offload policies for dynamic routing. | The framework provides simple offload mechanisms. You can also customize offload policies. |
+| cse.loadbalance.transactionControl.options | - | key/value pairs | No | Specifies the parameter configured for the SimpleTransactionControlFilter offload policy. You can add any filtration tag for this item. | - |
-### ????
+### Sample Code
-???????????src/main/resources/microservice.yaml????
+??in the src/main/resources/microservice.yaml file, configure a load balancing policy.
-????????
+??Configure a processing link?
```yaml
cse:
@@ -52,7 +52,7 @@ cse:
# other configurations omitted
```
-?????????
+??Add a routing policy:
```yaml
cse?
@@ -62,31 +62,30 @@ cse?
# other configurations omitted
```
-## ???????
+## Customizing Routing Policies
-???????ServiceComb???????????????????????????????????????
+??Based on the routing policy framework provided by ServiceComb, you can program to customize routing policies as required. Perform the following steps:
-* ????`com.netflix.loadbalancer.IRule`?????????
-???????public Server choose\(Object key\)??????LoadBalancerStats???????????????????????????stats????????????choose????????????????????????????????`io.servicecomb.loadbalance.SessionStickinessRule`?
+* Encode using the API method defined in the `com.netflix.loadbalancer.IRule` API. Encode in the public Server choose(Object key) method. LoadBalancerStats is a structure that encapsulates the running state of the load balancer. Determine on which instance the current routing request will be processed based on the running indexes of each instance by using the Server choose(Object key) method. Use method `io.servicecomb.loadbalance.SessionStickinessRule`for instance processing.
-* ?????????????class?classpath??
+* Compile the developed policy and ensure that the generated class is under classpath.
-* ??SDK???????????`AbcRule`??????? `cse.loadbalance.NFLoadBalancerRuleClassName=io.servicecomb.ribbon.rule.AbcRule`
-
-## ????
-### ????
+* Use the software development kit(SDK) to configure the routing policy. Use AbcRule as a routing policy example. The configuration is as follows: `cse.loadbalance.NFLoadBalancerRuleClassName=io.servicecomb.ribbon.rule.AbcRule`
-???provider????????????????????????????????????????????
+## Rate Limiting Policy
+### Scenario
-### ????
+Users at the provider end can use the rate limiting policy to limit the maximum number of requests sent from a specified microservice per second.
-1. ?????????????????????????
-2. provider????????????????????????????????DDoS????????????????
-3. ??????????????????
+### Precautions
-### ????
+1. There may be a small different between the rate limit and actual traffic.
+2. The rate limit function at the provider end is for service rather than security purpose. To prevent distributed denial of service(DDos) attacks, you need to take other measures.
+3. Traffic control is a microservice-level rather than process-level function.
-?????????microservice.yaml???????????????????????????????????????????handler????????
+### Configuration
+
+??Rate limiting policies are configured in the microservice.yaml file. For related configuration items, see Table 2. To enable the rate limiting policy at the provider end, you also need to configure the rate limiting handler on the server in the processing chain and add dependencies in the pom.xml file. An example of microservice.yaml file configuration is as follows:
```yaml
cse:
@@ -96,55 +95,58 @@ cse:
default: qps-flowcontrol-provider
```
-??**?2 QPS???????**
+??**Table2 Configuration items of the QPS rate limit**
+
+| Configuration Item | Default Value | Value Range | Mandatory | Description | Remarks |
+| :--------------------------------------- | :------------------ | :----------------------- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| cse.flowcontrol.Provider.qps.enabled | true | true/false | No | Specifies whether to enable traffic control at the provider end. | - |
+| cse.flowcontrol.Provider.qps.limit.\[ServiceName\] | 2147483647?max int? | \(0,2147483647\]?Integer | No | Specifies the number of requests allowed per second. | This parameter can only be configured for microservice |
+| cse.flowcontrol.Provider.qps.global.limit | 2147483647?max int? | (0,2147483647\]?Integer | No | Specifies the total number of requests allowed per second at the provider end | If no configuration is set for any specific microservices, this parameter takes effect |
+
+##
+## Fallback Policy
-| ??? | ??? | ???? | ???? | ?? | ?? |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| cse.flowcontrol.Provider.qps.enabled | true | true/false | ? | ????Provider?? | - |
-| cse.flowcontrol.Provider.qps.limit.\[ServiceName\] | 2147483647?max int? | \(0,2147483647\]??? | ? | ????????? | ???microservice??????? |
-| cse.flowcontrol.Provider.qps.global.limit | 2147483647?max int? | (0,2147483647\]??? | ? | provider??????????? | ?????????????????? |
+### Concept Description
-## ????
-### ????
+A fallback policy is used when a service request is abnormal.
-??????????????????????????????????????????????????????????
+There are three key concepts in fallback: isolation, fallbreak, and fault tolerance:
-??????????????????????????????
-* ?????????????????????????????????????????????????????????
-* ?????????????????????????????????????????????????????????????
-* ??????????????????????????????????????????????????????????????
+* Isolation is an exception detection mechanism. Two common items that need to be detected are timeout duration and the number of concurrent requests.
+* Fallbreak is an exception response mechanism, and it depends on isolation. Fallbreak is triggered based on the error rate. Two common items need to set are the number of requests to collect and error rate.
+* Fault tolerance is an exception handling mechanism that depends on fallbreak. Fault tolerance is called after a fallbreak. For fault tolerance, you need to set the number of fault tolerance call items.
-???????????"??"?????N??????M???????"??"???????????"??"????????????????Netflix Hystrix????????????????????????????[https://github.com/Netflix/Hystrix/wiki/Configuration](https://github.com/Netflix/Hystrix/wiki/Configuration)???ServiceComb??????????????null???????
+During fallback, if M(the threshold) errors are detected in N requests, the consumer will no longer send requests and the fault tolerance mechanism will be enabled. The preceding fallback process is accepted in Netflix Hystrix and helps you configure the parameters. Obtain information about the parameter configuration at [https://github.com/Netflix/Hystrix/wiki/Configuration](https://github.com/Netflix/Hystrix/wiki/Configuration). Currently, ServiceComb provides two types of fault tolerance modes: returning null values and throwing exceptions.
-### ????
+### Scenario
-??????????????????????????
+By configuring a fallback policy, you can handler microservice exceptions.
-### ????
+### Configuration
-??????????
+??Configuration items of fallback policies are as follows:
-??**?3 ???????????**
+??**Table 3 Configuration items of the fallback policy**
-| ??? | ??? | ???? | ???? | ?? | ?? |
-| :--- | :--- | :--- | :--- | :--- | :--- |
-| cse.isolation.timeout.enabled | FALSE | - | ? | ???????? | |
-| cse.isolation.timeoutInMilliseconds | 30000 | - | ? | ?????? | |
-| cse.isolation.maxConcurrentRequests | 10 | - | ? | ??????? | |
-| cse.circuitBreaker.enabled | TRUE | - | ? | ???????? | |
-| cse.circuitBreaker.forceOpen | FALSE | - | ? | ???????????? | |
-| cse.circuitBreaker.forceClosed | FALSE | - | ? | ???????? | ??forceOpen??????forceOpen??? |
-| cse.circuitBreaker.sleepWindowInMilliseconds | 15000 | - | ? | ?????????? | ?????????????????????????????????????????? |
-| cse.circuitBreaker.requestVolumeThreshold | 20 | - | ? | 10s????????????????????? | ??10???????10?1?????????1s???????????????????????1s???????? |
-| cse.circuitBreaker.errorThresholdPercentage | 50 | - | ? | ??????????????? | |
-| cse.fallback.enabled | TRUE | - | ? | ?????????????? | |
-| cse.fallback.maxConcurrentRequests | 10 | - | ? | ???????????cse.fallbackpolicy.policy??????????????????????????? | |
-| cse.fallbackpolicy.policy | throwexception | returnnulll \| throwexception | ? | ???????? | |
+| Configuration Item | Default value | Value Range | Mandatory | Description | Remarks |
+| :--------------------------------------- | :------------- | :---------------------------- | :-------- | :--------------------------------------- | :--------------------------------------- |
+| cse.isolation.timeout.enabled | FALSE | - | No | Specifies whether to enable timeout detection. | |
+| cse.isolation.timeoutInMilliseconds | 30000 | - | No | Specifies the timeout duration threshold. | |
+| cse.isolation.maxConcurrentRequests | 10 | - | No | Specifies the maximum number of concurrent requests. | |
+| cse.circuitBreaker.enabled | TRUE | - | No | Specifies whether to enable fallbreak. | |
+| cse.circuitBreaker.forceOpen | FALSE | - | No | Specifies that fallbreak is enable regardless of the number of failed requests or the error rate. | |
+| cse.circuitBreaker.forceClosed | FALSE | - | No | Specifies that fallbreak can be implemented at any time. | If this parameter and cse.circuitBreaker.forceOpen both need to be configured, cse.circuitBreaker.forceOpen has priority. |
+| cse.circuitBreaker.sleepWindowInMilliseconds | 15000 | - | No | Specifies the duration needed to recover from fallbreak. | After the recovery, the number of failed requests will be recalculated. Not: If the consumer fails to send a request to the provider after the recovery, fallbreak is enabled again. |
+| cse.circuitBreaker.requestVolumeThreshold | 20 | - | No | Specifies the threshold of failed requests sent within 10 seconds. If the threshold is reached, fallbreak is triggered. | Ten seconds will be divided into ten 1 seconds, and the error rate is calculated 1 second later after an error occurred. Therefore, fallbreak can be implemented at least 1 second after the call. |
+| cse.circuitBreaker.errorThresholdPercentage | 50 | - | No | Specifies the threshold of error rate. If the threshold is reached, fallbreak is triggered. | |
+| cse.fallback.enabled | TRUE | - | No | Specifies whether to enable troubleshooting measures after an error occurred. | |
+| cse.fallback.maxConcurrentRequests | 10 | - | No | Specifies the number of fault tolerance(cse.fallbackpolicy.policy) requests concurrently called. If the value exceeds 10, the measures will no longer be called, and exception are returned. | |
+| cse.fallbackpolicy.policy | throwexception | returnnulll \| throwexception | No | Specifies the error handling policies after an error occurred. | |
-**???** ????cse.isolation.timeout.enabled=true??????????????????????????????????????????????cse.isolation.timeout.enabled?????false??????????????cse.request.timeout=30000?
+**NOTE:** Be cautions when setting cse.isolation.timeout.enabled to TRUE, All processes are asynchronously processed in the system, and any error value returned by an intermediate process because the set timeout duration is reached can cause failure of the follow-up processes. Therefore, you are advised to keep the default value FALSE for cse.isolation.timeout.enabled. For timeout duration from the network aspect, you are advised to set cse.request.timeout=30000.
{: .notice--warning}
-## ????
+## Sample Code
```yaml
cse:
@@ -165,5 +167,6 @@ cse:
policy: throwexception
```
-> **???**
-> ????????????????????????handler?`bizkeeper-provider`???????handler?`bizkeeper-consumer`?
+> **NOTE:**
+>
+> You need to enable service governance for fallback, The provider handler is bizkeeper-provider, and the consumer handler is bizkeeper-consumer.
diff --git a/_users/service-definition.md b/_users/service-definition.md
index ae6afe2..6f8914d 100644
--- a/_users/service-definition.md
+++ b/_users/service-definition.md
@@ -1,55 +1,55 @@
---
-title: "????"
+title: "Service Definition"
lang: en
ref: service-definition
permalink: /users/service-definition/
-excerpt: "????"
+excerpt: "Service Definition"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## ????
+## 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.
-## ????
+## Configuration
-????microservice.yaml?????????????????????src/main/resources/microservice.yaml?
+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.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??????????????????????
-- ???????????????app??????????????properties???allowCrossApp=true????????app?????
+> 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: #???
+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
propertyExtentedClass: io.servicecomb.serviceregistry.MicroServicePropertyExtendedStub
-instance_description: #????
- properties: #???
+instance_description: #Instance description
+ properties: #Metadata
key3: value3
propertyExtentedClass: io.servicecomb.serviceregistry.MicroServicePropertyExtendedStub
```
diff --git a/_users/service-heartbeat.md b/_users/service-heartbeat.md
index e5a5ae6..2a776a1 100644
--- a/_users/service-heartbeat.md
+++ b/_users/service-heartbeat.md
@@ -1,31 +1,29 @@
---
-title: "????"
+title: "Service Heartbeat"
lang: en
ref: service-heartbeat
permalink: /users/service-heartbeat/
-excerpt: "????"
+excerpt: "Service Heartbeat"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## ????
+## Scenario
-????????????????????????????????????????????????????????????
+After a microservice instance is registered in the service center, the microservice need to periodically send heartbeats to the service center. If the service center receives no heartbeat within a specific period, the instance will be registered.
-## ??API
+## Involved APIs
-* `io.servicecomb.serviceregistry.client.ServiceRegistryClient`????????
+* `io.servicecomb.serviceregistry.client.ServiceRegistryClient` is the service client.
-## ????
-
-`ServiceRegistryClient`??????????`heartbeat`?????????????????
+`ServiceRegistryClient` provides heartbeat to send heartbeats. You can call it as required. The sample code is as follows:
```java
public static void main(String[] args) throws Exception {
- // ????????????
- // ????????????
+ // Register the microservice and the instance first
+ // Send the heartbeats. Otherwise, the instances will be lost.
while (true) {
System.out.println("heartbeat sended:" + client.heartbeat(service2.getServiceId(), instance.getInstanceId()));
Thread.sleep(3000);
diff --git a/_users/service-interface-constraints.md b/_users/service-interface-constraints.md
index 9b812f4..8aded14 100644
--- a/_users/service-interface-constraints.md
+++ b/_users/service-interface-constraints.md
@@ -1,17 +1,21 @@
---
-title: "??????"
+title: "API Constraints"
lang: en
ref: service-interface-constraints
permalink: /users/service-interface-constraints/
-excerpt: "??????"
+excerpt: "API Constraints"
last_modified_at: 2017-08-15T15:01:43-04:00
redirect_from:
- /theme-setup/
---
{% include toc %}
-## ??????
-Java Chassis??????????????????????????????????????????????????????????????
+## 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.
+
+For example:
```java
public Person query(String id);
@@ -19,9 +23,9 @@ public Object query(String id);
public class Person {String name;}
```
-???????????????????String???id?????????Person???Person????String???name???????????????????????????????????????????????????????????????????????
+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????????????swagger?????id??RequestParam??PathVariable??RequestBody??????????SpringMVC??JAX RS?????????
+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);
@@ -29,38 +33,40 @@ public Person query(@PathVariable String id);
public Person query(@RequestBody String id);
```
-?????????????????String, int??RequestParam??PathVariable??????????????JSON?????RequestBody??????HTTP??????????????????
-## ???????
-????????????????????
-* ?????????: java.lang.Object, net.sf.json.JsonObject?
-* ???????
+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.
+
+## 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> {...}
```
-* ???????????????????????`List<IPerson>, Map<String, PersonHolder<?>>, List, Map`?? `List<String>, List<Person>`???????????
+* 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 ...}
```
-?????????????????????????????????????????
-## ??????
-??ServiceComb-Java-Chassis????????????????????????????????????????
+Developers do not need to worry about the constraints. The program automatically checks them when it is started, and displays types as properties.
+
+## 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:
-* map?key???string
+* Map, The key supports only string.
-* highway (protobuf??)
- 1. ?????????null???Collection?array?????map?value
- 2. ???0????list??????????????????????
+* 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.
* springmvc
- 1. ???Date??path?query??? ??springmvc???Date?toString??path?query???swagger???????
+ 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/assets/images/thread-model-en.png b/assets/images/thread-model-en.png
new file mode 100644
index 0000000..952899e
Binary files /dev/null and b/assets/images/thread-model-en.png differ
----------------------------------------------------------------
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