NeverENG opened a new issue, #16: URL: https://github.com/apache/dubbo-net/issues/16
## 背景:先从协议常量看问题 目前 dubbo-net 的协议值散落在解析流程中。以 [Hessian2 读取器](https://github.com/apache/dubbo-net/blob/main/DubboService/Native/DubboHessian2Reader.cs)为例:`0x55` 表示带类型、长度可变的列表。读取列表时直接判断 `0x55`;判断一个 tag 是否属于列表时,又使用 `0x55–0x58` 的范围。同一条协议知识出现在不同位置,需要读者自行对应。 double 标记也写成 `(byte)'D'`,其字节值为 `0x44`。目前没有证据表明它被解错;问题是协议含义没有通过统一名称表达。[NativeDubboCodec](https://github.com/apache/dubbo-net/blob/main/DubboService/Native/NativeDubboCodec.cs) 中还包含帧 Magic、标志位及响应类型 `0–5`。这些值分别属于 Dubbo 帧、Hessian2 或响应协议,不应混入一个万能常量文件;超时、容量等运行策略更不应混入协议常量。 [dubbo-go 的 Hessian2 常量文件](https://github.com/apache/dubbo-go/blob/555a9ba6c4c81c6e3a0244b15e966b75e741fa2b/protocol/dubbo/hessian2/const.go) 值得借鉴的是**按协议归属为固定值命名**,而不是照搬 Go 的文件布局。 ## 背景:客户端管理责任需要更清楚 [DubboClient](https://github.com/apache/dubbo-net/blob/main/Clients/DubboClient.cs) 既是公开调用入口,又持有注册中心、metadata 管理器、服务驱动集合和执行器,并参与发现、选择、刷新与释放。功能虽已协同工作,但“谁拥有状态、谁接收变化、谁负责停止”需要跨类追踪。 对照 [dubbo-go 客户端入口](https://github.com/apache/dubbo-go/blob/555a9ba6c4c81c6e3a0244b15e966b75e741fa2b/client/client.go),本 Issue 借鉴**入口与内部调用组件分工**的思路,不要求 DubboNet 复制其 invoker 或整个框架。 ## 各部分的目标职责 | 部分 | 负责什么 | 不负责什么 | | --- | --- | --- | | 客户端入口 | 保持公开 API,接收调用并进入内部流程 | 直接维护协议解析规则或多份 Provider 状态 | | 调用编排 | 协调签名、协议、Provider 选择及一次调用的预留/释放 | 注册中心 SDK 的订阅细节 | | 服务发现 | 从 ZooKeeper/Nacos 获得 Provider 变化 | 解析 Hessian2 | | Provider 状态与负载均衡 | 维护可用节点视图并选择节点 | 维护第二份竞争性的“真实节点列表” | | Metadata | 获取、解析、缓存方法和类型信息 | 接管业务连接生命周期 | | 传输与协议 | Native/Triple/Telnet 各自的收发、编解码和格式校验 | 决定全局发现策略 | | 管理 Hub | 在确有共享资源时管理所有权、状态发布和生命周期 | 成为包揽所有逻辑的万能 Manager | | 错误边界 | 在出错层保留类型与上下文,在调用边界映射结果 | 把全仓库报错放进一个字符串文件 | 这是职责目标,不意味着每一行都需要一个新类。 ## 实施方式:总 Issue 管方向,小任务逐项落地 每个小任务分别写明:现有所有者、目标所有者、涉及文件、不变的行为、测试以及文档影响。文件搬移、格式化和行为修复不混在同一次改动中。 ### 第一组:协议常量 1. **Hessian2 tag**:盘点 `0x44`、`0x55` 等标记与编码范围,建立有语义名称的常量,替换相应解析引用。 2. **Dubbo 帧**:单独整理 Magic、帧长、标志位和掩码。 3. **响应类型**:为 `0–5` 命名,保持原解析分支。 4. **字节级验证**:覆盖关键 tag、帧头、边界值和非法输入,证明行为等价。 候选文件归属: ```text DubboService/Native/ Protocol/ DubboFrameConstants.cs DubboResponseKinds.cs Hessian2/ Hessian2Tags.cs ``` 不要求第一项就搬动整个读取器。协议固定值、安全限制和可调运行参数分别归属。 ### 第二组:客户端职责与错误边界 5. **入口与编排**:区分 `DubboClient` 的公开 API 和内部流程;保持现有调用契约。 6. **发现与 Provider 状态**:确定谁取得变化、谁拥有当前节点视图,避免双份状态。 7. **负载均衡与预留**:明确选择、预留和释放的归属;保持一次调用恰好释放一次。 8. **Metadata**:先界定对调用流程提供的结果与刷新触发条件,不在第一批深度重写。 9. **传输**:界定 Native、Triple、Telnet 的连接所有权。 10. **错误分类**:区分参数、协议、传输和远端返回错误。只为稳定复用的错误语义在所属层建立定义或构造方法;保留 tag、端点、请求 ID 等现场上下文,不建立全局 `Errors.cs`。 这组先确定责任,再决定是否形成 `Clients/Invocation/`、`Clients/Discovery/` 等目录;不为增加接口或缩短文件而拆类。 ### 第三组:管理 Hub 与生命周期 11. **共享注册中心资源**:确认连接池、引用与订阅由谁持有和释放。 12. **客户端级 Provider 状态**:确认服务快照、更新通知和执行器集合的唯一所有者。 13. **停止与释放**:明确客户端关闭后,刷新、回调和后台任务的停止路径。 完成所有权分析后,才决定演进现有管理类还是建立少量 Hub;不预设必须存在几个 Hub,也不维护第二套 Provider 缓存。 ## 第四组:双语文档的入口与内容管理 **架构决策仍记录在本 Issue 和实施讨论中。** 文档工作线管理的是用户如何安装、调用、配置和排障,不另建一套重复的内部设计文档。 建议先建立清楚的导航结构,再逐页迁移内容: ```text README.md # GitHub/NuGet 入口与最短示例 Docs/ index.md # 中英文入口与文档导航 zh/ index.md # 中文首页 getting-started.md guides/ invocation.md # 调用方式与参数 metadata.md # 元数据使用与限制 configuration.md # 可配置项 reference/ results-and-errors.md # 返回值与错误语义 protocols/ native-dubbo.md triple.md troubleshooting.md en/ index.md # English home ... # 与 zh 相同的相对路径及页面职责 ``` 这里的目录树是**目标导航草案**,不是要求一次生成所有页面。文档各部分的职责为: - **根 README**:项目简介、安装、最短可运行示例,以及指向 `Docs/index.md` 的入口。它仍是包的 README,不应因迁移而失去基本使用说明。 - **`Docs/index.md`**:只做语言选择和导航,不复制两种语言的完整内容。 - **`zh/index.md`、`en/index.md`**:各自语言的阅读路径和章节入口。 - **guides**:回答“用户如何使用”;metadata 页解释现有能力和边界,不承载内部重构决策。 - **reference**:集中说明结果字段与错误契约,避免快速开始、协议页和排障页分别定义一套说法。 - **protocols**:解释各协议的线格式、支持范围与限制。 - **troubleshooting**:按用户可见症状给出检查路径,并链接到唯一的配置或结果定义。 迁移按小项进行: 14. **建立导航**:先添加入口和页面清单,保持现有链接可用。 15. **归类现有内容**:梳理 [README](https://github.com/apache/dubbo-net/blob/main/README.md)、[NativeDubboProtocol.md](https://github.com/apache/dubbo-net/blob/main/Docs/NativeDubboProtocol.md) 和 [TripleProtocol.md](https://github.com/apache/dubbo-net/blob/main/Docs/TripleProtocol.md);明确每段内容的新归属,避免直接复制出多个版本。 16. **逐页双语迁移**:同一主题在 `zh` 与 `en` 使用相同相对路径;尚未完成翻译时明确标注并链接到现有内容,不用空白页面冒充已完成。 17. **检查链接与一致性**:每次移动页面检查 README、语言入口、跨语言链接和仓库内引用;文档中的默认值、协议支持范围必须与代码一致。 18. **处理历史文档**:[ImportReviewStatus.md](https://github.com/apache/dubbo-net/blob/main/Docs/ImportReviewStatus.md) 是导入审核记录,不混入日常使用导航;若将来移动,先处理已有引用。 ## 后续行为修复与总体验收 重连竞争、刷新失败后恢复、取消传递、缓存失效及释放交错等可靠性问题可在本 Issue 登记和关联,但须另开可测试的行为修复任务,不能伪装成常量或目录整理。 每个结构整理小项应独立审查、独立验证。保持公开 API、协议字节、异常类型、错误文字及调用结果契约;任何必要变化都要单独说明。文档迁移不得产生失效入口或两套相互矛盾的说明。不进行全仓库格式化,也不以文件数增多作为成功指标。 -- 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]
