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/incubator-servicecomb-docs.git
commit 0eba6db69e93cbb4c2c591909073f2f54936d9b8
Author: liubao <bao....@huawei.com>
AuthorDate: Fri May 25 18:49:29 2018 +0800
调整能力开发章节，重点完善Edge Service的使用和开发指南
---
java-chassis-reference/zh_CN/SUMMARY.md | 6 +-
.../zh_CN/catalog/open-service.md | 0
.../zh_CN/edge/by-servicecomb-sdk.md | 134 ++++++++++++++++-----
java-chassis-reference/zh_CN/edge/edge-service.md | 0
java-chassis-reference/zh_CN/edge/nginx.md | 2 +
java-chassis-reference/zh_CN/edge/open-service.md | 5 +
java-chassis-reference/zh_CN/edge/zuul.md | 4 +-
.../{edge => general-development}/secret-field.md | 0
8 files changed, 114 insertions(+), 37 deletions(-)
diff --git a/java-chassis-reference/zh_CN/SUMMARY.md
b/java-chassis-reference/zh_CN/SUMMARY.md
index c4e9607..e95a145 100644
--- a/java-chassis-reference/zh_CN/SUMMARY.md
+++ b/java-chassis-reference/zh_CN/SUMMARY.md
@@ -53,11 +53,11 @@
* [代理设置](general-development/dai-li-she-zhi.md)
* [框架上报版本号](general-development/report-framework-version.md)
* [跨应用调用](general-development/cross-app-invocation.md)
-* [服务能力开放](catalog/open-service.md)
+ * [定制序列化和反序列化方法](general-development/secret-field.md)
+* [服务能力开放](edge/open-service.md)
+ * [使用Edge Service做边缘服务](edge/by-servicecomb-sdk.md)
* [使用confd和Nginx做边缘服务](edge/nginx.md)
* [使用zuul做边缘服务](edge/zuul.md)
- * [使用ServiceComb SDK开发边缘服务](edge/by-servicecomb-sdk.md)
- * [定制序列化和反序列化方法](edge/secret-field.md)
* [服务打包和运行](catalog/service-package-run.md)
* [以standalone模式打包](packaging/standalone.md)
* [以WEB容器模式打包](packaging/web-container.md)
diff --git a/java-chassis-reference/zh_CN/catalog/open-service.md
b/java-chassis-reference/zh_CN/catalog/open-service.md
deleted file mode 100644
index e69de29..0000000
diff --git a/java-chassis-reference/zh_CN/edge/by-servicecomb-sdk.md
b/java-chassis-reference/zh_CN/edge/by-servicecomb-sdk.md
index b33ee84..816df59 100644
--- a/java-chassis-reference/zh_CN/edge/by-servicecomb-sdk.md
+++ b/java-chassis-reference/zh_CN/edge/by-servicecomb-sdk.md
@@ -1,20 +1,93 @@
-# 一、功能范围
+# 使用Edge Service做边缘服务
-Edge Service作为整个微服务系统对外的接口，向最终用户提供服务，接入RESTful请求，转发给内部微服务。Edge
Service以开发框架的形式提供，其中的服务映射、请求解析、加密解密、鉴权等逻辑需要业务通过扩展点自行开发。
+Edge Service是ServiceComb提供的JAVA网关服务。Edge
Service作为整个微服务系统对外的接口，向最终用户提供服务，接入RESTful请求，转发给内部微服务。Edge
Service以开发框架的形式提供，开发者可以非常简单的搭建一个Edge Service服务，通过简单的配置就可以定义路由转发规则。同时Edge
Service支持强大的扩展能力，服务映射、请求解析、加密解密、鉴权等逻辑都可以通过扩展实现。
-Edge Service本身也是一个微服务，需遵守所有微服务开发的规则，其本身部署为多实例，前端需使用负载均衡装置进行负载分发。
+Edge
Service本身也是一个微服务，需遵守所有微服务开发的规则。其本身可以部署为多实例，前端使用负载均衡装置进行负载分发；也可以部署为主备，直接接入用户请求。开发者可以根据Edge
Service承载的逻辑和业务访问量、组网情况来规划。
-页面开发、页面模板等表现层，不在Edge Service框架范围内，使用自行使用合适的技术去承载。但是Edge
Service也提供了足够的灵活性，可以使用vertx API实现非ServiceComb SDK开发的微服务的请求转发，可以查看专题文章中示例。
+## 开发Edge Service服务
+开发Edge Service和开发一个普通的微服务步骤差不多，开发者可以从导入[ServiceComb Edge Service
Demo](https://github.com/apache/incubator-servicecomb-java-chassis/tree/master/demo/demo-edge)入手。从头搭建项目包含如下几个步骤：
-# 二、特性
+* 配置依赖关系
-## 1.部署、启动无耦合
+在项目中加入edge-core的依赖，就可以启动Edge Service的功能。Edge
Service在请求转发的时候，会经过处理链，因此还可以加入相关的处理链的模块的依赖，下面的实例增加的负载均衡的处理链，这个是必须的。
+```
+<dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>edge-core</artifactId>
+</dependency>
+<dependency>
+ <groupId>org.apache.servicecomb</groupId>
+ <artifactId>handler-loadbalance</artifactId>
+</dependency>
+```
-Edge Service与转发目标微服务之间，没有部署、启动顺序上的要求，仅仅只要求转发请求时，目标微服务已经部署，并且已经启动。
+* 定义启动类
-## 2.自动根据能力集合进行路由
+和开发普通微服务一样，可以通过加载Spring的方式将服务拉起来。
+```
+public class EdgeMain {
+ public static void main(String[] args) throws Exception {
+ Log4jUtils.init();
+ BeanUtils.init();
+ }
+}
+```
-假设某微服务，兼容规划为所有高版本必须兼容低版本，部署了以下版本实例：
+* 增加配置文件microservie.yaml
+
+Edge
Service本身也是一个微服务，遵循微服务查找的规则，自己也会进行注册。注意APPLICAIONT_ID与需要转发的微服务相同。在下面的配置中，指定了Edge
Service监听的地址，处理链等信息。其中auth处理链是DEMO项目中自定义的处理链，用于实现认证。同时auth服务本身，不经过这个处理链，相当于不鉴权。
+```
+APPLICATION_ID: edge
+service_description:
+ name: edge
+ version: 0.0.1
+servicecomb:
+ service:
+ registry:
+ address: http://127.0.0.1:30100
+ rest:
+ address: 127.0.0.1:18080
+ handler:
+ chain:
+ Consumer:
+ default: auth,loadbalance
+ service:
+ auth: loadbalance
+```
+
+## 工作流程
+Edge Service的工作流程如下，蓝色背景部分在Eventloop线程中执行，黄色背景部分：
+ * 如果工作于reactive模式，则直接在Eventloop线程执行
+ * 如果工作于线程池模式，则在线程池的线程中执行
+
+
+## 定制路由规则
+使用Edge Service的核心工作是配置路由规则。场景不同，规则也不同。
+路由规则由一系列AbstractEdgeDispatcher组成。Edge
Service提供了几个常见的Dispatcher，通过配置即可启用，如果这些Dispatcher不满足业务场景需要，还可以自定义。
+
+### 使用DefaultEdgeDispatcher
+DefaultEdgeDispatcher是一个非常简单、容易管理的Dispatcher，使用这个Dispatcher，用户不用动态管理转发规则，应用于实际的业务场景非常方便，这个也是推荐的一种管理机制。它包含如下几个配置项：
+```
+servicecomb:
+ http:
+ dispatcher:
+ edge:
+ default:
+ enabled: true
+ prefix: rest
+ withVersion: true
+ pathIndex: 2
+```
+
+常见的这些配置项的示例及含义如下:
+* [prefix=rest;withVersion=true;pathIndex=2]微服务xService提供的URL为:
/xService/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求只转发到[1.0.0-2.0.0)版本的微服务实例。
+* [prefix=rest;withVersion=true;pathIndex=3]微服务xService提供的URL为:
/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求只转发到[1.0.0-2.0.0)版本的微服务实例。
+* [prefix=rest;withVersion=true;pathIndex=4]微服务xService提供的URL为:
/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求只转发到[1.0.0-2.0.0)版本的微服务实例。
+* [prefix=rest;withVersion=false;pathIndex=2]微服务xService提供的URL为:
/xService/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求可能转发到任意微服务实例。
+* [prefix=rest;withVersion=false;pathIndex=3]微服务xService提供的URL为:
/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，，请求可能转发到任意微服务实例。
+* [prefix=rest;withVersion=false;pathIndex=3]微服务xService提供的URL为:
/abc，通过Edge访问的地址为/rest/xService/abc，，请求可能转发到任意微服务实例。
+
+withVersion配置项提供了客户端灰度规则，可以让客户端指定访问的服务端版本。Edge
Service还包含根据接口兼容性自动路由的功能，请求会转发到包含了该接口的实例。假设某微服务，兼容规划为所有高版本必须兼容低版本，部署了以下版本实例：
* 1.0.0，提供了operation1
@@ -26,17 +99,26 @@ Edge Service在转发operation2时，会自动使用1.1.0+的规则来过滤实
以上过程用户不必做任何干预，全自动完成，以避免将新版本的operation转发到旧版本的实例中去。
-## 3.治理
+### 自定义Dispatcher
+
+自定义Dispatcher包含两个步骤：
+
+1. 实现AbstractEdgeDispatcher
+2.
通过SPI发布：增加文件META-INF/services/org.apache.servicecomb.transport.rest.vertx.VertxHttpDispatcher，并写入实现类
+
+详细的代码细节可以参考下面的章节"DEMO功能说明"。开发者也可以参考DefaultEdgeDispatcher等代码来定义自己的Dispatcher。
-路由转发基于ServiceComb sdk，是标准的ServiceComb consumer机制，自动支持所有consumer端的治理功能。
+### 进行认证鉴权和其他业务处理
-# 三、部署示例
+通过Edge Servie工作流程可以看出，可以通过多种方式来扩展Edge
Service的功能，包括Dispatcher、HttpServerFilter、Handler、HttpClientFilter等。比较常用和简单的是通过Handler来扩展。DEMO里面展示了如何通过Handler扩展来实现鉴权。详细的代码细节可以参考下面的章节"DEMO功能说明"。
+
+## 部署示例
-# 四、工作模式
+## 工作模式
-## 1.reactive \(默认\)
+### reactive \(默认\)
Edge Service默认工作于高性能的reactive模式，此模式要求工作于Edge Service转发流程中的业务代码不能有任何的阻塞操作，包括不限于：
@@ -52,7 +134,7 @@ Edge Service的底层是基于netty的vertx，以上约束即是netty的reactive
-## 2.线程池
+### 线程池
如果业务模型无法满足reactive要求，则需要使用线程池模式。
@@ -68,19 +150,7 @@ servicecomb:
-## 五、调用流程
-
-蓝色背景部分在Eventloop线程中执行
-
-黄色背景部分：
-
-* 如果工作于reactive模式，则直接在Eventloop线程执行
-
-* 如果工作于线程池模式，则在线程池的线程中执行
-
-
-
-## 六、开发手册
+## DEMO功能说明
请参考github上的edge service demo：
@@ -98,7 +168,7 @@ servicecomb:
通过edge-service访问微服务business的不同版本，并确认是由正确的实例处理的。
-## 1.注册Dispatcher
+### 1.注册Dispatcher
实现接口org.apache.servicecomb.transport.rest.vertx.VertxHttpDispatcher，或从org.apache.servicecomb.edge.core.AbstractEdgeDispatcher继承，实现自己的dispatcher功能。
@@ -132,7 +202,7 @@ _假设Dispatcher A和B都可以处理同一个url，并且A优先级更高，
* _如果A处理完，然后调用了RoutingContext.next\(\)，则会将请求转移给B处理_
-## 2.转发请求
+### 2.转发请求
注册路由时，指定了使用哪个方法来处理请求（下面使用onRequest来指代该方法），在onRequest中实现转发逻辑。
@@ -162,7 +232,7 @@ edgeInvoke调用内部，会作为ServiceComb标准consumer去转发调用。
作为标准consumer，意味着ServiceComb所有标准的治理能力在这里都是生效的。
-## 3.设置兼容规则
+### 3.设置兼容规则
不同的业务可能有不同的兼容规划，servicecomb默认的兼容规则，要求所有新版本兼容旧版本。如果满足这个要求，则不必做任何特殊的设置。
@@ -192,7 +262,7 @@ versionMapper的作用是将v1或是v2这样的串，转为1.0.0-2.0.0或2.0.0-3
接口不兼容会导致非常多的问题。java
chassis要求高版本服务兼容低版本服务，只允许增加接口不允许删除接口。在增加接口后，必须增加微服务的版本号。在开发阶段，接口变更频繁，开发者往往忘记这个规则。当这个约束被打破的时候，需要清理服务中心微服务的信息，并重启微服务和Edge
Service\(以及依赖于该微服务的其他服务\)。否则可能出现请求转发失败等情况。
-## 4.鉴权
+### 4.鉴权
Edge Service是系统的边界，对于很多请求需要执行鉴权逻辑。
diff --git a/java-chassis-reference/zh_CN/edge/edge-service.md
b/java-chassis-reference/zh_CN/edge/edge-service.md
deleted file mode 100644
index e69de29..0000000
diff --git a/java-chassis-reference/zh_CN/edge/nginx.md
b/java-chassis-reference/zh_CN/edge/nginx.md
index 4ec95e7..2f0d633 100644
--- a/java-chassis-reference/zh_CN/edge/nginx.md
+++ b/java-chassis-reference/zh_CN/edge/nginx.md
@@ -1,3 +1,5 @@
+# 使用confd和Nginx做边缘服务
+
## 概念阐述
### **confd**
diff --git a/java-chassis-reference/zh_CN/edge/open-service.md
b/java-chassis-reference/zh_CN/edge/open-service.md
new file mode 100644
index 0000000..e406c8c
--- /dev/null
+++ b/java-chassis-reference/zh_CN/edge/open-service.md
@@ -0,0 +1,5 @@
+# 服务能力开放
+
+大量的微服务能力需要通过网关开放给用户、其他外部系统访问。网关一方面扮演着汇集用户请求的作用，同时还会扮演认证、鉴权、流量控制、防攻击的用途。同时，由于网关是一个汇聚点，容易形成业务的瓶颈，通常还会采用多级网关机制，最外层的网关提供主备以及简单的请求转发功能，中间层的实现鉴权等功能，多实例部署。常见的可以用于网关的技术和服务包括LVS、Nginx、Zuul等。
+
+ServiceComb 也提供了自己的网关服务Edge Service。Edge
Service内建了强大的路由策略，支持接口级别的兼容性转发（灰度发布），内嵌ServiceComb治理能力，并支持非常灵活的扩展机制。
diff --git a/java-chassis-reference/zh_CN/edge/zuul.md
b/java-chassis-reference/zh_CN/edge/zuul.md
index 6a89957..8b52a06 100644
--- a/java-chassis-reference/zh_CN/edge/zuul.md
+++ b/java-chassis-reference/zh_CN/edge/zuul.md
@@ -1,3 +1,5 @@
+# 使用zuul做边缘服务
+
## 概念阐述
### API Gateway：
@@ -89,8 +91,6 @@ servicecomb:
address: 0.0.0.0:8082 #微服务端口，可不写
```
-本小节所有服务使用的都是本地的服务中心，具体的服务中心启动流程请参考[启动本地服务中心](#li2337491491436)
-
* **步骤 5 **Run ZuulMain Application
## 使用Zuul Proxy
diff --git a/java-chassis-reference/zh_CN/edge/secret-field.md
b/java-chassis-reference/zh_CN/general-development/secret-field.md
similarity index 100%
rename from java-chassis-reference/zh_CN/edge/secret-field.md
rename to java-chassis-reference/zh_CN/general-development/secret-field.md
--
To stop receiving notification emails like this one, please contact
liu...@apache.org.
