第 2 章：依赖配置声明：implementation vs api vs compileOnly vs runtimeOnly

正确声明依赖配置，是控制传递链、加速增量编译和减少构建不稳定性的核心手段。一旦用错配置，轻则泄露无关依赖到消费端，重则运行时直接崩溃。本章逐一拆解 Java Library 插件下四种常用配置的语义、传递规则和选型决策。

四种配置的核心差异

配置声明示例

在 build.gradle.kts 中应用 Java Library 插件后，即可使用 api 与 implementation 配置。

plugins {
    `java-library`
}

dependencies {
    // 通过 api 暴露：消费者编译时可见
    api("com.fasterxml.jackson.core:jackson-databind:2.15.2")

    // 通过 implementation 隐藏：仅当前模块编译时可见
    implementation("org.springframework.boot:spring-boot-starter-logging:3.1.0")

    // compileOnly：编译时需要，运行时由运行环境提供（如 Tomcat）
    compileOnly("jakarta.servlet:jakarta.servlet-api:6.0.0")

    // runtimeOnly：编译时不需要，仅运行时需要
    runtimeOnly("org.postgresql:postgresql:42.6.0")
}

调试命令：验证你的类路径

使用 dependencies 任务查看特定配置的依赖树，确认传递性是否符合预期。

# 查看 runtimeClasspath 的依赖树
./gradlew :my-app:dependencies --configuration runtimeClasspath

# 查看 compileClasspath 的依赖树
./gradlew :my-app:dependencies --configuration compileClasspath

使用 dependencyInsight 追踪某个传递依赖的来源与配置。

./gradlew :my-app:dependencyInsight --dependency jackson-databind --configuration compileClasspath

常见错误与优化策略

性能优化：增量编译与任务缓存

Gradle 的增量编译和构建缓存依靠输入文件的快照来判断任务是否过时。当依赖配置从 api 改为 implementation 后，消费者模块的编译类路径缩小，Gradle 可以更精确地判断变更是否影响消费者，从而跳过不必要的重新编译。

关键指标：

• 使用 api：消费者编译类路径包含传递依赖。若传递依赖变更，消费者任务必定重新执行。
• 使用 implementation：消费者编译类路径不包含传递依赖。传递依赖变更仅触发直接依赖模块的重新编译，消费者任务可安全地从缓存加载。