用途
该技能用于在纯 Java 项目中诊断和修复 Hibernate ORM / Jakarta Persistence 相关问题，采用“问题 → 反模式 → 修复”的库式组织方式，覆盖实体映射与查询。它保持框架中立，涵盖 EntityManager/Session 行为、JPQL/HQL 以及映射注解。若项目使用 Spring Boot 且已安装 java-springboot 和 spring-boot-testing 技能，则应使用它们处理 Spring Data 仓库、事务装配和 @DataJpaTest；Panache 与响应式持久化参见 Quarkus 技能；针对真实数据库的集成测试参见 java-testcontainers。
主要能力
技能首先要求检测技术栈：读取 pom.xml/build.gradle（或依赖树）以确认 hibernate-core 与持久化 API（jakarta.persistence 对应 Hibernate 6+/Jakarta EE 9+，javax.persistence 对应 Hibernate 5，参见 javax-to-jakarta-migration）；记录 Hibernate 主版本，因为行为存在差异（Hibernate 6.0-6.1 实现 Jakarta Persistence 3.0，6.2+ 实现 3.1，7.x 实现 3.2，且 Hibernate 7 需要 Java 17+）；记录数据库以及 schema 是否由 Flyway/Liquibase 管理；在“优化”任何内容之前，先在测试中开启 SQL 日志与统计以测量语句数量。
技能提供快速决策表，将症状映射到可能原因与参考文档：一个请求出现许多相似 SELECT 对应惰性关联上的 N+1；LazyInitializationException 对应会话外惰性访问；HHH000104 / HHH90003004 警告及大内存占用对应使用集合抓取连接的分页；插入慢且无 JDBC 批处理对应 IDENTITY 主键或未配置批处理；重复行/丢失子项/Set 异常对应错误的 equals/hashCode 或级联误用；丢失更新、死锁对应缺少锁策略；缓存导致数据陈旧或异常对应二级/查询缓存误用；schema 漂移、生产环境使用 ddl-auto 对应缺少迁移工具。
使用方式
技能给出顶层规则供评审时应用：关联方面，@ManyToOne/@OneToOne 默认 EAGER，应显式声明 fetch = FetchType.LAZY；@OneToMany/@ManyToMany 默认 LAZY 并应保持；按查询选择抓取方式（JOIN FETCH、实体图），而非将映射改为 EAGER。优先使用 @ManyToOne 拥有方加双向 @OneToMany(mappedBy=...)，仅在需要时使用，并通过辅助方法保持两侧同步。集合选择上，@ManyToMany 使用 Set；无 @JoinColumn 的单向 @OneToMany 或无排序的 List 会产生昂贵的更新模式。绝不在 @ManyToOne 或 @ManyToMany 上使用 CascadeType.REMOVE/ALL；仅在真正由父方拥有的子集合上使用 orphanRemoval。主键方面，生成的数值 id 使用 SEQUENCE（池化优化器，allocationSize 与数据库增量匹配）；IDENTITY 会禁用 JDBC 插入批处理；需要在客户端生成 id 时使用 UUID（优先时间有序）。实体方面，不要在关联上使用 Lombok @Data/@EqualsAndHashCode/@ToString；应有意实现 equals/hashCode。读端点返回 DTO/投影而非实体；绝不在 API 中直接暴露实体（惰性代理）。分页使用包含唯一决胜列的稳定 ORDER BY；绝不将 setMaxResults 与集合 JOIN FETCH 组合。事务保持在服务边界且简短；其中不得有远程调用或用户交互。批量工作应分批写入并刷新，并定期清理持久化上下文。在针对真实数据库引擎的测试中用语句数量验证行为。
适用场景
适用于纯 Java 项目中使用 Hibernate ORM / Jakarta Persistence 进行实体映射与查询时遇到的性能与正确性问题，包括 N+1 查询、惰性加载错误、标识符生成、实体 equals/hashCode、关联与级联、分页与批处理、锁与事务、缓存以及 schema 管理。
限制
技能本身为框架中立，不替代 Spring Boot、Quarkus 等特定框架的技能；版本相关细节需查阅 references/tooling-and-versions.md。schema 管理规则为：原型/本地可使用 hibernate.hbm2ddl.auto=update（或一次性测试用 create-drop）；生产（默认）使用 Flyway 或 Liquibase 的版本化迁移，并设置 hibernate.hbm2ddl.auto=validate（或 none）；外部管理的 schema 使用 none（或 validate），不要添加迁移工具。升级时应获取目标版本的迁移指南（优先于本技能）。
参考文档
references/fetching-and-n-plus-one.md：N+1 检测与修复、惰性 vs 急切、LazyInitializationException、open-session-in-view、DTO 投影。references/identifiers-and-entity-design.md：id 生成、equals/hashCode、Lombok、records vs 实体、枚举与转换器、值类型。references/associations-and-cascade.md：双向辅助方法、级联、orphanRemoval、集合选择、@ManyToMany。references/queries-pagination-batching.md：分页（偏移、键集、内存警告）、批量操作、JDBC 批处理、StatelessSession。references/locking-transactions-caching.md：乐观/悲观锁、事务边界、刷新模式、二级缓存。references/tooling-and-versions.md：SQL 日志、统计、测试、连接池大小、迁移、Hibernate 5/6/7 差异。
权威文档：Hibernate ORM 用户指南 https://docs.hibernate.org/orm/current/userguide/html_single/ 与 Jakarta Persistence https://jakarta.ee/specifications/persistence/。深度背景文章：https://vladmihalcea.com/。升级（获取目标版本页面，优先于本技能）：迁移指南 https://hibernate.org/orm/documentation/migrate/（6.6：https://docs.hibernate.org/orm/6.6/migration-guide/，7.0：https://docs.hibernate.org/orm/7.0/migration-guide/），发行说明 https://hibernate.org/orm/releases/。