减少JPA中N+1问题时需要安装的 jpa-patterns 技能
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
原文链接：减少JPA中N+1问题时需要安装的 jpa-patterns 技能（cccskills）
技能页面：jpa-patterns
本文结论
安装 jpa-patterns 后，使用 Spring Boot 开发的工程师可以与 AI 智能体一起推进 JPA/Hibernate 的实体设计和 N+1 问题对策。
本文将依次介绍发出请求后返回的内容、安装方法以及请求示例。
最后是在采纳建议之前需要确认的注意事项。
安装 jpa-patterns 后，智能体会一并审查关联定义和查询处理，并提出防止 N+1 问题的数据获取方式。
N+1 问题是指：一次获取列表后，为获取每行的关联数据而额外发出与行数等量 SQL 的状态。
例如，可以这样请求：
请审查该实体的关联定义，并提出防止 N+1 问题的数据获取方式
智能体首先会确认关联的加载方式。
技能的方针是：将关联统一设置为延迟加载（在使用时再获取的方式），并且不对集合添加 EAGER 配置。
仅在需要同时使用父子数据的地方，会返回在 Repository 中添加 JOIN FETCH 查询的方案。
@Query("select m from MarketEntity m left join fetch m.positions where m.id = :id")
Optional<MarketEntity> findWithPositions(@Param("id") Long id);
对于列表页面等仅读取的处理，也会提出使用 DTO 投影的方案。
DTO 投影是指：用只包含 ID、名称等必要字段的轻量类型来接收查询结果的方法。
修改后需开启 Hibernate 的 SQL 日志，通过发出的 SQL 数量来验证效果。
jpa-patterns 是一个将 Spring Boot 中 JPA/Hibernate 的设计到性能调优整合为统一方针的技能。
覆盖范围包括：实体、Repository、事务、索引、连接池等。
以下按工作类型分别介绍。
新建实体时，基本要求是通过注解明确指定表名、列的长度和是否必填。
枚举类型以字符串方式保存，创建时间和更新时间通过审计功能（auditing）自动记录。
关联通过 @OneToManyや@ManyToOne 等注解定义，父子的级联删除也在此阶段确定。
减少 SQL 的手段有两种：指定获取方式和使用投影。
关联以延迟加载为基本原则，仅在必要的查询中使用 JOIN FETCH 批量获取。
在只读页面中，原则上不返回完整实体，而是使用只返回所需列的投影。
更新操作通过在 Service 层方法上添加 @Transactional 来统一管理。
只读方法添加 @Transactional(readOnly = true)，并避免长时间持有事务。
不在事务间传递实体也是审查的对象之一。
列表搜索中使用 PageRequest 指定数量和排序，并用 Page 接收结果。
对于大量数据，也可以选择游标式分页——按大于上次读取 ID 的顺序依次获取。
索引的添加对象为状态、外键等经常用于过滤的列。
与搜索条件顺序一致的复合索引也是考虑对象。
批量注册使用 saveAll 和 Hibernate 的批处理配置统一发送。
连接池 HikariCP 提供了推荐配置值。
生产环境的表结构变更通过 Flyway 或 Liquibase 管理。
数据访问测试推荐使用 @DataJpaTest 和 Testcontainers 构建接近生产环境的配置。
安装方式有两种：通过命令安装和委托智能体安装。
命令如下，可以选择 Claude Code、Codex 等目标智能体。
npx skills add https://github.com/affaan-m/ECC --skill jpa-patterns
如果委托智能体安装，请直接发送以下内容。
这是请求在确认内容后再进行部署的请求，不会省略确认步骤。
次の Agent Skill をインストールしてください。
https://github.com/affaan-m/ECC/tree/main/skills/jpa-patterns
まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/jpa-patterns/、Codex なら ~/.agents/skills/jpa-patterns/ に配置してください。
存放位置根据是用于所有项目还是仅用于特定项目而有所不同。
| 智能体 | 所有项目通用 | 仅特定项目使用 |
|---|---|---|
| Claude Code | ~/.claude/skills/ | 项目的 .claude/skills/ |
| Codex | ~/.agents/skills/ | 项目的 .agents/skills/ |
jpa-patterns 是 affaan-m/ECC 仓库中的技能之一。
文件仅有 SKILL.md，可在部署前通读全文。
以下介绍 3 个可直接用于日常开发的请求示例。
只需用中文发送给安装了技能的智能体即可。
为列表搜索添加分页功能，并评估所需的索引
返回的内容是使用 PageRequest 指定数量和排序、返回 Page 的 Repository 方法方案。
同时会提出与过滤列和排序相对应的复合索引（例如状态与创建时间）建议。
对于数据量较大的列表，也会提出以 ID 为基准获取后续数据的游标式方案作为选项。
检查订单服务的事务范围，告诉我哪些方法可以设为只读
对于只读方法，返回的是添加 readOnly = true 的方案。
如果存在长时间持有事务或跨事务传递实体的写法，会将其列为审查对象。
还会特别提醒需要谨慎选择传播设置（事务的继承方式）。
编写 Repository 测试，并通过 SQL 日志确认是否发生了 N+1 问题
针对此请求，会返回使用 @DataJpaTest 和 Testcontainers 的测试方案。
同时会附上以下将 SQL 和绑定值输出到日志的配置，便于亲自确认发出的 SQL 数量。
logging.level.org.hibernate.SQL=DEBUG
logging.level.org.hibernate.orm.jdbc.bind=TRACE
jpa-patterns 是以 Spring Boot 和 JPA/Hibernate 为前提的技能。
对于使用其他 ORM 的项目或不使用 Spring Data JPA 的项目，提供的代码示例不能直接套用。
生产环境的表结构变更通过 Flyway 或 Liquibase 进行，方针是不依赖 Hibernate 的自动 DDL（从实体自动生成表的功能）。
对于正在使用自动 DDL 的项目，需要考虑这一前提差异来理解建议内容。
数据库迁移以追加型为基本原则，并注意不要在没有计划的情况下删除列。
连接池的推荐值为固定数值，LOB 的配置针对 PostgreSQL。
二级缓存的定位也是"谨慎考虑后使用"，需在确认适合自己的数据库和负载后再使用。
建议在通过测试和实际 SQL 日志确认后，再采纳提出的变更方案。
技能以 MIT 许可证公开。
安装前请阅读 SKILL.md 的内容，确认没有可疑处理。
不会自动修复。
智能体会提出使用延迟加载、JOIN FETCH 和投影的数据获取方案，是否采纳由开发者决定。
采纳后请通过 SQL 日志确认 SQL 数量。
适用对象为使用 Spring Boot 的 JPA/Hibernate 项目。
代码示例以 Spring Data JPA 的 Repository 和 @Transactional 为前提，无法在其他配置中直接使用。
可以。
不仅适用于新实体的设计，也适用于现有关联定义及查询/更新处理的审查。
从列表页面中 SQL 数量较多的地方开始请求，便于通过 SQL 日志对比效果。
jpa-patterns 是供使用 Spring Boot 和 JPA/Hibernate 的工程师与智能体一起推进实体设计和 N+1 问题对策的技能。
可以用统一方针审查关联定义、分页、索引和事务。
请在通过测试和 SQL 日志确认后再采纳建议。
详细信息汇总在 cccskills 页面。
本文转载自 cccskills 的文章「减少JPA中N+1问题时需要安装的 jpa-patterns 技能」。
技能详情和安装方法请参见 cccskills 的 jpa-patterns 页面。