JBoss EAP7.2中ClassLoader无法加载WAR包WEB-INF/lib内存在的类

问题背景 #

更新JNDI配置并重启部署后，服务首次调用ImportantClass时触发如下报错：

[TRACE] (ServerService Thread Pool -- 79) ..camel.util.ObjectHelper (485) Cannot load class: ImportantClass 
using classloader: ModuleClassLoader for Module "deployment.my-war-deployment.war" from Service Module Loader: 
java.lang.ClassNotFoundException: ImportantClass 
from [Module "deployment.my-war-deployment.war" from Service Module Loader]

WAR包的WEB-INF/lib目录下明确包含my-jar.jar（该JAR内存在ImportantClass），且my-jar.jar同时是另一个EAR部署my-ear-deployment.ear的模块之一；即使移除POM中该依赖的<scope>compile</scope>配置，问题仍存在。

可能原因及解决办法 #

1. 跨部署模块的类加载隔离冲突 #

JBoss EAP 7.x采用模块化类加载机制，当同一个JAR同时作为EAR模块和WAR的WEB-INF/lib依赖时，会出现类加载上下文冲突：EAR的my-jar.jar会被注册为独立的服务模块，WAR的类加载器可能被引导优先加载EAR中的模块版本，而非自身WEB-INF/lib内的JAR。

解决步骤：

• 检查EAR的jboss-deployment-structure.xml（若存在），确认是否将my-jar.jar标记为全局共享或对WAR可见。若存在类似<module name="deployment.my-ear-deployment.ear.my-jar.jar" export="true"/>的配置，会导致WAR优先加载EAR模块，若EAR模块的my-jar.jar版本不含目标类，就会触发异常。
• 在WAR包中创建/修改jboss-deployment-structure.xml，强制WAR优先加载自身WEB-INF/lib的JAR：

  <jboss-deployment-structure>
      <deployment>
          <dependencies>
              <!-- 排除对EAR中my-jar模块的依赖 -->
              <module name="deployment.my-ear-deployment.ear.my-jar.jar" export="false" optional="true"/>
          </dependencies>
          <!-- 开启WEB-INF/lib类加载优先级 -->
          <local-last value="false"/>
      </deployment>
  </jboss-deployment-structure>
  

2. JBoss类加载器缓存失效 #

更新JNDI配置重启后，JBoss的部署缓存可能未正确刷新，导致类加载上下文混乱。

解决步骤：

• 停止JBoss服务，删除JBOSS_HOME/standalone/data/content下的部署缓存文件，以及JBOSS_HOME/standalone/tmp下的临时文件。
• 重新执行mvn clean package打包WAR，确保my-jar.jar完整包含ImportantClass后重新部署。

3. 模块类加载器可见性配置异常 #

默认情况下，WAR的ModuleClassLoader应能访问自身WEB-INF/lib的JAR，但全局配置可能破坏这一逻辑。

解决步骤：

• 检查standalone.xml/domain.xml中urn:jboss:domain:ee:4.0子系统的配置，确认是否存在自定义jboss.module.path或影响类加载的全局参数，如有则调整为默认值。
• 在WAR的MANIFEST.MF中添加Dependencies: deployment.my-war-deployment.war，明确指定类加载依赖范围。

4. 编译与部署依赖版本不一致 #

即使移除POM的compile scope，若Maven仍从EAR模块拉取my-jar.jar，可能导致打包到WAR的JAR版本不正确。

解决步骤：

• 在Maven的WAR插件配置中，明确指定my-jar.jar的来源，确保打包到WEB-INF/lib的是正确版本：

  <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-war-plugin</artifactId>
      <version>3.3.2</version>
      <configuration>
          <webResources>
              <resource>
                  <directory>${project.basedir}/lib</directory>
                  <includes>
                      <include>my-jar.jar</include>
                  </includes>
                  <targetPath>WEB-INF/lib</targetPath>
              </resource>
          </webResources>
      </configuration>
  </plugin>
  

• 重新打包部署，验证WEB-INF/lib中的my-jar.jar版本正确性。

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