You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@servicecomb.apache.org by li...@apache.org on 2020/04/03 11:11:54 UTC
[servicecomb-docs] branch master updated: [SCB-1845]add TOC for
java-chassis documents to make easier to search
This is an automated email from the ASF dual-hosted git repository.
liubao pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/servicecomb-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 09aa0a8 [SCB-1845]add TOC for java-chassis documents to make easier to search
09aa0a8 is described below
commit 09aa0a8125f4a54914b90c08444e3db2f0b89562
Author: liubao <bi...@qq.com>
AuthorDate: Fri Apr 3 16:23:07 2020 +0800
[SCB-1845]add TOC for java-chassis documents to make easier to search
---
.../build-consumer/3rd-party-service-invoke.md | 155 +++++++++++----------
java-chassis-reference/zh_CN/docs/index.md | 10 +-
java-chassis-reference/zh_CN/docs/toc.md | 95 +++++++++++++
java-chassis-reference/zh_CN/mkdocs.yml | 1 +
4 files changed, 181 insertions(+), 80 deletions(-)
diff --git a/java-chassis-reference/zh_CN/docs/build-consumer/3rd-party-service-invoke.md b/java-chassis-reference/zh_CN/docs/build-consumer/3rd-party-service-invoke.md
index 18707c6..f8508eb 100644
--- a/java-chassis-reference/zh_CN/docs/build-consumer/3rd-party-service-invoke.md
+++ b/java-chassis-reference/zh_CN/docs/build-consumer/3rd-party-service-invoke.md
@@ -9,94 +9,99 @@ ServiceComb允许用户注册第三方REST服务的endpoint、接口契约等信
## 示例代码
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:
+
+ ```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);
- }
- ```
+ 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
- );
- ```
+
+ ```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;
- }
- ```
+ ```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. 使用治理功能
+5. 使用治理功能。使用治理功能的方法与普通的consumer调用provider场景类似。以限流策略为例，在consumer服务的microservice.yaml文件中进行如下配置:
- 使用治理功能的方法与普通的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`异常。
+ ```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服务相同。
- 当前仅支持一次性注册第三方服务及其实例信息，不支持增加、删除和修改操作。
+
diff --git a/java-chassis-reference/zh_CN/docs/index.md b/java-chassis-reference/zh_CN/docs/index.md
index 11d6ea0..2391afb 100644
--- a/java-chassis-reference/zh_CN/docs/index.md
+++ b/java-chassis-reference/zh_CN/docs/index.md
@@ -1,11 +1,11 @@
# 概述
-Apache ServiceComb Java Chassis 给开发者提供一个快速构建微服务的JAVA SDK。它包含如下特性：
+Apache ServiceComb Java Chassis 给开发者提供一个快速构建微服务的 JAVA SDK 。它包含如下特性：
-* 多种开发风格，REST(JAX-RS、Spring MVC）和RPC
-* 多种通信协议, HTTP over Vert.x、Http Over Servlet、Highway等
+* 多种开发风格，REST(JAX-RS、Spring MVC）和 RPC
+* 多种通信协议, HTTP over Vert.x、Http Over Servlet、Highway 等
* 统一一致的服务提供者、服务消费者处理链，以及基于契约的开箱即用的服务治理能力
-开发者可以通过[Apache ServiceComb 的开放性设计](http://servicecomb.apache.org/cn/docs/open-design/)了解更多特性和设计原理。
+开发者可以通过[设计选型参考](start/design.md)了解 Java Chassis 的设计思路。
开发者可以通过下面的链接获取其他版本的帮助文档。
@@ -15,4 +15,4 @@ Apache ServiceComb Java Chassis 给开发者提供一个快速构建微服务的
| 最新(2.0.0) | [中文](http://liubao68.gitee.io/servicecomb-java-chassis-doc/java-chassis/zh_CN/), [English](http://liubao68.gitee.io/servicecomb-java-chassis-doc/java-chassis/en_US/)| 由 gitee pages 托管，适合中国用户|
| 最新(2.0.0) | [中文](http://1v96us.coding-pages.com/docs/java-chassis/zh_CN/), [English](http://1v96us.coding-pages.com/docs/java-chassis/en_US/)| 由 coding pages 托管，适合中国用户|
| 1.3.0 | [中文](https://docs.servicecomb.io/java-chassis/1.x/zh_CN/), [English](https://docs.servicecomb.io/java-chassis/1.x/en_US/)| |
-| 1.2.1 | [中文](https://docs.servicecomb.io/java-chassis/1.x/zh_CN/), [English](https://docs.servicecomb.io/java-chassis/1.x/en_US/)| |
\ No newline at end of file
+| 1.2.1 | [中文](https://docs.servicecomb.io/java-chassis/1.x/zh_CN/), [English](https://docs.servicecomb.io/java-chassis/1.x/en_US/)| |
diff --git a/java-chassis-reference/zh_CN/docs/toc.md b/java-chassis-reference/zh_CN/docs/toc.md
new file mode 100644
index 0000000..ebaec45
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/toc.md
@@ -0,0 +1,95 @@
+
+# 目录
+
+* [概述](index.md)
+* [快速入门](start/catalog.md)
+ * [术语表](start/terminology.md)
+ * [微服务系统架构](start/architecture.md)
+ * [安装本地开发环境](start/development-environment.md)
+ * [开发第一个微服务](start/first-sample.md)
+ * [完整例子-bmi应用](featured-topics/application-bmi.md)
+ * [完整例子-porter应用](featured-topics/application-porter.md)
+* [设计选型参考](start/design.md)
+* [开发服务提供者](build-provider/catalog.md)
+ * [服务定义](build-provider/definition/service-definition.md)
+ * [定义服务契约](build-provider/define-contract.md)
+ * [使用隐式契约](build-provider/code-first.md)
+ * [使用Swagger注解](build-provider/swagger-annotation.md)
+ * [用SpringMVC开发微服务](build-provider/springmvc.md)
+ * [用JAX-RS开发微服务](build-provider/jaxrs.md)
+ * [用透明RPC开发微服务](build-provider/transparent-rpc.md)
+ * [接口定义和数据类型](build-provider/interface-constraints.md)
+ * [服务监听地址和发布地址](build-provider/listen-address-and-publish-address.md)
+ * [线程池](build-provider/thread-pool.md)
+ * 服务配置
+ * [限流策略](build-provider/configuration/ratelimite-strategy.md)
+ * [参数效验](build-provider/configuration/parameter-validator.md)
+ * [程序启动逻辑](build-provider/bootup.md)
+ * [Access Log配置](build-provider/access-log-configuration.md)
+* [开发服务消费者](build-consumer/catalog.md)
+ * [消费者通用配置项](build-consumer/common-configuration.md)
+ * [使用RestTemplate开发服务消费者](build-consumer/using-resttemplate.md)
+ * [使用AsynRestTemplate开发服务消费者](build-consumer/using-AsyncRestTemplate.md)
+ * [使用RPC方式开发服务消费者](build-consumer/develop-consumer-using-rpc.md)
+ * [使用服务契约](build-consumer/with-contract.md)
+ * 调用控制
+ * [限流策略](build-consumer/flow-control.md)
+ * [故障注入](build-consumer/fault-injection.md)
+ * [调用第三方REST服务](build-consumer/3rd-party-service-invoke.md)
+* [通用功能开发](general-development/catalog.md)
+ * [访问服务中心](general-development/visit-sc.md)
+ * [应用性能监控](general-development/metrics.md)
+ * [微服务调用链](general-development/microservice-invocation-chain.md)
+ * [自定义调用链打点](general-development/customized-tracing.md)
+ * [本地开发和测试](general-development/local-develop-test.md)
+ * [Http Filter](general-development/http-filter.md)
+ * [文件上传下载](general-development/upload-download.md)
+ * [Reactive](general-development/reactive.md)
+ * [DNS自定义配置](general-development/dnsconfig.md)
+ * [代理设置](general-development/dai-li-she-zhi.md)
+ * [框架上报版本号](general-development/report-framework-version.md)
+ * [跨应用调用](general-development/cross-app-invocation.md)
+ * [定制序列化和反序列化方法](general-development/secret-field.md)
+ * [使用Context传递控制消息](general-development/context.md)
+ * [返回值序列化扩展](general-development/produceprocess.md)
+ * [CORS机制](general-development/CORS.md)
+ * [获取熔断与实例隔离告警事件信息](general-development/AlarmEvent.md)
+ * [优雅停机](general-development/shutdown.md)
+ * [异常处理](general-development/error-handling.md)
+ * [微服务实例间多环境隔离](general-development/multienvironment.md)
+ * [线程模型](general-development/thread-model.md)
+* Transports:
+ * [REST over Servlet](transports/rest-over-servlet.md)
+ * [REST over Vertx](transports/rest-over-vertx.md)
+ * [Highway](transports/highway-rpc.md)
+ * [HTTP2](transports/http2.md)
+* 管理服务配置:
+ * [通用配置说明](config/general-config.md)
+ * [配置注入机制](config/inject-config.md)
+- 服务能力开放:
+ - [介绍](edge/open-service.md)
+ - [使用Edge Service做边缘服务](edge/by-servicecomb-sdk.md)
+ - [使用confd和Nginx做边缘服务](edge/nginx.md)
+ - [使用zuul做边缘服务](edge/zuul.md)
+- 服务打包和运行:
+ - [以standalone模式打包](packaging/standalone.md)
+ - [以WEB容器模式打包](packaging/web-container.md)
+- 微服务安全:
+ - [使用TLS通信](security/tls.md)
+ - [使用RSA认证](security/shi-yong-rsa-ren-zheng.md)
+- 专题文章:
+ - [在Spring Boot中使用java chassis](using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md)
+ - [使用 inspector 模块查看契约](featured-topics/using-inspector.md)
+ - [新功能介绍系列文章](featured-topics/features.md)
+ - [升级指导系列文章](featured-topics/upgrading.md)
+- 处理链参考:
+ - [处理链介绍](references-handlers/intruduction.md)
+ - [负载均衡](references-handlers/loadbalance.md)
+ - [隔离熔断容错](references-handlers/bizkeeper.md)
+ - [公钥认证](references-handlers/publickey.md)
+- 常用配置项参考:
+ - [REST Transport Client 配置项](config-reference/rest-transport-client.md)
+- 常见问题:
+ - [Q & A](question-and-answer/question_answer.md)
+ - [FAQ](question-and-answer/faq.md)
+ - [微服务接口兼容常见问题](question-and-answer/interface-compatibility.md)
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml b/java-chassis-reference/zh_CN/mkdocs.yml
index 18fc09a..39a03c0 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -2,6 +2,7 @@ site_name: ServiceComb Java Chassis 开发指南
nav:
+- 目录: toc.md
- 概述 : index.md
- 快速入门: start/catalog.md
- 设计选型参考: start/design.md