You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by ju...@apache.org on 2022/11/28 09:20:01 UTC
[apisix] branch master updated: docs: update consumer-group/router/service/script doc (#8332)
This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 164a3222f docs: update consumer-group/router/service/script doc (#8332)
164a3222f is described below
commit 164a3222fa8ef159a21726fb4a6bd7ab1ccb785c
Author: Fei Han <97...@users.noreply.github.com>
AuthorDate: Mon Nov 28 17:19:56 2022 +0800
docs: update consumer-group/router/service/script doc (#8332)
Co-authored-by: Sylvia <39...@users.noreply.github.com>
---
docs/en/latest/terminology/consumer-group.md | 17 +++-
docs/en/latest/terminology/route.md | 8 +-
docs/en/latest/terminology/router.md | 5 +
docs/en/latest/terminology/service.md | 81 +++++++++-------
docs/zh/latest/config.json | 1 +
.../latest/terminology/consumer-group.md | 46 +++++----
docs/zh/latest/terminology/route.md | 83 ++++++++++++++--
docs/zh/latest/terminology/router.md | 19 +++-
docs/zh/latest/terminology/script.md | 17 +++-
docs/zh/latest/terminology/service.md | 104 +++++++++++++--------
10 files changed, 268 insertions(+), 113 deletions(-)
diff --git a/docs/en/latest/terminology/consumer-group.md b/docs/en/latest/terminology/consumer-group.md
index 8daedf11f..1cb06c3d7 100644
--- a/docs/en/latest/terminology/consumer-group.md
+++ b/docs/en/latest/terminology/consumer-group.md
@@ -26,17 +26,20 @@ description: Consumer Group in Apache APISIX.
#
-->
+## Description
+
Consumer Groups are used to extract commonly used [Plugin](./plugin.md) configurations and can be bound directly to a [Consumer](./consumer.md).
With consumer groups, you can define any number of plugins, e.g. rate limiting and apply them to a set of consumers,
instead of managing each consumer individually.
-While configuring the same plugin for the same route, only one copy of the configuration is valid.
+## Example
The example below illustrates how to create a Consumer Group and bind it to a Consumer:
```shell
-curl http://127.0.0.1:9180/apisix/admin/consumer_groups/company_a -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/consumer_groups/company_a \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"limit-count": {
@@ -50,7 +53,8 @@ curl http://127.0.0.1:9180/apisix/admin/consumer_groups/company_a -H 'X-API-KEY:
```
```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "jack",
"plugins": {
@@ -64,7 +68,12 @@ curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
When APISIX can't find the Consumer Group with the `group_id`, the Admin API is terminated with a status code of `400`.
-If a Consumer already has the `plugins` field configured, the plugins in the Consumer Group will effectively be merged into it. The same plugin in the Consumer Group will not override the one configured directly in the Consumer.
+:::tip
+
+1. When the same plugin is configured in [consumer](./consumer.md), [routing](./route.md), [plugin config](./plugin-config.md) and [service](./service.md), only one configuration is in effect, and the consumer has the highest priority. Please refer to [Plugin](./plugin.md).
+2. If a Consumer already has the `plugins` field configured, the plugins in the Consumer Group will effectively be merged into it. The same plugin in the Consumer Group will not override the one configured directly in the Consumer.
+
+:::
For example, if we configure a Consumer Group as shown below:
diff --git a/docs/en/latest/terminology/route.md b/docs/en/latest/terminology/route.md
index f1d1185a9..896ee6fb5 100644
--- a/docs/en/latest/terminology/route.md
+++ b/docs/en/latest/terminology/route.md
@@ -1,5 +1,10 @@
---
title: Route
+keywords:
+ - API Gateway
+ - Apache APISIX
+ - Route
+description: This article describes the concept of Route and how to use it.
---
<!--
@@ -46,7 +51,8 @@ These shortcomings are independently abstracted in APISIX by two concepts: [Serv
The Route example shown below proxies the request with the URL `/index.html` to the Upstream service with the address `127.0.0.1:1980`.
```shell
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
"uri": "/index.html",
"upstream": {
diff --git a/docs/en/latest/terminology/router.md b/docs/en/latest/terminology/router.md
index 2427396a3..804514f12 100644
--- a/docs/en/latest/terminology/router.md
+++ b/docs/en/latest/terminology/router.md
@@ -1,5 +1,10 @@
---
title: Router
+keywords:
+ - API Gateway
+ - Apache APISIX
+ - Router
+description: This article describes how to choose a router for Apache APISIX.
---
<!--
diff --git a/docs/en/latest/terminology/service.md b/docs/en/latest/terminology/service.md
index 8f37ea429..0e08b890c 100644
--- a/docs/en/latest/terminology/service.md
+++ b/docs/en/latest/terminology/service.md
@@ -31,13 +31,17 @@ The relationship between Routes and a Service is usually N:1 as shown in the ima
As shown, different Routes could be bound to the same Service. This reduces redundancy as these bounded Routes will have the same [Upstream](./upstream.md) and [Plugin](./plugin.md) configurations.
+For more information about Service, please refer to [Admin API Service object](../admin-api.md#service).
+
## Examples
-The following example creates a Service that enables the current-limit Plugin and then binds it to the Routes with the ids `100` and `101`.
+The following example creates a Service that enables the `limit-count` Plugin and then binds it to the Routes with the ids `100` and `101`.
+
+1. Create a Service.
```shell
-# create new Service
-$ curl http://127.0.0.1:9180/apisix/admin/services/200 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/services/200 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"limit-count": {
@@ -54,41 +58,52 @@ $ curl http://127.0.0.1:9180/apisix/admin/services/200 -H 'X-API-KEY: edd1c9f034
}
}
}'
+```
-# create new Route and reference the service by id `200`
-curl http://127.0.0.1:9180/apisix/admin/routes/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "methods": ["GET"],
- "uri": "/index.html",
- "service_id": "200"
-}'
+2. create new Route and reference the service by id `200`
-curl http://127.0.0.1:9180/apisix/admin/routes/101 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "methods": ["GET"],
- "uri": "/foo/index.html",
- "service_id": "200"
-}'
-```
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/100 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "methods": ["GET"],
+ "uri": "/index.html",
+ "service_id": "200"
+ }'
+ ```
-We can also specify different Plugins or Upstream for the Routes than the ones defined in the Service. The example below creates a Route with a limit-count Plugin. This Route will continue to use the other configurations defined in the Service (here, the Upstream configuration).
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/101 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "methods": ["GET"],
+ "uri": "/foo/index.html",
+ "service_id": "200"
+ }'
+ ```
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/102 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "uri": "/bar/index.html",
- "id": "102",
- "service_id": "200",
- "plugins": {
- "limit-count": {
- "count": 2000,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
+We can also specify different Plugins or Upstream for the Routes than the ones defined in the Service. The example below creates a Route with a `limit-count` Plugin. This Route will continue to use the other configurations defined in the Service (here, the Upstream configuration).
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/102 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "uri": "/bar/index.html",
+ "id": "102",
+ "service_id": "200",
+ "plugins": {
+ "limit-count": {
+ "count": 2000,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
}
- }
-}'
-```
+ }'
+ ```
:::note
+
When a Route and a Service enable the same Plugin, the one defined in the Route is given the higher priority.
+
+:::
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index 8f2f3efe8..d6ebe8ca6 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -29,6 +29,7 @@
"items": [
"terminology/api-gateway",
"terminology/consumer",
+ "terminology/consumer-group",
"terminology/global-rule",
"terminology/plugin",
"terminology/plugin-config",
diff --git a/docs/en/latest/terminology/consumer-group.md b/docs/zh/latest/terminology/consumer-group.md
similarity index 50%
copy from docs/en/latest/terminology/consumer-group.md
copy to docs/zh/latest/terminology/consumer-group.md
index 8daedf11f..cda0a9644 100644
--- a/docs/en/latest/terminology/consumer-group.md
+++ b/docs/zh/latest/terminology/consumer-group.md
@@ -1,10 +1,10 @@
---
-title: Consumer Group
+title: Consumer Groups
keywords:
- - API gateway
+ - API 网关
- Apache APISIX
- - Consumer Group
-description: Consumer Group in Apache APISIX.
+ - Consumer Groups
+description: 本文介绍了 Apache APISIX Consumer Group 对象的概念及使用方法。
---
<!--
@@ -26,17 +26,17 @@ description: Consumer Group in Apache APISIX.
#
-->
-Consumer Groups are used to extract commonly used [Plugin](./plugin.md) configurations and can be bound directly to a [Consumer](./consumer.md).
+## 描述
-With consumer groups, you can define any number of plugins, e.g. rate limiting and apply them to a set of consumers,
-instead of managing each consumer individually.
+通过 Consumer Groups，你可以在同一个消费者组中启用任意数量的[插件](./plugin.md)，并在一个或者多个[消费者](./consumer.md)中引用该消费者组。
-While configuring the same plugin for the same route, only one copy of the configuration is valid.
+## 配置示例
-The example below illustrates how to create a Consumer Group and bind it to a Consumer:
+以下示例展示了如何创建消费者组并将其绑定到消费者中。
```shell
-curl http://127.0.0.1:9180/apisix/admin/consumer_groups/company_a -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/consumer_groups/company_a \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"limit-count": {
@@ -50,7 +50,8 @@ curl http://127.0.0.1:9180/apisix/admin/consumer_groups/company_a -H 'X-API-KEY:
```
```shell
-curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/consumers \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "jack",
"plugins": {
@@ -62,13 +63,22 @@ curl http://127.0.0.1:9180/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
}'
```
-When APISIX can't find the Consumer Group with the `group_id`, the Admin API is terminated with a status code of `400`.
+当 APISIX 无法找到 `group_id` 中定义的消费者组时，创建或者更新消费者的请求将会终止，并返回错误码 `404`。
-If a Consumer already has the `plugins` field configured, the plugins in the Consumer Group will effectively be merged into it. The same plugin in the Consumer Group will not override the one configured directly in the Consumer.
+如果消费者已经配置了 `plugins` 字段，那么消费者组中配置的插件将与之合并。
-For example, if we configure a Consumer Group as shown below:
+:::tip
-```json
+此处需要注意两点：
+
+1. 当在同一个插件分别配置在[消费者](./consumer.md)、[路由](./route.md)、[插件配置](./plugin-config.md)和[服务](./service.md)中时，只有一份配置是生效的，并且消费者的优先级最高。更多信息，请参考 [Plugin](./plugin.md)。
+2. 如果消费者和消费者组配置了相同的插件，则消费者中的插件配置优先级更高。对于第一点，因为消费者组需要配置在消费者中，因此你只需关心消费者中插件的优先级。
+
+:::
+
+如下示例，假如你配置了一个消费者组：
+
+```json title=“Consumer Group”
{
"id": "bar",
"plugins": {
@@ -79,9 +89,9 @@ For example, if we configure a Consumer Group as shown below:
}
```
-To a Consumer as shown below.
+并配置了消费者：
-```json
+```json title=“Consumer”
{
"username": "foo",
"group_id": "bar",
@@ -97,4 +107,4 @@ To a Consumer as shown below.
}
```
-Then the `body` in `response-rewrite` keeps `world`.
+那么 `response-rewrite` 中的 `body` 将保留 `world`。
diff --git a/docs/zh/latest/terminology/route.md b/docs/zh/latest/terminology/route.md
index 53ac72f11..097fa9f6d 100644
--- a/docs/zh/latest/terminology/route.md
+++ b/docs/zh/latest/terminology/route.md
@@ -1,5 +1,11 @@
---
title: Route
+keywords:
+ - API 网关
+ - Apache APISIX
+ - Route
+ - 路由
+description: 本文讲述了路由的概念以及使用方法。
---
<!--
@@ -21,21 +27,78 @@ title: Route
#
-->
-Route 字面意思就是路由，通过定义一些规则来匹配客户端的请求，然后根据匹配结果加载并执行相应的插件，并把请求转发给到指定 Upstream。
+## 描述
-Route 中主要包含三部分内容：匹配规则（比如 uri、host、remote_addr 等），插件配置（限流限速等）和上游信息。
-请看下图示例，是一些 Route 规则的实例，当某些属性值相同时，图中用相同颜色标识。
+Route（也称为路由）是 APISIX 中最基础和最核心的资源对象，APISIX 可以通过路由定义规则来匹配客户端请求，根据匹配结果加载并执行相应的插件，最后将请求转发给到指定的上游服务。
+
+## 配置简介
+
+路由中主要包含三部分内容：
+
+- 匹配规则：比如 `uri`、`host`、`remote_addr` 等等，你也可以自定义匹配规则，详细信息请参考 [Route body 请求参数](../admin-api.md#route-request-body-parameters)。
+- 插件配置：你可以根据业务需求，在路由中配置相应的插件来实现功能。详细信息请参考 [Plugin](./plugin.md) 和 [plugin-config](./plugin-config.md)。
+- 上游信息：路由会根据配置的负载均衡信息，将请求按照规则转发至相应的上游。详细信息请参考 [Upstream](./upstream.md)。
+
+下图示例是一些 Route 规则的实例，当某些属性值相同时，图中用相同颜色标识。
-我们直接在 Route 中完成所有参数的配置，优点是容易设置，每个 Route 都相对独立自由度比较高。但当我们的 Route 有比较多的重复配置（比如启用相同的插件配置或上游信息），一旦我们要更新这些相同属性时，就需要遍历所有 Route 并进行修改，给后期管理维护增加不少复杂度。
+你可以在路由中完成所有参数的配置，该方式设置容易设置，每个路由的相对独立自由度比较高。示例如下：
+
+```shell
+curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "plugins": {
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key_type": "var",
+ "key": "remote_addr"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
+
+当你的路由中有比较多的重复配置（比如启用相同的插件配置或上游信息），你也可以通过配置 [Service](service.md) 和 [Upstream](upstream.md) 的 ID 或者其他对象的 ID 来完成路由配置。示例如下：
+
+```shell
+curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "plugin_config_id": "123456789apacheapisix",
+ "upstream_id": "1"
+}'
+```
-上面提及重复的缺点在 APISIX 中独立抽象了 [Service](service.md) 和 [Upstream](upstream.md) 两个概念来解决。
+:::tip 提示
-下面创建的 Route 示例，是把 URL 为 "/index.html" 的请求代理到地址为 "127.0.0.1:1980" 的 Upstream 服务：
+APISIX 所有的资源对象的 ID，均使用字符串格式，如果使用的上游 ID、服务 ID 或其他资源对象的 ID 大于 14 个字符时，请务必使用字符串形式表示该资源对象。例如：
+
+```json
+ "plugin_config_id": "1234a67891234apisix",
+ "service_id": "434199918991639234",
+ "upstream_id": "123456789123456789"
+```
+
+:::
+
+## 配置示例
+
+以下示例创建的路由，是把 URI 为 `/index.html` 的请求代理到地址为 `127.0.0.1:1980` 的上游服务。
```shell
-$ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
{
"uri": "/index.html",
"upstream": {
@@ -45,7 +108,9 @@ $ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f
}
}
}'
+```
+```shell
HTTP/1.1 201 Created
Date: Sat, 31 Aug 2019 01:17:15 GMT
Content-Type: text/plain
@@ -56,6 +121,6 @@ Server: APISIX web server
{"node":{"value":{"uri":"\/index.html","upstream":{"nodes":{"127.0.0.1:1980":1},"type":"roundrobin"}},"createdIndex":61925,"key":"\/apisix\/routes\/1","modifiedIndex":61925}}
```
-当我们接收到成功应答，表示该 Route 已成功创建。
+当接收到成功应答后，表示该路由已成功创建。
-有关 Route 的具体选项，可具体查阅 [Admin API 之 Route](../admin-api.md#route)。
+更多信息，请参考 [Admin API 的 Route 对象](../admin-api.md#route)。
diff --git a/docs/zh/latest/terminology/router.md b/docs/zh/latest/terminology/router.md
index 92b2637c9..3bfaf4256 100644
--- a/docs/zh/latest/terminology/router.md
+++ b/docs/zh/latest/terminology/router.md
@@ -1,5 +1,10 @@
---
title: Router
+keywords:
+ - API 网关
+ - Apache APISIX
+ - Router
+description: 本文介绍了如何选择 Apache APISIX 的 Router。
---
<!--
@@ -21,19 +26,25 @@ title: Router
#
-->
+## 描述
+
APISIX 区别于其他 API 网关的一大特点是允许用户选择不同 Router 来更好匹配自由业务，在性能、自由之间做最适合选择。
-在本地配置 `conf/config.yaml` 中设置最符合自身业务需求的路由。
+你可以通过配置 `conf/config.yaml` 文件，来设置符合自身业务需求的路由。
+
+## 配置简介
+
+Router 具有以下配置：
- `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_uri_with_parameter`：同 `radixtree_uri` 但额外有参数匹配的功能。
+ - `radixtree_host_uri`：使用 `host + uri` 作为主索引（基于 `radixtree` 引擎），对当前请求会同时匹配 `host` 和 `uri`，支持的匹配条件与 `radixtree_uri` 基本一致。
- `apisix.router.ssl`：SSL 加载匹配路由。
- `radixtree_sni`：（默认）使用 `SNI` (Server Name Indication) 作为主索引（基于 radixtree 引擎）。
diff --git a/docs/zh/latest/terminology/script.md b/docs/zh/latest/terminology/script.md
index 7784c42d7..3e1820ec4 100644
--- a/docs/zh/latest/terminology/script.md
+++ b/docs/zh/latest/terminology/script.md
@@ -1,5 +1,10 @@
---
title: Script
+keywords:
+ - API 网关
+ - Apache APISIX
+ - Router
+description: 本文介绍了 Apache APISIX Script 的使用方法及注意事项。
---
<!--
@@ -21,15 +26,17 @@ title: Script
#
-->
-`Script` 表示将在 `HTTP` 请求/响应生命周期期间执行的脚本。
+## 描述
-`Script` 配置可直接绑定在 `Route` 上。
+Script 表示将在 `HTTP` 请求/响应生命周期期间执行的脚本。
-`Script` 与 `Plugin` 互斥，且优先执行 `Script` ，这意味着配置 `Script` 后，`Route` 上配置的 `Plugin` 将不被执行。
+Script 配置需要绑定在路由上。
-理论上，在 `Script` 中可以写任意 lua 代码，也可以直接调用已有插件以重用已有的代码。
+Script 与 Plugin 不兼容，并且 Script 优先执行 Script，这意味着配置 Script 后，Route 上配置的 Plugin 将**不被执行**。
-`Script` 也有执行阶段概念，支持 `access`、`header_filter`、`body_filter` 和 `log` 阶段。系统会在相应阶段中自动执行 `Script` 脚本中对应阶段的代码。
+理论上，在 Script 中可以编写任意 Lua 代码，你也可以直接调用已有的插件以复用已有的代码。
+
+Script 也有执行阶段概念，支持 `access`、`header_filter`、`body_filter` 和 `log` 阶段。系统会在相应阶段中自动执行 `Script` 脚本中对应阶段的代码。
```json
{
diff --git a/docs/zh/latest/terminology/service.md b/docs/zh/latest/terminology/service.md
index 6f34fee91..0a78fcea9 100644
--- a/docs/zh/latest/terminology/service.md
+++ b/docs/zh/latest/terminology/service.md
@@ -1,5 +1,10 @@
---
title: Service
+keywords:
+ - API 网关
+ - Apache APISIX
+ - Router
+description: 本文介绍了 Apache APISIX Service 对象的概念及其使用方法。
---
<!--
@@ -21,55 +26,72 @@ title: Service
#
-->
-`Service` 是某类 API 的抽象（也可以理解为一组 Route 的抽象）。它通常与上游服务抽象是一一对应的，`Route`
-与 `Service` 之间，通常是 N:1 的关系，参看下图。
+## 描述
+
+Service（也称之为服务）是某类 API 的抽象（也可以理解为一组 Route 的抽象）。它通常与上游服务抽象是一一对应的，但与路由之间，通常是 1:N 即一对多的关系。参看下图。
-不同 Route 规则同时绑定到一个 Service 上，这些 Route 将具有相同的上游和插件配置，减少冗余配置。
+不同路由规则同时绑定到一个服务上，这些路由将具有相同的上游和插件配置，减少冗余配置。当路由和服务都开启同一个插件时，路由中的插件优先级高于服务中的插件。关于插件优先级的更多信息，请参考 [Plugin](./plugin.md)。
-比如下面的例子，创建了一个启用限流插件的 Service，然后把 id 为 `100`、`101` 的 Route 都绑定在这个 Service 上。
+更多关于 Service 的信息，请参考 [Admin API 的 Service 对象](../admin-api.md#service)。
-```shell
-# create new Service
-$ curl http://127.0.0.1:9180/apisix/admin/services/200 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "limit-count": {
- "count": 2,
- "time_window": 60,
- "rejected_code": 503,
- "key": "remote_addr"
- }
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:1980": 1
+## 配置示例
+
+以下示例创建了一个启用限流插件的服务，并且将该服务绑定到 ID 为 `100` 和 `101` 的路由上。
+
+1. 创建服务。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/services/200 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "plugins": {
+ "limit-count": {
+ "count": 2,
+ "time_window": 60,
+ "rejected_code": 503,
+ "key": "remote_addr"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
}
- }
-}'
+ }'
+ ```
-# create new Route and reference the service by id `200`
-curl http://127.0.0.1:9180/apisix/admin/routes/100 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "methods": ["GET"],
- "uri": "/index.html",
- "service_id": "200"
-}'
+2. 创建 ID 为 `100` 的路由，并绑定 ID 为 `200` 的服务。
-curl http://127.0.0.1:9180/apisix/admin/routes/101 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "methods": ["GET"],
- "uri": "/foo/index.html",
- "service_id": "200"
-}'
-```
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/100 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "methods": ["GET"],
+ "uri": "/index.html",
+ "service_id": "200"
+ }'
+ ```
+
+3. 创建 ID 为 `101` 的路由，并绑定 ID 为 `200` 的服务。
+
+ ```shell
+ curl http://127.0.0.1:9180/apisix/admin/routes/101 \
+ -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "methods": ["GET"],
+ "uri": "/foo/index.html",
+ "service_id": "200"
+ }'
+ ```
-当然我们也可以为 Route 指定不同的插件参数或上游，比如下面这个 Route 设置了不同的限流参数，其他部分（比如上游）则继续使用 Service 中的配置参数。
+当然你也可以为路由指定不同的插件配置或上游。比如在以下示例中，我们设置了不同的限流参数，其他部分（比如上游）则继续使用上述服务中的配置参数。
```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/102 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9180/apisix/admin/routes/102 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/bar/index.html",
"id": "102",
@@ -85,4 +107,8 @@ curl http://127.0.0.1:9180/apisix/admin/routes/102 -H 'X-API-KEY: edd1c9f034335f
}'
```
-注意：当 Route 和 Service 都开启同一个插件时，Route 中的插件参数会优先于 Service 被使用。
+:::tip 提示
+
+当路由和服务都启用同一个插件时，路由中的插件配置会优先于服务。更多信息，请参考[Plugin](./plugin.md)。
+
+:::