依赖配置详解

源：Gradle 官方文档 - Dependency Management

理解不同的依赖配置类型及其作用范围，是优化构建性能和避免依赖冲突的关键。

依赖配置类型

implementation 推荐

作用域：编译和运行时

传递性：不传递

用途：内部实现依赖

dependencies {
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
}

特点：

• 依赖仅对当前模块可见
• 不会暴露给依赖该模块的其他模块
• 加快编译速度
• 减少重新编译

示例：

:app -> :core (implementation retrofit)

:app 无法访问 retrofit，只有 :core 可以使用。

api

作用域：编译和运行时

传递性：传递

用途：公共 API 依赖

dependencies {
    api("com.squareup.retrofit2:retrofit:2.11.0")
}

特点：

• 依赖会传递给下游模块
• 适用于库的公共 API
• 增加编译时间
• 增加依赖冲突风险

示例：

:app -> :core (api retrofit)

:app 可以直接使用 retrofit。

implementation vs api

特性	implementation	api
依赖传递	❌	✅
编译速度	快	慢
适用场景	内部实现	公共API
推荐度	⭐⭐⭐	⭐

选择原则：

• 默认使用 implementation
• 仅在必须暴露依赖时使用 api
• 库模块的返回类型使用 api

compileOnly

作用域：仅编译时

传递性：不传递

用途：仅编译需要的依赖

dependencies {
    compileOnly("javax.annotation:javax.annotation-api:1.3.2")
}

使用场景：

• 注解库（JSR 305）
• Lombok
• 接口定义
• 运行时由其他库提供

runtimeOnly

作用域：仅运行时

传递性：传递

用途：仅运行时需要的依赖

dependencies {
    runtimeOnly("mysql:mysql-connector-java:8.0.33")
}

使用场景：

• 数据库驱动
• 日志实现
• 运行时插件

---

Android 专用配置

debugImplementation / releaseImplementation

作用域：特定构建类型

dependencies {
    debugImplementation("com.squareup.leakcanary:leakcanary-android:2.14")
    releaseImplementation("com.example:release-only-lib:1.0")
}

使用场景：

• Debug 工具（LeakCanary）
• 日志库不同实现
• 性能监控工具

变体特定依赖

dependencies {
    // Product Flavor
    freeImplementation("com.google.android.gms:play-services-ads:23.0.0")
    paidImplementation("com.example:premium-features:1.0")
    
    // 组合
    freeDebugImplementation("com.example:free-debug-tools:1.0")
}

annotationProcessor / kapt / ksp

annotationProcessor（Java）：

dependencies {
    annotationProcessor("com.google.dagger:dagger-compiler:2.52")
}

kapt（Kotlin）：

plugins {
    kotlin("kapt")
}

dependencies {
    kapt("com.google.dagger:dagger-compiler:2.52")
}

ksp 推荐：

plugins {
    id("com.google.devtools.ksp") version "2.1.0-1.0.29"
}

dependencies {
    ksp("androidx.room:room-compiler:2.6.1")
}

对比：

特性	annotationProcessor	kapt	ksp
语言	Java	Kotlin	Kotlin
性能	-	慢	快 2x
推荐度	-	⭐	⭐⭐⭐

---

测试相关配置

testImplementation

作用域：单元测试

dependencies {
    testImplementation("junit:junit:4.13.2")
    testImplementation("org.mockito:mockito-core:5.11.0")
}

androidTestImplementation

作用域：Android 插桩测试

``kotlin dependencies { androidTestImplementation("androidx.test.ext:junit:1.2.1") androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1") }

### testRuntimeOnly

**作用域**：测试运行时

```kotlin
dependencies {
    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.10.2")
}

---

平台依赖

platform BOM

用途：导入 BOM，统一版本

dependencies {
    // 导入 Compose BOM
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    
    // 无需指定版本
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
}

enforcedPlatform

用途：强制使用 BOM 版本

dependencies {
    implementation(enforcedPlatform("androidx.compose:compose-bom:2024.12.01"))
}

对比：

特性	platform	enforcedPlatform
版本覆盖	可被覆盖	强制使用
推荐度	⭐⭐⭐	⭐

---

配置选择策略

库模块

// library/build.gradle.kts
dependencies {
    // 公共 API
    api("com.example:public-api:1.0")
    
    // 内部实现
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.google.code.gson:gson:2.10.1")
    
    // 注解处理
    ksp("androidx.room:room-compiler:2.6.1")
}

应用模块

// app/build.gradle.kts
dependencies {
    // 依赖库模块
    implementation(project(":core"))
    implementation(project(":features:login"))
    
    // 第三方库
    implementation("androidx.core:core-ktx:1.15.0")
    
   // Debug 工具
    debugImplementation("com.squareup.leakcanary:leakcanary-android:2.14")
    
    // 测试
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

---

性能影响

implementation 的优势

场景：

:app -> :core -> :network (implementation retrofit)

当 :network 修改 Retrofit 相关代码：

• 仅重新编译 :network
• :core 和 :app 无需重新编译

api 的劣势

场景：

:app -> :core -> :network (api retrofit)

当 :network 修改 Retrofit 相关代码：

• 重新编译 :network
• 重新编译 :core（因为暴露了 Retrofit）
• 重新编译 :app

性能对比：

• implementation：1 个模块重新编译
• api：3 个模块重新编译

---

最佳实践

优先使用 implementation：

• 默认选择
• 提升构建性能
• 减少依赖冲突

谨慎使用 api：

• 仅用于公共 API
• 库的返回类型
• 必须暴露的依赖

使用 BOM 管理版本：

• 统一相关库版本
• 避免版本冲突
• 简化依赖声明

测试依赖隔离：

• 使用 testImplementation
• 不污染主代码
• 减小 APK 体积

Debug 工具分离：

• 使用 debugImplementation
• Release 包不包含
• 减小生产 APK

使用 KSP 代替 Kapt：

• 性能提升 2倍
• 更好的增量编译
• Kotlin 原生支持