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 b03458d use new theme (#283)
b03458d is described below
commit b03458d1563e1fa3312a41f7eb41bd9b171fc0af
Author: liubao68 <[email protected]>
AuthorDate: Tue Jan 3 18:51:35 2023 +0800
use new theme (#283)
---
java-chassis-reference/README.md | 14 +++---
.../en_US/docs/edge/by-servicecomb-sdk.md | 26 ++++++-----
.../docs/general-development/produceprocess.md | 7 +--
java-chassis-reference/en_US/docs/index.md | 16 ++++---
java-chassis-reference/en_US/mkdocs.yml | 7 ++-
.../zh_CN/docs/edge/by-servicecomb-sdk.md | 52 +++++++++++-----------
.../docs/general-development/produceprocess.md | 7 +--
java-chassis-reference/zh_CN/mkdocs.yml | 4 +-
8 files changed, 71 insertions(+), 62 deletions(-)
diff --git a/java-chassis-reference/README.md b/java-chassis-reference/README.md
index 4274708..c623b8f 100644
--- a/java-chassis-reference/README.md
+++ b/java-chassis-reference/README.md
@@ -4,18 +4,20 @@
* [访问地址][publish_site_cn]
* 发布/查看
- 1. 参考[MkDocs安装指南](https://www.mkdocs.org/#installation),安装MkDocs
- 2. 发布： mkdocs build -d ../docs
- 3. 本地查看：mkdocs serve
+ * 参考[MkDocs安装指南](https://www.mkdocs.org/#installation), 安装 Python、Pip、MkDocs
+ * 安装主题: pip install mkdocs-material
+ * 发布： mkdocs build -d ../docs
+ * 本地查看：mkdocs serve
## This project is the servicecomb-java-chassis developers guide
* [Web address][publish_site_en]
* Publish
- 1. see [MkDocs installation guide](https://www.mkdocs.org/#installation)
- 2. publish using command：mkdocs build -d ../docs
- 3. for local reading：mkdocs serve
+ * see [MkDocs installation guide](https://www.mkdocs.org/#installation),
install Python, Pip, MkDocs
+ * install theme: pip install mkdocs-material
+ * publish using command: mkdocs build -d ../docs
+ * for local reading: mkdocs serve
[publish_site_cn]:
https://servicecomb.apache.org/references/java-chassis/zh_CN/
[publish_site_en]:
https://servicecomb.apache.org/references/java-chassis/en_US/
diff --git a/java-chassis-reference/en_US/docs/edge/by-servicecomb-sdk.md
b/java-chassis-reference/en_US/docs/edge/by-servicecomb-sdk.md
index 30ebcae..dec247c 100644
--- a/java-chassis-reference/en_US/docs/edge/by-servicecomb-sdk.md
+++ b/java-chassis-reference/en_US/docs/edge/by-servicecomb-sdk.md
@@ -64,7 +64,8 @@ The workflow of the Edge Service is as follows, the blue
background part is exec
The core job of using the Edge Service is to configure routing rules. The
rules are different, and the rules are different.
A routing rule consists of a series of AbstractEdgeDispatchers. The Edge
Service provides several common Dispatchers that can be enabled through
configuration. If these Dispatchers do not meet the needs of the business
scenario, they can be customized.
-### Using DefaultEdgeDispatcher
+* Using DefaultEdgeDispatcher
+
DefaultEdgeDispatcher is a very simple and easy to manage Dispatcher. With
this Dispatcher, users do not need to manage forwarding rules dynamically. It
is very convenient to apply to actual business scenarios. This is also a
recommended management mechanism. It contains the following configuration items:
```
servicecomb:
@@ -98,7 +99,8 @@ When Edge Service forwards operation2, it automatically uses
the rules of 1.1.0+
The above process does not require any intervention and is fully automated to
avoid forwarding the new version of the operation to the instance of the old
version.
-### Using URLMappedEdgeDispatcher
+* Using URLMappedEdgeDispatcher
+
URLMappedEdgeDispatcher allows users to configure mappings between URLs and
microservices. It is very flexible to define which URLs are forwarded to which
microservices. It contains the following configuration items:
```
servicecomb:
@@ -124,7 +126,7 @@ The meaning of the businessV1 configuration item is that
the request with the re
As can be seen from the above configuration, URLMappedEdgeDispatcher also
supports client grayscale. Of course, there will be more configuration items
than DefaultEdgeDispatcher. The URLMappedEdgeDispatcher supports dynamic
configuration modification of the configuration center to adjust routing rules.
-### Custom Dispatcher
+* Custom Dispatcher
Customizing the Dispatcher involves two steps:
@@ -133,7 +135,7 @@ Customizing the Dispatcher involves two steps:
Detailed code details can be found in the following section "DEMO Functional
Description". Developers can also refer to the Code such as
DefaultEdgeDispatcher to define their Dispatcher.
-### Perform authentication and other business processing
+* Perform authentication and other business processing
Through the Edge Service workflow, you can see that the Edge Service features
can be extended in a variety of ways, including Dispatcher, HttpServerFilter,
Handler, HttpClientFilter, and more. More common and straightforward is to
extend through Handler. DEMO shows how to implement authentication through
Handler extensions. Detailed code details can be found in the following section
"DEMO Functional Description".<Paste>
@@ -143,7 +145,7 @@ Through the Edge Service workflow, you can see that the
Edge Service features ca
## Operating mode
-###reactive \(default\)
+* reactive \(default\)
The Edge Service works by default in the high-performance reactive mode. This
mode requires that the business code working in the Edge Service forwarding
process cannot have any blocking operations, including:
@@ -159,7 +161,7 @@ The underlying Edge Service is based on netty's vertx. The
above constraint is n
-### Thread Pool
+* Thread Pool
If the business model cannot meet the reactive requirements, you need to use
the thread pool mode.
@@ -193,7 +195,7 @@ The demo contains the following projects:
Access different versions of microservices through edge-service and confirm
that the correct instance handles them.
-### 1.Register Dispatcher
+* Register Dispatcher
Implement the interface
org.apache.servicecomb.transport.rest.vertx.VertxHttpDispatcher, or inherit
from org.apache.servicecomb.edge.core.AbstractEdgeDispatcher to implement your
own dispatcher function.
@@ -201,7 +203,7 @@ The implementation class is registered to the system
through the Java standard S
Dispatcher needs to implement 2 methods:
-* ### getOrder
+* getOrder
Dispatcher needs to inject routing rules into vertx, and routing rules have a
priority order relationship.
@@ -209,7 +211,7 @@ All Dispatchers in the system are sorted according to the
return value of getOrd
If the GetOrder return values the two Dispatchers are the same, the order of
the two is unpredictable.
-* ### init
+* init
The init method is included in the io.vertx.ext.web.The router in the vertx
framework. You need to customize the routing rules through this object.
@@ -227,7 +229,7 @@ _Assuming Dispatcher A and B can both handle the same url,
and A has a higher pr
* _ If A is processed and then calling RoutingContext.next\(\), the request
will be transferred to B.
-### 2. Forwarding request
+* Forwarding request
When registering a route, it specifies which method is used to process the
request (the following method is used to refer to the method), and the
forwarding logic is implemented in the onRequest.
@@ -257,7 +259,7 @@ The edgeInvoke call is internally called and will be
forwarded as a ServiceComb
As a standard consumer, it means that the governance capabilities of all
ServiceComb standards are valid here.
-### 3. Setting compatibility rules
+* Setting compatibility rules
Different services may have different compatibility plans, servicecomb default
compatibility rules, and all new versions are required to be compatible with
the old version. If this requirement is met, no special settings need to be
made.
@@ -287,7 +289,7 @@ The role of versionMapper is to convert a string such as v1
or v2 to a compatibi
Incompatible interfaces can cause many problems. The java chassis requires
that the higher version of the service is compatible with the lower version of
the service, and only allows the addition of the interface to not allow the
interface to be deleted. After adding an interface, you must increase the
version number of the microservice. In the development phase, interfaces change
frequently, and developers often forget this rule. When this constraint is
broken, you need to clean up the [...]
-### 4.Authentication
+* Authentication
The Edge Service is the boundary of the system and requires authentication
logic for many requests.
diff --git
a/java-chassis-reference/en_US/docs/general-development/produceprocess.md
b/java-chassis-reference/en_US/docs/general-development/produceprocess.md
index f64077d..89d8f78 100644
--- a/java-chassis-reference/en_US/docs/general-development/produceprocess.md
+++ b/java-chassis-reference/en_US/docs/general-development/produceprocess.md
@@ -1,11 +1,12 @@
# return value serialization extension
+
## Concept Description
The current REST channel return value supports both application/json and
text/plain formats, supports developer extensions and rewrites, service
providers provide serialization capabilities through producer declarations, and
service consumers specify return value serialization through the request's
Accept header. By default, the data in application/json format is returned.
## Development Instructions
-* ### extension
+* extension
Developers can extend the return value serialization method programmatically
based on business needs. The implementation steps are as follows, taking the
extended support application/xml format as an example:
@@ -48,7 +49,7 @@ The current REST channel return value supports both
application/json and text/pl
In the META-INF/services/ folder under resources, create a new file
xxx.ProduceProcessor (xxx is the package name of the interface), and fill in
the content xxx.ProduceAppXmlProcessor (xxx is the package name of the
implementation class).
-* ### Rewrite
+* Rewrite
Developers can rewrite the existing application/json and text/plain
implementation logic, or rewrite the self-extended format to rewrite the xml
serialization method as an example:
@@ -60,7 +61,7 @@ The current REST channel return value supports both
application/json and text/pl
4. In the META-INF/services/ folder under resources, create a new file
xxx.ProduceProcessor (xxx is the package name of the interface), and fill in
the content xxx.ProduceAppXmlProcessor (xxx is the package name of the
implementation class).
-* ### verification
+* verification
Service providers provide xml serialization capabilities through producer
declarations
diff --git a/java-chassis-reference/en_US/docs/index.md
b/java-chassis-reference/en_US/docs/index.md
index d0b94b6..8f20f50 100644
--- a/java-chassis-reference/en_US/docs/index.md
+++ b/java-chassis-reference/en_US/docs/index.md
@@ -7,13 +7,15 @@ Apache ServiceComb Java Chassis provides developers with a
Java SDK to quickly b
For other versions, please check the following table.
-| version | link | notes |
-|:--------| :--- | :--- |
-| 2.8.x | [中文][apache.zh_CN], [English][apache.en_US] | |
-| 2.8.x | [中文][gitee.zh_CN], [English][gitee.en_US] | hosted by gitee pages |
+| version | link | notes |
+|:------| :--- |:-----------|
+| 3.x.x | [中文][apache.zh_CN], [English][apache.en_US] | Developing |
+| 2.8.x | [中文][apache.zh_CN.2.8.x], [English][apache.en_US.2.8.x] |
|
+| 1.3.x | [中文][apache.zh_CN.1.3.x], [English][apache.en_US.1.3.x] |
|
[apache.zh_CN]: https://servicecomb.apache.org/references/java-chassis/zh_CN/
[apache.en_US]: https://servicecomb.apache.org/references/java-chassis/en_US/
-[gitee.zh_CN]:
https://servicecomb.gitee.io/servicecomb-java-chassis-doc/java-chassis/zh_CN/
-[gitee.en_US]:
https://servicecomb.gitee.io/servicecomb-java-chassis-doc/java-chassis/en_US/
-
+[apache.zh_CN.2.8.x]:
https://servicecomb.apache.org/references/java-chassis/2.x/zh_CN/
+[apache.en_US.2.8.x]:
https://servicecomb.apache.org/references/java-chassis/2.x/en_US/
+[apache.zh_CN.1.3.x]:
https://servicecomb.apache.org/references/java-chassis/1.x/zh_CN/
+[apache.en_US.1.3.x]:
https://servicecomb.apache.org/references/java-chassis/1.x/en_US/
diff --git a/java-chassis-reference/en_US/mkdocs.yml
b/java-chassis-reference/en_US/mkdocs.yml
index 7a14320..c4796b0 100644
--- a/java-chassis-reference/en_US/mkdocs.yml
+++ b/java-chassis-reference/en_US/mkdocs.yml
@@ -93,7 +93,6 @@ nav:
- 'FAQ' : question-and-answer/faq.md
- Micro Service Interface Compatibility FAQ:
question-and-answer/interface-compatibility.md
-theme: readthedocs
-plugins:
- - search:
- lang: en
\ No newline at end of file
+theme: material
+plugins:
+ - search
diff --git a/java-chassis-reference/zh_CN/docs/edge/by-servicecomb-sdk.md
b/java-chassis-reference/zh_CN/docs/edge/by-servicecomb-sdk.md
index 0e0175a..f30eda4 100644
--- a/java-chassis-reference/zh_CN/docs/edge/by-servicecomb-sdk.md
+++ b/java-chassis-reference/zh_CN/docs/edge/by-servicecomb-sdk.md
@@ -90,7 +90,8 @@ servicecomb:
使用Edge Service的核心工作是配置路由规则。场景不同，规则也不同。
路由规则由一系列AbstractEdgeDispatcher组成。Edge
Service提供了几个常见的Dispatcher，通过配置即可启用，如果这些Dispatcher不满足业务场景需要，还可以自定义。
-### 使用 DefaultEdgeDispatcher
+* 使用 DefaultEdgeDispatcher
+
DefaultEdgeDispatcher是一个非常简单、容易管理的Dispatcher，使用这个Dispatcher，用户不用动态管理转发规则，应用于实际的业务场景非常方便，这个也是推荐的一种管理机制。它包含如下几个配置项：
```
servicecomb:
@@ -106,18 +107,18 @@ servicecomb:
常见的这些配置项的示例及含义如下:
-* [prefix=rest;withVersion=true;prefixSegmentCount=1]微服务xService提供的URL为:
/xService/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求只转发到[1.0.0-2.0.0)版本的微服务实例。
-* [prefix=rest;withVersion=true;prefixSegmentCount=2]微服务xService提供的URL为:
/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求只转发到[1.0.0-2.0.0)版本的微服务实例。
-* [prefix=rest;withVersion=true;prefixSegmentCount=3]微服务xService提供的URL为:
/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求只转发到[1.0.0-2.0.0)版本的微服务实例。
-* [prefix=rest;withVersion=false;prefixSegmentCount=1]微服务xService提供的URL为:
/xService/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求可能转发到任意微服务实例。
-* [prefix=rest;withVersion=false;prefixSegmentCount=2]微服务xService提供的URL为:
/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，，请求可能转发到任意微服务实例。
-* [prefix=rest;withVersion=false;prefixSegmentCount=2]微服务xService提供的URL为:
/abc，通过Edge访问的地址为/rest/xService/abc，，请求可能转发到任意微服务实例。
+ * [prefix=rest;withVersion=true;prefixSegmentCount=1]微服务xService提供的URL为:
/xService/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求只转发到[1.0.0-2.0.0)版本的微服务实例。
+ * [prefix=rest;withVersion=true;prefixSegmentCount=2]微服务xService提供的URL为:
/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求只转发到[1.0.0-2.0.0)版本的微服务实例。
+ * [prefix=rest;withVersion=true;prefixSegmentCount=3]微服务xService提供的URL为:
/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求只转发到[1.0.0-2.0.0)版本的微服务实例。
+ * [prefix=rest;withVersion=false;prefixSegmentCount=1]微服务xService提供的URL为:
/xService/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，请求可能转发到任意微服务实例。
+ * [prefix=rest;withVersion=false;prefixSegmentCount=2]微服务xService提供的URL为:
/v1/abc，通过Edge访问的地址为/rest/xService/v1/abc，，请求可能转发到任意微服务实例。
+ * [prefix=rest;withVersion=false;prefixSegmentCount=2]微服务xService提供的URL为:
/abc，通过Edge访问的地址为/rest/xService/abc，，请求可能转发到任意微服务实例。
withVersion配置项提供了客户端灰度规则，可以让客户端指定访问的服务端版本。Edge
Service还包含根据接口兼容性自动路由的功能，请求会转发到包含了该接口的实例。假设某微服务，兼容规划为所有高版本必须兼容低版本，部署了以下版本实例：
-* 1.0.0，提供了operation1
+ * 1.0.0，提供了operation1
-* 1.1.0，提供了operation1、operation2
+ * 1.1.0，提供了operation1、operation2
Edge Service在转发operation1时，会自动使用1.0.0+的规则来过滤实例
@@ -125,7 +126,8 @@ Edge Service在转发operation2时，会自动使用1.1.0+的规则来过滤实
以上过程用户不必做任何干预，全自动完成，以避免将新版本的operation转发到旧版本的实例中去。
-### 使用 URLMappedEdgeDispatcher
+* 使用 URLMappedEdgeDispatcher
+
URLMappedEdgeDispatcher
允许用户配置URL和微服务的映射关系。使用它可以非常灵活的定义哪些URL转发到哪些微服务。它包含如下几个配置项：
```yaml
@@ -154,7 +156,7 @@ servicecomb:
从上面的配置可以看出，URLMappedEdgeDispatcher也支持客户端灰度。当然配置项会比DefaultEdgeDispatcher多。URLMappedEdgeDispatcher支持通过配置中心动态的修改配置，调整路由规则。
-### 使用 CommonHttpEdgeDispatcher
+* 使用 CommonHttpEdgeDispatcher
CommonHttpEdgeDispatcher 能够将请求转发到监听 HTTP 或者 HTTP 2 协议的 Provider， 对于 Provider
的开发框架没有限制，也不
要求 Provider 注册契约信息。
@@ -178,7 +180,7 @@ servicecomb:
CommonHttpEdgeDispatcher 配置项的含义和 URLMappedEdgeDispatcher 类似。
-### 自定义 Dispatcher
+* 自定义 Dispatcher
自定义Dispatcher包含两个步骤：
@@ -187,7 +189,7 @@ CommonHttpEdgeDispatcher 配置项的含义和 URLMappedEdgeDispatcher 类似。
详细的代码细节可以参考下面的章节"DEMO功能说明"。开发者也可以参考DefaultEdgeDispatcher等代码来定义自己的Dispatcher。
-### 进行认证鉴权和其他业务处理
+* 进行认证鉴权和其他业务处理
通过Edge Servie工作流程可以看出，可以通过多种方式来扩展Edge
Service的功能，包括Dispatcher、HttpServerFilter、Handler、HttpClientFilter等。比较常用和简单的是通过Handler来扩展。DEMO里面展示了如何通过Handler扩展来实现鉴权。详细的代码细节可以参考下面的章节"DEMO功能说明"。
@@ -197,23 +199,23 @@ CommonHttpEdgeDispatcher 配置项的含义和 URLMappedEdgeDispatcher
类似。
## 工作模式
-### reactive \(默认\)
+* reactive \(默认\)
Edge Service默认工作于高性能的reactive模式，此模式要求工作于Edge Service转发流程中的业务代码不能有任何的阻塞操作，包括不限于：
-* 远程同步调用，比如同步查询数据库、同步调用微服务，或是同步查询远程缓存等等
+ * 远程同步调用，比如同步查询数据库、同步调用微服务，或是同步查询远程缓存等等
-* 任何的sleep调用
+ * 任何的sleep调用
-* 任何的wait调用
+ * 任何的wait调用
-* 超大的循环
+ * 超大的循环
Edge Service的底层是基于netty的vertx，以上约束即是netty的reactive模式约束。
-### 线程池
+* 线程池
如果业务模型无法满足reactive要求，则需要使用线程池模式。
@@ -233,7 +235,7 @@ servicecomb:
DEMO 源码请参考 [edge service
demo](https://github.com/apache/servicecomb-java-chassis/tree/master/demo/demo-edge)
-### 1.注册Dispatcher
+* 注册Dispatcher
实现接口org.apache.servicecomb.transport.rest.vertx.VertxHttpDispatcher，或从
org.apache.servicecomb.edge.core.AbstractEdgeDispatcher继承，实现自己的dispatcher功能。
@@ -242,7 +244,7 @@
org.apache.servicecomb.edge.core.AbstractEdgeDispatcher继承，实现自己的d
Dispatcher需要实现2个方法：
-* ### getOrder
+* getOrder
Dispatcher需要向vertx注入路由规则，路由规则之间是有优先级顺序关系的。
@@ -250,7 +252,7 @@ Dispatcher需要向vertx注入路由规则，路由规则之间是有优先级
如果2个Dispatcher的getOrder返回值相同，则2者的顺序不可预知。
-* ### init
+* init
init方法入参为vertx框架中的io.vertx.ext.web.Router，需要通过该对象实现路由规则的定制。
@@ -268,7 +270,7 @@ _假设Dispatcher A和B都可以处理同一个url，并且A优先级更高，
* _如果A处理完，然后调用了RoutingContext.next\(\)，则会将请求转移给B处理_
-### 2.转发请求
+* 转发请求
注册路由时，指定了使用哪个方法来处理请求（下面使用onRequest来指代该方法），在onRequest中实现转发逻辑。
@@ -298,7 +300,7 @@ edgeInvoke调用内部，会作为ServiceComb标准consumer去转发调用。
作为标准consumer，意味着ServiceComb所有标准的治理能力在这里都是生效的。
-### 3.设置兼容规则
+* 设置兼容规则
不同的业务可能有不同的兼容规划，servicecomb默认的兼容规则，要求所有新版本兼容旧版本。如果满足这个要求，则不必做任何特殊的设置。
@@ -325,7 +327,7 @@
edgeInvocation.setVersionRule(versionMapper.getOrCreate(pathVersion).getVersionR
versionMapper的作用是将v1或是v2这样的串，转为1.0.0-2.0.0或2.0.0-3.0.0这样的兼容规则。
-### 4.鉴权
+* 鉴权
Edge Service是系统的边界，对于很多请求需要执行鉴权逻辑。
diff --git
a/java-chassis-reference/zh_CN/docs/general-development/produceprocess.md
b/java-chassis-reference/zh_CN/docs/general-development/produceprocess.md
index 6e204f0..f6d112e 100644
--- a/java-chassis-reference/zh_CN/docs/general-development/produceprocess.md
+++ b/java-chassis-reference/zh_CN/docs/general-development/produceprocess.md
@@ -1,11 +1,12 @@
# 返回值序列化扩展
+
## 概念阐述
当前REST通道返回值支持application/json和text/plain两种格式，支持开发人员扩展和重写，服务提供者通过produces声明可提供序列化能力，服务消费者通过请求的Accept头指明返回值序列化方式，默认返回application/json格式的数据。
## 开发说明
-* ### 扩展
+* 扩展
开发人员可以根据业务需要，通过编程的方式来扩展返回值序列化方式。实施步骤如下，以扩展支持application/xml格式为例：
@@ -48,7 +49,7 @@
在resources下META-INF/services/文件夹新建文件xxx.ProduceProcessor（xxx为接口的包名），内容填写xxx.ProduceAppXmlProcessor（xxx为实现类的包名）。
-* ### 重写
+* 重写
开发人员可以对现有的application/json和text/plain两种格式实现逻辑进行重写，也可以对自行扩展的格式进行重写，以重写xml序列化方式为例：
@@ -60,7 +61,7 @@
4.在resources下META-INF/services/文件夹新建文件xxx.ProduceProcessor（xxx为接口的包名），内容填写xxx.ProduceAppXmlProcessor（xxx为实现类的包名）。
-* ### 验证
+* 验证
服务提供者通过produces声明可提供xml序列化能力
diff --git a/java-chassis-reference/zh_CN/mkdocs.yml
b/java-chassis-reference/zh_CN/mkdocs.yml
index 55b7a43..40b0860 100644
--- a/java-chassis-reference/zh_CN/mkdocs.yml
+++ b/java-chassis-reference/zh_CN/mkdocs.yml
@@ -61,6 +61,6 @@ nav:
- 'FAQ' : question-and-answer/faq.md
- 'Q & A' : question-and-answer/question_answer.md
- 微服务接口兼容常见问题: question-and-answer/interface-compatibility.md
-theme: readthedocs
+theme: material
plugins:
- - bingsearch
\ No newline at end of file
+ - search
