Skip to content

Commit 1419c7c

Browse files
AetheranceAetherance
authored
docs(golang): add static router config docs for tag and condition router (#3202)
* docs(golang): add static router api docs for tag and condition router * docs(golang): update static router sample links to main --------- Co-authored-by: Aetherance <inkToAether@gmail.com>
1 parent 6d8c7c7 commit 1419c7c

File tree

4 files changed

+185
-5
lines changed

4 files changed

+185
-5
lines changed

‎content/en/overview/mannual/golang-sdk/tutorial/traffic/condition_router.md‎

Lines changed: 42 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ ins, err := dubbo.NewInstance(
6464
rep, err := srv.Greet(context.Background(), &greet.GreetRequest{Name: "hello world"})
6565
```
6666

67-
> A configuration in Nacos is needed if you want to use condition router.
67+
> The example above uses dynamic configuration and requires a config in Nacos or another config center.
6868
6969
Example config:
7070

@@ -85,4 +85,44 @@ conditions:
8585
```
8686
8787
For the complete example, please
88-
see: [Full Example Code](https://github.com/apache/dubbo-go-samples/tree/main/router/condition).
88+
see: [Full Example Code](https://github.com/apache/dubbo-go-samples/tree/main/router/condition).
89+
90+
### Static configuration API
91+
92+
Besides the dynamic approach above, condition router also supports injecting routing rules statically in code. Static configuration does not require a config center, and it can work with direct URLs or with instances discovered from a registry.
93+
94+
The following example shows a service-scope static condition router:
95+
96+
```go
97+
ins, err := dubbo.NewInstance(
98+
dubbo.WithName(clientApplication),
99+
dubbo.WithRouter(
100+
router.WithScope("service"),
101+
router.WithKey(greet.GreetServiceName),
102+
router.WithPriority(100),
103+
router.WithForce(true),
104+
router.WithConditions([]string{
105+
"method = Greet => port = 20000",
106+
}),
107+
),
108+
)
109+
```
110+
111+
Parameters:
112+
113+
- `router.WithScope("service")`: applies the rule at service scope.
114+
- `router.WithKey(greet.GreetServiceName)`: binds the rule to the target service key.
115+
- `router.WithConditions(...)`: declares the static condition expressions.
116+
- `router.WithForce(true)`: controls whether fallback is allowed when the rule does not match.
117+
118+
The static sample in `dubbo-go-samples` uses direct URLs only to keep the example minimal; it does not mean the API is limited to direct-connect scenarios.
119+
120+
For the static example, please
121+
see: [Full Example Code](https://github.com/apache/dubbo-go-samples/tree/main/router/static_config/condition).
122+
123+
### Priority and merge semantics
124+
125+
- Dynamically delivered routing rules override static configuration.
126+
- When `dubbo.WithRouter(...)` is called multiple times, append semantics apply and multiple static router entries are appended to the instance configuration.
127+
- When `router.WithConditions(...)` is set multiple times on the same static router entry, replace semantics apply and the later setting replaces the earlier one.
128+
- Repeatedly injecting the exact same static rule usually leads to the same effective routing result, but the implementation does not compare old and new content and short-circuit as a no-op.

‎content/en/overview/mannual/golang-sdk/tutorial/traffic/tag_router.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,3 +64,54 @@ Parameters:
6464
6565
For the complete example, please
6666
see: [Full Example Code](https://github.com/apache/dubbo-go-samples/tree/main/router/tag).
67+
68+
### Static configuration API
69+
70+
Besides the usage above, tag router also supports injecting routing rules statically in code. Static configuration does not require a config center, and it can work with direct URLs or with instances discovered from a registry.
71+
72+
The following example shows an application-scope static tag router:
73+
74+
```go
75+
ins, err := dubbo.NewInstance(
76+
dubbo.WithName(clientApplication),
77+
dubbo.WithRouter(
78+
router.WithScope("application"),
79+
router.WithKey(clientApplication),
80+
router.WithPriority(100),
81+
router.WithForce(false),
82+
router.WithTags([]global.Tag{
83+
{
84+
Name: "gray",
85+
Addresses: []string{"127.0.0.1:20002"},
86+
},
87+
}),
88+
),
89+
)
90+
```
91+
92+
Request tag attachment:
93+
94+
```go
95+
ctx := context.WithValue(context.Background(), constant.AttachmentKey, map[string]string{
96+
constant.Tagkey: "gray",
97+
})
98+
```
99+
100+
Parameters:
101+
102+
- `router.WithScope("application")`: applies the rule at application scope.
103+
- `router.WithKey(clientApplication)`: binds the rule to the consumer application.
104+
- `router.WithTags(...)`: declares the static mapping from tag to address list.
105+
- `router.WithForce(...)`: controls whether fallback is allowed when no tagged provider matches.
106+
107+
The static sample in `dubbo-go-samples` uses direct URLs only to keep the example minimal; it does not mean the API is limited to direct-connect scenarios.
108+
109+
For the static example, please
110+
see: [Full Example Code](https://github.com/apache/dubbo-go-samples/tree/main/router/static_config/tag).
111+
112+
### Priority and merge semantics
113+
114+
- Dynamically delivered routing rules override static configuration.
115+
- When `dubbo.WithRouter(...)` is called multiple times, append semantics apply and multiple static router entries are appended to the instance configuration.
116+
- When `router.WithTags(...)` is set multiple times on the same static router entry, replace semantics apply and the later setting replaces the earlier one.
117+
- Repeatedly injecting the exact same static rule usually leads to the same effective routing result, but the implementation does not compare old and new content and short-circuit as a no-op.

‎content/zh-cn/overview/mannual/golang-sdk/tutorial/traffic/condition_router.md‎

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ ins, err := dubbo.NewInstance(
6363
rep, err := srv.Greet(context.Background(), &greet.GreetRequest{Name: "hello world"})
6464
```
6565

66-
> 使用condition router必须在nacos等配置中心动态设置匹配规则。
66+
> 上述示例使用的是动态配置方式，需要在nacos等配置中心动态设置匹配规则。
6767
6868
Nacos配置示例:
6969

@@ -84,4 +84,43 @@ conditions:
8484
- match: "port = 20000"
8585
```
8686
87-
完整示例请见: [本示例完整代码](https://github.com/apache/dubbo-go-samples/tree/main/router/condition)。
87+
完整示例请见: [本示例完整代码](https://github.com/apache/dubbo-go-samples/tree/main/router/condition)。
88+
89+
### 静态配置 API
90+
91+
除上面的动态配置方式外，Condition router 也支持通过静态配置 API 在代码中注入路由规则。静态配置不要求配置中心参与，可以配合直连 URL 使用，也可以配合注册中心使用。
92+
93+
下面是一个服务级静态 condition router 的示例：
94+
95+
```go
96+
ins, err := dubbo.NewInstance(
97+
dubbo.WithName(clientApplication),
98+
dubbo.WithRouter(
99+
router.WithScope("service"),
100+
router.WithKey(greet.GreetServiceName),
101+
router.WithPriority(100),
102+
router.WithForce(true),
103+
router.WithConditions([]string{
104+
"method = Greet => port = 20000",
105+
}),
106+
),
107+
)
108+
```
109+
110+
参数：
111+
112+
- `router.WithScope("service")`: 按服务维度生效。
113+
- `router.WithKey(greet.GreetServiceName)`: 指定当前规则作用的服务键。
114+
- `router.WithConditions(...)`: 静态声明 condition router 的匹配表达式。
115+
- `router.WithForce(true)`: 控制规则命中失败时是否允许回退。
116+
117+
`dubbo-go-samples` 中的静态示例使用直连 URL，只是为了最小化演示，不代表该 API 只能用于直连场景。
118+
119+
静态配置示例请见: [本示例完整代码](https://github.com/apache/dubbo-go-samples/tree/main/router/static_config/condition)。
120+
121+
### 规则优先级与合并语义
122+
123+
- 动态配置的路由规则会覆盖静态配置。
124+
- 多次调用 `dubbo.WithRouter(...)` 时，采用 append 语义，多条静态路由会被追加到实例配置中。
125+
- 对同一条静态路由多次设置 `router.WithConditions(...)` 时，采用 replace 语义，后一次设置会替换前一次设置。
126+
- 重复注入完全相同的静态规则时，最终路由结果通常保持一致，但实现上不会先比较新旧内容并短路跳过。

‎content/zh-cn/overview/mannual/golang-sdk/tutorial/traffic/tag_router.md‎

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -60,4 +60,54 @@ resp, err := svc.Greet(ctx, &greet.GreetRequest{Name: name})
6060

6161
> 未携带标签的流量只能打到未携带标签的服务，携带标签的流量则可以打到携带相应标签的服务以及不具有标签的服务（取决于是否配置force参数）。
6262
63-
完整示例请见: [本示例完整代码](https://github.com/apache/dubbo-go-samples/tree/main/router/tag)。
63+
完整示例请见: [本示例完整代码](https://github.com/apache/dubbo-go-samples/tree/main/router/tag)。
64+
65+
### 静态配置 API
66+
67+
除上面的用法外，Tag router 也支持通过静态配置 API 在代码中注入路由规则。静态配置不要求配置中心参与，可以配合直连 URL 使用，也可以配合注册中心使用。
68+
69+
下面是一个应用级静态 tag router 的示例：
70+
71+
```go
72+
ins, err := dubbo.NewInstance(
73+
dubbo.WithName(clientApplication),
74+
dubbo.WithRouter(
75+
router.WithScope("application"),
76+
router.WithKey(clientApplication),
77+
router.WithPriority(100),
78+
router.WithForce(false),
79+
router.WithTags([]global.Tag{
80+
{
81+
Name: "gray",
82+
Addresses: []string{"127.0.0.1:20002"},
83+
},
84+
}),
85+
),
86+
)
87+
```
88+
89+
携带请求 tag：
90+
91+
```go
92+
ctx := context.WithValue(context.Background(), constant.AttachmentKey, map[string]string{
93+
constant.Tagkey: "gray",
94+
})
95+
```
96+
97+
参数：
98+
99+
- `router.WithScope("application")`: 按应用维度生效。
100+
- `router.WithKey(clientApplication)`: 指定当前路由规则绑定的 consumer application。
101+
- `router.WithTags(...)`: 静态声明 tag 到地址列表的映射关系。
102+
- `router.WithForce(...)`: 控制 tag 不匹配时是否允许回退。
103+
104+
`dubbo-go-samples` 中的静态示例使用直连 URL，只是为了最小化演示，不代表静态配置 API 只能用于直连场景。
105+
106+
静态配置示例请见: [本示例完整代码](https://github.com/apache/dubbo-go-samples/tree/main/router/static_config/tag)。
107+
108+
### 规则优先级与合并语义
109+
110+
- 动态配置的路由规则会覆盖静态配置。
111+
- 多次调用 `dubbo.WithRouter(...)` 时，采用 append 语义，多条静态路由会被追加到实例配置中。
112+
- 对同一条静态路由多次设置 `router.WithTags(...)` 时，采用 replace 语义，后一次设置会替换前一次设置。
113+
- 重复注入完全相同的静态规则时，最终路由结果通常保持一致，但实现上不会先比较新旧内容并短路跳过。

0 commit comments

Comments
 (0)
⚡