问题现象与分析
在gradle多项目构建中，当一个子项目（如 interceptor）依赖于另一个子项目（如 commonutils）时，有时会出现 interceptor 无法识别 commonutils 中已声明的某些外部库的情况。具体表现为编译错误，例如 task :interceptor:compilejava failed，并伴随类似 cannot find symbol 的导入错误，指示特定类（如 com.google.gson.gson 或 com.rometools.rome.feed.rss.channel）无法被识别。
考虑以下项目结构：
Root project 'main-project' +--- Project ':CommonUtils' +--- Project ':Interceptor' \--- Project ':SearchService'
其中 Interceptor 项目依赖于 CommonUtils。如果 CommonUtils 中声明了 com.google.code.gson:gson 和 com.rometools:rome 等依赖，而 Interceptor 尝试使用这些库中的类，但 CommonUtils 的 build.gradle 中这些依赖被声明为 implementation，则 Interceptor 在编译时将无法访问这些传递性依赖。
CommonUtils 的 build.gradle 示例：
// ... (plugins, bootJar, jar, ext, processResources 配置省略)
dependencies {
// ... 其他依赖
implementation 'com.google.code.gson:gson:2.8.2' // 问题可能出在这里
implementation 'com.rometools:rome:1.18.0' // 问题可能出在这里
// ... 其他依赖
}
// ... (dependencyManagement 配置省略)Interceptor 的 build.gradle 示例：
// ... (plugins, bootJar, jar 配置省略)
dependencies {
implementation project(':CommonUtils') // Interceptor 依赖 CommonUtils
// ... 其他依赖
}问题的核心在于Gradle依赖配置的传递性规则。
Gradle依赖配置详解：implementation 与 api
Gradle提供了多种依赖配置类型，其中 implementation 和 api 是在库模块开发中理解依赖传递性至关重要的两种。
implementation： 当一个模块使用 implementation 声明一个依赖时，该依赖只对当前模块的编译和运行时可见。它不会被传递给依赖当前模块的其他模块。这意味着，如果 CommonUtils 使用 implementation 引入了 Gson，那么 Interceptor 即使依赖了 CommonUtils，也无法直接访问 Gson 的类。这种方式的优点是减少了消费模块的编译类路径，有助于加快编译速度，并避免不必要的依赖泄露，从而更好地封装模块内部实现。
api： 当一个模块使用 api 声明一个依赖时，该依赖不仅对当前模块的编译和运行时可见，还会被传递给所有依赖当前模块的其他模块。这意味着，如果 CommonUtils 使用 api 引入了 Gson，那么 Interceptor 依赖 CommonUtils 后，就可以直接访问 Gson 的类。api 配置适用于那些作为当前模块公共API一部分的依赖，即消费模块需要直接使用这些依赖中的类或接口。
解决方案一：优化共享模块依赖配置为 api
如果 CommonUtils 模块的公共接口或方法中确实使用了 Gson 或 Rometools 中的类型，或者这些库是 CommonUtils 对外提供服务时不可或缺的一部分，那么将这些依赖声明为 api 是最符合逻辑和推荐的做法。
适用场景： 当一个库模块（如 CommonUtils）需要将其内部使用的某些第三方库的类或接口暴露给其消费者（如 Interceptor）时，应使用 api 配置。
操作步骤： 修改 CommonUtils 的 build.gradle，将需要传递给 Interceptor 的依赖从 implementation 改为 api。
示例代码（CommonUtils/build.gradle）：
plugins {
id 'org.springframework.boot' version '2.2.0.RELEASE'
id 'io.spring.dependency-management' version '1.0.8.RELEASE'
id 'java'
}
// ... (其他配置)
dependencies {
// ... 其他依赖
api 'com.google.code.gson:gson:2.8.2' // 从 implementation 改为 api
api 'com.rometools:rome:1.18.0' // 从 implementation 改为 api
// ... 其他依赖
}
// ... (dependencyManagement 配置)通过此更改，Gson 和 Rometools 将作为 CommonUtils 公共API的一部分，传递给 Interceptor，从而解决编译错误。
解决方案二：在消费模块中显式声明依赖
另一种解决方案是，如果 Gson 和 Rometools 严格来说不属于 CommonUtils 的公共API，而只是 Interceptor 自身也需要这些库，那么可以在 Interceptor 模块中显式地声明这些依赖。
适用场景： 当消费模块（如 Interceptor）需要使用某些外部库，而这些库并非被其依赖的模块（如 CommonUtils）作为公共API暴露时。这有助于保持模块间的独立性，避免不必要的传递性依赖。
操作步骤： 在 Interceptor 的 build.gradle 中，添加缺失的依赖声明。
示例代码（Interceptor/build.gradle）：
plugins {
id 'org.springframework.boot' version '2.2.0.RELEASE'
id 'io.spring.dependency-management' version '1.0.8.RELEASE'
id 'java'
}
// ... (其他配置)
dependencies {
implementation project(':CommonUtils')
implementation 'io.jsonwebtoken:jjwt-api:0.11.5'
implementation 'org.apache.commons:commons-io:1.3.2'
implementation 'org.springframework.boot:spring-boot-starter-security'
implementation 'org.springframework.boot:spring-boot-starter-web'
compileOnly 'javax.servlet:javax.servlet-api:3.1.0'
// 显式添加 Interceptor 自身需要的 Gson 和 Rometools 依赖
implementation 'com.google.code.gson:gson:2.8.2'
implementation 'com.rometools:rome:1.18.0'
}这种方法虽然解决了编译问题，但可能导致依赖的重复声明（如果 CommonUtils 也需要这些依赖），并可能在未来版本升级时需要同步更新多处。然而，它确保了 Interceptor 对其自身所需依赖的明确性。
最佳实践与注意事项
-
选择 api 还是 implementation？
- 优先使用 implementation。它有助于构建更松耦合的模块，减少编译类路径，加快增量编译速度。只有当一个依赖的类型或方法确实出现在你的模块的公共API（即其他模块会直接调用你的模块中使用了该依赖的类型或方法）时，才考虑使用 api。
- 如果 CommonUtils 只是内部使用 Gson 进行数据处理，而没有在任何公共方法签名或返回类型中暴露 Gson 类型，那么 implementation 是更合适的。此时，如果 Interceptor 也需要 Gson，则应在 Interceptor 中单独声明。
- 如果 CommonUtils 有一个方法 public MyObject deserialize(String json)，其中 MyObject 是由 Gson 序列化/反序列化的，并且 MyObject 自身也是 CommonUtils 公共API的一部分，那么 Gson 可能就需要 api。
依赖版本管理： 在多项目环境中，建议使用 platform 或 dependencyManagement 块来统一管理共享依赖的版本，避免版本冲突和不一致。例如，在根项目的 build.gradle 中定义 ext 变量或使用 platform。
IDE同步： 在修改 build.gradle 文件后，务必在IDE（如IntelliJ IDEA）中执行Gradle项目同步或重新导入，以确保IDE的依赖视图与Gradle构建配置保持一致。这通常可以通过点击Gradle工具窗口中的“刷新”按钮或执行“File -> Sync Project with Gradle Files”来完成。
构建性能： 滥用 api 配置可能导致更大的编译类路径和更长的编译时间，因为更多的依赖需要被传递。谨慎使用 api 有助于优化构建性能。
总结
Gradle多项目构建中的依赖解析问题，尤其是子项目间外部依赖的可见性问题，通常源于对 implementation 和 api 依赖配置的误解或不当使用。通过将共享模块中需要对外暴露的依赖声明为 api，或者在消费模块中显式声明其所需依赖，可以有效地解决这类问题。理解这两种配置的语义差异，并根据模块间的实际依赖关系和API设计进行选择，是构建高效、健壮Gradle多项目工程的关键。
