Android 依赖管理

源：Android 官方文档 - 添加 build 依赖项

Android 项目中的依赖管理除了遵循 Gradle 通用规则外，还有一些 Android 专项的配置和最佳实践。

依赖配置类型

implementation

依赖项仅在编译和运行时可用，不会暴露给其他模块。这是推荐用于大多数场景的配置类型。

dependencies {
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("com.google.android.material:material:1.12.0")
}

特点：

• 不会传递到依赖此模块的其他模块
• 构建时间更短（减少重新编译）

api 谨慎使用

依赖项会传递给依赖此模块的其他模块。

dependencies {
    api("com.example:shared-api:1.0.0")
}

影响：

• API 变更会导致依赖链上所有模块重新编译
• 增加构建时间

使用场景：

• 库模块需要暴露某个依赖的类型给使用者
• 多模块项目中共享通用接口定义

compileOnly

仅在编译时可用，不打包到 APK。⚠️ 不支持 AAR 依赖。

dependencies {
    compileOnly("org.projectlombok:lombok:1.18.30")
}

场景：

• 注解处理器（已不推荐，使用 ksp 或 kapt）
• 编译时检查的库
• 运行时由系统提供的库

runtimeOnly

仅在运行时可用，编译时不可用。

dependencies {
    runtimeOnly("com.example:runtime-lib:1.0")
}

ksp / kapt / annotationProcessor

用于注解处理器。优先级：ksp > kapt > annotationProcessor。

KSP（推荐）

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

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

KAPT

plugins {
    kotlin("kapt")
}

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

Java 项目

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

Version Catalog

[versions]
room = "2.6.1"
ksp = "2.1.0-1.0.29"

[libraries]
room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }

[plugins]
ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }

lintChecks / lintPublish

用于自定义 Lint 检查。

dependencies {
    lintChecks(project(":lint-checks"))
    lintPublish(project(":lint-rules-to-publish"))
}

变体特定依赖

基础语法

为特定构建变体、构建类型或产品变种添加依赖：

dependencies {
    // 仅 debug 构建
    debugImplementation("com.squareup.leakcanary:leakcanary-android:2.14")
    
    // 仅 release 构建
    releaseImplementation("com.google.firebase:firebase-crashlytics:19.2.1")
    
    // 仅 free 变种
    freeImplementation("com.google.android.gms:play-services-ads:23.6.0")
    
    // 仅 paid 变种
    paidImplementation(project(":premium-features"))
}

组合变体依赖

需要先初始化配置：

val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-debug-tools"))
}

测试依赖

dependencies {
    // 单元测试（JVM）
    testImplementation("junit:junit:4.13.2")
    testImplementation("org.mockito:mockito-core:5.14.2")
    
    // Instrumentation 测试（Android）
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
    
    // 特定变体的测试
    testFreeImplementation("com.example:free-test-utils:1.0")
}

Android 专项依赖

AndroidX 库

dependencies {
    implementation("androidx.core:core-ktx:1.15.0")
    implementation("androidx.appcompat:appcompat:1.7.0")
    implementation("androidx.activity:activity-ktx:1.9.3")
    implementation("androidx.fragment:fragment-ktx:1.8.5")
}

Jetpack Compose

android {
    buildFeatures {
        compose = true
    }
    
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.15"
    }
}

dependencies {
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.compose.material3:material3")
    implementation("androidx.compose.ui:ui-tooling-preview")
    debugImplementation("androidx.compose.ui:ui-tooling")
}

Google Play Services

dependencies {
    implementation("com.google.android.gms:play-services-location:21.3.0")
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

最佳实践

使用 BOM 管理版本：

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

依赖顺序影响：

• 编译类路径顺序
• 资源优先级（早声明的优先级更高）
• Manifest 合并顺序

检查依赖树：

./gradlew :app:dependencies