本文详解 gradle 中 transitive dependencies（传递依赖）未被正确解析的根本原因与修复方法，重点说明 `java-library` 插件与 `api`/`implementation` 配置的区别，并提供可直接复用的配置示例。
在多模块或私有库依赖场景中，开发者常遇到这样的典型错误：
error: package org.springframework.boot does not exist import org.springframework.boot.SpringApplication;
即使下游项目（如 MyFirstEndPoint）仅声明了对上游库（如 MyStarterWeb）的依赖，却无法访问其内部使用的 Spring Boot 类——这并非 Gradle “失灵”，而是依赖可见性配置不当导致的传递依赖中断。
根本原因：implementation 隐式屏蔽传递依赖
Gradle 默认使用 implementation 声明依赖时，会将其标记为“仅本模块编译/运行所需”，不向消费者暴露。这意味着：
- MyStarterWeb 若用 implementation 'spring-boot-starter-web'，则该依赖对 MyFirstEndPoint 不可见；
- MyFirstEndPoint 编译时找不到 org.springframework.boot.* 等类，报错不可避免。
要让依赖“穿透”到下游项目，必须显式声明其为 API 依赖——即该依赖是库公共接口的一部分，调用方需感知并使用。
正确解法：启用 java-library 插件 + 使用 api 配置
✅ 步骤 1：在 MyStarterWeb 的 build.gradle 中启用 java-library
plugins {
id 'java-library' // 关键：启用 API/implementation 分离能力
id 'org.springframework.boot' version '3.0.2'
id 'io.spring.dependency-management' version '1.1.0'
}⚠️ 注意：java-library 插件必须显式声明（不能仅靠 java 插件）。它提供了 api、implementation、compileOnly 等语义化配置，是实现依赖传递控制的基础。
✅ 步骤 2：将对外暴露的依赖改用 api
dependencies {
api 'org.springframework.boot:spring-boot-starter-web:3.0.2'
api 'javax.servlet:javax.servlet-api:4.0.1' // 如需 Servlet API 暴露给使用者
implementation 'org.springframework.boot:spring-boot-starter-validation' // 内部使用，不透出
}- api → 该依赖会作为 MyStarterWeb 的 API 合约一部分，自动成为 MyFirstEndPoint 的传递依赖；
- implementation → 仅用于 MyStarterWeb 内部逻辑（如工具类、测试辅助），不会出现在下游的 classpath 中。
✅ 步骤 3：下游项目保持简洁声明
// MyFirstEndPoint/build.gradle
dependencies {
implementation 'com.mygroup:MyStarterWeb:0.0.1-SNAPSHOT'
}无需重复声明 Spring Boot 相关依赖——Gradle 将自动解析并拉取 MyStarterWeb 的 api 依赖树（包括 spring-boot-starter-web 及其全部 transitive deps）。
补充说明与最佳实践
- ? 验证是否生效：执行 ./gradlew dependencies --configuration compileClasspath，检查 MyFirstEndPoint 的依赖树中是否包含 spring-boot-starter-web；
- ? 发布私有库时注意：若通过 maven-publish 发布 MyStarterWeb，java-library 插件会自动生成符合 Maven POM 规范的
compile 条目，确保其他构建工具（如 Maven）也能正确解析传递依赖； - ? 避免滥用 api：仅将真正构成你库公共 API 的依赖设为 api（如 Spring MVC 注解、自定义 starter 的 @EnableXxx），否则会导致下游项目引入冗余依赖，增加冲突风险；
- ? Gradle 版本兼容性：本文方案适用于 Gradle 6.0+（推荐 7.6+ 或 8.x）。旧版本（
遵循以上配置，即可彻底解决 “Gradle 不解析依赖的依赖” 这一高频痛点，让模块间依赖关系清晰、可预测、可维护。
