增加所有组件的使用文档

README.md

@@ -5,14 +5,16 @@
 [![Build Status](https://github.com/w-sodalite/satex/actions/workflows/rust.yml/badge.svg?branch=master)](https://github.com/w-sodalite/satex/actions/workflows/rust.yml)
 [![Crates.io](https://img.shields.io/crates/v/satex)](https://crates.io/crates/satex)
 
-## 优势
+## 特点
 
 - 纯异步IO实现
 - 丰富的路由组件以及灵活的路由配置
 - 内置服务发现、健康检查以及多种负载均衡策略
 - 完全兼容[tower](https://crates.io/crates/tower)和[tower-http](https://crates.io/crates/tower-http)的生态，包括中间件、服务和工具等。
 
-## 路由结构
+## 路由
+
+### 逻辑结构
 
 - **matcher**：负责接收并解析进入的HTTP请求。通过精确匹配算法，它能快速地识别出请求的目标路径、方法以及其他相关参数。
 
@@ -21,66 +23,78 @@
 
 - **service**：负责处理经过`layer`层筛选的请求。你可以在这一层实现具体的业务逻辑，例如调用后端服务、处理数据等。
 
-## 内置组件
-
-- 路由组件
-
-    - **Matcher**
-        * `Method`：根据请求方法（如GET、POST等）进行匹配。
-        * `Query`：根据请求的查询参数进行匹配。
-        * `Header`：根据请求头信息进行匹配。
-        * `Host`：根据请求的主机名进行匹配。
-        * `Path`：根据请求路径进行匹配，使用[`path-tree`](https://docs.rs/path-tree)进行处理，支持变量绑定。
-        * `RemoteAddr`：根据客户端的IP地址进行匹配。
-        * `Cookie`: 根据请求的Cookie进行匹配。
-        * `Time`：根据请求时间进行匹配。
-
-    - **Layer**
-        * `Cors`：处理跨域请求。
-        * `KeepHostHeader`：保持原始的Host请求头。
-        * `PathStrip`：从请求路径中删除或替换特定部分。
-        * `RateLimit`：限制来自单个IP的请求频率。
-        * `SetHeader`：设置请求头和响应头信息。
-        * `ConcurrentcyLimit`：限制同时处理的请求数量。
-        * `RequestBodyLimit`：限制请求体的最大大小。
-        * `SetStatus`：设置响应状态码。
-        * `RewritePath`: 重写请求的接口地址，支持使用`Path`匹配路由绑定的变量。
-
-    - **Service**
-        * `Echo`：简单地返回接收到的请求内容。
-        * `Static`：提供静态文件服务。
-        * `Proxy`：反向代理服务，代理请求到另一个服务或地址。
-
-
-- 反向代理支持
-
-    - 服务发现(Discovery)
-        * `Builtin`：内置的服务发现，通过配置的方式注册服务集合，内部会定时检测服务节点的可用性。
-
-    - 负载均衡(LoadBalance)
-        * `IpHash`：IP哈希负载策略使用客户端的IP地址进行哈希计算，根据哈希值将请求分配给后端服务器。这样可以确保来自同一IP地址的请求始终被发送到同一台服务器，这有助于保持会话和状态信息的持续性。
-        * `Random`：随机负载策略随机选择一台服务器将请求发送过去。这种策略简单且易于实现，适用于没有特殊需求的情况。
-        * `Sequential`：顺序负载策略按照服务器列表的顺序依次将请求发送过去。这种策略适用于服务器性能基本一致的情况。
-        * `StandBy`：备用负载策略在主服务器故障时，将请求切换到备用服务器上。这种策略可以提高系统的可用性和可靠性。
-        * `Weight`：权重负载策略根据服务器的性能或权重值来分配请求。权重值高的服务器将获得更多的请求，而权重值低的服务器将获得较少的请求。这种策略可以帮助平衡服务器的负载，提高系统的性能和效率。
-
-## 配置示例
-
-[examples](./examples)
+### 内置组件
+
+- #### Matcher
+
+  | 名称           | 描述                     |                使用文档                |
+  |:-------------|------------------------|:----------------------------------:|
+  | `Method`     | 根据请求方法（如GET、POST等）进行匹配 |   [文档](docs/matchers/method.md)    |
+  | `Query`      | 根据请求的查询参数进行匹配          |    [文档](docs/matchers/query.md)    |
+  | `Header`     | 根据请求头信息进行匹配            |   [文档](docs/matchers/header.md)    |
+  | `Host`       | 根据请求的主机名进行匹配           |    [文档](docs/matchers/host.md)     |
+  | `Path`       | 根据请求路径进行匹配             |    [文档](docs/matchers/path.md)     |
+  | `RemoteAddr` | 根据客户端的IP地址进行匹配         | [文档](docs/matchers/remote_addr.md) |
+  | `Cookie`     | 根据请求的Cookie进行匹配        |   [文档](docs/matchers/cookie.md)    |
+  | `Time`       | 根据请求时间进行匹配             |    [文档](docs/matchers/time.md)     |
+
+- #### Layer
+
+  | 名称                  | 描述           |                使用文档                |
+  |:--------------------|--------------|:----------------------------------:|
+  | `Cors`              | 处理跨域请求       |     [文档](docs/layers/cors.md)      |
+  | `KeepHostHeader`    | 保持原始的Host请求头 |    [文档](docs/matchers/query.md)    |
+  | `PathStrip`         | 从请求路径中删除特定部分 |   [文档](docs/matchers/header.md)    |
+  | `RateLimit`         | 限制请求频率       |    [文档](docs/matchers/host.md)     |
+  | `RewritePath`       | 重写请求的接口地址    |    [文档](docs/matchers/time.md)     |
+  | `SetRequestHeader`  | 设置请求头信息      |    [文档](docs/matchers/path.md)     |
+  | `SetResponseHeader` | 设置响应头信息      |    [文档](docs/matchers/path.md)     |
+  | `XForward`          | 设置XForward信息 |    [文档](docs/matchers/path.md)     |
+  | `ConcurrentcyLimit` | 限制同时处理的请求数量  | [文档](docs/matchers/remote_addr.md) |
+  | `RequestBodyLimit`  | 限制请求体的最大大小   |   [文档](docs/matchers/cookie.md)    |
+  | `SetStatus`         | 设置响应状态码      |    [文档](docs/matchers/time.md)     |
+
+- #### Service
+
+  | 名称       | 描述                    |             使用文档              |
+  |:---------|-----------------------|:-----------------------------:|
+  | `Echo`   | 简单地返回接收到的请求内容         |  [文档](docs/services/echo.md)  |
+  | `Static` | 提供静态文件服务              | [文档](docs/services/static.md) |
+  | `Proxy`  | 反向代理服务，代理请求到另一个服务或地址。 | [文档](docs/services/proxy.md)  |
+
+- #### Discovery
+
+  | 名称        | 描述                                     |              使用文档               |
+  |:----------|----------------------------------------|:-------------------------------:|
+  | `Builtin` | 内置的服务发现，通过配置的方式注册服务集合，内部会定时检测服务节点的可用性。 | [文档](docs/discovery/builtin.md) |
+
+- #### LoadBalance
+
+  | 名称           | 描述                                                                                         |                 使用文档                  |
+  |:-------------|--------------------------------------------------------------------------------------------|:-------------------------------------:|
+  | `IpHash`     | IP哈希负载策略使用客户端的IP地址进行哈希计算，根据哈希值将请求分配给后端服务器。这样可以确保来自同一IP地址的请求始终被发送到同一台服务器，这有助于保持会话和状态信息的持续性。 |  [文档](docs/load_balance/ip_hash.md)   |
+  | `Random`     | 随机负载策略随机选择一台服务器将请求发送过去。这种策略简单且易于实现，适用于没有特殊需求的情况。                                           |   [文档](docs/load_balance/random.md)   |
+  | `Sequential` | 顺序负载策略按照服务器列表的顺序依次将请求发送过去。这种策略适用于服务器性能基本一致的情况。                                             | [文档](docs/load_balance/sequential.md) |
+  | `StandBy`    | 备用负载策略在主服务器故障时，将请求切换到备用服务器上。这种策略可以提高系统的可用性和可靠性。                                            |  [文档](docs/load_balance/stand_by.md)  |
+  | `Weight`     | 权重负载策略根据服务器的性能或权重值来分配请求。权重值高的服务器将获得更多的请求，而权重值低的服务器将获得较少的请求。这种策略可以帮助平衡服务器的负载，提高系统的性能和效率。    |   [文档](docs/load_balance/weight.md)   |
+
+## 配置文件
+
+应用启动配置文件为`satex.yaml`，具体内容见[示例配置](examples/satex.yaml)。
 
 ## 构建和启动
 
-- ### 构建
+- ### 1.构建
 
     - 安装`RUST`环境，按照[官方文档](https://www.rust-lang.org/zh-CN/learn/get-started)初始化环境。
-        >  国内可以使用[rsproxy](https://rsproxy.cn/#getStarted)镜像加速下载。
+      > 国内可以使用[rsproxy](https://rsproxy.cn/#getStarted)镜像加速下载。
 
     - 使用`cargo`安装，执行命令：`cargo install satex`即可安装最新版本的`satex`。
 
     - 或者使用源码进行构建，下载源码到本地，在根目录执行`cargo build --release`，编译成功后在`target/release`
       目录下可以找到`satex`。
 
-- ### 启动
+- ### 2.启动
 
   > 使用`-c`指定配置文件`satex.yaml`的路径
 

docs/discovery/builtin.md

@@ -0,0 +1,35 @@
+# Builtin
+
+> 内置的服务发现，通过配置的方式注册服务集合，内部会定时检测服务节点的健康状态。
+
+## 参数
+
+| 参数           |   类型    | 是否必须 | 默认值 | 描述                  |
+|:-------------|:-------:|:----:|:---:|:--------------------|
+| server       |  `str`  | `Y`  |     | 服务名称                |
+| uris         | `[str]` | `Y`  |     | 服务节点列表              |
+| interval     |  `u32`  | `Y`  |     | 服务节点健康状态检查间隔时间，单位：秒 |
+| load_balance |  `str`  | `Y`  |     | 负载均衡策略              |
+
+## 配置示例
+
+```yaml
+server:
+  port: 9000
+
+discovery:
+  - kind: Builtin
+    args:
+      server: server1
+      uris:
+        - 127.0.0.1:9000
+        - 127.0.0.1:9001
+        - 127.0.0.1:9002
+      interval: 10
+      load_balance: Random
+
+router:
+  routes:
+    - id: discovery-route
+      service: Proxy=http://server1
+```

docs/layers/concurrency_limit.md

@@ -0,0 +1,35 @@
+# ConcurrencyLimit
+
+> 限制请求的同时并发数量
+
+## 参数
+
+| 参数  |  类型   | 是否必须 | 默认值 | 描述        |
+|:----|:-----:|:----:|:---:|:----------|
+| max | `u32` | `Y`  |     | 允许的最大并发数量 |
+
+## 配置示例
+
+- ### 简单模式
+
+    ```yaml
+    router:
+      routes:
+        - id: concurrency-limit-shortcut
+          layers:
+            - ConcurrencyLimit=10
+          service: Static=examples/resources
+    ```
+
+- ### 完整模式
+
+    ```yaml
+    router:
+      routes:
+        - id: concurrency-limit-complete
+          layers:
+            - kind: ConcurrencyLimit
+              args:
+                max: 10
+          service: Static=examples/resources
+    ```

docs/layers/cors.md

@@ -0,0 +1,43 @@
+# Cors
+
+> 用于处理跨域请求
+
+## 参数
+
+| 参数                    |   类型    | 是否必须 |  默认值  | 描述         |
+|:----------------------|:-------:|:----:|:-----:|:-----------|
+| allow_credentials     | `bool`  | `N`  | false | 是否允许携带认证信息 |
+| allow_headers         | `[str]` | `N`  |  []   | 允许携带的头     |
+| allow_methods         | `[str]` | `N`  | [GET] | 允许请求的方法    |
+| allow_origin          | `[str]` | `N`  |  []   | 允许的域       |
+| allow_private_network | `bool`  | `N`  | false | 是否允许私有网络   |
+| expose_headers        | `[str]` | `N`  |  []   | 允许返回的头     |
+| max_age               |  `u32`  | `N`  |   0   | 最大有效期      |
+| vary                  | `[str]` | `N`  |  []   | vary列表     |
+
+## 配置示例
+
+- ### 简单模式
+
+    ```yaml
+    router:
+      routes:
+        - id: cors-shortcut
+          layers:
+            - Cors
+          service: Static=examples/resources
+    ```
+
+- ### 完整模式
+
+    ```yaml
+    router:
+      routes:
+        - id: rewrite-path-complete
+          layers:
+            - kind: Cors
+              args:
+                allow_credentials: false
+                allow_origin: '*'
+          service: Static=examples/resources
+    ```

docs/layers/keep_host_header.md

@@ -0,0 +1,31 @@
+# KeepHostHeader
+
+> 通用用在反向代理时，转发到后端的请求仍然保持客户端传递的`Host`信息。
+
+## 参数
+
+无
+
+## 配置示例
+
+- ### 简单模式
+
+    ```yaml
+    router:
+      routes:
+        - id: cors-shortcut
+          layers:
+            - KeepHostHeader
+          service: Static=examples/resources
+    ```
+
+- ### 完整模式
+
+    ```yaml
+    router:
+      routes:
+        - id: rewrite-path-complete
+          layers:
+            - kind: KeepHostHeader
+          service: Static=examples/resources
+    ```

docs/layers/path_strip.md

@@ -0,0 +1,35 @@
+# PathStrip
+
+> 从请求路径中删除特定部分
+
+## 参数
+
+| 参数    |  类型   | 是否必须 | 默认值 | 描述    |
+|:------|:-----:|:----:|:---:|:------|
+| level | `u32` | `Y`  |     | 截取的级别 |
+
+## 配置示例
+
+- ### 简单模式
+
+    ```yaml
+    router:
+      routes:
+        - id: path-strip-shortcut
+          layers:
+            - PathStrip=1
+          service: Static=examples/resources
+    ```
+
+- ### 完整模式
+
+    ```yaml
+    router:
+      routes:
+        - id: rewrite-path-complete
+          layers:
+            - kind: PathStrip
+              args:
+                level: 1
+          service: Static=examples/resources
+    ```

docs/layers/rate_limit.md

@@ -0,0 +1,43 @@
+# RateLimit
+
+> 使用令牌桶的来限制请求的速率
+
+## 参数
+
+| 参数       |   类型   | 是否必须 |  默认值  | 描述                                                    |
+|:---------|:------:|:----:|:-----:|:------------------------------------------------------|
+| policy   | `str`  | `Y`  |       | 超过限制后的策略：`Await`：超过限制后等待直到重新填充。`Break`：超过限制后直接中断请求失败。 |
+| max      | `u32`  | `Y`  |       | 最大Token数                                              |
+| refill   | `u32`  | `Y`  |       | 重新填充的Token数                                           |
+| interval | `u32`  | `N`  |   1   | 填充Token间隔时间，单位：秒。                                     |
+| fair     | `bool` | `N`  | false | 是否使用公平模式                                              |
+
+## 配置示例
+
+- ### 简单模式
+
+    ```yaml
+    router:
+      routes:
+        - id: rate-limit-shortcut
+          layers:
+            - RateLimit=Await,10,10,1,false
+          service: Static=examples/resources
+    ```
+
+- ### 完整模式
+
+    ```yaml
+    router:
+      routes:
+        - id: rate-limit-complete
+          layers:
+            - kind: RateLimit
+              args:
+                policy: Await
+                max: 10
+                refill: 10
+                interval: 1
+                fair: false
+          service: Static=examples/resources
+    ```