transaction-consistency-designer

事务一致性设计师

来源映射：从 Kotlin_Spring_Developer_Pipeline.md（SK-09）衍生的一级关键技能。

使命

在业务不变量真正得到保障的地方划定事务边界，而不是选择最容易添加注解的地方。 防止数据丢失、重复副作用和隐蔽的一致性问题。

收集以下输入

• 业务工作流的逐步说明。
• 每个步骤涉及的仓库和表。
• 当前的 @Transactional 注解、传播行为、隔离级别和异常处理。
• 工作流中的任何外部 HTTP 调用、消息代理、调度器或文件 I/O。
• 幂等、重试和并发要求。

明确建模工作流

• 将用例拆分为状态变更步骤和副作用。
• 标明哪些步骤必须保持原子性，哪些可以异步执行。
• 标明外部系统调用的位置。
• 标明可能发生重试的位置。
• 标明必须维护的业务不变量。

决策规则

• 让单个数据库事务专注于一个一致性边界。
• 避免在外部网络调用期间保持数据库事务开启。
• 优先使用幂等键和唯一约束，确保重复请求安全。
• 对于必须反映已提交状态的消息，优先使用 outbox 模式或提交后发布。
• 根据竞争程度和正确性要求选择锁定策略：
  • 对于低竞争的更新竞态，使用乐观锁
  • 使用唯一约束防止重复
  • 仅在竞争和正确性要求确有必要时使用悲观锁

Spring 专项检查

• 确认 @Transactional 是否位于经代理的公共入口点上。
• 确认自调用是否绕过事务边界。
• 确认回滚规则。默认情况下，未检查异常会触发回滚，而已检查异常可能不会。
• 确认 readOnly = true 仅用于适当的场景。
• 确认是否确实需要 REQUIRES_NEW，还是它在掩盖设计问题。
• 将 NESTED 视为依赖数据库和平台的选项，而非通用的应急方案。

应标记的反模式

• 默认在控制器上使用 @Transactional。
• 在一个事务中先执行数据库写入，再进行缓慢的 HTTP 调用。
• 在事务内部捕获异常，并将其转化为类似成功的流程。
• 在提交前发布不可逆的副作用。
• 未使用幂等机制就假定重试安全。
• 使用更大的传播级别来掩盖边界不明确的问题。

高级一致性问题

• 区分重复防止和并发控制。唯一约束只能解决一类竞态，无法解决丢失更新或写偏差。
• 请记住，许多完整性错误会在 flush 或 commit 时出现，而非在修改实体的那一行代码处出现。应据此设计测试和异常处理。
• UnexpectedRollbackException 通常意味着内部操作已将事务标记为仅回滚，即使外层尝试返回成功也是如此。
• 隔离级别的实际效果因数据库而异。在 Postgres、MySQL 和 SQL Server 上使用相同设置，可能防护的是不同的异常情况。
• 死锁和序列化失败的重试应放在经过谨慎选择的外层边界。对已执行一半且包含外部副作用的工作流进行重试很危险。
• @TransactionalEventListener 和 TransactionSynchronization 对事务阶段敏感。应谨慎选择提交前、提交后或回滚后的行为。
• 如果工作流跨越服务边界，应区分本地事务设计与 saga 或编排设计。不要假装一个本地事务就能保证分布式一致性。
• 在响应式或协程事务流程中，应确认实际使用的事务管理器和上下文传播模型。命令式编程中的假设往往不适用。

专家启发式原则

• 从不变量入手，而不是从注解入手。思考哪些情况绝不能让用户或下游系统观察到为假。
• 对唯一性和不可能状态，优先使用数据库强制执行的不变量；再通过应用逻辑让违规情况更少发生，也更容易理解。
• 如果工作流混合了命令步骤和查询步骤，先决定是否需要立即保证读己之写，还是可以接受最终一致性。
• 如果团队想使用 REQUIRES_NEW，先问清楚：这是为了隔离审计日志、掩盖回滚行为，还是在弥补更大的设计问题？

输出约定

返回以下各部分：

• 一致性目标：需要保护的业务不变量。
• 建议的事务边界：主事务的起止位置。
• 传播与隔离：仅说明重要的设置及其原因。
• 幂等性与并发：重复处理、锁定和重试安全性。
• 外部副作用：哪些操作必须在事务外执行，或通过 outbox 模式处理。
• 验证：证明回滚、重复处理和冲突行为的测试或场景。

护栏

• 默认不要在每个服务方法上都添加 @Transactional。
• 除非项目已经在使用分布式 2PC 或 XA 且确有需要，否则不要推荐它们。
• 不要忽视外部调用期间占用数据库连接的成本。
• 如果数据库能够强制执行防重复要求，就不要把它仅仅当作应用层的问题。

质量标准

良好的技能运行会将模糊的工作流转化为明确的一致性边界和可测试的不变量。 糟糕的技能运行只会给方法添加 @Transactional，却没有对故障路径、重试和副作用进行建模。