3.2 WAL：补充 ErrCommitUnknown 的 API 层提交状态确认约束 #4

New Issue

2026-06-09T10:31:52+08:00

dailz commented

2026-06-09 10:31:52 +08:00

背景

第 3.2 节定义了 ErrCommitUnknown：当 WAL bytes 已写入但 fsync 返回错误时，提交结果是不确定的。调用方不能把它当作写入一定失败并盲目重试。

问题

当前文档说明了调用方需要通过读取 key 或事务层提供的事务 ID / commit record 查询提交状态，但尚未定义 API 层最小约束。

单 key autocommit 阶段可以通过读 key 做弱确认，但以下场景会有歧义：

Delete 操作
空 value 写入
重复写同一个 key
非幂等多 key 事务

风险

如果 API 层不明确，用户可能在 ErrCommitUnknown 后盲目重试，导致事务重复提交、Delete 状态误判或业务层非幂等副作用。

建议

在 3.2 或后续 API / 事务章节中补充：

第一阶段单 key autocommit 的 ErrCommitUnknown 只支持弱状态确认
文档需要说明哪些操作可以通过读 key 判断，哪些操作存在歧义
后续 MVCC / SSI 事务层必须提供 txnID / commit record / 幂等标识查询提交状态
对非幂等事务，必须禁止用户仅凭错误类型盲目重试

参考

docs/design.md:119 fsync unknown 处理
docs/design.md:121 ErrCommitUnknown 调用方语义
docs/design.md:322 事务边界与 commit sequence

## 背景第 3.2 节定义了 `ErrCommitUnknown`：当 WAL bytes 已写入但 fsync 返回错误时，提交结果是不确定的。调用方不能把它当作写入一定失败并盲目重试。 ## 问题当前文档说明了调用方需要通过读取 key 或事务层提供的事务 ID / commit record 查询提交状态，但尚未定义 API 层最小约束。单 key autocommit 阶段可以通过读 key 做弱确认，但以下场景会有歧义： - Delete 操作 - 空 value 写入 - 重复写同一个 key - 非幂等多 key 事务 ## 风险如果 API 层不明确，用户可能在 `ErrCommitUnknown` 后盲目重试，导致事务重复提交、Delete 状态误判或业务层非幂等副作用。 ## 建议在 3.2 或后续 API / 事务章节中补充： - 第一阶段单 key autocommit 的 `ErrCommitUnknown` 只支持弱状态确认 - 文档需要说明哪些操作可以通过读 key 判断，哪些操作存在歧义 - 后续 MVCC / SSI 事务层必须提供 txnID / commit record / 幂等标识查询提交状态 - 对非幂等事务，必须禁止用户仅凭错误类型盲目重试 ## 参考 - `docs/design.md:119` fsync unknown 处理 - `docs/design.md:121` ErrCommitUnknown 调用方语义 - `docs/design.md:322` 事务边界与 commit sequence

dailz closed this issue

2026-06-09 11:39:14 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dailz/go-kv#4