Gradle 8.10中`implementation`依赖为何在子项目中不可见？

Question

在 Gradle 8.10 多项目构建中，子项目无法访问父项目或兄弟项目中声明的 `implementation` 依赖，这是**预期行为而非 bug**。`implementation` 是严格封装的配置（自 Gradle 3.4 引入），仅对当前项目的编译和运行时类路径可见，**不会传递给依赖它的其他模块**。例如：若 `:lib` 声明 `implementation 'com.google.guava:guava:33.2.0-jre'`，即使 `:app` 通过 `implementation project(':lib')` 引入它，`:app` 的源码中也无法直接使用 `com.google.common.collect.Lists`——因为 Guava 未被传递。解决方式取决于需求：需 API 复用时改用 `api`；仅需内部使用则保持 `implementation` 并在 `:app` 中显式声明所需依赖；或通过 `java-library` 插件 + `api/implementation` 显式建模依赖边界。Gradle 8.10 进一步强化了配置隔离与依赖传递的确定性，避免隐式泄露导致的版本冲突与构建不一致。

Answer 1

```html

一、现象层：为什么子项目“看不到”父/兄弟项目的 implementation 依赖？

在 Gradle 8.10 多项目构建中，当 :lib 声明 implementation 'com.google.guava:guava:33.2.0-jre'，而 :app 通过 implementation project(':lib') 引入时，:app 的源码中调用 Lists.newArrayList() 会编译失败——这不是环境异常，而是 Gradle 依赖传递模型的**主动设计**。自 Gradle 3.4 起，implementation 配置即被定义为非传递性（non-transitive），其语义是：“仅供本模块内部编译/运行使用，不暴露给消费者”。Gradle 8.10 进一步收紧了配置解析逻辑，禁用隐式 fallback 与宽松匹配，使该行为更确定、可审计。

二、机制层：Gradle 依赖配置的语义契约与演进脉络

配置名	可见范围	是否传递	适用场景	Gradle 版本强化点
implementation	本模块编译 + 运行时	❌ 否	私有工具类、内部实现细节	8.10 强制隔离配置图谱，禁止跨项目隐式泄露
api	本模块 + 消费者编译期	✅ 是	公共 API 接口依赖（如 Jackson、SLF4J API）	8.10 对 api 依赖版本冲突执行严格仲裁（fail-fast）
runtimeOnly	仅运行时类路径	❌ 否（默认）	数据库驱动、Logback 实现	8.10 禁止 runtimeOnly 依赖参与编译期解析

三、诊断层：如何精准定位“不可见依赖”的根源？

执行以下命令可可视化依赖传递链：

./gradlew :app:dependencies --configuration compileClasspath

观察输出中 :lib 下的 guava 是否出现在 compileClasspath 的 transitive dependencies 区域；若仅出现在 :lib 自身的 implementation 分支下，则验证了封装性。同时检查 build.gradle 中是否误用 java 插件（无 api/implementation 语义）而非 java-library 插件——后者才是启用依赖边界建模的前提。

四、解法层：按架构意图选择适配策略

1. API 复用场景：在 :lib 中启用 java-library 插件，并将 Guava 改为 api 'com.google.guava:guava:33.2.0-jre' —— 此时 :app 可直接使用 Lists；
2. 实现隐藏场景：保持 :lib 使用 implementation，并在 :app 显式声明 implementation 'com.google.guava:guava:33.2.0-jre'，实现依赖解耦与版本自主控制；
3. 契约抽象场景：抽取 guava-api 接口模块（仅含 Lists 声明），由 :lib api project(':guava-api')，再由 :app implementation project(':guava-api')，达成编译期契约与运行时实现分离。

五、架构层：Gradle 8.10 的依赖治理升级全景

graph LR
A[依赖声明] -->|java-library 插件| B[api/implementation 语义建模]
B --> C[Configuration Avoidance API]
C --> D[惰性配置解析]
D --> E[构建缓存友好性提升]
E --> F[跨项目依赖图确定性验证]
F --> G[8.10 新增：--dry-run --scan 输出依赖决策日志]

六、反模式警示：常见误操作与后果

• ❌ 在 allprojects 中全局 apply java 插件 → 导致 api/implementation 不可用，退化为旧式 compile 行为；
• ❌ 使用 compile（已废弃）替代 implementation → 触发 Gradle 8.10 构建失败（ERROR_PRONE）；
• ❌ 为“省事”在根 build.gradle 中 subprojects { dependencies { implementation ... } } → 破坏模块边界，引发版本漂移与测试污染。

七、演进建议：面向未来的 Gradle 工程实践

建议所有多项目构建统一采用以下基线：

1. 根项目启用 enableFeaturePreview('VERSION_CATALOGS') 和 enableFeaturePreview('TYPESAFE_PROJECT_ACCESSORS')；
2. 每个子项目显式声明 plugins { id 'java-library' }；
3. 依赖统一收口至 gradle/libs.versions.toml，并通过 libs.guava 类型安全引用；
4. CI 流水线中增加 ./gradlew --dry-run checkDependents 验证传递性合规性。

八、结语：从“为什么不能”到“如何更好设计”

Gradle 8.10 并非限制能力，而是将依赖治理从“约定俗成”推向“契约驱动”。implementation 的不可见性不是缺陷，而是对模块化、可维护性与可重现性的底层支撑。真正的工程成熟度，体现在能否基于 api/implementation 语义精确刻画组件间的协作契约——这正是现代 JVM 生态构建演进的核心范式跃迁。

```