Skip to content

docs: 修正 BanNet 协议章节(原文与实现完全不符) - #258

Merged
NeverENG merged 1 commit into
mainfrom
docs/protocol-correction
Aug 12, 2026
Merged

docs: 修正 BanNet 协议章节(原文与实现完全不符)#258
NeverENG merged 1 commit into
mainfrom
docs/protocol-correction

Conversation

@NeverENG

Copy link
Copy Markdown
Owner

README 的协议章节此前每一行都与代码不符,且随 #257 加入 notfound 状态进一步失真。SDK 已发布,该章节成为集成方的必读依据,不能继续与实现相悖。

原文 实际
帧头 [dataLen u32][msgID u32] 6 字节定长头 [dataLen u32 LE][msgIDLen u16 LE] + 变长 msgID;整数小端(原文未提字节序)
msgID 数字 1/2/3 ASCII 字符串 PUT/GET/DEL,另有 SCAN(原文缺失)
响应 「首字节为状态标志 0x00/0x01 [statusLen u8][status bytes],状态是字符串,共 5 种

补充各状态对客户端的语义(overloaded/error 可重试;notfound/dropped 是确定性结果,重试无意义),以及「只把 ok 视为成功、未知状态按失败处理」的前向兼容约定——这正是新增状态可以安全引入的原因。

纯文档改动,无代码变更。

🤖 Generated with Claude Code

该章节此前描述的协议与代码完全不同,且随 notfound 状态的加入进一步失真。逐条更正:

  帧头    原写 [dataLen u32][msgID u32],实为 6 字节定长头
          [dataLen u32 LE][msgIDLen u16 LE] 之后接变长 msgID;且整数为小端,原文未提
  msgID   原写数字 1/2/3,实为 ASCII 字符串 PUT/GET/DEL(另有 SCAN,原文缺失)
  响应    原写「首字节为状态标志 0x00/0x01」,实为 [statusLen u8][status bytes],
          状态是字符串;且共有 ok/notfound/overloaded/dropped/error 五种,原文只描述两种

补上各状态对客户端的语义(哪些可重试、哪些是确定性拒绝),并说明「只把 ok 视为成功、
未知状态按失败处理」这一前向兼容约定。该章节因 SDK 的加入已成为集成方的必读依据,
不能继续与实现相悖。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@NeverENG
NeverENG merged commit 5336b76 into main Aug 12, 2026
3 checks passed
@github-actions

Copy link
Copy Markdown

🐯 BanGD 数据库内核评审

整体风险:🟢 低

变更总结:这是一个纯文档型 PR,修正 README 中 BanNet 协议章节的失实现象。原文档声称帧结构为 [dataLen u32][msgID u32]、msgID 是数字 1/2/3、响应首字节为单字节状态标志,而实际实现(bannet/datapack.go、client/conn.go)是 6 字节定长头(dataLen u32 LE + msgIDLen u16 LE)+ 变长 ASCII msgID(PUT/GET/DEL/SCAN),响应以 [statusLen u8][status string] 开头、共 5 种字符串状态。文档改动补充了 msgID 为小端整数字节序、SCAN 指令、5 种状态语义及客户端处理策略,并明确了「只认 ok 为成功、未知状态按失败处理」的前向兼容约定,与 pkg/proto 的 EncodeScanRequest/EncodeScanResponse 实现及 client 的 statusError/retryable 逻辑保持一致。无任何代码变更。

本评审不阻塞合入;架构级建议以 Issue 形式跟踪,普通问题在下方内联列出。

未发现需要从架构层面改进的问题。


本次评审消耗 token:共 18967 tokens(输入 12167,输出 400,缓存命中 6400,缓存写入 0)|维度 [concurrency, memory, lock, storage, performance]|补充阅读周边文件 [bannet/datapack.go, client/conn.go, client/wire_compat_test.go, client/errors.go, pkg/proto/scan.go]|对抗式复核 3 票/条,过滤疑似误报 0 条

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant