Skip to content
Permalink
Browse files
docs(lint): import Chinese copywriting autocorrect linter (#6568)
Co-authored-by: leslie <59061168+leslie-tsang@users.noreply.github.com>
Co-authored-by: 琚致远 <juzhiyuan@apache.org>
  • Loading branch information
3 people committed Mar 24, 2022
1 parent 2149ab1 commit 96838b9b47347429d79ba5cc10c3267b8c62bee9
Showing 83 changed files with 612 additions and 587 deletions.
@@ -34,3 +34,17 @@ jobs:
echo "You need to run ./utils/fix-zh-doc-segment.py to fix them."
exit 1
fi
Chinse-Copywriting-lint:
name: Chinese Copywriting
runs-on: ubuntu-latest
timeout-minutes: 1
steps:
- uses: actions/checkout@v3
- name: check Chinese copywriting
run: |
version=v1.5.6
wget -O- "https://github.com/huacnlee/autocorrect/releases/download/$version/autocorrect-linux-amd64.tar.gz" | tar -xzv
mv -v autocorrect /usr/local/bin/
autocorrect --version
git ls-files | grep "^docs/zh/latest/.*.md$" | xargs -t autocorrect --lint
@@ -58,6 +58,18 @@ Once we've discussed your changes and you've got your code ready, make sure that

- npm based [markdownlint-cli](https://www.npmjs.com/package/markdownlint-cli)

For linting all files' license header we use:

- [license-eye](https://github.com/apache/skywalking-eyes)

For linting our shell files we use:

- [shellcheck](https://github.com/koalaman/shellcheck)

For linting our zh document files we use:

- [autocorrect](https://github.com/huacnlee/autocorrect)

* Active Voice

In general, use active voice when formulating the sentence instead of passive voice. A sentence written in the active voice will emphasize

Large diffs are not rendered by default.

@@ -190,7 +190,7 @@ local i = 1
local s = "apisix"
```

变量命名使用 `snake_case`(蛇形命名法) 风格:
变量命名使用 `snake_case`(蛇形命名法)风格:

```lua
--No
@@ -246,7 +246,7 @@ end
local t = {1, 2, nil, 3}
```

如果一定要使用空值,请用 `ngx.null` 来表示:
如果一定要使用空值,请用 `ngx.null` 来表示

```lua
--Yes
@@ -344,7 +344,7 @@ local function foo()
end
```

为了风格的统一,`require``ngx` 也需要 `local`:
为了风格的统一,`require``ngx` 也需要 `local`

```lua
--No
@@ -403,9 +403,9 @@ HTTP/1.1 404 Not Found

在 route 中,我们可以通过 `uri` 结合 `vars` 字段来实现更多的条件匹配,`vars` 的更多使用细节请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。

## upstream 节点是否支持配置 [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) 地址?
## upstream 节点是否支持配置 [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) 地址

这是支持的,下面是一个 `FQDN``httpbin.default.svc.cluster.local`(一个 Kubernetes Service) 的示例:
这是支持的,下面是一个 `FQDN``httpbin.default.svc.cluster.local`(一个 Kubernetes Service)的示例:

```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -546,7 +546,7 @@ apisix:
# ... 忽略其余无关项
```

**注意:**
**注意**

尝试使用 cosocket 连接任何 TLS 服务时,如果 APISIX 不信任对端 TLS 服务证书,都需要配置 `apisix.ssl.ssl_trusted_certificate`

Large diffs are not rendered by default.

Large diffs are not rendered by default.

@@ -98,7 +98,7 @@ HTTP/1.1 503 Service Temporarily Unavailable
结合 [consumer-restriction](../plugins/consumer-restriction.md) 插件,限制 jack 对该 route 的访问

```shell
# 设置黑名单,禁止jack访问该API
# 设置黑名单,禁止 jack 访问该 API
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
@@ -119,7 +119,7 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
"uri": "/hello"
}'
# 反复测试,均返回 403,jack被禁止访问
# 反复测试,均返回 403,jack 被禁止访问
$ curl http://127.0.0.1:9080/hello -H 'apikey: auth-one' -I
HTTP/1.1 403
...
@@ -23,7 +23,7 @@ title: Debug Mode

### 基本调试模式

设置 `conf/debug.yaml` 即可开启基本调试模式:
设置 `conf/debug.yaml` 即可开启基本调试模式

```
basic:
@@ -29,7 +29,7 @@ title: Plugin Config
# 创建 Plugin config
$ curl http://127.0.0.1:9080/apisix/admin/plugin_configs/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
"desc": "吾乃插件配置1",
"desc": "吾乃插件配置 1",
"plugins": {
"limit-count": {
"count": 2,
@@ -62,7 +62,7 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f

```
{
"desc": "吾乃插件配置1",
"desc": "吾乃插件配置 1",
"plugins": {
"ip-restriction": {
"whitelist": [
@@ -27,13 +27,13 @@ APISIX 区别于其他 API 网关的一大特点是允许用户选择不同 Rout

- `apisix.router.http`: HTTP 请求路由。

- `radixtree_uri`: (默认)只使用 `uri` 作为主索引。基于 `radixtree` 引擎,支持全量和深前缀匹配,更多见 [如何使用 router-radixtree](../../../en/latest/router-radixtree.md)。
- `radixtree_uri`(默认)只使用 `uri` 作为主索引。基于 `radixtree` 引擎,支持全量和深前缀匹配,更多见 [如何使用 router-radixtree](../../../en/latest/router-radixtree.md)。
- `绝对匹配`:完整匹配给定的 `uri` ,比如 `/foo/bar``/foo/glo`
- `前缀匹配`:末尾使用 `*` 代表给定的 `uri` 是前缀匹配。比如 `/foo*`,则允许匹配 `/foo/``/foo/a``/foo/b`等。
- `匹配优先级`:优先尝试绝对匹配,若无法命中绝对匹配,再尝试前缀匹配。
- `任意过滤属性`:允许指定任何 Nginx 内置变量作为过滤条件,比如 URL 请求参数、请求头、cookie 等。
- `radixtree_uri_with_parameter`: 同 `radixtree_uri` 但额外有参数匹配的功能。
- `radixtree_host_uri`: 使用 `host + uri` 作为主索引(基于 `radixtree` 引擎),对当前请求会同时匹配 host 和 uri,支持的匹配条件与 `radixtree_uri` 基本一致。
- `radixtree_host_uri`使用 `host + uri` 作为主索引(基于 `radixtree` 引擎),对当前请求会同时匹配 host 和 uri,支持的匹配条件与 `radixtree_uri` 基本一致。

- `apisix.router.ssl`: SSL 加载匹配路由。
- `radixtree_sni`: (默认)使用 `SNI` (Server Name Indication) 作为主索引(基于 radixtree 引擎)。
- `apisix.router.ssl`SSL 加载匹配路由。
- `radixtree_sni`(默认)使用 `SNI` (Server Name Indication) 作为主索引(基于 radixtree 引擎)。
@@ -124,7 +124,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13

#### Consumer

创建一个 consumer 对象:
创建一个 consumer 对象

```shell
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -25,7 +25,7 @@ title: 压力测试

使用谷歌云的服务器进行测试,型号为 n1-highcpu-8 (8 vCPUs, 7.2 GB memory)

我们最多只使用 4 核去运行 APISIX, 剩下的 4 核用于系统和压力测试工具 [wrk](https://github.com/wg/wrk)。
我们最多只使用 4 核去运行 APISIX剩下的 4 核用于系统和压力测试工具 [wrk](https://github.com/wg/wrk)。

### 测试反向代理

@@ -39,13 +39,13 @@ title: 压力测试

#### 延时

请注意 y 轴延时的单位是**微秒(μs)**,而不是毫秒:
请注意 y 轴延时的单位是**微秒(μs)**,而不是毫秒:

![latency-1](../../assets/images/latency-1.jpg)

#### 火焰图

火焰图的采样结果:
火焰图的采样结果

![flamegraph-1](../../assets/images/flamegraph-1.jpg)

@@ -61,11 +61,11 @@ title: 压力测试

#### Latency

请注意 y 轴延时的单位是**微秒(μs)**,而不是毫秒:
请注意 y 轴延时的单位是**微秒(μs)**,而不是毫秒:

![latency-2](../../assets/images/latency-2.jpg)

#### 火焰图

火焰图的采样结果:
火焰图的采样结果
![火焰图采样结果](../../assets/images/flamegraph-2.jpg)
@@ -23,17 +23,17 @@ title: 证书

`APISIX` 支持通过 TLS 扩展 SNI 实现加载特定的 SSL 证书以实现对 https 的支持。

SNI(Server Name Indication)是用来改善 SSL 和 TLS 的一项特性,它允许客户端在服务器端向其发送证书之前向服务器端发送请求的域名,服务器端根据客户端请求的域名选择合适的 SSL 证书发送给客户端。
SNIServer Name Indication是用来改善 SSL 和 TLS 的一项特性,它允许客户端在服务器端向其发送证书之前向服务器端发送请求的域名,服务器端根据客户端请求的域名选择合适的 SSL 证书发送给客户端。

### 单一域名指定

通常情况下一个 SSL 证书只包含一个静态域名,配置一个 `ssl` 参数对象,它包括 `cert``key``sni`三个属性,详细如下:

* `cert`: SSL 密钥对的公钥,pem 格式
* `key`: SSL 密钥对的私钥,pem 格式
* `snis`: SSL 证书所指定的一个或多个域名,注意在设置这个参数之前,你需要确保这个证书对应的私钥是有效的。
* `cert`SSL 密钥对的公钥,pem 格式
* `key`SSL 密钥对的私钥,pem 格式
* `snis`SSL 证书所指定的一个或多个域名,注意在设置这个参数之前,你需要确保这个证书对应的私钥是有效的。

为了简化示例,我们会使用下面的 Python 脚本:
为了简化示例,我们会使用下面的 Python 脚本

```python
#!/usr/bin/env python
@@ -108,7 +108,7 @@ curl --resolve 'test.com:9443:127.0.0.1' https://test.com:9443/hello -vvv
一个 SSL 证书的域名也可能包含泛域名,如 `*.test.com`,它代表所有以 `test.com` 结尾的域名都可以使用该证书。
比如 `*.test.com`,可以匹配 `www.test.com``mail.test.com`
看下面这个例子,请注意我们把 `*.test.com` 作为 sni 传递进来:
看下面这个例子,请注意我们把 `*.test.com` 作为 sni 传递进来
```shell
./ssl.py t.crt t.key '*.test.com'
@@ -86,7 +86,7 @@ APISIX 中一些插件添加了自己的 control API。如果你对他们感兴
}
```

只有启用了的插件才会被包含在返回结果中 `plugins` 部分。(返回结果中的)一些插件可能会缺失如 `consumer_schema` 或者 `type` 字段,这取决于插件的定义。
只有启用了的插件才会被包含在返回结果中 `plugins` 部分。返回结果中的一些插件可能会缺失如 `consumer_schema` 或者 `type` 字段,这取决于插件的定义。

### GET /v1/healthcheck

@@ -31,7 +31,7 @@ title: 调试功能

## 示例

示例1`502` 响应状态码来源于 `Upstream` (IP 地址不可用)
示例 1`502` 响应状态码来源于 `Upstream` (IP 地址不可用)

```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -72,7 +72,7 @@ $ curl http://127.0.0.1:9080/hello -v

具有 `X-APISIX-Upstream-Status: 502` 的响应头。

示例2: `502` 响应状态码来源于 `APISIX`
示例 2:`502` 响应状态码来源于 `APISIX`

```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -106,7 +106,7 @@ Fault Injection!

没有 `X-APISIX-Upstream-Status` 的响应头。

示例3`Upstream` 具有多节点,并且所有节点不可用
示例 3`Upstream` 具有多节点,并且所有节点不可用

```shell
$ curl http://127.0.0.1:9080/apisix/admin/upstreams/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -133,7 +133,7 @@ APISIX 是通过 `upstream.nodes` 来配置上游服务的,所以使用注册
1. 首先要选择状态为 “UP” 的实例: overriddenStatus 值不为 "UNKNOWN" 以 overriddenStatus 为准,否则以 status 的值为准;
2. IP 地址:以 ipAddr 的值为 IP; 并且必须是 IPv4 或 IPv6 格式的;
3. 端口:端口取值规则是,如果 port["@enabled"] 等于 "true" 那么使用 port["\$"] 的值;如果 securePort["@enabled"] 等于 "true" 那么使用 securePort["$"] 的值;
4. 权重:权重取值顺序是,先判断 `metadata.weight` 是否有值,如果没有,则取配置中的 `eureka.weight` 的值, 如果还没有,则取默认值`100`
4. 权重:权重取值顺序是,先判断 `metadata.weight` 是否有值,如果没有,则取配置中的 `eureka.weight` 的值如果还没有,则取默认值`100`

这个例子转成 APISIX nodes 的结果如下:

@@ -176,12 +176,12 @@ discovery:
- "http://${username}:${password}@${eureka_host1}:${eureka_port1}"
- "http://${username}:${password}@${eureka_host2}:${eureka_port2}"
prefix: "/eureka/"
fetch_interval: 30 # 从 eureka 中拉取数据的时间间隔,默认30秒
fetch_interval: 30 # 从 eureka 中拉取数据的时间间隔,默认 30 秒
weight: 100 # default weight for node
timeout:
connect: 2000 # 连接 eureka 的超时时间,默认2000ms
send: 2000 # 向 eureka 发送数据的超时时间,默认2000ms
read: 5000 # 从 eureka 读数据的超时时间,默认5000ms
connect: 2000 # 连接 eureka 的超时时间,默认 2000ms
send: 2000 # 向 eureka 发送数据的超时时间,默认 2000ms
read: 5000 # 从 eureka 读数据的超时时间,默认 5000ms
```

通过 `discovery.eureka.host` 配置 eureka 的服务器地址。

0 comments on commit 96838b9

Please sign in to comment.