You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by GitBox <gi...@apache.org> on 2022/08/21 11:20:45 UTC
[GitHub] [apisix] lunarwhite opened a new pull request, #7751: docs(plugin): refactor request-id.md
lunarwhite opened a new pull request, #7751:
URL: https://github.com/apache/apisix/pull/7751
### Description
update documents under `docs/zh/latest/plugins/` along with `docs/en/latest/plugins/`
### Checklist
- [x] I have explained the need for this PR and the problem it solves
- [x] I have explained the changes or the new features added to this PR
- [ ] I have added tests corresponding to this change
- [x] I have updated the documentation to reflect this change
- [x] I have verified that this change is backward compatible (If not, please discuss on the [APISIX mailing list](https://github.com/apache/apisix/tree/master#community) first)
<!--
Note
1. Mark the PR as draft until it's ready to be reviewed.
2. Always add/update tests for any changes unless you have a good reason.
3. Always update the documentation to reflect the changes made in the PR.
4. Make a new commit to resolve conversations instead of `push -f`.
5. To resolve merge conflicts, merge master instead of rebasing.
6. Use "request review" to notify the reviewer after making changes.
7. Only a reviewer can mark a conversation as resolved.
-->
--
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY merged pull request #7751: docs(plugin): refactor request-id.md
Posted by GitBox <gi...@apache.org>.
SylviaBABY merged PR #7751:
URL: https://github.com/apache/apisix/pull/7751
--
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] hf400159 commented on a diff in pull request #7751: docs(plugin): refactor request-id.md
Posted by GitBox <gi...@apache.org>.
hf400159 commented on code in PR #7751:
URL: https://github.com/apache/apisix/pull/7751#discussion_r951082589
##########
docs/zh/latest/plugins/request-id.md:
##########
@@ -23,28 +28,63 @@ title: request-id
## 描述
-`request-id` 插件通过 APISIX 为每一个请求代理添加唯一 ID（UUID），以用于追踪 API 请求。该插件在 `header_name` 已经在请求中存在时不会为请求添加新的 ID。
+`request-id` 插件通过 APISIX 为每一个请求代理添加 unique ID，以用于追踪 API 请求。
+
+:::note 注意
+
+如果请求已经有了配置好 `header_name` 属性的请求头，该插件将不会为请求添加 unique ID。
Review Comment:
```suggestion
如果请求已经配置了 `header_name` 属性的请求头，该插件将不会为请求添加 unique ID。
```
##########
docs/zh/latest/plugins/request-id.md:
##########
@@ -23,28 +28,63 @@ title: request-id
## 描述
-`request-id` 插件通过 APISIX 为每一个请求代理添加唯一 ID（UUID），以用于追踪 API 请求。该插件在 `header_name` 已经在请求中存在时不会为请求添加新的 ID。
+`request-id` 插件通过 APISIX 为每一个请求代理添加 unique ID，以用于追踪 API 请求。
+
+:::note 注意
+
+如果请求已经有了配置好 `header_name` 属性的请求头，该插件将不会为请求添加 unique ID。
+
+:::
## 属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------------- | ------- | -------- | -------------- | ------ | ------------------------------ |
-| header_name | string | 可选 | "X-Request-Id" | | Request ID header name |
-| include_in_response | boolean | 可选 | true | | 是否需要在返回头中包含该唯一 ID |
-| algorithm | string | 可选 | "uuid" | ["uuid", "snowflake", "nanoid"] | ID 生成算法 |
+| header_name | string | 否 | "X-Request-Id" | | unique ID 的请求头的名称。 |
+| include_in_response | boolean | 否 | true | | 当设置为 `true` 时，将 unique ID 加入返回头。 |
+| algorithm | string | 否 | "uuid" | ["uuid", "snowflake", "nanoid"] | 指定的 unique ID 生成算法。 |
-:::warning
+### 使用 snowflake 算法生成 unique ID
-当使用 `snowflake` 算法时，请确保 APISIX 有权限写入 etcd。
+:::caution 警告
+
+- 当使用 `snowflake` 算法时，请确保 APISIX 有权限写入 etcd。
+- 在决定使用 `snowflake` 算法时，请先阅读本文档了解一些配置细节。因为一旦启用相关配置信息，则不可随意调整，否则可能会导致生成重复的 ID。
Review Comment:
```suggestion
- 在决定使用 `snowflake` 算法时，请仔细阅读本文档了解配置细节。因为一旦启用相关配置信息后，就不能随意调整，否则可能会导致生成重复的 ID。
```
##########
docs/zh/latest/plugins/request-id.md:
##########
@@ -23,28 +28,63 @@ title: request-id
## 描述
-`request-id` 插件通过 APISIX 为每一个请求代理添加唯一 ID（UUID），以用于追踪 API 请求。该插件在 `header_name` 已经在请求中存在时不会为请求添加新的 ID。
+`request-id` 插件通过 APISIX 为每一个请求代理添加 unique ID，以用于追踪 API 请求。
Review Comment:
```suggestion
`request-id` 插件通过 APISIX 为每一个请求代理添加 unique ID 用于追踪 API 请求。
```
##########
docs/zh/latest/plugins/request-id.md:
##########
@@ -23,28 +28,63 @@ title: request-id
## 描述
-`request-id` 插件通过 APISIX 为每一个请求代理添加唯一 ID（UUID），以用于追踪 API 请求。该插件在 `header_name` 已经在请求中存在时不会为请求添加新的 ID。
+`request-id` 插件通过 APISIX 为每一个请求代理添加 unique ID，以用于追踪 API 请求。
+
+:::note 注意
+
+如果请求已经有了配置好 `header_name` 属性的请求头，该插件将不会为请求添加 unique ID。
+
+:::
## 属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------------- | ------- | -------- | -------------- | ------ | ------------------------------ |
-| header_name | string | 可选 | "X-Request-Id" | | Request ID header name |
-| include_in_response | boolean | 可选 | true | | 是否需要在返回头中包含该唯一 ID |
-| algorithm | string | 可选 | "uuid" | ["uuid", "snowflake", "nanoid"] | ID 生成算法 |
+| header_name | string | 否 | "X-Request-Id" | | unique ID 的请求头的名称。 |
+| include_in_response | boolean | 否 | true | | 当设置为 `true` 时，将 unique ID 加入返回头。 |
+| algorithm | string | 否 | "uuid" | ["uuid", "snowflake", "nanoid"] | 指定的 unique ID 生成算法。 |
-:::warning
+### 使用 snowflake 算法生成 unique ID
-当使用 `snowflake` 算法时，请确保 APISIX 有权限写入 etcd。
+:::caution 警告
+
+- 当使用 `snowflake` 算法时，请确保 APISIX 有权限写入 etcd。
+- 在决定使用 `snowflake` 算法时，请先阅读本文档了解一些配置细节。因为一旦启用相关配置信息，则不可随意调整，否则可能会导致生成重复的 ID。
:::
-## 如何启用
+`snowflake` 算法支持灵活配置来满足各种需求，可配置的参数如下：
+
+| 名称 | 类型 | 必选项 | 默认值 | 描述 |
+| ------------------- | ------- | -------- | -------------- | ------------------------------ |
+| enable | boolean | 否 | false | 当设置为 `true` 时， 启用 `snowflake` 算法。 |
+| snowflake_epoc | integer | 否 | 1609459200000 | 起始时间戳，以毫秒为单位。默认为 `2021-01-01T00:00:00Z`, 可以支持 `69 年`到 `2090-09-07 15:47:35Z`。 |
+| data_machine_bits | integer | 否 | 12 | 最多支持的机器（进程）数量。 与 `snowflake` 定义中 `workerIDs` 和 `datacenterIDs` 的集合对应，插件会为每一个进程分配一个 unique ID。最大支持进程数为 `pow(2, data_machine_bits)`。即对于默认值 `12 bits`，最多支持的进程数为 `4096`。|
+| sequence_bits | integer | 否 | 10 | 每个节点每毫秒内最多产生的 ID 数量。 每个进程每毫秒最多产生 `1024` 个 ID。 |
+| data_machine_ttl | integer | 否 | 30 | etcd 中 `data_machine` 注册有效时间，以秒为单位。 |
+| data_machine_interval | integer | 否 | 10 | etcd 中 `data_machine` 续约间隔时间，以秒为单位。 |
-创建一条路由并在该路由上启用 `request-id` 插件：
+要使用 `snowflake` 算法，你必须先在配置文件 `conf/config.yaml` 中启用：
Review Comment:
```suggestion
如果你需要使用 `snowflake` 算法，请务必在配置文件 `./conf/config.yaml` 中添加以下参数：
```
--
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [apisix] SylviaBABY commented on a diff in pull request #7751: docs(plugin): refactor request-id.md
Posted by GitBox <gi...@apache.org>.
SylviaBABY commented on code in PR #7751:
URL: https://github.com/apache/apisix/pull/7751#discussion_r950945228
##########
docs/zh/latest/plugins/request-id.md:
##########
@@ -63,70 +103,24 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
-```shell
-$ curl -i http://127.0.0.1:9080/hello
-HTTP/1.1 200 OK
-X-Request-Id: fe32076a-d0a5-49a6-a361-6c244c1df956
-......
-```
-
-### 使用 snowflake 算法生成 ID
-
-> 支持使用 snowflake 算法来生成 ID。
-> 在决定使用 snowflake 时，请优先阅读一下文档。因为一旦启用配置信息则不可随意调整配置信息。否则可能会导致生成重复 ID。
+按上述配置启用插件后，APISIX 将为你的每个请求创建一个 unique ID。
-snowflake 算法默认是不启用的，需要在 `conf/config.yaml` 中开启配置。
+使用 `curl` 命令请求该路由：
-```yaml
-plugin_attr:
- request-id:
- snowflake:
- enable: true
- snowflake_epoc: 1609459200000
- data_machine_bits: 12
- sequence_bits: 10
- data_machine_ttl: 30
- data_machine_interval: 10
+```shell
+curl -i http://127.0.0.1:9080/hello
```
-#### 配置参数
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------------- | ------- | -------- | -------------- | ------ | ------------------------------ |
-| enable | boolean | 可选 | false | | 当设置为 true 时， 启用 snowflake 算法。 |
-| snowflake_epoc | integer | 可选 | 1609459200000 | | 起始时间戳（单位： 毫秒）|
-| data_machine_bits | integer | 可选 | 12 | | 最多支持机器（进程）数量 `1 << data_machine_bits` |
-| sequence_bits | integer | 可选 | 10 | | 每个节点每毫秒内最多产生 ID 数量 `1 << sequence_bits` |
-| data_machine_ttl | integer | 可选 | 30 | | `etcd` 中 `data_machine` 注册有效时间（单位： 秒）|
-| data_machine_interval | integer | 可选 | 10 | | `etcd` 中 `data_machine` 续约间隔时间（单位： 秒）|
+返回的 HTTP 响应头中如果带有 `200` 状态码，且每次返回不同的 `X-Request-Id`，则表示插件生效：
-- snowflake_epoc 默认起始时间为 `2021-01-01T00:00:00Z`, 按默认配置可以支持 `69 年` 大约可以使用到 `2090-09-07 15:47:35Z`
-- data_machine_bits 对应的是 snowflake 定义中的 WorkerID 和 DatacenterID 的集合，插件会为每一个进程分配一个唯一 ID，最大支持进程数为 `pow(2, data_machine_bits)`。默认占 `12 bits` 最多支持 `4096` 个进程。
-- sequence_bits 默认占 `10 bits`, 每个进程每毫秒最多生成 `1024` 个 ID
-
-#### 配置示例
-
-> snowflake 支持灵活配置来满足各式各样的需求
-
-- snowflake 原版配置
-
-> - 起始时间 2014-10-20T15:00:00.000Z， 精确到毫秒为单位。大约可以使用 `69 年`
-> - 最多支持 `1024` 个进程
-> - 每个进程每毫秒最多产生 `4096` 个 ID
-
-```yaml
-plugin_attr:
- request-id:
- snowflake:
- enable: true
- snowflake_epoc: 1413817200000
- data_machine_bits: 10
- sequence_bits: 12
+```shell
+HTTP/1.1 200 OK
+X-Request-Id: fe32076a-d0a5-49a6-a361-6c244c1df956
```
## 禁用插件
-在路由 `plugins` 配置块中删除 `request-id 配置，reload 即可禁用该插件，无需重启 APISIX。
+当你需要禁用该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
Review Comment:
```suggestion
curl http://127.0.0.1:9080/apisix/admin/routes/5 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
```
##########
docs/zh/latest/plugins/request-id.md:
##########
@@ -23,28 +28,63 @@ title: request-id
## 描述
-`request-id` 插件通过 APISIX 为每一个请求代理添加唯一 ID（UUID），以用于追踪 API 请求。该插件在 `header_name` 已经在请求中存在时不会为请求添加新的 ID。
+`request-id` 插件通过 APISIX 为每一个请求代理添加 unique ID，以用于追踪 API 请求。
+
+:::note 注意
+
+如果请求已经有了配置好 `header_name` 属性的请求头，该插件将不会为请求添加 unique ID。
+
+:::
## 属性
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ------------------- | ------- | -------- | -------------- | ------ | ------------------------------ |
-| header_name | string | 可选 | "X-Request-Id" | | Request ID header name |
-| include_in_response | boolean | 可选 | true | | 是否需要在返回头中包含该唯一 ID |
-| algorithm | string | 可选 | "uuid" | ["uuid", "snowflake", "nanoid"] | ID 生成算法 |
+| header_name | string | 否 | "X-Request-Id" | | unique ID 的请求头的名称。 |
+| include_in_response | boolean | 否 | true | | 当设置为 `true` 时，将 unique ID 加入返回头。 |
+| algorithm | string | 否 | "uuid" | ["uuid", "snowflake", "nanoid"] | 指定的 unique ID 生成算法。 |
-:::warning
+### 使用 snowflake 算法生成 unique ID
-当使用 `snowflake` 算法时，请确保 APISIX 有权限写入 etcd。
+:::caution 警告
+
+- 当使用 `snowflake` 算法时，请确保 APISIX 有权限写入 etcd。
+- 在决定使用 `snowflake` 算法时，请先阅读一下文档。因为一旦启用配置信息则不可随意调整配置信息，否则可能会导致生成重复的 ID。
Review Comment:
```suggestion
- 在决定使用 `snowflake` 算法时，请先阅读本文档了解一些配置细节。因为一旦启用相关配置信息，则不可随意调整，否则可能会导致生成重复的 ID。
```
--
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: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org