From 5d2f4a3b24924450642f610872c68aecf1797bb5 Mon Sep 17 00:00:00 2001 From: liubao Date: Fri, 3 Apr 2020 16:23:07 +0800 Subject: [PATCH] [SCB-1845]add TOC for java-chassis documents to make easier to search --- .../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(-) create mode 100644 java-chassis-reference/zh_CN/docs/toc.md 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 18707c69..f8508eb2 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 11d6ea0c..2391afbd 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 00000000..ebaec451 --- /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 18fc09af..39a03c09 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