xiaobaicai66695 commented on issue #1523:
URL: https://github.com/apache/dubbo-admin/issues/1523#issuecomment-5276736296
# Router 规则下发链路实施计划
## 1. 目标
以 `develop` 为实现基线，打通 Router 规则的完整下发与生效链路：
```text
Admin 前端
-> Console API 校验与建模
-> ResourceManager / RuleGovernor
-> Zookeeper / Nacos 配置中心
-> dubbo-go DynamicConfiguration
-> RouterChain 生效
```
同时补齐 Admin 对配置中心规则的回读：
```text
Zookeeper / Nacos
-> Admin config watcher
-> ResourceStore
-> Admin 列表 / 详情
```
本期优先保证规则能够正确创建、更新、删除并真实影响 dubbo-go 路由结果。可靠性和完整治理拆到后续维护阶段。Java
侧只作为协议参考，不属于修改范围。
## 2. develop 基线下的核心缺口
### 2.1 已有 Router 链路仍需修正
- Condition 的 Service Argument Route 在规则不存在时仍走 Update，需要改为 Create/Update
upsert，并处理已有规则 `Spec == nil`。
- Condition 前端生成的规则名需要统一：
- service：`<interface>:<version>:<group>.condition-router`
- application：`<application>.condition-router`
- Tag 只支持 application 粒度，表单和 YAML 页面均应生成
`<provider-application>.tag-router`，不能混入 service/config version 信息。
### 2.2 配置中心公共链路不完整
- ZK 规则目前未按标准 group 写入，应统一为 `/dubbo/config/dubbo/<rule-key>`，并支持自动创建父节点以及
Update 时节点不存在的场景。
- ZK RuleGovernor 和 config watcher 应使用
`Address.ConfigCenter`；registry、mapping、metadata 等 watcher 仍使用各自原有地址。未配置
ConfigCenter 时沿用现有回退到 Registry 的行为。
- ZK watcher 需要同时识别标准规则节点和必要的 legacy 节点，但必须过滤
`/dubbo/config`、`/dubbo/config/dubbo` 等根节点。
- 新规则写入不得顺带删除外部 legacy 配置；legacy 迁移和清理另行处理。
- ZK/Nacos Governor 目前直接序列化内部 proto，无法保证每类 Router 的外部 YAML 契约，需要增加按
`ResourceKind` 分派的 codec。
### 2.3 Affinity 缺少完整 Admin 链路
`develop` 已有 Affinity proto/resource 和少量 console service，但仍缺：
- `AffinityRouteKind` 接入 `RuleResourceKinds`。
- 内部 `affinity` 与外部 YAML `affinityAware` 的双向转换。
- 完整 Console API、ZK subscriber、Nacos watcher/Governor 转换。
- 前端 CRUD 入口。
- 从 Admin 发布到 dubbo-go RouterChain 生效的真实 E2E。
### 2.4 Condition v3.1 缺少无损管理链路
dubbo-go 已有 Condition v3.1 的部分解析和路由能力，Admin 也定义了部分 `ConditionRule/From/To`
辅助结构，但当前主资源、通用响应和配置转换仍主要按 v3.0 的 `[]string` conditions 处理，无法无损保存 v3.1 的结构化
`from/to/weight`。
需要补齐：
- 能同时表达 v3.0 字符串 conditions 和 v3.1 结构化 conditions 的版本化模型。
- v3.1 YAML 的双向无损 codec，回读和再次下发不得降级成 v3.0 字符串。
- Console API 和前端对 v3.1 的创建、编辑、详情展示与版本判别。
- ZK/Nacos 下发和回读对 v3.1 结构的完整保留。
- 从 Admin 发布到 dubbo-go v3.1 Condition Router 生效的 E2E。
### 2.5 Script 缺少完整 Admin 链路
dubbo-go 已实现 Script Router，但 Admin 尚无对应资源和管理能力，需要新增：
- Script proto/resource、ResourceKind 和 `.script-router` suffix。
- Script 外部 YAML codec。
- Console API、ZK/Nacos 发布与回读。
- 前端脚本编辑和 CRUD 入口。
- 从 Admin 发布到 dubbo-go 编译、执行和删除失效的 E2E。
Script 本期遵循 dubbo-go 当前能力边界：只作用于 consumer、只支持 application 粒度、规则名为
`<provider-application>.script-router`，脚本类型只允许已注册的 `javascript`。
## 3. 核心实施计划
### 阶段一：修正公共下发基础和已有规则
- [ ] 修复 Service Argument Route 的 Create/Update upsert，并增加首次创建、已有规则更新和 nil
Spec 测试。
- [ ] 统一 Condition service/application 规则名，补齐前端表单测试。
- [ ] 统一 Tag application 规则名，修复表单和 YAML 页面并补齐测试。
- [ ] 增加配置 group 常量 `dubbo`，ZK 统一写入 `/dubbo/config/dubbo/<rule-key>`。
- [ ] ZK Create 自动创建缺失父节点；Update 在标准节点不存在时完成创建。
- [ ] RuleGovernor 和 config watcher 改用 `Address.ConfigCenter`，并验证 Registry 与
ConfigCenter 分离场景。
- [ ] 过滤 ZK 配置根节点，保留必要的 legacy 只读兼容，但不自动删除 legacy 数据。
- [ ] 建立公共规则编码入口，使 ZK/Nacos 使用同一份外部 YAML。
### 阶段二：补齐 Affinity
外部契约：
| scope | rule key |
| --- | --- |
| service | `<interface>:<version>:<group>.affinity-router` |
| application | `<provider-application>.affinity-router` |
```yaml
configVersion: v3.1
scope: service
key: org.apache.demo.DemoService:1.0.0:demo
enabled: true
runtime: true
affinityAware:
key: region
ratio: 80
```
- [ ] 将 `AffinityRouteKind` 加入 Governor 支持集合。
- [ ] 实现 Affinity encode/decode，确保外部字段为 `affinityAware`，并增加 round-trip 测试。
- [ ] 校验 scope、key、规则名、affinity key 以及 `[0, 100]` 的 ratio。
- [ ] 补齐 search/detail/create/update/delete 的 model、handler、service 和
`/api/v1` 路由。
- [ ] ZK subscriber 增加 `.affinity-router` upsert/delete。
- [ ] Nacos 增加 `*.affinity-router` watcher，并补齐 Governor 回读转换。
- [ ] 增加 Affinity 最小前端 CRUD，支持 service/application 两种 scope。
### 阶段三：补齐 Condition v3.1 无损链路
v3.1 外部结构示例：
```yaml
configVersion: v3.1
scope: service
key: org.apache.demo.DemoService:1.0.0:demo
enabled: true
force: false
runtime: true
conditions:
- from:
match: env=gray
to:
- match: env=gray
weight: 100
- match: env!=gray
weight: 0
```
- [ ] 设计版本化 Condition 内部模型：v3.0 保留 `[]string`，v3.1 保留结构化
`from/to/weight`，两者不能相互覆盖或静默降级。
- [ ] 实现按 `configVersion` 分派的 Condition encode/decode，并增加 v3.0、v3.1 和跨版本
round-trip 测试。
- [ ] 补齐 v3.1 的 scope、key、规则名、from/to、match 和 weight 校验；非法结构必须在写入配置中心前失败。
- [ ] 调整 Condition Console API 的请求、响应和详情逻辑，使 v3.1 结构能够完整创建、更新和查询。
- [ ] 调整 ZK subscriber、Nacos watcher 和 Governor 回读转换，保证外部 v3.1 YAML 进入 Store
后仍保持原结构。
- [ ] 前端按 `configVersion` 切换 v3.0/v3.1 编辑方式；至少支持 v3.1 YAML 创建、编辑和详情展示，不得把结构化
conditions 转成字符串。
- [ ] 保持 Condition v3.0 现有 API 和配置兼容，并增加回归测试。
### 阶段四：新增 Script Router Admin 链路
外部契约：
```text
规则名：<provider-application>.script-router
ZK：/dubbo/config/dubbo/<provider-application>.script-router
Nacos：DataId=<provider-application>.script-router, Group=dubbo
```
```yaml
configVersion: v3.0
scope: application
key: demo-provider
enabled: true
type: javascript
script: |
(function route(invokers, invocation, context) {
return invokers;
})()
```
- [ ] 新增 `ScriptRoute` proto、生成代码、Resource/ResourceList 和 `ScriptRouteKind`。
- [ ] 增加 `.script-router` 常量并接入 suffix set 和 Governor 支持集合。
- [ ] 实现 Script encode/decode 和 round-trip 测试。
- [ ] 后端强制 application scope、`javascript` 类型、非空脚本和脚本大小上限；Admin 不执行脚本。
- [ ] 补齐 search/detail/create/update/delete 的 model、handler、service 和
`/api/v1` 路由。
- [ ] ZK subscriber 增加 `.script-router` upsert/delete。
- [ ] Nacos 增加 `*.script-router` watcher，并补齐 Governor 回读转换。
- [ ] 增加 Script 最小前端 CRUD 和多行脚本编辑器。
### 阶段五：端到端验收
- [ ] Condition 和 Tag 各执行一次 create/update/delete，确认规则名、ZK/Nacos 位置和回读正确。
- [ ] Condition v3.1 分别验证 service/application 规则，确认多条 from/to、多个 destination
和 weight 在 Admin、配置中心及回读过程中无损，并真实改变路由结果。
- [ ] Affinity 分别验证 service/application key，create/update 后路由结果改变，delete 后恢复。
- [ ] Script 验证 `<provider-application>.script-router` 被 consumer
监听，create/update 后新脚本生效，delete 后脚本失效。
- [ ] Zookeeper 和 Nacos 均验证 Admin 请求、配置中心真实内容、dubbo-go 配置事件和最终 invoker 结果。
- [ ] 外部直接修改或删除配置后，Admin watcher 能同步列表和详情。
验收标准不是 Admin API 返回成功，而是：配置中心内容符合契约、dubbo-go 收到 Add/Update/Delete，并且
`RouterChain.Route` 的结果符合预期。
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
