使用Gradle与Java模块时commons-math3模块找不到问题求助

问题概述 #

使用Java 17 + Gradle构建的模块化项目中，引入Apache Commons Math3库时，编译报错提示找不到模块commons.math3，但已通过gradlew dependencies确认依赖已成功下载。

现有配置代码 #

module-info.java 配置 #

module com.example {
    requires org.apache.pdfbox;
    requires org.apache.poi.ooxml;
    requires commons.math3;
    requires org.apache.commons.collections4;
    exports org.example;
}

build.gradle 依赖配置 #

dependencies {
    implementation 'org.apache.pdfbox:pdfbox:2.0.30'
    implementation 'org.apache.poi:poi-ooxml:5.3.0'
    implementation 'org.apache.commons:commons-math3:3.6'
}

报错信息 #

error: module not found: commons.math3
        requires commons.math3;

解决方案 #

Apache Commons Math3 3.6版本属于自动模块（未包含module-info.java的JAR包），它的自动模块名并非commons.math3，而是org.apache.commons.math3。

修改module-info.java中的依赖声明即可解决问题：

module com.example {
    requires org.apache.pdfbox;
    requires org.apache.poi.ooxml;
    // 修正为正确的自动模块名
    requires org.apache.commons.math3;
    requires org.apache.commons.collections4;
    exports org.example;
}

补充说明 #

自动模块的模块名规则：

• 优先读取JAR包META-INF/MANIFEST.MF中的Automatic-Module-Name属性值
• 若该属性不存在，则通过JAR文件名结合groupId推导：移除版本号，将非字母数字字符替换为.，最终生成模块名（commons-math3的groupId为org.apache.commons，因此自动模块名为org.apache.commons.math3）

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