event-driven-messaging

事件驱动消息传递

除非完整系统能证明更强的语义，否则应按至少一次投递来设计。

事件契约

• 使用不可变的事件封套，包含 eventId、eventType、occurredAt、schemaVersion 和负载。
• 将已发布的架构视为 API。以兼容方式添加字段，绝不悄然改变字段含义。
• 将关联 ID 和因果 ID 放入标头或封套中。
• 不要发布 JPA 实体或特定于框架的序列化格式。

生产者规则

• 仅在源状态变更已持久化后发布。
• 当数据库状态与代理发布必须保持一致时，使用事务发件箱。
• 当需要保证每个聚合内的顺序时，使用确定性的分区键。
• 明确配置投递超时和确认机制。

消费者规则

• 使用持久化的已处理事件记录，或天然幂等的写入，使处理程序具备幂等性。
• 将事务边界控制在状态变更和幂等性标记周围。
• 配置重试前，先区分临时故障和永久故障。
• 通过退避机制限制重试次数，然后将无法处理的消息路由到死信目标。
• 保留原始事件、失败原因和尝试次数，以便重放。

测试

• 测试序列化兼容性和处理程序幂等性。
• 使用 Testcontainers 进行代理集成测试。
• 测试重复、乱序、延迟和无法处理的消息。

示例

• 请参阅 examples/good-consumer.java 和 examples/bad-consumer.java。

常见问题

• Agent 因代理支持事务而假设投递恰好一次——端到端副作用仍需要幂等性。
• Agent 无限重试验证失败——应及时将永久失败的消息移入死信队列。
• Agent 在数据库事务中发布消息，却未使用事务发件箱——崩溃可能导致状态与事件投递不一致。
• Agent 使用随机分区键——因此会丢失同一聚合内的顺序。
• Agent 直接将消息反序列化为 JPA 实体——应使用带版本的事件契约。