---
name: transaction-pattern
when: '事务, @Transactional, 分布式事务, 事务传播, 事务隔离, 数据一致性, 回滚, commit, rollback, 补偿事务'
scope:
  - backend
products:
  - '*'
id: ka-pattern-transaction-pattern
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 事务
  - '@Transactional'
  - 分布式事务
  - 事务传播
  - 事务隔离
  - 数据一致性
  - 回滚
  - commit
  - rollback
  - 补偿事务
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 写操作 Service 方法必须标注 @Transactional，且显式指定 rollbackFor = Exception.class
- 禁止在 Controller 层使用事务注解，事务边界必须在 Service 层
- @Transactional 方法禁止被同类内部调用（AOP 代理失效），必须通过注入调用
- 事务方法必须短小快速，禁止在事务中执行外部 HTTP 调用、文件 I/O、MQ 发送
- 只读查询方法必须标注 @Transactional(readOnly = true)，降低数据库压力
- 跨服务分布式事务优先使用最终一致性（事件 + 补偿），禁止强依赖 2PC/XA
- 跨服务事务必须有补偿机制：正向操作失败自动补偿或定时对账修复
- 嵌套事务优先使用 REQUIRES_NEW 分割独立事务单元，避免大事务锁表
- 传播行为默认 REQUIRED 即可，禁止随意使用 REQUIRES_NEW（容易产生数据不一致）

## 验收项
- [AC-01] 写操作有 @Transactional(rollbackFor = Exception.class)
- [AC-02] 事务方法无外部调用和文件 I/O
- [AC-03] 只读方法有 readOnly = true
- [AC-04] 跨服务事务有补偿机制
- [AC-05] 无同类内部调用导致 AOP 失效
- [AC-06] rollbackFor 显式指定
- [AC-07] 无内部调用导致事务失效
- [AC-08] 只读查询标注 readOnly
