spring-data-jpa

Spring Data JPA 实现

用途

当任务专门涉及 Spring Boot 代码库中的持久化设计或实现时，请使用此技能。此技能通过聚合根指导、查询模式选择、CQRS 读模型决策，以及随附的仓库和关系模板来提供帮助。

关键规则

• 不要为每个实体都创建仓库。只为聚合根创建仓库。
• 查询变得复杂时，不要依赖冗长的派生查询方法名。
• 实体状态转换很重要时，不要盲目使用 save()；应了解 persist 与 merge 的行为。
• 对于读密集型路径，优先使用投影或专用查询服务。
• 除非现有架构有意采用其他做法，否则应将事务边界放在服务层。

工作流

步骤 1：识别持久化问题

先收集最少量的上下文：

1. 该类型是聚合根还是内部实体？
2. 任务主要涉及读侧、写侧，还是两者都有？
3. 查询属于简单查找、筛选搜索、聚合、投影，还是动态条件查询？
4. 此路径是否对性能敏感？
5. 是否存在会影响关系建模的模块边界或松耦合约束？

步骤 2：选择实现模式

使用此表决定接下来要加载什么。

模式	适用场景	阅读
简单仓库	基本 CRUD 和 1-2 个简单查找	现有代码或无需阅读
@Query 仓库	多个筛选条件、联接、排序、易读的 JPQL	references/query-patterns.md
DTO 投影	只读且对性能要求较高的响应	references/dto-projections.md
自定义仓库	Criteria API、批量操作、EntityManager 逻辑	references/custom-repositories.md
CQRS 查询服务	分离读写模型、报表、专用读取路径	references/cqrs-query-service.md

使用此决策指南：

需求	简单	@Query	DTO	自定义	CQRS
基本 CRUD	是	是	否	是	是
自定义筛选条件	否	是	是	是	是
最佳读取性能	否	有时	是	有时	是
复杂动态逻辑	否	否	否	是	是
清晰区分读写	否	否	有时	有时	是

步骤 3：加载匹配的参考资料

仅加载当前任务所需的参考资料：

• references/query-patterns.md
• references/dto-projections.md
• references/custom-repositories.md
• references/cqrs-query-service.md
• references/relationships.md
• references/performance-guide.md

步骤 4：应用匹配的资源

使用 assets/ 中随附的模板，而不是从头重建模式：

• assets/query-repository.java
• assets/dto-projection.java
• assets/custom-repository.java
• assets/query-service.java
• assets/relationship-patterns.java

模板使用与 creating-springboot-projects 相同的占位符约定：{{PACKAGE}}、{{MODULE}}、{{NAME}}、{{TABLE_NAME}}、{{TYPE}}、{{FIELD}}。完整表格请参阅 creating-springboot-projects/SKILL.md#placeholder-convention。

步骤 5：验证关系和事务边界

在最终确定更改之前，请检查：

• 仓库仅存在于聚合根边界
• 延迟加载行为是有意选择的
• 行数可能增长时使用了分页或投影
• 在联接实体更合适时，没有引入 @ManyToMany
• 适当的读取服务使用了 @Transactional(readOnly = true)
• 写操作保留在服务层事务中

步骤 6：验证对性能敏感的路径

如果任务涉及以下内容，请阅读 references/performance-guide.md：

• N+1 风险
• 获取计划问题
• 无界查询
• 批量操作
• 应使用投影的繁重读取视图

优先采用的高价值模式

仓库边界

• 聚合根应拥有仓库。
• 内部子实体通常不需要。

查询风格

• 简单查询使用派生查询方法。
• 对于联接、可读文本块或多个筛选条件，使用 @Query。
• 当响应不需要实体时，使用 DTO 投影。
• 当读取模型与写入模型不同时，使用 CQRS 查询服务。

关系

• 在可能的情况下，优先使用 @ManyToOne，而不是 @OneToMany。
• 当松散耦合比导航更重要时，使用 ID，而不是实体引用。
• 将 @ManyToMany 视为警示信号；优先使用显式联接实体。

输出格式

提出或实现持久化变更时，请返回：

## Recommended pattern
- Pattern:
- Why:

## Files to change
- `path/to/file`

## References used
- `references/...`

## Risks to verify
- ...

不适用此技能的情况

• Spring Data JPA 以外的通用 SQL 或数据库管理工作
• 整个项目的迁移规划
• 属于 creating-springboot-projects 的广泛项目脚手架工作