K2 将流上的每条记录至少一次投递给每个订阅。消费者 可能会多次收到同一条记录,因此请设计消费者以 处理重复记录。
本页说明 K2 如何将记录从流投递给您的消费者。有关 消费者发送的请求,请参阅消费记录。
| 保证 | 行为 |
|---|---|
| 投递 | 每个订阅至少一次。 |
| 扇出 | 每个订阅都会收到每条记录。一个流最多可以有 100 个订阅。 |
| 分担工作 | 在订阅内,K2 从不会将相同记录同时租给两个 worker。 |
| 重新投递 | 如果批次通过 nack 释放,或租约在 ack 之前到期,记录会再次投递。 |
| 保留 | 消费记录不会删除它。记录会保留在流中,直到保留期结束。 |
| 批次 | 记录以批次为单位确认、释放和重新投递。没有按记录确认。 |
| 顺序 | K2 不保证共享同一订阅的 worker 处理记录的顺序。 |
| 去重 | K2 不会在生产或消费时对记录去重。 |
每个订阅跟踪自己在 流中的位置。每个订阅都会收到每条记录,从一个 订阅消费不会影响任何其他订阅。
记录在被消费时不会被移除。它们会保留在流中,直到 保留期结束。这意味着您可以:
- 稍后添加新订阅,并通过将
start_at设置为earliest来读取在它存在之前生产的记录。 - 在同一流上运行多个独立应用。例如,告警系统、归档器和功能管道可以各自拥有自己的订阅。
无论记录是否已被消费,保留期都适用。如果订阅 落后的时间超过保留期(例如因为其 消费者停机),K2 会删除它尚未读取的记录。请将 保留期设置为覆盖您需要容忍的最长消费者停机时间。
多个 worker 可以从同一订阅消费。K2 会在 它们之间拆分记录,因此每个 worker 会收到记录的子集。同一订阅上最多 128 个 worker 可以同时持有租约。
- 每个批次是恰好由一个
worker_id持有的租约。 - 每个
worker_id一次只能持有一个租约。 - 一个订阅最多可以有 128 个活动租约。
- K2 从不会将相同记录同时租给两个 worker。
当 worker 请求批次时,K2 会将该批次租给该 worker 五分钟。然后批次会以下列方式之一结束:
| worker 的操作 | 结果 |
|---|---|
| 确认(ack) 该批次 | 这些记录被标记为此订阅已处理,并释放租约。 |
| 释放(nack) 该批次 | K2 会在任意 worker 请求的下一批次中再次投递这些记录,并使用新的 batch_id。 |
| 延长 租约 | 租约被设置为在该请求后五分钟到期。 |
| 在持有租约时再次请求批次 | K2 返回同一批次和记录,并刷新租约。 |
| 直到租约到期都无操作 | K2 会将记录再次投递给下一个请求批次的 worker,并使用新的 batch_id。 |
确认、nack 和重新投递适用于整个批次。如果批次中的 一条记录失败,您不能单独确认其他记录。要么在消费者中 处理失败的记录,要么 nack 该批次,以便 K2 再次投递其中的每条 记录。
在包含已释放或已过期记录的新批次被确认之前, 订阅不会越过这些记录。
如果租约已过期且 K2 已在新批次中投递这些记录,则来自 原始 worker 的确认不会生效。这就是 K2 至少一次 而不是恰好一次投递记录的原因:worker 可以处理一个批次, 未能及时确认,然后另一 worker 会处理相同的记录。
成功的生产请求表示 K2 已存储批次中的每条记录。 批次写入是原子的,因此批次中的所有记录要么全部存储,要么一条也不存储。
某些生产失败的结果未知,批次可能已存储,也可能尚未存储。如果您重试该批次,K2 可能会将记录存储两次。有关详情, 请参阅处理错误。
因此重复可能来自两个地方:生产者重试批次,或 K2 向消费者重新投递批次。
为使重复安全,请让您的消费者幂等,这样处理 同一条记录两次与处理一次效果相同。例如:
- 生产时在每条记录中包含唯一 ID,放在 content 或标头中。
- 写入数据库时将该 ID 用作主键,以便第二次插入同一记录被拒绝或忽略。
- 将该 ID 作为幂等键传递给下游 API(例如支付或电子邮件 API),以便它们替您拒绝重复。
为减少重新投递,请在处理完每个批次后立即确认, 如果处理超过五分钟则延长租约。