Kafka offset 与幂等：一次处理的边界究竟在哪里

Kafka offset 表示某个分区里的日志位置，不是业务已处理条数。要分清读到哪里、提交了哪里，以及业务真正完成到哪里。poll 已读到 100 并交给线程池，不代表此前所有订单都已写入数据库。恢复检查点应根据从前往后已经可靠完成的那一段确定，不能只选见过的最大 offset 或最后完成的编号。

通常提交的是下一条待处理的位置。整批都完成后应使用客户端提供的 nextOffsets 等信息；批中还有没完成的记录时，不能越过最早未完成者。offset 数字可能因日志压缩、事务控制记录或被过滤的事务内容而有空缺。因此“连续完成”指已经读取的记录按顺序都完成，不要求中间每个整数都对应一条记录。

幂等生产者解决某些生产会话中协议重试导致的重复写入，不能去重应用主动再次调用 send 产生的同一业务事实。Kafka 事务可以把写入 Kafka 的输出记录和输入消费 offset 纳入同一事务边界，配合 read_committed 让下游观察已提交事务。外部数据库、邮件、支付 API 不会因此自动加入 Kafka 事务，它们仍需要自己的幂等与一致性协议。

假设本批真实返回 offset 为 [5,8,10]，next position 为 12。任务 8 先完成时，5 尚未完成，可提交位置仍是 5；5 完成后，最早未完成为 10，所以可提交 10；10 完成后才能推进到客户端给出的 12。等待不存在的 6、7、9 会永久卡住，直接提交最大完成值加一则可能跳过 5。必须同时保存已读取顺序和每项完成状态。

外部数据库处理常采用先提交业务，再提交 Kafka offset。若中间失败，恢复会再次处理已经提交的业务，所以需要数据库唯一约束、条件更新或业务幂等记录。若颠倒顺序，提交 offset 后数据库失败，恢复会从更后面开始，导致业务遗漏。这个两步故障窗口不能靠把 commitSync 改成 commitAsync 消除，它们改变的是等待与错误处理方式，不改变两个系统缺少共同事务的事实。

如果输入和输出都在 Kafka，可以开始事务、写入输出，再把下一条输入位置及消费组信息一起加入事务后提交。失败时要按 SDK 规则中止或处理不可继续的错误，不能所有异常都直接重试。下游使用 read_committed 才会按事务提交结果读取；长时间未决定的事务也可能挡住之后的可见进度。

transactional.id 还用于恢复和隔离旧生产者，必须管理好稳定性与唯一活动实例，不能随意给多个并行实例共用。

真实同步提交入口先获取消费者调用保护并确保状态可用，再检查组信息，将提交映射复制给协调器并等待结果。映射复制使一次请求使用明确输入，但复制不会把错误的业务检查点变成正确值。调用方若传入越过未完成记录的位置，协议层通常无法判断你的数据库业务还没有成功。

方法还处理 leader epoch 元数据并记录提交耗时，说明 offset 不是脱离日志历史的孤立整数。日志截断和分区领导者变化时，epoch 能为位置解释提供额外上下文。教学模型使用字符串映射只是为了让提交边界独立可读；真实实现应使用 TopicPartition 与 OffsetAndMetadata，保留客户端提供的元数据。

无参数 commitSync 使用客户端已消费位置，并不自动等待你自行创建的工作线程。如果 poll 之后异步处理仍在运行，无参数提交可能领先实际业务。只有严格顺序处理完全部返回记录等前置条件满足时，才可以把客户端位置直接作为业务完成位置。异步架构通常需要显式位置映射。

commitSync 超时，只说明客户端没有在规定时间内拿到成功结果，服务端仍可能已经保存了提交位置。使用异步提交时，还要处理新旧请求及回调的先后关系：在较新的位置已经提交后，盲目重提旧失败回调里的位置，可能让进度倒退。位置通常应由一个线程管理，只向前推进，并确认请求仍属于当前这次分区分配；换成异步方法本身并不能解决这些问题。

输入严格递增的真实 offset 数组和该批次结束后的 nextPosition。任意顺序调用 complete(offset)，查询 safePosition：有未完成记录时返回最早未完成的 offset，否则返回 nextPosition。重复完成幂等；未知 offset 拒绝。

给每个真实记录建立一个布尔完成标记，另用 cursor 指向数组中最早未完成的位置。记录数 n 决定状态长度，offset 的数值跨度不决定内存量，因而 [5,1000000] 不需要分配百万格数组。收到完成事件时，用二分搜索将日志位置映射到数组下标。

完成标记设为真后，从 cursor 开始连续跳过已经完成的项。某个后面的任务先完成，只会留下一个真标记，不会让游标跨越前面仍为假的项。每个下标一生最多被游标经过一次，所以虽然单次 complete 可能推进很多格，整个批次推进成本仍为 O(n)，无需每次从头扫描。

当游标到达末尾，返回输入的 nextPosition，而不是最后一个 offset 加一。这保留客户端已经越过控制记录等空洞的语义，也避免在极值附近随意做加一。这个批次模型假定没有更早批次未完成；推广到多批次时必须以分区为单位把批次串成同一条已登记序列，不能分别取各批最大进度。

每次完成用二分查找 O(log n)，完成标记写入常数；cursor 在全部操作中最多推进 n 次。数组克隆与校验各扫描一次。重复完成不会回退游标，也不会产生额外线性扫描。

先定义你的“一次”是什么：一次协议写入、一次 Kafka 到 Kafka 的事务处理，还是一次真实扣款。幂等生产者可以减少客户端重试造成的重复，但上游把同一订单事件主动发两遍仍需业务识别。外部副作用最好由接收方支持稳定幂等键及结果查询，不能仅在发送方内存里记一个成功标志就宣称已覆盖所有故障。

消费消息并修改数据库时，可以把 eventId 的唯一记录和业务修改放进同一个事务，重复收到事件就读取已有结果。如果 offset 也存入这份数据库，要明确重启时以哪份位置为准。分区换人处理时，还要让数据库拒绝旧实例继续写入，例如用正确的事务锁定、条件更新或由资源端检查的 fencing 代次。

租约可以协调分工，但到期不会停止旧线程，不能单独当成写入保护。若数据库和 Kafka 各存一份位置，却没有协调规则，恢复时就可能不知道该从哪里继续。

验证 exactly-once 边界要注入重复发送、发送确认丢失、业务提交后进程终止、事务中止和重平衡等不同故障，按业务 ID 比较最终作用次数与日志结果。只运行一次正常流程看到一条输出，不能证明失败场景也只产生一次作用。对未决事务与最老未完成记录设置告警，才能避免系统看似在线却长期不再向前推进。