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/02/13 07:43:14 UTC
[servicecomb-docs] branch master updated: [SCB-1708]add inspector module developer guide

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 bd6aaed  [SCB-1708]add inspector module developer guide
bd6aaed is described below

commit bd6aaedb62aa3c6dfc239d2db2af685716f9c8ab
Author: liubao <bi...@qq.com>
AuthorDate: Thu Feb 13 15:08:48 2020 +0800

    [SCB-1708]add inspector module developer guide
---
 .../en_US/docs/references-handlers/intruduction.md |   2 +-
 .../zh_CN/docs/assets/inspector-01.png             | Bin 0 -> 44499 bytes
 .../zh_CN/docs/assets/inspector-02.png             | Bin 0 -> 38918 bytes
 .../zh_CN/docs/featured-topics/using-inspector.md  |  73 +++++++++++++++++++++
 .../zh_CN/docs/references-handlers/intruduction.md |  12 ++--
 .../diff-spring-mvc.md                             |   2 +-
 ...a-chassis-in-spring-boot.md => introduction.md} |   7 +-
 .../using-java-chassis-in-spring-boot.md           |  39 ++---------
 java-chassis-reference/zh_CN/mkdocs.yml            |   9 +--
 9 files changed, 92 insertions(+), 52 deletions(-)

diff --git a/java-chassis-reference/en_US/docs/references-handlers/intruduction.md b/java-chassis-reference/en_US/docs/references-handlers/intruduction.md
index 0fc8110..70f9aee 100644
--- a/java-chassis-reference/en_US/docs/references-handlers/intruduction.md
+++ b/java-chassis-reference/en_US/docs/references-handlers/intruduction.md
@@ -12,7 +12,7 @@ servicecomb:
         default: qps-flowcontrol-consumer,loadbalance
       Provider: 
         default: qps-flowcontrol-provider
- ```
+```
 
 We can also enable different handlers for each microservice, 
 
diff --git a/java-chassis-reference/zh_CN/docs/assets/inspector-01.png b/java-chassis-reference/zh_CN/docs/assets/inspector-01.png
new file mode 100644
index 0000000..d692fce
Binary files /dev/null and b/java-chassis-reference/zh_CN/docs/assets/inspector-01.png differ
diff --git a/java-chassis-reference/zh_CN/docs/assets/inspector-02.png b/java-chassis-reference/zh_CN/docs/assets/inspector-02.png
new file mode 100644
index 0000000..4865d1c
Binary files /dev/null and b/java-chassis-reference/zh_CN/docs/assets/inspector-02.png differ
diff --git a/java-chassis-reference/zh_CN/docs/featured-topics/using-inspector.md b/java-chassis-reference/zh_CN/docs/featured-topics/using-inspector.md
new file mode 100644
index 0000000..a3e58d6
--- /dev/null
+++ b/java-chassis-reference/zh_CN/docs/featured-topics/using-inspector.md
@@ -0,0 +1,73 @@
+# 使用 inspector 模块查看契约
+
+inspector 提供了用户查看、下载契约，生成文档和对API接口进行测试的功能。这个功能直接在微服务提供，用于弥补通过服务中心查看契约和对接口进行测试的不足。inspector功能后续会做进一步增强，除了管理契约，还可以观察微服务的内部状态，帮助定位一些常见问题。
+
+## 启用inspector
+
+在项目中启用inspector很简单，只需要在pom中增加如下依赖即可。 
+    
+    <dependency>
+      <groupId>org.apache.servicecomb</groupId>
+      <artifactId>inspector</artifactId>
+    </dependency>
+
+如果项目中依赖了 solution-basic , 这个模块会自动包含进来。
+
+引入依然后启动微服务即可使用相关契约管理功能。下面假设微服务监听的端口为8080。
+
+## 使用inspector功能
+
+inspector提供了管理界面，集成了swagger编辑器。输入 http://localhost:8080/inspector/index.html 后，出现如下界面。
+
+ 
+***SWAGER编辑界面***
+
+![](../assets/inspector-01.png)
+
+在SWAGGER编辑界面，可以对接口进行测试。
+
+***HTML界面***
+
+![](../assets/inspector-02.png)
+
+HTML页面提供了更容易读写的格式，方便开发者查看接口说明。
+
+ 
+输入 http://localhost:8080/inspector/schemas 可以查询所有的schema列表
+
+```json
+["goodsRepositoryApi","goodsService","onlineMallApi","stockApi","goodsCategoryApi","goodsPriceApi"]
+```
+
+
+输入 ```http://localhost:8080/inspector/download/schemas?format=HTML``` 可以下载文档。format支持HTML和SWAGGER两种格式。这个接口会下载所有契约文件，打包为zip格式。
+
+
+输入 ```http://localhost:8080/inspector/schemas/goodsService?download=false&format=HTML``` 可以查看、下载单个契约文件。
+
+ 
+## 保护 inspector 接口的访问控制
+
+该功能被设计为辅助开发、设计、运维，第一次访问的时候加载很慢，不建议开放给最终用户大规模并发访问使用。 如果在生产环境带入
+这个功能，可以通过必要的隔离措施和访问控制，限制最终用户对于这个接口的访问。
+
+
+可以使用 java-chassis 提供的线程池隔离功能， 将这个服务放到独立的线程池，避免对其他服务的访问产生影响。具体操作步骤包括，
+
+定义线程池：
+
+```
+  <bean id="servicecomb.samples.executor.groupThreadPool" class="org.apache.servicecomb.core.executor.GroupExecutor"
+    init-method="init"/>
+```
+
+启用线程池:
+
+```json
+servicecomb:
+  executors:
+   Provider:
+     inspector: servicecomb.samples.executor.groupThreadPool
+```
+ 
+
diff --git a/java-chassis-reference/zh_CN/docs/references-handlers/intruduction.md b/java-chassis-reference/zh_CN/docs/references-handlers/intruduction.md
index 73bc03b..ab80dea 100644
--- a/java-chassis-reference/zh_CN/docs/references-handlers/intruduction.md
+++ b/java-chassis-reference/zh_CN/docs/references-handlers/intruduction.md
@@ -5,7 +5,7 @@
 ### 处理链配置
 处理链分为Consumer和Provider，分别配置如下：
 
-```
+```yaml
 servicecomb:
   handler:
     chain:
@@ -13,13 +13,13 @@ servicecomb:
         default: qps-flowcontrol-consumer,loadbalance
       Provider: 
         default: qps-flowcontrol-provider
- ```
+```
 
 通过名字配置处理链，可以根据需要调整处理链的顺序，配置在前面的处理链先执行。
 
 上述配置指定目标微服务缺省处理链，开发者还可以对特定的微服务配置不同的处理链，比如：
 
-```
+```yaml
 servicecomb:
   handler:
     chain:
@@ -36,7 +36,7 @@ servicecomb:
 
 * 实现Handler接口
 
-```
+```java
 public class AuthHandler implements Handler {
   @Override
   public void handle(Invocation invocation, AsyncResponse asyncResponse) throws Exception {
@@ -59,7 +59,7 @@ public class AuthHandler implements Handler {
 
 * 增加*.handler.xml文件，给Handler取一个名字
 
-```
+```xml
 <config>
   <handler id="auth"
     class="org.apache.servicecomb.authentication.gateway.AuthHandler" />
@@ -68,7 +68,7 @@ public class AuthHandler implements Handler {
 
 * 在microservice.yaml中启用新增加的处理链
 
-```
+```yaml
 servicecomb:
   handler:
     chain:
diff --git a/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/diff-spring-mvc.md b/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/diff-spring-mvc.md
index 4da5a9f..c8b8c01 100644
--- a/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/diff-spring-mvc.md
+++ b/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/diff-spring-mvc.md
@@ -1,4 +1,4 @@
-# Spring MVC开发习惯的差异
+# 与原生 Spring MVC 开发习惯的差异
 
 java chassis支持使用Spring MVC提供的标签\(org.springframework.web.bind.annotation\)来声明REST接口，但是两者是独立的实现，而且有不一样的设计目标。java chassis的目标是提供跨语言、支持多通信协议的框架，因此去掉了Spring MVC中一些对跨语言支持不是很好的特性，也不支持特定运行框架强相关的特性，比如直接访问Servlet协议定义的HttpServletRequest。java-chassis支持的Spring MVC标签是spring boot的子集， 下面是一些显著的差别。
 
diff --git a/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md b/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/introduction.md
similarity index 89%
copy from java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md
copy to java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/introduction.md
index be35e93..796c51d 100644
--- a/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md
+++ b/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/introduction.md
@@ -1,4 +1,4 @@
-# 在Spring Boot中使用java chassis
+# java chassis 与 Spring Boot 集成介绍
 
 [Spring Boot](https://projects.spring.io/spring-boot/)可以让开发者能够更加快速的构建Spring应用。主要提供了如下功能：
 
@@ -10,14 +10,12 @@
 
 将Spring Boot用于微服务开发，可以极大的简化开发者配置和部署。java-chassis提供了完善的的服务治理能力、良好的跨语言特性和高效的异步通信能力，通过使用java chassis，可以快速启用各种满足商业运维需要的功能。
 
-本文将介绍如何在Spring Boot中集成和使用。开发者通常会以如下几种方式使用Spring Boot：
+开发者通常会以如下几种方式使用Spring Boot：
 
 1. JAVA应用方式：引入spring-boot-starter，开发普通JAVA应用，该应用不会启动WEB服务器。
 
 2. Web开发方式：引入spring-boot-starter-web，开发Web应用，该应用会包含一个内嵌的Tomcat或者Jetty服务器，并且使用The Spring Web MVC framework（简称Spring MVC）开发REST接口。
 
-## java-chassis 集成 spring boot的方式
-
 在两种情况下，都可以集成java chassis，原理图如下：
 
 * JAVA应用方式
@@ -32,6 +30,5 @@
 
 该集成方式的本质是将Spring MVC的DispatcherServlet替换为java chassis的RestServlet，通过java-chassis提供REST/RPC服务。
 
-## 两种集成方式的区别
 
 两种开发方式都会启用java chassis的全量功能，JAVA应用方式运行于独立的HTTP服务器（基于vert.x构建）上，性能上存在很大的优势。Web开发方式运行于Tomcat或者其他内置的Web服务器之上，作为一个Servlet接收请求，因此在开发过程中，可以使用Web容器提供的一些功能，比如提供页面服务，使用Filter等。当应用只需要提供REST服务，并且对性能要求很高的场景，建议使用JAVA应用方式。
diff --git a/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md b/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md
index be35e93..dea5a19 100644
--- a/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md
+++ b/java-chassis-reference/zh_CN/docs/using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md
@@ -1,37 +1,10 @@
 # 在Spring Boot中使用java chassis
 
-[Spring Boot](https://projects.spring.io/spring-boot/)可以让开发者能够更加快速的构建Spring应用。主要提供了如下功能：
+本文将介绍如何在Spring Boot中集成和使用 java-chassis ， 包括如下内容：
 
-1. 创建独立可执行的Spring应用。通过将应用程序打包为jar，就可以通过java -jar来执行应用程序。
+* [java chassis 与 Spring Boot 集成介绍](introduction.md)
+* [java chassis spring boot starter说明](components-for-spring-boot.md)
+* [JAVA应用方式开发步骤](java-application.md)
+* [Web开发方式开发步骤](web-application.md)
+* [与原生 Spring MVC 开发习惯的差异](diff-spring-mvc.md)
 
-2. 内嵌Tomcat, Jetty等WEB服务器，而不需要开发者打包war。
-
-3. 提供starter简化maven依赖关系配置。
-
-将Spring Boot用于微服务开发，可以极大的简化开发者配置和部署。java-chassis提供了完善的的服务治理能力、良好的跨语言特性和高效的异步通信能力，通过使用java chassis，可以快速启用各种满足商业运维需要的功能。
-
-本文将介绍如何在Spring Boot中集成和使用。开发者通常会以如下几种方式使用Spring Boot：
-
-1. JAVA应用方式：引入spring-boot-starter，开发普通JAVA应用，该应用不会启动WEB服务器。
-
-2. Web开发方式：引入spring-boot-starter-web，开发Web应用，该应用会包含一个内嵌的Tomcat或者Jetty服务器，并且使用The Spring Web MVC framework（简称Spring MVC）开发REST接口。
-
-## java-chassis 集成 spring boot的方式
-
-在两种情况下，都可以集成java chassis，原理图如下：
-
-* JAVA应用方式
-
-![](../assets/using-java-chassis-in-spring-boot-002.png)
-
-这种集成方式相对简单，相当于直接将java-chassis通过Spring Boot应用拉起，通过java-chassis 提供REST/RPC服务。
-
-* Web开发方式
-
-![](../assets/using-java-chassis-in-spring-boot-001.png)
-
-该集成方式的本质是将Spring MVC的DispatcherServlet替换为java chassis的RestServlet，通过java-chassis提供REST/RPC服务。
-
-## 两种集成方式的区别
-
-两种开发方式都会启用java chassis的全量功能，JAVA应用方式运行于独立的HTTP服务器（基于vert.x构建）上，性能上存在很大的优势。Web开发方式运行于Tomcat或者其他内置的Web服务器之上，作为一个Servlet接收请求，因此在开发过程中，可以使用Web容器提供的一些功能，比如提供页面服务，使用Filter等。当应用只需要提供REST服务，并且对性能要求很高的场景，建议使用JAVA应用方式。
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml b/java-chassis-reference/zh_CN/mkdocs.yml
index fc09ef5..731448e 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -76,12 +76,9 @@ nav:
 - 微服务安全: 
     - 使用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
-    - 提供的spring boot starter说明: using-java-chassis-in-spring-boot/components-for-spring-boot.md
-    - JAVA应用方式开发步骤: using-java-chassis-in-spring-boot/java-application.md
-    - Web开发方式开发步骤: using-java-chassis-in-spring-boot/web-application.md
-    - Spring MVC开发习惯的差异: using-java-chassis-in-spring-boot/diff-spring-mvc.md
+- 专题文章:
+    - 在Spring Boot中使用java chassis: using-java-chassis-in-spring-boot/using-java-chassis-in-spring-boot.md
+    - 使用 inspector 模块查看契约: featured-topics/using-inspector.md
 - 处理链参考: 
     - 处理链介绍: references-handlers/intruduction.md
     - 负载均衡: references-handlers/loadbalance.md