本文详解 android 项目中因远程 maven 依赖（如 typesense-java）自带嵌入式依赖（shaded jar）导致的 duplicate class 错误，说明其与本地 jar 行为差异的根本原因，并提供 gradle 排除策略、潜在风险警示及工程化改进建议。
本文详解 android 项目中因远程 maven 依赖（如 typesense-java）自带嵌入式依赖（shaded jar）导致的 duplicate class 错误，说明其与本地 jar 行为差异的根本原因，并提供 gradle 排除策略、潜在风险警示及工程化改进建议。
在 Android 开发中，当你通过 implementation 'org.typesense:typesense-java:0.0.9-beta9' 引入远程依赖时出现大量 Duplicate class xxx found in modules ... 报错（如 com.fasterxml.jackson.databind.type.ArrayType、okio.Throttler），而改用本地 JAR（implementation files('libs/typesense-java-0.0.9-beta9.jar')）却能正常构建——这一看似矛盾的现象，根源在于 JAR 的打包方式差异。
typesense-java:0.0.9-beta9 是一个 shaded（重定位/阴影）JAR：它将 Jackson、OkHttp、Log4j、Kotlin stdlib 等全部依赖以原始字节码形式直接打包进自身 JAR 文件内，而非声明为 Maven 依赖项。当通过远程坐标引入时，Gradle 会：
- 下载该 shaded JAR（含所有内嵌类）；
- 同时根据其 POM 文件（若存在且未正确声明
provided ）或元数据，额外解析并拉取其传递依赖（如 jackson-databind:2.14.1、okio:2.8.0）； - 导致同一类（如 ArrayType）既存在于 shaded JAR 中，又存在于独立下载的 jackson-databind 模块中 → 触发 Android 构建期的 DEX 合并冲突。
而本地 JAR 无对应 POM，Gradle 仅将其视为扁平二进制依赖，不执行任何传递依赖解析，因此不会引入重复模块——这正是行为差异的本质。
✅ 推荐解决方案：显式排除所有嵌入依赖
在 build.gradle 中使用依赖约束语法，禁止 Gradle 解析 typesense-java 的任何传递依赖：
dependencies {
implementation("org.typesense:typesense-java:0.0.9-beta9") {
exclude group: '*', module: '*' // 排除所有传递依赖
}
// 其余依赖保持不变
implementation 'androidx.core:core-ktx:1.9.0'
implementation 'com.squareup.okhttp3:okhttp:4.11.0' // 显式声明你真正需要的版本
implementation 'com.fasterxml.jackson.core:jackson-databind:2.15.2' // 统一 Jackson 版本
}
⚠️ 注意事项：
- exclude group: '*', module: '*' 是最彻底的排除方式，适用于已知 JAR 自包含全部依赖的场景；
- 你必须手动声明项目所需的底层库版本（如 OkHttp、Jackson），否则编译或运行时可能因类缺失失败；
- 若其他依赖（如某 AndroidX 库）也间接引入了 Jackson 或 OkHttp，需确保版本兼容，必要时用 configurations.all { resolutionStrategy { force '...' } } 统一版本。
❗ 风险提示：Kotlin stdlib 冲突隐患
该 shaded JAR 还内嵌了 Kotlin 标准库（kotlin-stdlib-*）。在 Android 项目中，core-ktx 等 KTX 库已提供相同功能，若未排除，将导致 kotlin.KotlinNullPointerException 等运行时异常或方法解析歧义。上述 exclude group: '*', module: '*' 已覆盖此风险，但建议额外验证：
./gradlew app:dependencies --configuration implementation | grep "kotlin-stdlib"
确保输出中不再出现来自 typesense-java 的 kotlin stdlib 条目。
? 根本改进方向（对库维护者）
理想方案是发布 非 shaded 的标准 Maven 依赖：
- typesense-java 的 pom.xml 应将 jackson-databind、okhttp、kotlin-stdlib 等声明为
compile （默认），而非打包进 JAR； - 用户可自由控制这些依赖的版本与排除策略，符合 Maven/Gradle 最佳实践；
- 同时提供一个可选的 typesense-java-shaded 变体供特殊环境使用。
当前版本（0.0.9-beta9）尚未支持 Kotlin 项目开箱即用，主因即在于此阴影 JAR 与 Android Gradle Plugin 对 Kotlin 依赖的严格校验机制不兼容。后续升级至非 shaded 版本后，该限制自然解除。
综上，面对此类问题，核心思路是：识别 shaded JAR → 阻断其传递依赖解析 → 显式管理底层库 → 验证 Kotlin 兼容性。这不仅是解决 typesense-java 的权宜之计，更是处理各类“自包含 SDK”依赖的通用范式。
