1. 问题背景：Gradle多项目依赖的可见性挑战
在复杂的Gradle多项目结构中，例如一个根项目包含CommonUtils、Interceptor和SearchService等子项目，当Interceptor项目依赖于CommonUtils项目时，如果CommonUtils内部使用的某些外部库（如com.google.gson.Gson或com.rometools.rome.feed.rss.Channel）在Interceptor中被直接引用，而这些库在CommonUtils中是以implementation方式声明的，那么Interceptor在编译时将无法找到这些类，导致编译失败。
这是因为Gradle的implementation配置具有非传递性。当一个模块（如CommonUtils）使用implementation声明其依赖时，这些依赖只在其自身模块的编译和运行时可见，而不会自动暴露给依赖它的其他模块（如Interceptor）。这种设计旨在优化编译速度和减少不必要的依赖耦合，但同时也要求开发者明确管理跨模块的依赖可见性。
2. 解决方案一：利用 api 配置实现依赖传递
解决上述问题的首选方法之一是将CommonUtils中那些需要被Interceptor直接使用的外部依赖，从implementation配置更改为api配置。
2.1 api 与 implementation 的区别
- implementation: 依赖仅对当前模块的编译和运行时可见，不会传递给依赖当前模块的其他模块。这有助于构建更小、更快的类路径，并减少模块间的耦合。
- api: 依赖对当前模块的编译和运行时可见，并且会传递给依赖当前模块的其他模块。这意味着如果模块A通过api依赖了库X，而模块B又依赖了模块A，那么模块B也可以直接使用库X中的类。
2.2 示例代码：修改 CommonUtils 的 build.gradle
为了让Interceptor能够访问Gson和Rome相关的类，我们需要在CommonUtils的build.gradle文件中，将对应的依赖声明从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 {
// 将需要传递给其他项目的依赖从 'implementation' 改为 'api'
api 'com.google.code.gson:gson:2.8.2'
api 'com.rometools:rome:1.18.0' // 优先使用新版本
// api 'rome:rome:1.0' // 如果旧版本也需要，同样改为api
// 其他不需要传递的依赖保持 'implementation'
implementation 'com.itextpdf:itextpdf:5.5.13.3'
implementation 'org.springframework.boot:spring-boot-starter-web'
// ... 其他 implementation 依赖 ...
// 示例：fileTree 同样可以考虑其内部 jar 的可见性
// api fileTree(dir: 'libs', include: '*.jar') // 如果libs下的jar也需要传递
// ... 其他依赖 ...
}
// ... 其他配置 ...注意事项：
- 使用api会增加依赖当前模块的其他模块的编译类路径，可能导致编译时间略微增加。
- 过度使用api可能会导致不必要的依赖传递和依赖地狱问题。应仅将那些被模块API直接暴露或作为公共契约一部分的依赖声明为api。
- 对于像lombok这样的仅在编译阶段或注解处理阶段需要的工具，通常保持为compileOnly或annotationProcessor，不应声明为api。
3. 解决方案二：在下游项目重新声明外部依赖
另一种解决依赖可见性问题的方法是，直接在需要使用这些外部依赖的下游项目（本例中是Interceptor）中，重新声明这些依赖。
3.1 适用场景
当上游项目（CommonUtils）的职责是提供内部工具类，而不希望其内部依赖暴露给所有消费者时，或者当某个外部依赖仅在下游项目中的特定场景下才需要时，此方法更为合适。
3.2 示例代码：修改 Interceptor 的 build.gradle
在Interceptor的build.gradle文件中，直接添加Gson和Rome的依赖声明。
// 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 {
// 声明对 CommonUtils 项目的依赖
implementation project(':CommonUtils')
// 重新声明 Interceptor 自己需要的外部依赖
implementation 'com.google.code.gson:gson:2.8.2'
implementation 'com.rometools:rome:1.18.0' // 注意版本与 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'
}
// ... 其他配置 ...注意事项：
- 此方法要求在多个地方维护相同的依赖版本，增加了维护成本。建议使用Gradle的版本管理机制（如ext块或platform依赖）来统一管理版本。
- 它使得依赖关系更加明确，每个模块都清晰地声明了自己直接需要的外部库。
4. 总结与最佳实践
在Gradle多项目构建中处理依赖传递性问题时，理解api和implementation的区别至关重要。
- 何时使用 api: 当一个模块的公共API直接暴露了某个外部库的类型，或者该外部库是该模块公共契约的一部分时，应使用api。例如，如果CommonUtils返回Gson对象或接受Channel对象作为参数，那么Gson和Rome就应该声明为api。
- 何时使用 implementation: 对于模块内部实现细节所依赖的库，不希望暴露给外部消费者时，使用implementation。这有助于保持模块的封装性，减少编译时间，并避免不必要的依赖冲突。
- 何时重新声明依赖: 当上游模块不应承担传递特定外部依赖的责任，而下游模块确实需要该依赖时，可以在下游模块中明确声明。这增加了依赖的显式性，但可能引入版本不一致的风险。
在实际开发中，推荐优先考虑使用api来解决依赖传递问题，因为它能更好地反映模块间的实际API依赖关系。同时，结合Gradle的依赖管理工具（如dependencyManagement或platform）来统一管理版本，以避免潜在的冲突和版本漂移问题。在IntelliJ IDEA等IDE中，进行Gradle项目同步（Gradle -> Reimport All Gradle Projects）通常是解决IDE无法识别依赖的有效步骤。
