spring-data-jpa-rrezartprebreza-spring-boot-skills

1. 基本信息

项目	内容
名称	spring-data-jpa-rrezartprebreza-spring-boot-skills
作者/维护者	rrezartprebreza（个人开发者）
来源链接	https://github.com/rrezartprebreza/spring-boot-skills/tree/main/skills/spring-boot-4/spring-data-jpa
许可证	MIT（GitHub API 获取）
GitHub Stars	196（整个 spring-boot-skills 合集仓库；该数字属整个合集，不代表本技能自身热度，GitHub API 获取）
Forks	35（同上，合集整体，GitHub API 获取）
最新版本	无独立版本号；仓库整体最近一次修订为 2026-07-30（GitHub API 获取）
安装方式	复制该子目录到 agent 的 skills 目录（见第 10 章）

2. 功能介绍与亮点

这是一份 Spring Data JPA 持久化层的编码规范，把实体建模惯例、N+1 查询预防、投影查询、深分页与批量写入等一系列日常最容易踩坑的模式整理成可直接对照执行的清单。核心内容：

实体建模惯例：@GeneratedValue(strategy = GenerationType.UUID) 而非自增整数暴露给外部、@Enumerated(EnumType.STRING) 而非 ORDINAL（避免枚举顺序调整后数据错位）、构造函数用 @NoArgsConstructor(access = PROTECTED) 隐藏、实体上只留 @Getter 不留 @Setter（行为方法代替直接赋值）
N+1 查询识别与修复：给出 JOIN FETCH、@EntityGraph 两种修复路径，以及只读场景下用接口投影（Interface Projection）跳过实体加载、避免懒加载异常
深分页优化：对比 OFFSET 分页（页码越深扫描行数越多）与 Keyset（“seek”）分页，给出用 (createdAt, id) 元组打破排序并列的具体 JPQL 写法与索引建议
批量写入：说明 jdbc.batch_size 等 Hibernate 批处理配置，并指出 GenerationType.IDENTITY 会静默关闭批处理这一容易被忽略的坑，建议改用 UUID 或序列
12 条“agent 常犯错误”清单：FetchType.EAGER 误用、ORDINAL 枚举、Long 自增 ID、列表接口用 findAll() 不分页、深分页仍用 OFFSET、orphanRemoval 遗漏，以及一批 Spring Boot 3→4 迁移期的破坏性变化——spring-boot-starter-data-jpa 不再传递引入 Flyway 需显式添加、@EntityScan 包路径变更、切片测试的 @MockBean/@SpyBean 被移除需改用 @MockitoBean/@MockitoSpyBean、spring.dao.exceptiontranslation.enabled 属性改名

全部内容为纯 Markdown 文档配 Java 代码示例，无外部脚本或可执行文件。

3. 适用场景

所属分类：工程效率与代码质量——内容是持久化层的技术栈编码规范，不涉及 agent 自身配置或第三方系统集成。

适合任何用 Spring Data JPA 做持久化层的 Spring Boot 团队——只要项目连数据库，这个依赖几乎是默认选择，受众比“是否采用 DDD/六边形架构/API-first”这类特定方法论选择更广。尤其对正在升级到 Spring Boot 4 的团队，实体扫描包路径变更、测试注解替换、Flyway 依赖不再传递引入这几处若被 agent 忽略，会造成编译失败或迁移脚本悄悄不执行；N+1 查询与深分页问题则是即便不升级版本、日常开发中最容易被 agent 生成代码时忽略、上线后才在慢查询日志里暴露的性能隐患。

4. 跨 Agent 兼容性

Claude Code：原生支持——仓库明确提供 .claude/skills/ 安装路径与徽章标注兼容
Codex：原生支持——仓库同时提供 .codex/skills/ 安装路径与徽章标注兼容
OpenClaw：未验证——SKILL.md 遵循标准 YAML front matter + Markdown 正文格式，理论上可迁移，但仓库文档未点名支持
Hermes Agent：未验证——同上，未见任何提及

5. 推荐理由

Spring Data JPA 是绝大多数 Spring Boot 后端项目访问数据库的默认方式，而 N+1 查询、深分页性能塌陷、批量写入被静默关闭这几类问题恰恰是 agent 生成持久化代码时最容易犯、又最不容易在代码审查阶段被发现的错误——往往要等到生产环境慢查询日志才暴露。这份技能把实体建模惯例、两种 N+1 修复路径与 Keyset 分页写法整理成可直接照做的规范，另外单列一份 Spring Boot 3→4 迁移期的破坏性变化清单（包路径搬迁、测试注解改名、依赖不再传递引入），对正在升级到 Boot 4 的团队尤其实用。

6. 评分

维度	分数	说明
受欢迎程度	5	该技能所属子目录本身尚无独立的第三方评测或引用；所属合集仓库由单一开发者维护，196 星与 35 复刻数字属整体仓库，不可归给单个子技能；第三方技能市场 skills.sh 显示该子技能被独立安装 56 次，是本仓库 19 个 Spring Boot 4 子技能中安装数最高的一个，但仍属起步阶段的小体量数字
可用性	9	复制单个文件夹即可安装，无需配置或付费依赖；仓库最近一次修订为 2026-07-30，内容随 Spring Boot 4 当前版本同步维护；正文含完整可直接复制的实体、Repository、分页与批量写入代码示例
安全性	9	纯 Markdown 文档配 Java 示例，技能自身不执行任何命令、不联网、不要求任何凭据；许可证明确（MIT）；第三方平台 skills.sh 显示 Socket 与 Snyk 两项独立安全审计均为 Pass；内容未见任何可疑指令或误导性说明

综合评分：7.7

7. 跟同类 Skills 相比的优势

项目	定位	与本技能的差异
kotlin-backend-jpa-entity-mapping（Kotlin/kotlin-agent-skills，JetBrains 官方维护，983 星）	面向 Kotlin 语言的 JPA 实体建模规范，聚焦 `data class` 与 Hibernate 身份/相等语义冲突、Kotlin 特有的 ORM 陷阱	语言与问题域都不同——面向 Kotlin 项目的身份/相等性建模问题，不覆盖 N+1 修复路径、Keyset 深分页写法或 Boot 3→4 迁移期的破坏性变化清单；两者分别服务 Kotlin 与 Java 技术栈的团队
domain-driven-design（同仓库另一子技能）	聚焦聚合根、值对象、领域事件的 DDD 建模规范，附带轻量 JPA 映射约定	JPA 相关内容只是 DDD 建模的附属说明，不含 N+1 识别修复、深分页、批量写入配置或 Boot 3→4 持久化层迁移清单；本技能覆盖的是日常持久化层编码本身，不要求项目采用 DDD 方法论

8. 用户评价

该技能目前在第三方平台尚无具名用户评价。

9. 其他补充

仓库同时维护 Spring Boot 3 分支下的等价版本（skills/spring-boot-3/spring-data-jpa），实体建模、N+1 修复与分页优化等核心规则不变，Boot 4 专属的迁移清单在 Boot 3 分支不适用。

10. 安装使用方式

Claude Code：

mkdir -p "$PROJECT_DIR/.claude/skills"
cp -r skills/spring-boot-4/spring-data-jpa "$PROJECT_DIR/.claude/skills/"

Codex：

mkdir -p "$PROJECT_DIR/.codex/skills"
cp -r skills/spring-boot-4/spring-data-jpa "$PROJECT_DIR/.codex/skills/"

安装后无需重启 agent，下次涉及 JPA 实体、Repository 查询或持久化层代码的对话会自动触发该技能。

11. 注意事项

内容专为 Spring Data JPA（基于 Hibernate 的关系型数据库访问）编写，若项目使用 MongoDB、Spring Data JDBC 或其他非 JPA 持久化方案，整份技能不适用
Boot 4 迁移清单覆盖的是仓库 2026-07-30 最近一次更新时已知的变化；Spring Boot 4.x 后续小版本若继续调整相关 API 或属性名，需自行核实是否有新变化
仓库由单一个人开发者维护，无官方或厂商背书，长期维护延续性依赖作者个人投入