1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | transactional-patterns-rrezartprebreza-spring-boot-skills |
| 作者/维护者 | rrezartprebreza（个人开发者） |
| 来源链接 | https://github.com/rrezartprebreza/spring-boot-skills/tree/main/skills/spring-boot-4/transactional-patterns |
| 许可证 | MIT（GitHub API 获取） |
| GitHub Stars | 194（整个 spring-boot-skills 合集仓库；该数字反映合集整体热度，不代表本子技能自身热度，GitHub API 获取） |
| Forks | 35（同上，合集整体，GitHub API 获取） |
| 最新版本 | 无独立版本号；本子技能目录随 2026-07-04 的“Restructure skills and add Spring Boot 4 variants”提交加入，仓库整体最近一次内容修订为 2026-07-30（GitHub API 获取） |
| 安装方式 | 复制该子目录到 agent 的 skills 目录（见第 10 章） |
2. 功能介绍与亮点
这是一份面向 Spring Boot 4.x（含 Spring Framework 7 核心能力）的事务处理实战指南，教 AI 编程 agent 正确使用 @Transactional 及相关模式，而不是套用训练数据里常见的错误写法。核心内容覆盖八个主题：
- 基础规则：
@Transactional只放在 service 层方法上；默认传播行为REQUIRED；只读方法显式标注readOnly = true以启用优化 - 传播机制：六种传播类型（
REQUIRED/REQUIRES_NEW/SUPPORTS/NOT_SUPPORTED/MANDATORY/NEVER）逐条给出行为说明与代码示例，附审计日志“独立于父事务提交”的实战场景 - 自调用陷阱：完整示范 Spring 代理机制下
this.method()调用绕过事务代理导致@Transactional静默失效的经典坑，并给出拆分 Bean 的修复方案 - 异常处理：区分运行时异常默认回滚与检查异常需显式声明
rollbackFor，以及noRollbackFor的使用场景 - 乐观锁：
@Version字段配合并发更新冲突处理 - 瞬时故障重试：指出 Spring Boot 4 已将重试能力收编进核心框架（
@EnableResilientMethods+@Retryable），而非沿用 Spring Retry 依赖库，并说明重试注解必须放在事务方法的调用方而非事务方法自身，否则会在已标记回滚的事务内重跑 - 分布式事务（Saga 模式）：多服务操作场景下用补偿动作代替分布式事务的实现范式
- 提交后副作用：用
@TransactionalEventListener(AFTER_COMMIT)避免“事务回滚但邮件/消息已发出”的经典数据不一致问题
文末附 8 条“agent 常犯错误”清单（如误用已废弃的 Spring Retry API、把 @Retryable 与 @Transactional 叠加导致重试发生在必回滚的事务内部等），每条对应上文某个具体陷阱。全部内容为纯 Markdown 配可编译 Java 代码示例，并与仓库内 domain-driven-design 子技能（领域事件发布）相互引用。
3. 适用场景
所属分类：工程效率与代码质量——本技能产出的是应用自身事务边界与并发控制相关的业务代码，属于技术栈编码指南范畴。
适合任何使用 Spring Boot 4.x（或 3.x，可切换到仓库对应分支）、代码中存在跨表写入或多步骤数据库操作的后端开发者。尤其适合用 AI 编程 agent 生成或修改服务层代码的团队——事务传播、自调用失效、提交后副作用这几类问题在人工代码审查中也容易被忽略，是运行时才会暴露的静默数据一致性问题，这份技能把判断标准前置到 agent 生成代码之前。
4. 跨 Agent 兼容性
- Claude Code：原生支持——仓库明确提供
.claude/skills/安装路径与徽章标注兼容 - Codex：原生支持——仓库同时提供
.codex/skills/安装路径与徽章标注兼容 - OpenClaw：未验证——SKILL.md 遵循标准 YAML front matter + Markdown 正文格式，理论上可迁移，但仓库文档未点名支持
- Hermes Agent：未验证——同上，未见任何提及
5. 推荐理由
事务处理是 Spring 后端最容易“看起来能跑但实际有坑”的领域之一：自调用绕过代理、检查异常不触发回滚、提交前发出副作用——这些错误往往编译、测试都能通过，却在生产环境的并发或异常场景下才暴露为数据不一致。这份技能把此类陷阱连同修复写法整理成一份可被 agent 直接读取的清单，并同步覆盖 Spring Boot 4 刚收编入核心框架的重试机制，对任何用 agent 编写或维护 Spring 服务层代码的团队都是直接可用的护栏。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 5 | 该技能所属子目录本身尚无独立的第三方讨论或引用证据；所属合集仓库由单一开发者维护，194 星与 35 复刻数字属整体仓库，不可归给单个子技能 |
| 可用性 | 9 | 复制单个文件夹即可安装，无需配置或付费依赖；内容随 Spring Boot 4 当前版本同步维护，仓库最近一次修订为 2026-07-30；代码示例完整可编译，覆盖依赖声明到完整用例 |
| 安全性 | 9 | 纯 Markdown 文档配代码示例，技能自身不执行任何命令、不联网、不要求任何凭据；仓库许可证明确（MIT）；内容未见任何可疑指令或误导性说明 |
综合评分：7.7
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与本技能的差异 |
|---|---|---|
| Spring Boot Reviewer（第三方 skills 市场） | 面向 Spring Boot 应用的综合代码审查技能，检查依赖注入方式、N+1 查询、REST 设计、安全实践等多个维度 | 覆盖面更广，事务边界缺失只是众多检查项之一，停留在“发现问题”层面；本技能专注事务这一单一主题，给出传播机制、自调用、提交后副作用等具体修复写法 |
| Spring Framework Core & AOP（第三方 skills 市场） | 讲解 Spring 核心机制（依赖注入、AOP 代理、事务管理）的基础教学型技能 | 事务管理只是 AOP 原理教学的一节，偏概念讲解；本技能是聚焦实战场景的陷阱清单，附完整可运行代码而非原理说明 |
| spring-security-jwt-rrezartprebreza-spring-boot-skills | 同一仓库内的 JWT 无状态认证实现指南 | 主题互补而非重叠——一个管认证边界，一个管事务边界，均遵循同一仓库“agent 常见错误清单”的写法体系 |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价。
9. 其他补充
仓库同时维护 Spring Boot 3 分支下的等价版本（内容随目标框架版本调整，如重试机制、Starter 命名等版本特有差异），供仍在 Spring Boot 3.x 的团队使用。
10. 安装使用方式
Claude Code：
mkdir -p "$PROJECT_DIR/.claude/skills"
cp -r skills/spring-boot-4/transactional-patterns "$PROJECT_DIR/.claude/skills/"Codex：
mkdir -p "$PROJECT_DIR/.codex/skills"
cp -r skills/spring-boot-4/transactional-patterns "$PROJECT_DIR/.codex/skills/"安装后无需重启 agent，下次涉及事务相关代码改动时会被自动读取触发；仓库同时提供 Spring Boot 3 分支的等价目录（skills/spring-boot-3/transactional-patterns），按项目实际框架版本二选一。
11. 注意事项
- 内容以 Spring Boot 4 / Spring Framework 7 API 为准（如重试能力已收编入核心框架），若项目仍在 Spring Boot 3.x，需改用仓库对应分支目录，两者写法存在差异
- 技能覆盖的是通用事务模式，不含项目特定的隔离级别或超时配置建议，仍需结合具体业务场景调整
- 仓库由个人开发者维护，无企业组织背书，长期维护的连续性无法保证