JPA持久化失败UnknownEntity错误解决方案

在实际项目中，许多开发者在整合 Spring 5 与 Hibernate 时，常常会遇到一个令人头疼的问题——UnknownEntity 错误。这个错误看似是代码缺陷，实则绝大多数情况下是元数据注册环节出了问题，与业务逻辑本身并无关联。

通俗地讲，就是 JPA 的 EntityManagerFactory 根本没有识别出你定义的实体类，错误通常表现为 org.hibernate.UnknownEntityTypeException，或者直接抛出 IllegalArgumentException: Unknown entity。

如果你在 Spring 5 项目中通过 LocalContainerEntityManagerFactoryBean 来构建 EntityManagerFactory，那么请务必留意：仅靠 XML 里声明一个 或 是无效的，JPA 实体并不会被自动加载。你必须手动提供一份符合规范的 META-INF/persistence.xml 文件——将其放在 src/main/resources 目录下，千万不能放错位置。

那么，合格的 persistence.xml 应该长什么样？直接看示例：

                    com.example.model.User        com.example.model.Order                                                                                                                            

配置文件搞定之后，Spring XML 配置也必须对应起来。在 config.xml 中，必须将 persistenceUnitName 设置为与 persistence.xml 里的 name 完全一致：

解决了核心配置之后，来看看哪些地方最容易翻车。

• 实体未注册：persistence.xml 里的 标签漏写了，或者包路径拼写错误；
• 文件放错位置：persistence.xml 没有放在 META-INF/ 目录下，注意大小写必须完全一致，而且要确保 Maven 打包时能将它放入 classes/META-INF/；
• 持久化单元名称不匹配：Spring 配置中写的 persistenceUnitName 与 persistence.xml 里的 name 没有严格对应，差一个字符都不行；
• 依赖冲突：有些开发者习惯性地同时添加 hibernate-core 和 hibernate-entitymanager，但实际上 Spring 5 推荐使用 spring-orm + hibernate-core 5.4+ 就足够了，不需要单独的 hibernate-entitymanager；
• 验证加载：启动时不要只盯着错误日志，正常启动后应该能看到类似 HHH000412: Hibernate Core {5.4.32.Final} 和 HHH000426: Discovered a new persistence unit: oraclePU 这样的日志，说明配置已经正确加载。

最后给出一个实用建议。如果项目条件允许，不如尽早迁移到 Java Config 或 Spring Boot 方式。通过 @Configuration + @EnableJpaRepositories 就能轻松搞定，XML 配置确实比较脆弱。尤其是 Spring Boot 的 spring-boot-starter-data-jpa，可以自动扫描 @Entity 类，基本可以和 UnknownEntity 错误说再见了。

配置走对之后，再执行 EntityManager.persist(entity) 就不会出现异常，Oracle 数据库那边的持久化通路也就彻底打通了。