本文详解如何在JDK 17模块化项目中正确声明Jackson依赖（如com.fasterxml.jackson.core），解决module not found编译错误及包不可见问题，涵盖模块名适配、版本兼容性、Gradle配置与构建清理等关键步骤。
本文详解如何在jdk 17模块化项目中正确声明jackson依赖（如`com.fasterxml.jackson.core`），解决`module not found`编译错误及包不可见问题，涵盖模块名适配、版本兼容性、gradle配置与构建清理等关键步骤。
在基于Java Platform Module System（JPMS）的项目中，当你为模块（如 foo）编写 module-info.java 并尝试通过 requires com.fasterxml.jackson.core; 声明依赖时，却收到编译错误：
error: module not found: com.fasterxml.jackson.core
这并非因依赖未引入，而是模块系统无法识别Jackson JAR中声明的模块名——根本原因在于：Jackson自2.12起重构了模块命名规范，且2.15.1版本存在module-info.class生成异常（GitHub Issue #1027），导致模块解析失败。
✅ 正确的模块名：不是com.fasterxml.jackson.core，而是jackson.core
Jackson官方从2.12版本开始，将模块名简化为小写短名称（遵循JEP 261推荐实践）。实际模块名需以jar --describe-module命令确认：
jar --describe-module --file=$HOME/.gradle/caches/modules-2/files-2.1/com.fasterxml.jackson.core/jackson-core/2.15.1/.../jackson-core-2.15.1.jar
输出示例：
立即学习“Java免费学习笔记（深入）”；
jackson-core-2.15.1.jar module jackson.core@2.15.1 requires java.base mandated exports com.fasterxml.jackson.core
✅ 正确写法（注意大小写与命名）：
module foo {
requires org.slf4j;
requires org.apache.commons.lang3;
requires jackson.annotations; // 替换 com.fasterxml.jackson.annotation
requires jackson.core; // 替换 com.fasterxml.jackson.core
requires jackson.databind; // 替换 com.fasterxml.jackson.databind
}⚠️ 注意：模块名严格区分大小写，且无com.fasterxml.前缀；jackson.annotations对应jackson-annotations，jackson.core对应jackson-core，jackson.databind对应jackson-databind。
?️ 版本选择：避开2.15.1的module-info缺陷
Jackson 2.15.1因构建流程问题，在JAR中嵌入了不兼容JPMS的module-info.class（重复声明或签名错误），导致模块系统拒绝加载。官方已确认该问题，并于2.15.2修复（Issue #1027）。
✅ 推荐方案（立即生效）：
- 降级至稳定兼容版本：2.15.0 或 2.14.3（经验证完全支持JPMS）
- 或 升级至已发布修复版：2.15.2+（截至2026年7月，2.15.2/2.15.3均已稳定）
Gradle配置示例（统一版本，避免冲突）：
dependencies {
// ✅ 统一使用2.15.0（兼容JPMS且无module-info缺陷）
implementation 'com.fasterxml.jackson.core:jackson-annotations:2.15.0'
implementation 'com.fasterxml.jackson.core:jackson-core:2.15.0'
implementation 'com.fasterxml.jackson.core:jackson-databind:2.15.0'
// 其他依赖保持不变...
}? 构建与环境清理（关键！常被忽略）
即使修改了module-info.java和依赖版本，旧缓存仍会导致错误持续：
-
强制清理Gradle缓存与构建产物：
./gradlew clean ./gradlew --refresh-dependencies build
-
IDE同步（IntelliJ IDEA为例）：
- File → Invalidate Caches and Restart → Invalidate and Restart
- 重启后右键项目 → Reload project
-
验证模块是否被正确读取： 在module-info.java中添加open（仅调试用，非生产推荐）：
module foo { opens foo to jackson.databind; // 允许反射访问（如反序列化） requires jackson.core; requires jackson.databind; // ... }
? 补充注意事项
- Kotlin用户特别注意：若使用jackson-module-kotlin，必须确保其版本与jackson-databind完全一致（如2.15.0），否则jacksonMapperBuilder()等扩展函数将因签名不匹配而抛NoSuchMethodError。
- Spring Boot项目：Spring Boot 3.x默认启用JPMS，建议在pom.xml或build.gradle中显式管理Jackson版本，避免Starter传递旧版（如2.12.x）覆盖。
-
Maven用户：在pom.xml中使用<dependencyManagement>统一锁定所有Jackson模块版本，防止间接依赖污染：
<dependencyManagement> <dependencies> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-bom</artifactId> <version>2.15.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>
✅ 总结：三步快速修复
| 步骤 | 操作 | 目标 |
|---|---|---|
| 1. 修正模块名 | 将requires com.fasterxml.jackson.* → requires jackson.* | 符合JPMS模块命名规范 |
| 2. 锁定兼容版本 | 使用2.15.0或2.15.2+，确保jackson-core/databind/annotations版本严格一致 | 规避2.15.1的module-info缺陷 |
| 3. 彻底清理重建 | clean + --refresh-dependencies + IDE缓存重置 | 清除残留旧模块元数据 |
完成以上操作后，javac将成功解析Jackson模块，package com.fasterxml.jackson.databind is not visible等可见性错误也将自然消失。模块化不仅是语法升级，更是依赖契约的显式化——精准声明，方得可靠。
