hf400159 commented on code in PR #7933:
URL: https://github.com/apache/apisix/pull/7933#discussion_r975029487
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -23,53 +30,56 @@ title: traffic-split
## 描述
-traffic-split 插件使用户可以逐步引导各个上游之间的流量百分比。
+`traffic-split` 插件可以通过配置 `match` 和 `weighted_upstreams`
属性，从而动态地将部分流量引导至各种上游服务。该插件可应用于灰度发布和蓝绿发布的场景。
-注：由于加权循环算法（特别是在重置 wrr 状态时）的缺点，因此每个上游之间的比率可能不太准确。
+`match` 属性是用于引导流量的自定义规则，`weighted_upstreams` 属性则用于引导流量的上游服务。当一个请求被 `match`
属性匹配时，它将根据配置的 `weights` 属性被引导至上游服务。你也可以不使用 `match` 属性，只根据 `weighted_upstreams`
属性来引导所有流量。
+
+:::note 注意
+
+由于使用了加权循环算法（特别是在重置 `wrr` 状态时），因此在使用该插件时，可能会存在上游服务之间的流量比例不精准现象。
Review Comment:
```suggestion
由于该插件使用了加权循环算法（特别是在重置 `wrr` 状态时），因此在使用该插件时，可能会存在上游服务之间的流量比例不精准现象。
```
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -23,53 +30,56 @@ title: traffic-split
## 描述
-traffic-split 插件使用户可以逐步引导各个上游之间的流量百分比。
+`traffic-split` 插件可以通过配置 `match` 和 `weighted_upstreams`
属性，从而动态地将部分流量引导至各种上游服务。该插件可应用于灰度发布和蓝绿发布的场景。
-注：由于加权循环算法（特别是在重置 wrr 状态时）的缺点，因此每个上游之间的比率可能不太准确。
+`match` 属性是用于引导流量的自定义规则，`weighted_upstreams` 属性则用于引导流量的上游服务。当一个请求被 `match`
属性匹配时，它将根据配置的 `weights` 属性被引导至上游服务。你也可以不使用 `match` 属性，只根据 `weighted_upstreams`
属性来引导所有流量。
+
+:::note 注意
+
+由于使用了加权循环算法（特别是在重置 `wrr` 状态时），因此在使用该插件时，可能会存在上游服务之间的流量比例不精准现象。
+
+:::
## 属性
| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述
|
Review Comment:
```suggestion
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
```
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -141,16 +152,29 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
->注：1、通过 `upstream_id` 方式来绑定已定义的上游，它可以复用上游具有的健康检测、重试等功能。2、支持 `upstream` 和
`upstream_id` 的两种配置方式一起使用。
+:::tip 提示
+
+通过 `upstream_id` 方式来绑定已定义的上游，可以复用上游已存在的健康检测、重试等功能。
+
+:::
+
+:::note 注意
-## 示例
+支持同时使用 `upstream` 和 `upstream_id` 两种配置方式。
Review Comment:
```suggestion
`weighted_upstreams` 属性支持同时使用 `upstream` 和 `upstream_id` 两种配置方式。
```
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -551,35 +591,45 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-**测试插件：**
+**测试**
-请求头 `x-api-id` 等于 1，命中带 1981 端口的上游。
+1. 通过 `curl` 命令发出请求，请求头 `x-api-id` 为 `1`，则会命中 `1980` 端口的服务：
+
+```shell
+curl http://127.0.0.1:9080/hello -H 'x-api-id: 1'
+```
```shell
-$ curl http://127.0.0.1:9080/hello -H 'x-api-id: 1'
1981
```
-请求头 `x-api-id` 等于 2，命中带 1982 端口的上游。
+2. 如果请求头 `x-api-id` 为 `2`，则会命中 `1982` 端口的服务：
+
+```shell
+curl http://127.0.0.1:9080/hello -H 'x-api-id: 2'
+```
```shell
-$ curl http://127.0.0.1:9080/hello -H 'x-api-id: 2'
1982
```
-请求头 `x-api-id` 等于 3，规则不匹配，命中带 1980 端口的上游。
+3. 如果请求头 `x-api-id` 为 `3`，规则不匹配，则会命中带 `1980` 端口的服务：
+
+```shell
+curl http://127.0.0.1:9080/hello -H 'x-api-id: 3'
+```
```shell
-$ curl http://127.0.0.1:9080/hello -H 'x-api-id: 3'
1980
```
## 禁用插件
-当你想去掉 traffic-split 插件的时候，很简单，在插件的配置中把对应的 json 配置删除即可，无须重启服务，即刻生效：
+当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+$ curl http://127.0.0.1:9180/apisix/admin/routes/1 \
Review Comment:
```suggestion
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
```
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -423,75 +464,74 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-插件设置了请求的 `match` 规则及端口为 `1981` 的 upstream，route 上具有端口为 `1980` 的 upstream 。
+**测试**
+
+1. 通过 `curl` 命令发出请求，如果两个 `vars` 表达式均匹配成功，`match` 规则校验通过后，将会有 60% 的请求被引导至插件
`1981` 端口的上游服务，40% 的请求命中到路由的 `1980` 端口的上游服务：
-**测试插件：**
+```shell
+curl 'http://127.0.0.1:9080/index.html?name=jack&name2=rose' \
+-H 'user-id:30' -H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2:
world' -i
+```
->1、两个 `vars` 的表达式匹配成功， `match` 规则校验通过后，60% 的请求命中到插件的 1981 端口 upstream, 40%
的请求命中到 `route` 的 1980 端口 upstream。
+在请求 5 次后，其中会有 3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务：
```shell
-$ curl 'http://127.0.0.1:9080/index.html?name=jack&name2=rose' -H 'user-id:30'
-H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2: world' -i
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
world 1981
```
```shell
-$ curl 'http://127.0.0.1:9080/index.html?name=jack&name2=rose' -H 'user-id:30'
-H 'user-id2:22' -H 'apisix-key: hello' -H 'apisix-key2: world' -i
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
-......
-
+...
hello 1980
```
-在请求 5 次后，3 次命中 `1981` 端口的服务，2 次命中 `1980` 端口的服务。
+2. 如果第二个 `vars` 的表达式匹配失败（如缺少 `name2` 请求参数），`match` 规则校验通过后，效果将会与上一种相同。即有 60%
的请求被引导至插件 `1981` 端口的上游服务，40% 的请求命中到路由的 `1980` 端口的上游服务：
Review Comment:
```suggestion
2. 如果第二个 `vars` 的表达式匹配失败（例如缺少 `name2` 请求参数），`match` 规则校验通过后，效果将会与上一种相同。即有
60% 的请求被引导至插件 `1981` 端口的上游服务，40% 的请求命中到路由的 `1980` 端口的上游服务：
```
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -141,16 +152,29 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
->注：1、通过 `upstream_id` 方式来绑定已定义的上游，它可以复用上游具有的健康检测、重试等功能。2、支持 `upstream` 和
`upstream_id` 的两种配置方式一起使用。
+:::tip 提示
+
+通过 `upstream_id` 方式来绑定已定义的上游，可以复用上游已存在的健康检测、重试等功能。
+
+:::
+
+:::note 注意
-## 示例
+支持同时使用 `upstream` 和 `upstream_id` 两种配置方式。
+
+:::
+
+## 测试插件
### 灰度发布
-缺少 `match` 规则部分，根据插件中 `weighted_upstreams` 配置的 `weight` 值做流量分流。将 `插件的
upstream` 与 `route 的 upstream` 按 3:2 的流量比例进行划分，其中 60% 的流量到达插件中的 `1981` 端口的
upstream， 40% 的流量到达 route 上默认 `1980` 端口的 upstream。
+灰度发布（又名金丝雀发布）是指在黑与白之间，能够平滑过渡的一种发布方式。 在其上可以进行 A/B 测试，即让一部分用户继续用产品特性
A，一部分用户开始用产品特性 B。如果用户对特性 B 没有什么反对意见，那么逐步扩大范围，把所有用户都迁移到特性 B 上面来。
Review Comment:
```suggestion
灰度发布（又名金丝雀发布）是指在已经上线与未上线服务之间，能够平滑过渡的一种发布方式。 在其上可以进行 A/B 测试，即让一部分用户继续用产品特性
A，一部分用户开始用产品特性 B。如果用户对特性 B 没有什么反对意见，那么逐步扩大范围，把所有用户都迁移到特性 B 上面来。
```
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -23,53 +30,56 @@ title: traffic-split
## 描述
-traffic-split 插件使用户可以逐步引导各个上游之间的流量百分比。
+`traffic-split` 插件可以通过配置 `match` 和 `weighted_upstreams`
属性，从而动态地将部分流量引导至各种上游服务。该插件可应用于灰度发布和蓝绿发布的场景。
-注：由于加权循环算法（特别是在重置 wrr 状态时）的缺点，因此每个上游之间的比率可能不太准确。
+`match` 属性是用于引导流量的自定义规则，`weighted_upstreams` 属性则用于引导流量的上游服务。当一个请求被 `match`
属性匹配时，它将根据配置的 `weights` 属性被引导至上游服务。你也可以不使用 `match` 属性，只根据 `weighted_upstreams`
属性来引导所有流量。
+
+:::note 注意
+
+由于使用了加权循环算法（特别是在重置 `wrr` 状态时），因此在使用该插件时，可能会存在上游服务之间的流量比例不精准现象。
+
+:::
## 属性
| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述
|
Review Comment:
```suggestion
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
```
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -141,16 +152,29 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
->注：1、通过 `upstream_id` 方式来绑定已定义的上游，它可以复用上游具有的健康检测、重试等功能。2、支持 `upstream` 和
`upstream_id` 的两种配置方式一起使用。
+:::tip 提示
+
+通过 `upstream_id` 方式来绑定已定义的上游，可以复用上游已存在的健康检测、重试等功能。
Review Comment:
```suggestion
通过 `upstream_id` 方式来绑定已定义的上游，可以复用上游已存在的健康检查、重试等功能。
```
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -23,53 +30,56 @@ title: traffic-split
## 描述
-traffic-split 插件使用户可以逐步引导各个上游之间的流量百分比。
+`traffic-split` 插件可以通过配置 `match` 和 `weighted_upstreams`
属性，从而动态地将部分流量引导至各种上游服务。该插件可应用于灰度发布和蓝绿发布的场景。
-注：由于加权循环算法（特别是在重置 wrr 状态时）的缺点，因此每个上游之间的比率可能不太准确。
+`match` 属性是用于引导流量的自定义规则，`weighted_upstreams` 属性则用于引导流量的上游服务。当一个请求被 `match`
属性匹配时，它将根据配置的 `weights` 属性被引导至上游服务。你也可以不使用 `match` 属性，只根据 `weighted_upstreams`
属性来引导所有流量。
+
+:::note 注意
+
+由于使用了加权循环算法（特别是在重置 `wrr` 状态时），因此在使用该插件时，可能会存在上游服务之间的流量比例不精准现象。
+
+:::
## 属性
| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述
|
| ---------------------- | --------------| ------ | ------ | ------
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| rules.match | array[object] | 可选 | | |
匹配规则列表，默认为空且规则将被无条件执行。
|
-| rules.match.vars | array[array] | 可选 | | |
由一个或多个{var, operator, val}元素组成的列表，类似这样：{{var, operator, val}, {var, operator,
val}, ...}}。例如：{"arg_name", "==", "json"}，表示当前请求参数 name 是 json。这里的 var 与 Nginx
内部自身变量命名是保持一致，所以也可以使用 request_uri、host 等；对于 operator 部分，目前已支持的运算符有
==、~=、~~、>、<、in、has 和 ! 。操作符的具体用法请看
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 的
`operator-list` 部分。 |
-| rules.weighted_upstreams | array[object] | 可选 | | |
上游配置规则列表。
|
-| weighted_upstreams.upstream_id | string / integer | 可选 | | |
通过上游 id 绑定对应上游。
|
-| weighted_upstreams.upstream | object | 可选 | | | 上游配置信息。
|
-| upstream.type | enum | 可选 | roundrobin |
[roundrobin, chash] | roundrobin 支持权重的负载，chash 一致性哈希，两者是二选一。
|
-| upstream.hash_on | enum | 可选 | vars | | `hash_on` 支持的类型有
`vars`（Nginx 内置变量），`header`（自定义
header），`cookie`，`consumer`，`vars_combinations`，默认值为 `vars`。更多详细信息请参考
[upstream](../admin-api.md#upstream) 用法。
|
-| upstream.key | string | 可选 | | | 该选项只有类型是
`chash` 才有效。根据 `key` 来查找对应的 node `id`，相同的 `key` 在同一个对象中，永远返回相同 id。更多详细信息请参考
[upstream](../admin-api.md#upstream) 用法。
|
-| upstream.nodes | object | 可选 | | | 哈希表，内部元素的
key 是上游机器地址 列表，格式为地址 + Port，其中地址部 分可以是 IP 也可以是域名，⽐如 192.168.1.100:80、foo.com:80
等。 value 则是节点的权重，特别的，当权重 值为 0 有特殊含义，通常代表该上游节点 失效，永远不希望被选中。
|
-| upstream.timeout | object | 可选 | 15 | |
设置连接、发送消息、接收消息的超时时间（时间单位：秒，都默认为 15 秒）。
|
-| upstream.pass_host | enum | 可选 | "pass" | ["pass", "node",
"rewrite"] | `pass`：将客户端的 host 透传给上游； `node`：使用 `upstream` node 中配置的 host；
`rewrite`：使用配置项 `upstream_host` 的值
|
-| upstream.name | string | 可选 | | | 标识上游服务名称、使⽤场景等。
|
-| upstream.upstream_host | string | 可选 | | | 只在
pass_host 配置为 rewrite 时有效。
|
-| weighted_upstreams.weight | integer | 可选 | weight = 1 |
| 根据 `weight` 值做流量划分，多个 weight 之间使用 roundrobin 算法划分。
|
-
-目前在 `weighted_upstreams.upstream` 的配置中，不支持的字段有：
-service_name、discovery_type、checks、retries、retry_timeout、desc、scheme、labels、create_time
和 update_time。但是你可以通过 `weighted_upstreams.upstream_id` 绑定 `upstream` 对象来实现他们。
-
-traffic-split 插件主要由 `match` 和 `weighted_upstreams` 两部分组成，`match`
是自定义的条件规则，`weighted_upstreams` 是 upstream 的配置信息。如果配置 `match` 和
`weighted_upstreams` 信息，那么在 `match` 规则校验通过后，会根据 `weighted_upstreams` 中的
`weight` 值；引导插件中各个 upstream 之间的流量比例，否则，所有流量直接到达 `route` 或 `service` 上配置的
`upstream`。当然你也可以只配置 `weighted_upstreams` 部分，这样会直接根据 `weighted_upstreams` 中的
`weight` 值，引导插件中各个 upstream 之间的流量比例。
-
-注：1、在 `match` 里，vars 中的表达式是 `and` 的关系，多个 `vars` 之间是 `or` 的关系。2、在插件的
weighted_upstreams 域中，如果存在只有 `weight` 的结构，表示 `route` 或 `service` 上的 upstream
流量权重值。例如：
-
-```json
-"weighted_upstreams": [
- ......
- {
- "weight": 2
- }
-]
-```
+| rules.match | array[object] | 否 | | |
匹配规则列表，默认为空且规则将被无条件执行。
|
+| rules.match.vars | array[array] | 否 | | |
由一个或多个 `{var, operator, val}` 元素组成的列表，例如：`{"arg_name", "==", "json"}`，表示当前请求参数
`name` 是 `json`。这里的 `var` 与 NGINX 内部自身变量命名是保持一致，所以也可以使用 `request_uri`、`host`
等；对于已支持的运算符，具体用法请参考
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 的
`operator-list` 部分。 |
+| rules.weighted_upstreams | array[object] | 否 | | |
上游配置规则列表。
|
+| weighted_upstreams.upstream_id | string/integer | 否 | | |
通过上游 `id` 绑定对应上游。
|
+| weighted_upstreams.upstream | object | 否 | | | 上游配置信息。
|
+| upstream.type | enum | 否 | roundrobin | [roundrobin,
chash] | 流量引导机制的类型；`roundrobin` 表示支持权重的负载，`chash` 表示使用一致性哈希。
|
+| upstream.hash_on | enum | 否 | vars | | 该属性仅当
`upstream.type` 是 `chash` 时有效。支持的类型有 `vars`（NGINX 内置变量），`header`（自定义
header），`cookie`，`consumer`，`vars_combinations`。更多信息请参考
[Upstream](../admin-api.md#upstream) 用法。
|
+| upstream.key | string | 否 | | | 该属性仅当
`upstream.type` 是 `chash` 时有效。根据 `hash_on` 和 `key` 来查找对应的 Node `id`。更多信息请参考
[Upstream](../admin-api.md#upstream) 用法。
|
+| upstream.nodes | object | 否 | | |
哈希表，键是上游节点的 IP 地址与可选端口的组合，值是节点的权重。将 `weight` 设置为 `0` 表示一个请求永远不会被转发到该节点。
|
+| upstream.timeout | object | 否 | 15 | |
发送和接收消息的超时时间（单位为秒）。
|
+| upstream.pass_host | enum | 否 | "pass" | ["pass", "node",
"rewrite"] | 当请求被转发到上游时配置 `host`。`pass` 代表将客户端的 `host` 透明传输给上游；`node` 代表使用
`upstream` Node 中配置的 `host`； `rewrite` 代表使用配置项 `upstream_host` 的值。
|
+| upstream.name | string | 否 | | | 标识上游服务名称、使⽤场景等。
|
+| upstream.upstream_host | string | 否 | | | 上游服务请求的
`host`，仅当 `pass_host` 属性配置为 `rewrite` 时生效。
|
+| weighted_upstreams.weight | integer | 否 | weight = 1 | |
根据 `weight` 值做流量划分，多个 `weight` 之间使用 `roundrobin` 算法划分。
|
+
+:::note 注意
+
+目前 `weighted_upstreams.upstream` 的配置不支持
`service_name`、`discovery_type`、`checks`、`retries`、`retry_timeout`、`desc`、`scheme`、`labels`、`create_time`
和 `update_time` 等字段。如果你需要使用这些字段，可以在创建上游对象时指定这些字段，然后在该插件中配置
`weighted_upstreams.upstream_id` 属性即可。
+
+:::
+
+:::info 重要
-## 如何启用
+在 `match` 属性中，变量中的表达式以 AND 方式关联，多个变量以 OR 方式关联。
-创建一个路由并启用 `traffic-split` 插件，在配置插件上游信息时，有以下两种方式：
+如果只配置了 `weight` 属性，那么它就对应于在 Route 或 Service 上配置的上游服务的权重。
Review Comment:
如果你仅配置了 `weight` 属性，那么它将会使用该 Route 或 Service 中的上游服务的权重。
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -23,53 +30,56 @@ title: traffic-split
## 描述
-traffic-split 插件使用户可以逐步引导各个上游之间的流量百分比。
+`traffic-split` 插件可以通过配置 `match` 和 `weighted_upstreams`
属性，从而动态地将部分流量引导至各种上游服务。该插件可应用于灰度发布和蓝绿发布的场景。
-注：由于加权循环算法（特别是在重置 wrr 状态时）的缺点，因此每个上游之间的比率可能不太准确。
+`match` 属性是用于引导流量的自定义规则，`weighted_upstreams` 属性则用于引导流量的上游服务。当一个请求被 `match`
属性匹配时，它将根据配置的 `weights` 属性被引导至上游服务。你也可以不使用 `match` 属性，只根据 `weighted_upstreams`
属性来引导所有流量。
+
+:::note 注意
+
+由于使用了加权循环算法（特别是在重置 `wrr` 状态时），因此在使用该插件时，可能会存在上游服务之间的流量比例不精准现象。
+
+:::
## 属性
| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述
|
| ---------------------- | --------------| ------ | ------ | ------
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| rules.match | array[object] | 可选 | | |
匹配规则列表，默认为空且规则将被无条件执行。
|
-| rules.match.vars | array[array] | 可选 | | |
由一个或多个{var, operator, val}元素组成的列表，类似这样：{{var, operator, val}, {var, operator,
val}, ...}}。例如：{"arg_name", "==", "json"}，表示当前请求参数 name 是 json。这里的 var 与 Nginx
内部自身变量命名是保持一致，所以也可以使用 request_uri、host 等；对于 operator 部分，目前已支持的运算符有
==、~=、~~、>、<、in、has 和 ! 。操作符的具体用法请看
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 的
`operator-list` 部分。 |
-| rules.weighted_upstreams | array[object] | 可选 | | |
上游配置规则列表。
|
-| weighted_upstreams.upstream_id | string / integer | 可选 | | |
通过上游 id 绑定对应上游。
|
-| weighted_upstreams.upstream | object | 可选 | | | 上游配置信息。
|
-| upstream.type | enum | 可选 | roundrobin |
[roundrobin, chash] | roundrobin 支持权重的负载，chash 一致性哈希，两者是二选一。
|
-| upstream.hash_on | enum | 可选 | vars | | `hash_on` 支持的类型有
`vars`（Nginx 内置变量），`header`（自定义
header），`cookie`，`consumer`，`vars_combinations`，默认值为 `vars`。更多详细信息请参考
[upstream](../admin-api.md#upstream) 用法。
|
-| upstream.key | string | 可选 | | | 该选项只有类型是
`chash` 才有效。根据 `key` 来查找对应的 node `id`，相同的 `key` 在同一个对象中，永远返回相同 id。更多详细信息请参考
[upstream](../admin-api.md#upstream) 用法。
|
-| upstream.nodes | object | 可选 | | | 哈希表，内部元素的
key 是上游机器地址 列表，格式为地址 + Port，其中地址部 分可以是 IP 也可以是域名，⽐如 192.168.1.100:80、foo.com:80
等。 value 则是节点的权重，特别的，当权重 值为 0 有特殊含义，通常代表该上游节点 失效，永远不希望被选中。
|
-| upstream.timeout | object | 可选 | 15 | |
设置连接、发送消息、接收消息的超时时间（时间单位：秒，都默认为 15 秒）。
|
-| upstream.pass_host | enum | 可选 | "pass" | ["pass", "node",
"rewrite"] | `pass`：将客户端的 host 透传给上游； `node`：使用 `upstream` node 中配置的 host；
`rewrite`：使用配置项 `upstream_host` 的值
|
-| upstream.name | string | 可选 | | | 标识上游服务名称、使⽤场景等。
|
-| upstream.upstream_host | string | 可选 | | | 只在
pass_host 配置为 rewrite 时有效。
|
-| weighted_upstreams.weight | integer | 可选 | weight = 1 |
| 根据 `weight` 值做流量划分，多个 weight 之间使用 roundrobin 算法划分。
|
-
-目前在 `weighted_upstreams.upstream` 的配置中，不支持的字段有：
-service_name、discovery_type、checks、retries、retry_timeout、desc、scheme、labels、create_time
和 update_time。但是你可以通过 `weighted_upstreams.upstream_id` 绑定 `upstream` 对象来实现他们。
-
-traffic-split 插件主要由 `match` 和 `weighted_upstreams` 两部分组成，`match`
是自定义的条件规则，`weighted_upstreams` 是 upstream 的配置信息。如果配置 `match` 和
`weighted_upstreams` 信息，那么在 `match` 规则校验通过后，会根据 `weighted_upstreams` 中的
`weight` 值；引导插件中各个 upstream 之间的流量比例，否则，所有流量直接到达 `route` 或 `service` 上配置的
`upstream`。当然你也可以只配置 `weighted_upstreams` 部分，这样会直接根据 `weighted_upstreams` 中的
`weight` 值，引导插件中各个 upstream 之间的流量比例。
-
-注：1、在 `match` 里，vars 中的表达式是 `and` 的关系，多个 `vars` 之间是 `or` 的关系。2、在插件的
weighted_upstreams 域中，如果存在只有 `weight` 的结构，表示 `route` 或 `service` 上的 upstream
流量权重值。例如：
-
-```json
-"weighted_upstreams": [
- ......
- {
- "weight": 2
- }
-]
-```
+| rules.match | array[object] | 否 | | |
匹配规则列表，默认为空且规则将被无条件执行。
|
+| rules.match.vars | array[array] | 否 | | |
由一个或多个 `{var, operator, val}` 元素组成的列表，例如：`{"arg_name", "==", "json"}`，表示当前请求参数
`name` 是 `json`。这里的 `var` 与 NGINX 内部自身变量命名是保持一致，所以也可以使用 `request_uri`、`host`
等；对于已支持的运算符，具体用法请参考
[lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 的
`operator-list` 部分。 |
+| rules.weighted_upstreams | array[object] | 否 | | |
上游配置规则列表。
|
+| weighted_upstreams.upstream_id | string/integer | 否 | | |
通过上游 `id` 绑定对应上游。
|
+| weighted_upstreams.upstream | object | 否 | | | 上游配置信息。
|
+| upstream.type | enum | 否 | roundrobin | [roundrobin,
chash] | 流量引导机制的类型；`roundrobin` 表示支持权重的负载，`chash` 表示使用一致性哈希。
|
+| upstream.hash_on | enum | 否 | vars | | 该属性仅当
`upstream.type` 是 `chash` 时有效。支持的类型有 `vars`（NGINX 内置变量），`header`（自定义
header），`cookie`，`consumer`，`vars_combinations`。更多信息请参考
[Upstream](../admin-api.md#upstream) 用法。
|
+| upstream.key | string | 否 | | | 该属性仅当
`upstream.type` 是 `chash` 时有效。根据 `hash_on` 和 `key` 来查找对应的 Node `id`。更多信息请参考
[Upstream](../admin-api.md#upstream) 用法。
|
+| upstream.nodes | object | 否 | | |
哈希表，键是上游节点的 IP 地址与可选端口的组合，值是节点的权重。将 `weight` 设置为 `0` 表示一个请求永远不会被转发到该节点。
|
+| upstream.timeout | object | 否 | 15 | |
发送和接收消息的超时时间（单位为秒）。
|
+| upstream.pass_host | enum | 否 | "pass" | ["pass", "node",
"rewrite"] | 当请求被转发到上游时配置 `host`。`pass` 代表将客户端的 `host` 透明传输给上游；`node` 代表使用
`upstream` Node 中配置的 `host`； `rewrite` 代表使用配置项 `upstream_host` 的值。
|
+| upstream.name | string | 否 | | | 标识上游服务名称、使⽤场景等。
|
Review Comment:
```suggestion
| upstream.name | string | 否 | | |
标识上游服务名称、使用场景等。
|
```
##########
docs/zh/latest/plugins/traffic-split.md:
##########
@@ -141,16 +152,29 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
->注：1、通过 `upstream_id` 方式来绑定已定义的上游，它可以复用上游具有的健康检测、重试等功能。2、支持 `upstream` 和
`upstream_id` 的两种配置方式一起使用。
+:::tip 提示
+
+通过 `upstream_id` 方式来绑定已定义的上游，可以复用上游已存在的健康检测、重试等功能。
+
+:::
+
+:::note 注意
-## 示例
+支持同时使用 `upstream` 和 `upstream_id` 两种配置方式。
+
+:::
+
+## 测试插件
### 灰度发布
-缺少 `match` 规则部分，根据插件中 `weighted_upstreams` 配置的 `weight` 值做流量分流。将 `插件的
upstream` 与 `route 的 upstream` 按 3:2 的流量比例进行划分，其中 60% 的流量到达插件中的 `1981` 端口的
upstream， 40% 的流量到达 route 上默认 `1980` 端口的 upstream。
+灰度发布（又名金丝雀发布）是指在黑与白之间，能够平滑过渡的一种发布方式。 在其上可以进行 A/B 测试，即让一部分用户继续用产品特性
A，一部分用户开始用产品特性 B。如果用户对特性 B 没有什么反对意见，那么逐步扩大范围，把所有用户都迁移到特性 B 上面来。
+
+以下示例展示了如何通过配置 `weighted_upstreams` 的 `weight` 属性来实现流量分流。按 3:2 的权重流量比例进行划分，其中
60% 的流量到达运行在 `1981` 端口上的上游服务，40% 的流量到达运行在`1980` 端口上的上游服务：
Review Comment:
```suggestion
以下示例展示了如何通过配置 `weighted_upstreams` 的 `weight` 属性来实现流量分流。按 3:2 的权重流量比例进行划分，其中
60% 的流量到达运行在 `1981` 端口上的上游服务，40% 的流量到达运行在 `1980` 端口上的上游服务：
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
