412-frameworks-quarkus-panache

使用 Panache 的 Hibernate ORM

在 Quarkus 中应用 Hibernate ORM 的 Panache 模式。

此技能涵盖哪些内容？

• Active Record（PanacheEntity）与 PanacheRepository：何时使用各自的模式
• 参数化 JPQL / Panache 查询：位置参数（?1）和命名参数（:param），避免不安全的字符串拼接
• 在实体上使用 @NamedQuery 编写可复用、经过构建时验证的查询
• 使用 project(Class) 进行 DTO 投影，避免暴露受管理的实体
• 使用 Page.of(pageIndex, pageSize) 分页，并使用 query.count() 计数
• 在 JPQL 查询中使用 JOIN FETCH，避免 N+1 问题
• 使用 @Version 实现乐观锁，并处理 OptimisticLockException
• 使用 @Transactional 标注应用服务
• 在 @QuarkusTest 测试中使用 @TestTransaction 自动回滚
• 在 REST 边界映射实体与暴露 DTO
• 通过 Hibernate 执行原生查询，在同一事务中使用可控 SQL；在边界处绕过 Hibernate 时，可与 @411 配合使用 JDBC

范围： 根据参考规则以及正反代码示例应用建议。

约束

持久化变更前先编译；完成后验证。

• MANDATORY：应用任何变更前运行 ./mvnw compile 或 mvn compile
• PREREQUISITE：应用 Panache 改进前，项目必须能够编译
• SAFETY：如果编译失败，立即停止
• BLOCKING CONDITION：必须由用户解决编译错误后才能继续
• VERIFY：应用改进后运行 ./mvnw clean verify 或 mvn clean verify
• BEFORE APPLYING：阅读参考文档，了解详细规则和示例

何时使用此技能

• 审查 Quarkus 中的 Panache 实体或仓库
• 使用 Panache 改进 Hibernate ORM 数据访问
• 为 Panache 查询添加 DTO 投影、JOIN FETCH、分页或乐观锁
• 修复 N+1 查询问题，或在 Quarkus Panache 中添加 @Version 并发控制
• 改进 Panache Active Record 与 Repository 的设计

工作流

1. 阅读参考文档并评估项目上下文

阅读 references/412-frameworks-quarkus-panache.md，并检查当前项目设置，再提出变更建议。

2. 明确范围并确定目标改进

确定所需结果、约束条件，以及要应用的最小安全变更集。

3. 应用符合框架规范的变更

遵循参考模式和项目惯例，实现或重构配置与代码。

4. 运行验证并报告结果

运行适当的构建和测试，并总结变更内容、验证情况以及后续操作。

参考文档

详细指南、示例和约束请参阅 references/412-frameworks-quarkus-panache.md。