Web应用部署Wildfly连接Couchbase时遇ClassNotFoundException

核心原因 #

Wildfly的模块化类加载机制默认会限制对sun.misc.Unsafe这类JDK内部API的访问，而独立Java项目没有这种类加载限制，所以能正常运行。Couchbase SDK底层依赖这个类做高性能操作，因此在Wildfly环境下会抛出找不到类的异常。

解决方案 #

1. 配置Wildfly的sun.misc模块 #

• 在Wildfly的modules/system/layers/base/sun/misc/main目录下（没有就手动创建），新建module.xml文件，内容如下：

<?xml version="1.0" encoding="UTF-8"?>
<module name="sun.misc" xmlns="urn:jboss:module:1.9">
    <resources>
        <!-- 空资源，该类属于JDK自带 -->
    </resources>
    <dependencies>
        <system export="true">
            <paths>
                <path name="sun/misc"/>
            </paths>
        </system>
    </dependencies>
</module>

• 在你的Web应用WEB-INF目录下新建jboss-deployment-structure.xml文件，添加模块依赖：

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
    <deployment>
        <dependencies>
            <module name="sun.misc" export="true"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

2. 修改Wildfly启动参数，开放内部API访问 #

找到Wildfly的单机启动脚本standalone.bat，在脚本中添加以下JVM参数：

set "JAVA_OPTS=%JAVA_OPTS% --add-opens java.base/sun.misc=ALL-UNNAMED"

这个参数允许你的Web应用（属于未命名模块）访问JDKjava.base模块下的sun.misc包。

3. 确认Couchbase SDK版本兼容性 #

避免使用老旧的Couchbase SDK版本，旧版本对OpenJDK 21和Wildfly 29的模块化支持可能存在问题。推荐使用最新的4.x版本，比如Maven项目可在pom.xml中配置：

<dependency>
    <groupId>com.couchbase.client</groupId>
    <artifactId>java-client</artifactId>
    <version>4.1.6</version> <!-- 或更高兼容版本 -->
</dependency>

4. 排查依赖冲突 #

如果你的应用打包时自带了Couchbase依赖，需确保Wildfly没有优先加载系统内置的同名模块导致冲突。可在jboss-deployment-structure.xml中添加排除规则：

<jboss-deployment-structure>
    <deployment>
        <exclusions>
            <module name="com.couchbase.client"/> <!-- 若Wildfly内置Couchbase模块则添加 -->
        </exclusions>
        <dependencies>
            <module name="sun.misc" export="true"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

验证步骤 #

1. 重启Wildfly，重新部署应用后执行连接代码。
2. 若仍报错，查看服务器日志中的模块加载警告，确认sun.misc模块是否被正确加载。
3. 对比独立项目的Couchbase SDK版本，确保Web应用使用相同版本。

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