[GitHub] liubao68 closed pull request #69: 3rd party REST service invoke

[GitBox <gi...@apache.org>]

liubao68 closed pull request #69: 3rd party REST service invoke
URL: https://github.com/apache/incubator-servicecomb-docs/pull/69
 
 
   

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/3rd-party-service-invoke.md b/java-chassis-reference/en_US/build-consumer/3rd-party-service-invoke.md
new file mode 100644
index 0000000..1ab74eb
--- /dev/null
+++ b/java-chassis-reference/en_US/build-consumer/3rd-party-service-invoke.md
@@ -0,0 +1,101 @@
+# Invoking 3rd party REST service
+
+## Concept Description
+
+ServiceComb allows users to register the information of 3rd party REST service, including endpoint and swagger, so that users can invoke 3rd party services like invoking ServiceComb provider services.
+Using this feature, all the requests sent to 3rd party service will be processed by consumer handler chain and HttpClientFilters, which means this feature allows service governance function on invoking 3rd party service, and other ServiceComb custom extension mechanism is also supported.
+
+## Sample Code
+
+1. Assume that there is a REST 3rd party service, whose listen port is 8080, and rest interface contract is like below:
+  ```yaml
+  ---
+  swagger: "2.0"
+  info:
+    version: "0.0.1"
+    title: "3rd party REST service for example"
+  basePath: "/rest"
+  consumes:
+  - "application/json"
+  produces:
+  - "text/plain"
+  paths:
+    /{pathVar}:
+      get:
+        operationId: "testPathVar"
+        parameters:
+        - name: "pathVar"
+          in: "path"
+          required: true
+          type: "string"
+        responses:
+          200:
+            description: "response of 200, return \"Received, OK. [${pathVar}]\""
+            schema:
+              type: "string"
+  ```
+
+2. To invoke this service, a java interface class should be written according to the rest contract and annotated by rest annotations.
+  The way to write java interface class is similar to writing SpringMVC or JAX-RS style
+  ServiceComb provider service. Interface code is like below:
+  ```java
+  @Path("/rest")
+  @Api(produces = MediaType.TEXT_PLAIN)
+  public interface VertxServerIntf {
+    @Path("/{pathVar}")
+    @GET
+    String testPathVar(@PathParam("pathVar") String pathVar);
+  }
+  ```
+
+3. Register the information of 3rd party rest service on consumer side:
+  ```java
+  String endpoint = "rest://127.0.0.1:8080";
+  RegistryUtils.getServiceRegistry().registerMicroserviceMappingByEndpoints(
+      // 3rd party rest service name, you can specify the name on your need as long as you obey the microservice naming rule
+      "thirdPartyService",
+      // service version
+      "0.0.1",
+      // list of endpoints
+      Collections.singletonList(endpoint),
+      // java interface class to generate swagger schema
+      ThirdPartyRestServiceInterface.class
+  );
+  ```
+
+4. Invoke 3rd party rest service in the way similar to invoking ServiceComb provider service.
+  Here is a RPC style invoking example:
+  ```java
+  // declare rpc reference to 3rd party rest service, schemaId is the same as microservice name
+  @RpcReference(microserviceName = "thirdPartyService", schemaId = "thirdPartyService")
+  ThirdPartyRestServiceInterface thirdPartyRestService;
+
+  @RequestMapping(path = "/{pathVar}", method = RequestMethod.GET)
+  public String testInvoke(@PathVariable(name = "pathVar") String pathVar) {
+    LOGGER.info("testInvoke() is called, pathVar = [{}]", pathVar);
+    // invoke 3rd party rest service
+    String response = thirdPartyRestService.testPathVar(pathVar);
+    LOGGER.info("testInvoke() response = [{}]", response);
+    return response;
+  }
+  ```
+
+5. Service governance on invoking 3rd party REST service
+
+  The service governance configuration on invoking 3rd party REST service is similar to the scenario that ServiceComb consumer invokes ServiceComb provider. Take the rate limiting policy for example, the configuration of consumer side microservice.yaml is like below:
+  ```yaml
+    servicecomb:
+      flowcontrol:
+        Consumer:
+          qps:
+            enabled: true
+            limit:
+              thirdPartyService: 1
+  ```
+  As the config above, the rate to send request to the service named as "thirdPartyService", which is the 3rd party rest service, is limited to 1QPS.
+  When request rate is above 1QPS, consumer will get an `InvocationException` indicating `429 Too Many Requests` error.
+
+> ***Cautions:***
+- endpoint is prefixed with `rest`, instead of `http`. You can refer the endpoints registered to service center to write it.
+- One 3rd party REST service can hold multiple endpoints. Consumer side load balance function is supported.
+- Currently the information of a 3rd party service can only be initialized for once. i.e. adding, deleting and modifying is not supported.
diff --git a/java-chassis-reference/zh_CN/build-consumer/3rd-party-service-invoke.md b/java-chassis-reference/zh_CN/build-consumer/3rd-party-service-invoke.md
new file mode 100644
index 0000000..18707c6
--- /dev/null
+++ b/java-chassis-reference/zh_CN/build-consumer/3rd-party-service-invoke.md
@@ -0,0 +1,102 @@
+# 调用第三方服务
+
+## 概念阐述
+
+ServiceComb允许用户注册第三方REST服务的endpoint、接口契约等信息，使用户可以以调用ServiceComb provider服务相同的方式编写调用第三方服务的代码。
+使用该功能调用第三方服务时，发往第三方服务的请求会经过consumer端handler链、HttpClientFilter的处理，
+即该功能支持对第三方服务调用的治理功能，并且也支持ServiceComb既有的用户自定义扩展处理机制。
+
+## 示例代码
+
+1. 假设用户在本地开发了一个REST服务作为第三方REST服务，监听端口号为8080，其REST接口如契约所示：
+  ```yaml
+  ---
+  swagger: "2.0"
+  info:
+    version: "0.0.1"
+    title: "3rd party REST service for example"
+  basePath: "/rest"
+  consumes:
+  - "application/json"
+  produces:
+  - "text/plain"
+  paths:
+    /{pathVar}:
+      get:
+        operationId: "testPathVar"
+        parameters:
+        - name: "pathVar"
+          in: "path"
+          required: true
+          type: "string"
+        responses:
+          200:
+            description: "response of 200, return \"Received, OK. [${pathVar}]\""
+            schema:
+              type: "string"
+  ```
+
+2. 为调用此服务，需要先根据其REST接口编写一个Java接口类，并打上参数注解。
+  Java接口类的编写方式参照使用隐式契约开发SpringMVC和JAX-RS风格的provider方式。
+  接口代码示例如下：
+  ```java
+  @Path("/rest")
+  @Api(produces = MediaType.TEXT_PLAIN)
+  public interface VertxServerIntf {
+    @Path("/{pathVar}")
+    @GET
+    String testPathVar(@PathParam("pathVar") String pathVar);
+  }
+  ```
+
+3. 在consumer服务中调用ServiceComb提供的方法将其进行注册：
+  ```java
+  String endpoint = "rest://127.0.0.1:8080";
+  RegistryUtils.getServiceRegistry().registerMicroserviceMappingByEndpoints(
+      // 3rd party rest service name, you can specify the name on your need as long as you obey the microservice naming rule
+      "thirdPartyService",
+      // service version
+      "0.0.1",
+      // list of endpoints
+      Collections.singletonList(endpoint),
+      // java interface class to generate swagger schema
+      ThirdPartyRestServiceInterface.class
+  );
+  ```
+
+4. 调用第三方服务，声明和调用方式与调用ServiceComb provider服务相同，此处以RPC调用方式为例。
+  ```java
+  // declare rpc reference to 3rd party rest service, schemaId is the same as microservice name
+  @RpcReference(microserviceName = "thirdPartyService", schemaId = "thirdPartyService")
+  ThirdPartyRestServiceInterface thirdPartyRestService;
+
+  @RequestMapping(path = "/{pathVar}", method = RequestMethod.GET)
+  public String testInvoke(@PathVariable(name = "pathVar") String pathVar) {
+    LOGGER.info("testInvoke() is called, pathVar = [{}]", pathVar);
+    // invoke 3rd party rest service
+    String response = thirdPartyRestService.testPathVar(pathVar);
+    LOGGER.info("testInvoke() response = [{}]", response);
+    return response;
+  }
+  ```
+
+5. 使用治理功能
+
+  使用治理功能的方法与普通的consumer调用provider场景类似。以限流策略为例，在consumer服务的microservice.yaml文件中进行如下配置:
+  ```yaml
+    servicecomb:
+      flowcontrol:
+        Consumer:
+          qps:
+            enabled: true
+            limit:
+              thirdPartyService: 1
+  ```
+  此时即将consumer调用名为`thirdPartyService`的第三方REST服务的QPS设置为1。当consumer调用`thirdPartyService`的流量高于1QPS时，
+  将会得到`429 Too Many Requests`的`InvocationException`异常。
+
+> ***注意：***
+- endpoint信息是以`rest`开头的，而非`http`，可以参照ServiceComb微服务注册到服务中心的endpoint样式进行编写。
+- 当第三方服务有多个实例（地址）时，可以在endpoint list中指定多个地址，ServiceComb支持对多个地址进行负载均衡处理，处理方式和对待ServiceComb
+ provider服务相同。
+- 当前仅支持一次性注册第三方服务及其实例信息，不支持增加、删除和修改操作。


 

----------------------------------------------------------------
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