This is an automated email from the ASF dual-hosted git repository.
Alanxtl pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/dubbo-website.git
The following commit(s) were added to refs/heads/master by this push:
new 0a801bafc76 docs(golang-sdk): improve Script Router usage and
verification docs (#3228)
0a801bafc76 is described below
commit 0a801bafc76be241088358255924f94f3e5baeb8
Author: XiaoFei <[email protected]>
AuthorDate: Mon Aug 24 21:00:49 2026 +0800
docs(golang-sdk): improve Script Router usage and verification docs (#3228)
---
.../golang-sdk/tutorial/traffic/script_router.md | 106 ++++++++++++++++++---
.../golang-sdk/tutorial/traffic/script_router.md | 105 ++++++++++++++++----
2 files changed, 180 insertions(+), 31 deletions(-)
diff --git
a/content/en/overview/mannual/golang-sdk/tutorial/traffic/script_router.md
b/content/en/overview/mannual/golang-sdk/tutorial/traffic/script_router.md
index 218a0b626a5..524166fea76 100644
--- a/content/en/overview/mannual/golang-sdk/tutorial/traffic/script_router.md
+++ b/content/en/overview/mannual/golang-sdk/tutorial/traffic/script_router.md
@@ -7,28 +7,58 @@ weight: 1
Sample source: <a
href="https://github.com/apache/dubbo-go-samples/tree/main/router/script";
target="_blank">dubbo-go-samples/router/script</a>.
-## How to use
+Script Router runs on the consumer and uses a JavaScript script to filter
candidate providers. It currently supports application-scoped dynamic rules.
Use it when routing decisions depend on runtime information such as a provider
URL, RPC method, or invocation attachment, for example to pin traffic to a port
or select instances by tenant or gray-release marker.
-### Prerequisites
+For simple matching by address, method, or application name, prefer Condition
Router. Script Router is more expressive, but scripts cost more to execute and
maintain. Keep production scripts small and verify that they always return
callable providers.
-- Docker and Docker Compose environment to deploy Nacos registry.
-- Nacos Version 2.x+
-- Go 1.23+
+## Prerequisites
-#### Run Nacos
+- Docker and Docker Compose to run Nacos.
+- Nacos 2.x or later.
+- Go 1.23 or later.
+- The `dubbo-go-samples/router/script` sample.
-Follow this instruction
-to [install and start Nacos
server](https://dubbo-next.staged.apache.org/zh-cn/overview/reference/integrations/nacos/).
+### Start Nacos
-### Script router
+Follow the [Nacos quick
start](https://dubbo-next.staged.apache.org/zh-cn/overview/reference/integrations/nacos/)
to start Nacos. This sample uses `127.0.0.1:8848` for both the registry and
configuration center.
-Similar to the condition router, the script router enables traffic control
using expressions. However,
-while it offers more powerful matching capabilities, this comes at the cost of
higher resource consumption.
-Therefore, it should be used sparingly in production environments.
+## Script arguments
-The example code for the script router is similar to that of the condition
router,
-with slight differences in the Nacos configuration.
-Therefore, only the Nacos configuration is provided here.
+The route script receives `invokers`, `invocation`, and `context`. It must
return an array containing the selected original candidates.
+
+| Argument | Description | Common use |
+| --- | --- | --- |
+| `invokers` | The currently available provider candidates. Call `GetURL()` on
each item to read its service URL. | Filter instances by URL port, address, or
parameter. |
+| `invocation` | Information about the current RPC call. | Route by method
name, arguments, or attachments. |
+| `context` | The context of the current call. | Read call-chain context when
the script needs it. |
+
+The following script keeps only the provider on port `20000`:
+
+```javascript
+(function(invokers, invocation, context) {
+ if (!invokers || invokers.length === 0) return [];
+ return invokers.filter(function(invoker) {
+ var url = invoker.GetURL();
+ return url && url.Port === "20000";
+ });
+})(invokers, invocation, context);
+```
+
+## Configure Script Router
+
+The sample consumer connects to the Nacos configuration center through
`dubbo.WithConfigCenter`. After the providers start, Script Router subscribes
to the rule for the provider application.
+
+Create the following configuration in Nacos:
+
+| Setting | Value |
+| --- | --- |
+| Data ID | `script-server.script-router` |
+| Group | `DEFAULT_GROUP` |
+| Format | `YAML` |
+
+The Data ID format is `{provider application name}.script-router`. Both
providers in this sample use `script-server` as their application name, so the
Data ID is `script-server.script-router`; `key` must use the same application
name.
+
+Save the following content in Nacos:
```yaml
scope: "application"
@@ -44,3 +74,49 @@ script: |
});
})(invokers, invocation, context);
```
+
+Field descriptions:
+
+| Field | Description |
+| --- | --- |
+| `scope` | The Script Router scope; use `application`. |
+| `key` | The application name of the target provider. |
+| `enabled` | Whether to enable the rule; `false` skips script execution. |
+| `type` | The script type; the sample uses `javascript`. |
+| `script` | The JavaScript script that returns the filtered provider list. |
+
+## Run and verify
+
+Open three terminals in the `dubbo-go-samples/router/script` directory.
+
+Start both providers first:
+
+```bash
+go run ./go-server/cmd/server.go # port 20000
+go run ./go-node2-server/cmd/server_node2.go # port 20001
+```
+
+Then start the consumer:
+
+```bash
+go run ./go-client/cmd/client.go
+```
+
+The consumer calls `Greet` every five seconds. Before the rule is published in
Nacos, responses alternate between providers on `20000` and `20001`. After
saving the rule, the consumer does not need to restart and subsequent logs
should only contain port `20000`:
+
+```text
+receive: hello world from: 20000
+```
+
+Delete the Nacos configuration or set `enabled` to `false` to allow calls to
route to both providers again. If the rule does not take effect, check the Data
ID, Group, configuration-center connection, and script return value.
+
+## Script Router vs. Condition Router
+
+| Aspect | Script Router | Condition Router |
+| --- | --- | --- |
+| Rule expression | JavaScript script | Declarative condition expression such
as `consumer => provider` |
+| Use case | Custom computation, complex filtering, or decisions based on call
information | Common matching by address, method, or application name |
+| Configuration | Nacos dynamic application-scoped rule | Dynamic rules and
static rules declared in code |
+| Cost | Higher execution and maintenance cost; scripts require review |
Simpler and easier to read |
+
+Use Condition Router for ordinary traffic-control requirements first, and use
Script Router only when condition expressions are not sufficient.
diff --git
a/content/zh-cn/overview/mannual/golang-sdk/tutorial/traffic/script_router.md
b/content/zh-cn/overview/mannual/golang-sdk/tutorial/traffic/script_router.md
index 157f91a6661..a5c78432440 100644
---
a/content/zh-cn/overview/mannual/golang-sdk/tutorial/traffic/script_router.md
+++
b/content/zh-cn/overview/mannual/golang-sdk/tutorial/traffic/script_router.md
@@ -7,24 +7,58 @@ weight: 1
示例源码：<a
href="https://github.com/apache/dubbo-go-samples/tree/main/router/script";
target="_blank">dubbo-go-samples/router/script</a>。
-## 使用方法
+Script Router 在消费端通过 JavaScript 脚本筛选候选 Provider，目前支持应用级动态规则。它适合根据 Provider
URL、RPC 方法、调用附件等运行时信息实现自定义路由，例如将流量固定到指定端口、按租户或灰度标识选择实例。
-### 前置准备
+对于只需按地址、方法或应用名进行简单匹配的场景，优先使用 Condition Router。Script Router
的表达能力更强，但脚本执行和维护成本更高，生产环境应限制脚本复杂度，并验证脚本始终返回可调用的 Provider 列表。
-- Docker 以及 Docker compose 环境来部署Nacos配置中心。
-- Nacos 2.x+
-- Go 1.23+
+## 前置准备
-#### 启动Nacos配置中心
+- Docker 和 Docker Compose，用于运行 Nacos。
+- Nacos 2.x+。
+- Go 1.23+。
+- 已下载 `dubbo-go-samples/router/script` 示例。
-参考这个教程来[启动Nacos](https://dubbo-next.staged.apache.org/zh-cn/overview/reference/integrations/nacos/)。
+### 启动 Nacos
-### Script router 介绍
+按照 [Nacos
快速开始](https://dubbo-next.staged.apache.org/zh-cn/overview/reference/integrations/nacos/)
启动 Nacos。示例中的注册中心和配置中心地址均为 `127.0.0.1:8848`。
-Script router与condition router类似，都提供了使用表达式进行流量管控的功能。
-但是Script router具有更强大的匹配功能，与此同时带来的是匹配消耗的资源更多，因此在生产环境中应当尽量少使用。
+## 脚本入参
-Script router的示例代码与Condition router类似，在nacos配置上略有差别，这里仅提供nacos上的简单配置。
+路由脚本以 `invokers`、`invocation`、`context` 三个参数执行，必须返回由原始候选项组成的数组。
+
+| 入参 | 含义 | 常见用法 |
+| --- | --- | --- |
+| `invokers` | 当前可用的候选 Provider 列表。每项可通过 `GetURL()` 获取服务 URL。 | 根据 URL
的端口、地址或参数过滤实例。 |
+| `invocation` | 当前 RPC 调用信息。 | 根据方法名、参数或 attachments 实现按调用维度的路由。 |
+| `context` | 当前调用上下文。 | 在脚本需要时读取调用链路中的上下文信息。 |
+
+下面的脚本只保留端口为 `20000` 的 Provider：
+
+```javascript
+(function(invokers, invocation, context) {
+ if (!invokers || invokers.length === 0) return [];
+ return invokers.filter(function(invoker) {
+ var url = invoker.GetURL();
+ return url && url.Port === "20000";
+ });
+})(invokers, invocation, context);
+```
+
+## 配置 Script Router
+
+示例 consumer 通过 `dubbo.WithConfigCenter` 连接 Nacos 配置中心。启动 Provider 后，Script
Router 会按照 Provider 的应用名订阅规则。
+
+在 Nacos 配置中心新增配置：
+
+| 配置项 | 值 |
+| --- | --- |
+| Data ID | `script-server.script-router` |
+| Group | `DEFAULT_GROUP` |
+| 格式 | `YAML` |
+
+Data ID 的命名规则为 `{provider application name}.script-router`。本示例中两个 Provider 都使用
`script-server` 作为应用名，因此 Data ID 为 `script-server.script-router`；`key`
也必须与该应用名一致。
+
+将以下内容保存到 Nacos：
```yaml
scope: "application"
@@ -41,9 +75,48 @@ script: |
})(invokers, invocation, context);
```
-参数说明:
+字段说明：
+
+| 字段 | 说明 |
+| --- | --- |
+| `scope` | Script Router 使用 `application` 作用域。 |
+| `key` | 规则目标 Provider 的应用名。 |
+| `enabled` | 是否启用规则；设置为 `false` 时不执行脚本。 |
+| `type` | 脚本类型，当前支持 `javascript`。 |
+| `script` | 返回过滤后 Provider 列表的 JavaScript 脚本。 |
+
+## 运行并验证
+
+在 `dubbo-go-samples/router/script` 目录中分别打开三个终端。
+
+先启动两个 Provider：
+
+```bash
+go run ./go-server/cmd/server.go # 端口 20000
+go run ./go-node2-server/cmd/server_node2.go # 端口 20001
+```
+
+再启动 consumer：
+
+```bash
+go run ./go-client/cmd/client.go
+```
+
+consumer 每 5 秒调用一次 `Greet`。未在 Nacos 下发规则时，响应会在 `20000` 和 `20001` 两个 Provider
之间切换。保存上述规则后无需重启 consumer，后续日志应只包含端口 `20000`：
+
+```text
+receive: hello world from: 20000
+```
+
+删除 Nacos 配置或将 `enabled` 改为 `false` 后，调用会恢复为可路由到两个 Provider。若规则未生效，请检查 Data
ID、Group、配置中心连接以及脚本返回值。
+
+## 与 Condition Router 的区别
+
+| 对比项 | Script Router | Condition Router |
+| --- | --- | --- |
+| 规则表达 | JavaScript 脚本 | 声明式条件表达式，例如 `consumer => provider` |
+| 适用场景 | 自定义计算、复杂筛选或基于调用信息决策 | 地址、方法、应用名等常规匹配 |
+| 配置方式 | Nacos 动态应用级规则 | 支持动态规则，也支持代码中的静态规则 |
+| 成本 | 执行和维护成本更高，需要审查脚本 | 规则简单、可读性更高 |
-| 参数 | 说明 |
-|--------|--------------------|
-| type | script的类型，目前仅可使用js |
-| script | script实际内容 |
+因此，应先使用 Condition Router 覆盖常规流量控制需求；只有条件表达式无法满足时，再使用 Script Router。
