---
title: PacketCache v1/v2：缓存、发布返回与业务完成
type: concept-note
status: maintained
created: 2026-10-28
updated: 2026-10-28
---

# PacketCache v1/v2：缓存、发布返回与业务完成

## 来源与适用范围

来源为用户于 2026-10-28 提供的虚构 PacketCache 规范 v1 及随后提供的 v2，关键条款分别保存在下文。本文是对给定规范的学习整理；没有真实实现或本地实验，结论按版本适用。

## v1 接口约定（原版本仍成立）

| 接口或事件 | v1 规定 |
| --- | --- |
| `stage(packet)` | 将包加入未发布缓存。 |
| `commit()` | 将当前缓存一次性发布到接收队列并清空缓存；返回时发布已经完成。 |
| `receiver.read()` | 只读取接收队列。 |
| 发布完成 | 不承诺接收者业务处理完成。 |

`stage(packet)` 后，包仍在未发布缓存中；仅执行该操作不能使包进入 `receiver.read()` 的读取范围。`commit()` 将当前缓存发布到接收队列并清空缓存，因此是从缓存到接收队列的发布步骤。

规范明确把发布完成绑定到 `commit()` 返回：当调用返回时，这次发布已经完成，不能将它解释为仅提交了发布请求、还需等待发布完成。但这不意味着返回时队列中必然仍保留这些包；若包已被读取，队列内容可能已变化。

接收队列中的数据属于 `receiver.read()` 的读取范围；发布完成并不等于接收者已读取，更不等于接收者已完成业务处理。若关注业务完成，需要另外取得业务完成依据，v1 未提供相应接口或保证。

## v1 并发边界

规范没有定义并发一致性，不能据“一次性发布”推导并发调用下的线性化、原子可见性、线程安全或并发 `stage()` 与 `commit()` 的批次归属，也不能据此保证并发读取时返回后的队列快照。上述发布返回保证应按给定条款理解，不扩展为未定义的并发契约。

## v2：请求接受与发布完成分离

2026-10-28 补充：用户提供的虚构 PacketCache 规范 v2，关键条款如下。v2 是版本边界变化，不否定上文 v1 的定义；未取得真实实现，也未执行实验。以下结论仅依据本次提供的规范。

| 接口或事件 | v2 规定 |
| --- | --- |
| `stage(packet)` | 仍将包写入未发布缓存。 |
| `commit()` | 只接受发布请求并返回 token；不保证包已进入接收队列。 |
| `wait(token)` 成功 | 才确认对应发布完成。 |
| `receiver.read()` | 与 v1 相同，只读取接收队列。 |
| 发布完成 | 不承诺业务处理完成。 |

因此，v2 的 `commit()` 返回只能作为发布请求被接受的依据，不能作为发布完成的依据；也不能反向推断此时包一定尚未入队。需要确认发布完成时，应保存返回的 token，并等待 `wait(token)` 成功。未取得成功结果时，按给定条款仍无法确认发布完成，不能据此认定发布必然失败或包必然未入队。

`wait(token)` 成功不保证包仍留在队列中，也不证明接收者已经读取或完成业务处理。业务完成仍需独立依据。v2 未提供缓存清空时点、请求批次归属、等待失败或超时的语义、重试策略及并发一致性保证，不能从 v1 或 token 的存在补推这些约定。

直接依赖的[接收指南](../Projects/DEMO-PacketCache/Receive_Guide.md)按版本列出操作路径；v1 仍以 `commit()` 返回确认发布，v2 改以 `wait(token)` 成功确认发布。

