Skip to content

Commit 59a95e2

Browse files
F-cqF-cq
authored
docs(sdks/apigw-manager): 新增插件补充文档 (TencentBlueKing#229)
1 parent 67dd553 commit 59a95e2

3 files changed

Lines changed: 198 additions & 29 deletions

File tree

‎sdks/apigw-manager/docs/plugin-use-guide.md‎

Lines changed: 196 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,18 @@
55
> 用户之前在页面创建的插件配置，不过 yaml 如果没有配置上一次 yaml 配置的插件，则会移除上一次 yaml 配置的插件。
66
> `CORS` 插件和 `IP 访问保护插件` 不推荐在 yaml 配置绑定在环境上。
77
8-
## 1. 跨域资源共享（CORS）插件
8+
## 1. 跨域资源共享（CORS）插件 （配置支持：资源/环境）
99

1010
### 1.1 参数说明
1111

12-
| 参数 | 类型 | 默认值 | 描述 |
13-
| ---------------- | ------ | ------ | ------------------------------------------------------------ |
14-
| allow_origins | 字符串 | "" | 允许跨域访问的 Origin，可以使用 * 表示允许所有 Origin 通过。 |
15-
| allow_methods | 字符串 | "**" | 允许跨域访问的 Method，可以使用 * 表示允许所有 Method 通过。 |
16-
| allow_headers | 字符串 | "**" | 允许跨域访问时请求方携带的 Header，可以使用 * 表示允许所有 Header 通过。 |
17-
| expose_headers | 字符串 | "" | 允许跨域访问时响应方携带的 Header，可以使用 * 表示允许任意 Header。 |
18-
| max_age | 整数 | 86400 | 浏览器缓存 CORS 结果的最大时间，单位为秒。 |
19-
| allow_credential | 布尔值 | true | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。 |
12+
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
13+
| ---------------- |-------|------|---------|-----------------------------------------------|
14+
| allow_origins | 字符串 | 否 | "" | 允许跨域访问的 Origin，可以使用 * 表示允许所有 Origin 通过。 |
15+
| allow_methods | 字符串 | 是 | "**" | 允许跨域访问的 Method，可以使用 * 表示允许所有 Method 通过。 |
16+
| allow_headers | 字符串 | 是 | "**" | 允许跨域访问时请求方携带的 Header，可以使用 * 表示允许所有 Header 通过。 |
17+
| expose_headers | 字符串 | 否 | "" | 允许跨域访问时响应方携带的 Header，可以使用 * 表示允许任意 Header。 |
18+
| max_age | 整数 | 是 | 86400 | 浏览器缓存 CORS 结果的最大时间，单位为秒。 |
19+
| allow_credential | 布尔值 | 否 | true | 是否允许跨域访问的请求方携带凭据（如 Cookie 等）。 |
2020

2121
### 1.2 配置例子
2222

@@ -31,14 +31,14 @@
3131
allow_credential: false
3232
```
3333
34-
## 2. Header 转换插件
34+
## 2. Header 转换插件 （配置支持：资源/环境）
3535
3636
### 2.1 参数说明
3737
38-
| 参数 | 类型 | 默认值 | 描述 |
39-
| ------ | ---- | ------ | ---------------------------- |
40-
| set | 数组 | [] | 设置的请求头，包括键和值。 |
41-
| remove | 数组 | [] | 删除的请求头，只需要提供键。 |
38+
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
39+
| ------ | ---- |-----| ------ | ---------------------------- |
40+
| set | 数组 | 否 | [] | 设置的请求头，包括键和值。 |
41+
| remove | 数组 | 否 | [] | 删除的请求头，只需要提供键。 |
4242
4343
### 2.2 配置例子
4444
@@ -51,15 +51,15 @@
5151
remove: []
5252
```
5353
54-
## 3. IP 访问保护插件
54+
## 3. IP 访问保护插件 （配置支持：资源/环境）
5555
5656
### 3.1 参数说明
5757
58-
| 参数 | 类型 | 默认值 | 描述 |
59-
| --------- | ------ | ------ | -------------------------------------- |
60-
| whitelist | 字符串 | "" | 白名单中的 IP 地址，支持 CIDR 表示法。 |
61-
| blacklist | 字符串 | "" | 黑名单中的 IP 地址，支持 CIDR 表示法。 |
62-
| message | 字符串 | "" | 当 IP 地址不被允许时显示的消息。 |
58+
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
59+
| --------- | ------ |-----| ------ | -------------------------------------- |
60+
| whitelist | 字符串 | 否 | "" | 白名单中的 IP 地址，支持 CIDR 表示法。 |
61+
| blacklist | 字符串 | 否 | "" | 黑名单中的 IP 地址，支持 CIDR 表示法。 |
62+
| message | 字符串 | 否 | "" | 当 IP 地址不被允许时显示的消息。 |
6363
6464
### 3.2 配置例子
6565
@@ -71,16 +71,16 @@
7171
message: 'Your IP is not allowed'
7272
```
7373
74-
## 4. 频率控制插件
74+
## 4. 频率控制插件 （配置支持：资源/环境）
7575
7676
### 4.1 参数说明
7777
78-
| 参数 | 类型 | 默认值 | 描述 |
79-
| ----------- | ------ | ------ | ------------------------------------------------ |
80-
| rates | 对象 | {} | 包含默认频率限制和特殊应用频率限制的对象。 |
81-
| default | 对象 | {} | 单个应用的默认频率限制，包括次数和时间范围。 |
82-
| specials | 数组 | [] | 特殊应用频率限制，对指定应用设置单独的频率限制。 |
83-
| bk_app_code | 字符串 | "" | 蓝鲸应用 ID，用于特殊应用频率限制。 |
78+
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
79+
| ----------- | ------ |-----| ------ | ------------------------------------------------ |
80+
| rates | 对象 | 是 | {} | 包含默认频率限制和特殊应用频率限制的对象。 |
81+
| default | 对象 | 是 | {} | 单个应用的默认频率限制，包括次数和时间范围。 |
82+
| specials | 数组 | 否 | [] | 特殊应用频率限制，对指定应用设置单独的频率限制。 |
83+
| bk_app_code | 字符串 | 否 | "" | 蓝鲸应用 ID，用于特殊应用频率限制。 |
8484
8585
### 4.2 配置例子
8686
@@ -92,3 +92,172 @@
9292
- period: 1
9393
tokens: 100
9494
```
95+
96+
## 5. mocking 插件（配置支持：资源）
97+
98+
### 5.1 参数说明
99+
100+
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
101+
|-----------------------|-----|-----|-----|--------|
102+
| response_example | 字符串 | 否 | "" | 响应体。 |
103+
| response_headers | 对象 | 否 | {} | 响应头。 |
104+
| response_status | 整数 | 否 | 200 | 响应状态码。 |
105+
106+
### 5.2 配置例子
107+
108+
```yaml
109+
- type: bk-mock
110+
yaml: |-
111+
response_example: ''
112+
response_headers:
113+
- key: key1
114+
value: value1
115+
response_status: 200
116+
```
117+
118+
## 6. API 熔断插件 （配置支持：资源）
119+
120+
### 6.1 参数说明
121+
122+
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
123+
|-------------------------|-----|-----|-----|----------------------------------|
124+
| break_response_body | 字符串 | 否 | "" | 当上游服务处于不健康状态时返回的 HTTP 响应体信息。 |
125+
| break_response_headers | 对象 | 否 | {} | 当上游服务处于不健康状态时返回的 HTTP 响应头信息。 |
126+
| unhealthy | 对象 | 否 | {} | 当上游服务处于不健康状态时的 HTTP 的状态码和异常请求次数。 |
127+
| unhealthy.http_statuses | 数组 | 否 | [] | 不健康状态码列表。 |
128+
| unhealthy.failures | 整数 | 否 | 3 | 触发不健康状态的异常请求次数。 |
129+
| healthy | 对象 | 否 | {} | 上游服务处于健康状态时的 HTTP 状态码和连续正常请求次数。 |
130+
| healthy.http_statuses | 数组 | 否 | [] | 健康状态码列表。 |
131+
| healthy.successes | 整数 | 否 | 3 | 触发健康状态的连续正常请求次数。 |
132+
| break_response_code | 整数 | 是 | 502 | 当上游服务处于不健康状态时返回的 HTTP 错误码。 |
133+
| max_breaker_sec | 整数 | 否 | 300 | 上游服务熔断的最大持续时间，以秒为单位，最小 3 秒。 |
134+
135+
### 6.2 配置例子
136+
137+
```yaml
138+
- type: api-breaker
139+
yaml: |-
140+
break_response_body: ''
141+
break_response_headers:
142+
- key: key1
143+
value: value1
144+
unhealthy:
145+
http_statuses:
146+
- 500
147+
successes: 3
148+
healthy:
149+
http_statuses:
150+
- 200
151+
failures: 3
152+
break_response_code: 502
153+
max_breaker_sec: 300
154+
```
155+
156+
157+
## 7. 故障注入插件 （配置支持：资源）
158+
159+
### 7.1 参数说明
160+
161+
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
162+
|-------------------|---------|------|---|-----------------------|
163+
| abort | 对象 | 否 | {} | 中断状态。 |
164+
| abort.http_status | 整数 | 是 | | 返回给客户端的 HTTP 状态码。 |
165+
| abort.body | 字符串 | 否 | "" | 返回给客户端的 HTTP 状态码。 |
166+
| abort.percentage | 整数 | 否 | | 将被中断的请求占比。 |
167+
| abort.vars | 字符串 | 否 | "" | 执行故障注入的规则，当规则匹配通过后才会执行故障注。 |
168+
| delay | 对象 | 否 | {} | 延迟状态。 |
169+
| delay.duration | 小数 | 是 | | 延迟时间，可以指定小数。 |
170+
| delay.percentage | 整数 | 否 | | 将被延迟的请求占比。 |
171+
| delay.vars | 字符串 | 否 | "" | 执行请求延迟的规则，当规则匹配通过后才会延迟请求。 |
172+
173+
### 7.2 配置例子
174+
175+
```yaml
176+
- type: fault-injection
177+
yaml: |-
178+
abort:
179+
http_status: 503
180+
body: ''
181+
percentage: 50
182+
vars: ''
183+
unhealthy:
184+
duration: 3
185+
percentage: 30
186+
vars: ''
187+
```
188+
189+
## 8. 请求校验插件 （配置支持：资源）
190+
191+
### 8.1 参数说明
192+
193+
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
194+
|----------------|-----|-----|------|-----------------------------------|
195+
| body_schema | 字符串 | 否 | "" | request body 数据的 JSON Schema。 |
196+
| header_schema | 字符串 | 否 | "" | request header 数据的 JSON Schema。 |
197+
| rejected_msg | 字符串 | 否 | "" | 拒绝信息。 |
198+
| rejected_code | 整数 | 否 | 400 | 拒绝状态码。 |
199+
200+
### 8.2 配置例子
201+
202+
```yaml
203+
- type: request-validation
204+
yaml: |-
205+
body_schema: \'{"type": "object"}\'
206+
body_schema: \'{"type": "object"}\'
207+
rejected_msg: ''
208+
rejected_code: 400
209+
```
210+
211+
## 9. Response 转换插件 （配置支持：资源）
212+
213+
### 9.1 参数说明
214+
215+
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
216+
|-------------|-----|-----|-------|--------------------------------------------------------------------|
217+
| status_code | 整数 | 否 | | 修改上游返回状态码，默认保留原始响应代码。 |
218+
| body | 字符串 | 否 | "" | 修改上游返回的 body 内容，如果设置了新内容，header 里面的 content-length 字段也会被去掉。 |
219+
| vars | 字符串 | 否 | "" | vars 是一个表达式列表，只有满足条件的请求和响应才会修改 body 和 header 信息，来自 lua-resty-expr。 |
220+
| body_base64 | 布尔值 | 否 | false | 当设置时，在写给客户端之前，在body中传递的主体将被解码，这在一些图像和 Protobuffer 场景中使用。 |
221+
| headers | 对象 | 否 | {} | 处理响应头。 |
222+
| headers.add | 数组 | 否 | [] | 添加新的响应头，只需要提供键。格式为 ["name: value", ...]。 |
223+
| headers.set | 数组 | 否 | [] | 改写响应头，包括键和值。 格式为 {"name": "value", ...}。 |
224+
| headers.remove | 数组 | 否 | [] | 移除响应头，只需要提供键。 格式为 ["name", ...]。 |
225+
226+
### 9.2 配置例子
227+
228+
```yaml
229+
- type: response-rewrite
230+
yaml: |-
231+
status_code: 200
232+
body: ''
233+
vars: ''
234+
body_base64: false
235+
headers:
236+
add:
237+
- key: 'key1: value1'
238+
remove:
239+
- key: key1
240+
set:
241+
- key: key1
242+
value: value1
243+
```
244+
245+
246+
## 10. 重定向插件 （配置支持：资源）
247+
248+
### 10.1 参数说明
249+
250+
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
251+
|-------------|------|-----|---------|---------------------------|
252+
| uri | 字符串 | 否 | "" | 要重定向到的 URI，可以包含 NGINX 变量。 |
253+
| ret_code | 整数 | 否 | 302 | HTTP 响应码。 |
254+
255+
### 10.2 配置例子
256+
257+
```yaml
258+
- type: redirect
259+
yaml: |-
260+
uri: ''
261+
ret_code: 302
262+
```
263+

‎sdks/apigw-manager/src/apigw_manager/plugin/config.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -616,7 +616,7 @@ def build_response_rewrite_validation(
616616
for k, v in headers.add.items():
617617
if ":" in k:
618618
raise ValueError(f"key {k} can not contain ':'")
619-
add_data.append({"key": "{}:{}".format(k, v)})
619+
add_data.append({"key": "{}: {}".format(k, v)})
620620

621621
set_data = []
622622
for k, v in headers.set.items():

‎sdks/apigw-manager/tests/apigw_manager/plugin/test_config.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -502,7 +502,7 @@ def test_build_request_validation(
502502
"body_base64: false\n"
503503
"headers:\n"
504504
" add:\n"
505-
" - key: key1:value1\n"
505+
" - key: 'key1: value1'\n"
506506
" remove:\n"
507507
" - key: key1\n"
508508
" set:\n"

0 commit comments

Comments
 (0)