从EAP5升级至EAP7时Persistence.xml无法读取实体类问题

我来帮你搞定这个升级时遇到的坑！从EAP5升到EAP7，Hibernate版本（EAP7默认用Hibernate 5.x）和JBoss类加载机制都有不小变化，你遇到的HHH000183报错，核心就是Hibernate没扫描到xxx.jar里的实体类，结合你的EAR结构，按下面的步骤排查：

1. 先检查persistence.xml的实体扫描配置 #

EAP5的Hibernate 3.x可能会默认扫描jar中的实体，但EAP7的Hibernate 5.x更严格，你需要明确告诉它要加载哪些实体：

• 显式指定实体类：在<persistence-unit>标签内添加<class>元素，把每个实体的全限定类名列出来，比如：

  <persistence-unit name="yourPU" transaction-type="JTA">
      <class>xdirectory.xsubdirectory.YourFirstEntity</class>
      <class>xdirectory.xsubdirectory.YourSecondEntity</class>
      <!-- 其他实体类 -->
      <!-- 其他配置比如数据源、方言等 -->
  </persistence-unit>
  

• 开启自动扫描：如果不想逐个列实体，添加<exclude-unlisted-classes>false</exclude-unlisted-classes>到<persistence-unit>中，让Hibernate自动扫描当前jar下的所有带@Entity注解的类。注意这个配置要放在其他配置之前。

2. 适配EAP7的类加载机制 #

EAP7的类加载器和EAP5差异很大，EAR/lib下的jar默认属于common类加载器，而Hibernate的实体扫描可能默认只扫描应用类加载器下的资源。你可以通过以下方式调整：

• 添加jboss-deployment-structure.xml：在EAR的META-INF目录下创建这个文件，配置让xxx.jar的类能被Hibernate加载：

  <jboss-deployment-structure>
      <deployment>
          <dependencies>
              <!-- 把xxx.jar标记为部署级模块，允许Hibernate访问 -->
              <module name="deployment.your-app-name.ear.xxx.jar" export="true"/>
          </dependencies>
      </deployment>
  </jboss-deployment-structure>
  

• 调整jar的位置：如果你的EAR包含web模块，可以把xxx.jar从EAR/lib移到web模块的WEB-INF/lib下，这样应用类加载器会优先加载这个jar，Hibernate的扫描逻辑更容易覆盖到。

3. 验证实体类和注解的正确性 #

升级时容易忽略依赖包的变化，导致注解失效：

• 确认实体类上的@Entity注解是正确的包：EAP7.0及之前用javax.persistence.Entity，如果是EAP7.3+的Jakarta EE版本，要换成jakarta.persistence.Entity
• 检查实体类有没有被正确打包到xxx.jar中：用命令jar tf xxx.jar查看，确认xdirectory/xsubdirectory/下有对应的.class文件

4. 检查Hibernate的持久化单元配置 #

确保<persistence-unit>的classloader属性指定了正确的类加载器，比如：

<persistence-unit name="yourPU" transaction-type="JTA" classloader="application">
    <!-- 其他配置 -->
</persistence-unit>

这个属性会强制Hibernate使用应用类加载器来扫描实体，避免类加载器隔离的问题。

先从persistence.xml的配置开始排查，这是最常见的原因，如果不行再调整类加载配置，一般就能解决问题了。

内容的提问来源于stack exchange，提问作者Ranjeeta