投递语义

这一课你将能做到

1. 用自己的话解释 at-most-once / at-least-once / exactly-once 各在哪一步丢、在哪一步重，并能画出时序
2. 实现「去重表 + 唯一索引」的消费幂等骨架，说清 eventId 的两种生成规则
3. 画出 Outbox 两步（同库事务写 outbox → 异步发 Kafka），对比「事务后直接 send」的风险边界

为什么要学

Kafka 面试里最容易被问倒的词就是 exactly-once：很多人把「开了个配置」当成「系统不丢不重」，一上生产就翻车。工程真相是：

• 大多数业务系统落地在 at-least-once + 幂等消费
• 「MySQL 写成功 + Kafka 发出去」是两个系统两步操作，没有一键原子——Outbox 是经典补丁
• 幂等生产者只解决生产侧重复，消费侧重复要靠业务键

人话：宁可「多做一次但结果一样」，也别「少做一次钱少了」——这是分布式系统投递的第一性原则。

先建立图像

at-most-once : 先 commit 位点 → 再处理
               崩溃在处理中？消息跳过 → 可能丢（日志场景可接受）

at-least-once: 先处理 → 再 commit
               崩溃在 commit 前？重启后重投 → 可能重复 ← 默认按这个设计

exactly-once : 事务 API + 幂等存储，边界内不丢不重
               Kafka 事务擅长「读 Topic → 写 Topic」链路
               跨 MySQL 仍要业务幂等/Outbox 兜底

语义	含义	实现要点	代价
at-most-once	尽量不重，可能丢	先提交位点	关键业务不可接受
at-least-once	尽量不丢，可能重	先处理再提交 + 幂等	消费方要做幂等
exactly-once	边界内不丢不重	Kafka 事务 / 幂等生产者 / 业务幂等	复杂度与延迟

Outbox 模式：
  同一 DB 事务：UPDATE orders + INSERT outbox_events   ← 原子
  独立发送器：轮询 outbox → producer.send → 标记已发
  → 根治「库成功消息失败」与「消息成功库回滚」两类不一致

跟着做

步骤 1：在纸上画「处理成功但未 commit」

时序四步：

1. poll 到 offset=10
2. 发邮件成功
3. 进程崩溃（位点未提交）
4. 重启再 poll → 又从 offset=10 开始 → 邮件再发一次

笔记结论：这就是 at-least-once；邮件接口必须幂等或去重，否则用户收两封。

步骤 2：落地去重表幂等骨架

@Entity
@Table(name = "processed_events",
       indexes = @Index(name = "uk_event_id", columnList = "eventId", unique = true))
public class ProcessedEvent {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String eventId;
    private Instant processedAt;
    // 构造器/getter 省略
}

@Service
@RequiredArgsConstructor
public class OrderCreatedHandler {
    private final ProcessedEventRepo processedEventRepo;
    private final NotifyService notifyService;

    @Transactional
    public void handleOrderCreated(OrderCreatedEvent evt) {
        // 已处理：直接返回（重复投递安全跳过）
        if (processedEventRepo.existsByEventId(evt.eventId())) {
            return;
        }
        notifyService.sendEmail(evt);                                  // 副作用
        processedEventRepo.save(new ProcessedEvent(evt.eventId(), Instant.now()));
    }
}