1. 为什么需要约定插件

在Android项目中，随着模块数量的增加和团队规模的扩大，build.gradle文件往往会变得臃肿且难以维护。每个模块的构建脚本中充斥着大量重复的配置代码，这不仅增加了维护成本，也容易导致配置不一致的问题。

典型的Android项目可能面临以下痛点：

• 相同的Java版本、编译选项、依赖版本需要在多个模块中重复声明
• 代码质量检查工具（如ktlint、detekt）的配置需要在每个模块中复制粘贴
• 当需要修改某个通用配置时（如升级Kotlin版本），需要在所有模块中逐一修改
• 新成员加入时，容易遗漏某些必要的配置项

约定插件（Convention Plugins）正是为了解决这些问题而生的。它允许我们将通用的构建逻辑封装成可重用的插件，然后在各个模块中通过简单的id引用这些预定义的配置。

2. 约定插件的工作原理

2.1 约定插件的核心概念

约定插件本质上是一种Gradle插件，它通过预定义一组"约定"（即默认配置）来标准化项目的构建过程。与普通插件不同，约定插件通常不提供新功能，而是对现有插件（如Android Gradle Plugin）进行标准化配置。

约定插件的工作流程：

1. 在buildSrc或独立模块中定义插件
2. 插件内部应用必要的核心插件（如com.android.library）
3. 配置这些插件的标准参数（如compileSdkVersion、minSdkVersion等）
4. 在具体模块中应用约定插件而非原始插件

2.2 约定插件的实现方式

Gradle支持两种主要的约定插件实现方式：

1. 预编译脚本插件：

   • 使用Groovy或Kotlin DSL编写
   • 存放在buildSrc/src/main/groovy或buildSrc/src/main/kotlin目录
   • 文件扩展名为.gradle或.gradle.kts
   • 通过文件名自动生成插件ID

2. 二进制插件：

   • 使用Java或Kotlin实现Plugin接口
   • 需要打包发布到仓库
   • 适合跨项目复用的复杂逻辑

对于大多数Android项目，预编译脚本插件已经足够，因为它：

• 无需额外发布步骤
• 修改后立即生效
• 可以使用DSL语法，编写更简洁

3. 创建Android约定插件

3.1 项目结构准备

首先确保项目包含buildSrc目录，这是Gradle专门用于构建逻辑的模块：

project-root/ ├── buildSrc/ │ ├── build.gradle.kts │ ├── src/ │ │ └── main/ │ │ ├── kotlin/ │ │ │ └── android-library.gradle.kts │ │ └── groovy/ ├── app/ │ └── build.gradle.kts ├── feature/ │ └── build.gradle.kts └── settings.gradle.kts

buildSrc/build.gradle.kts需要配置Kotlin DSL插件：

plugins { `kotlin-dsl` } repositories { google() mavenCentral() gradlePluginPortal() } dependencies { implementation("com.android.tools.build:gradle:8.1.0") implementation(kotlin("gradle-plugin", version = "1.8.0")) }

3.2 基础Android库约定插件

创建buildSrc/src/main/kotlin/android-library.gradle.kts：

plugins { id("com.android.library") id("org.jetbrains.kotlin.android") } android { compileSdk = 33 defaultConfig { minSdk = 24 targetSdk = 33 testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" consumerProguardFiles("consumer-rules.pro") } compileOptions { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } kotlinOptions { jvmTarget = "17" } buildFeatures { compose = true } composeOptions { kotlinCompilerExtensionVersion = "1.4.0" } } dependencies { // 基础依赖 implementation("androidx.core:core-ktx:1.10.1") implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.6.1") // 测试依赖 testImplementation("junit:junit:4.13.2") androidTestImplementation("androidx.test.ext:junit:1.1.5") }

3.3 应用约定插件

在模块的build.gradle.kts中，只需简单应用约定插件：

plugins { id("android-library") // 对应android-library.gradle.kts文件名 }

相比传统方式，这减少了约80%的样板代码，同时确保了所有模块配置一致。

4. 进阶约定插件技巧

4.1 多层级约定插件

对于大型项目，可以创建不同层级的约定插件：

1. 基础插件：定义最基础的Android配置
2. 特性插件：基于基础插件添加特定功能（如Compose、Hilt等）
3. 模块专用插件：针对特定模块类型的定制

例如，创建compose-feature.gradle.kts：

plugins { id("android-library") } android { buildFeatures { compose = true } composeOptions { kotlinCompilerExtensionVersion = "1.4.0" } } dependencies { implementation(platform("androidx.compose:compose-bom:2023.06.01")) implementation("androidx.compose.ui:ui") implementation("androidx.compose.material:material") }

4.2 可配置的约定插件

通过扩展使插件可配置：

interface AndroidLibraryExtension { val minSdk: Property<Int> val targetSdk: Property<Int> val composeEnabled: Property<Boolean> } val extension = project.extensions.create<AndroidLibraryExtension>("androidLibrary") plugins { id("com.android.library") id("org.jetbrains.kotlin.android") } android { compileSdk = 33 defaultConfig { minSdk = extension.minSdk.getOrElse(24) targetSdk = extension.targetSdk.getOrElse(33) } buildFeatures { compose = extension.composeEnabled.getOrElse(false) } }

使用时可覆盖默认值：

androidLibrary { minSdk = 26 composeEnabled = true }

4.3 依赖管理统一化

在约定插件中集中管理依赖版本：

object Libs { const val KOTLIN_VERSION = "1.8.0" const val COMPOSE_BOM = "2023.06.01" object AndroidX { const val CORE_KTX = "1.10.1" const val LIFECYCLE = "2.6.1" } } dependencies { implementation("androidx.core:core-ktx:${Libs.AndroidX.CORE_KTX}") implementation("androidx.lifecycle:lifecycle-runtime-ktx:${Libs.AndroidX.LIFECYCLE}") }

5. 迁移现有项目到约定插件

5.1 分阶段迁移策略

1. 分析阶段：

   • 识别各模块中的重复配置
   • 统计使用的插件和依赖版本
   • 确定配置差异点

2. 基础插件创建：

   • 实现覆盖80%用例的基础插件
   • 保留必要的可配置项

3. 模块迁移：

   • 从简单模块开始迁移
   • 逐步验证构建结果
   • 最后处理特殊模块

5.2 常见问题解决

问题1：插件应用顺序冲突解决方案：确保约定插件内部正确排序核心插件：

plugins { id("com.android.library") apply false id("org.jetbrains.kotlin.android") apply false } apply(plugin = "com.android.library") apply(plugin = "org.jetbrains.kotlin.android")

问题2：版本冲突解决方案：在约定插件中强制依赖版本：

dependencies { constraints { implementation("org.jetbrains.kotlin:kotlin-stdlib") { version { strictly(Libs.KOTLIN_VERSION) } } } }

问题3：构建速度下降解决方案：

• 避免在约定插件中执行耗时操作
• 使用@Incubating注解标记可能变化的API
• 定期清理buildSrc缓存

6. 约定插件的最佳实践

1. 命名规范：

   • 使用android-前缀表示Android相关插件
   • 使用kmp-前缀表示多平台插件
   • 文件名使用kebab-case（如android-library.gradle.kts）

2. 文档要求：

   • 每个插件顶部添加注释说明用途
   • 记录可配置参数
   • 提供使用示例

3. 测试策略：

   • 为复杂插件编写集成测试
   • 使用Gradle TestKit验证插件行为
   • 创建示例模块验证实际应用效果

4. 性能优化：

   • 避免在插件应用阶段执行IO操作
   • 延迟昂贵操作的执行时机
   • 使用Gradle配置缓存兼容模式

5. 版本管理：

   • 在独立文件中定义插件版本
   • 使用版本目录（Version Catalog）统一管理
   • 定期检查插件兼容性

7. 约定插件在大型项目中的实际应用

在某大型电商App中，通过约定插件实现了：

• 50+模块的配置统一管理
• 新模块初始化时间从2小时缩短到15分钟
• 依赖版本升级时间从3天减少到2小时
• 构建错误率降低70%

关键实现包括：

1. 自动化代码质量检查：

   plugins { id("org.jlleitschuh.gradle.ktlint") id("io.gitlab.arturbosch.detekt") } ktlint { version.set("0.48.2") android.set(true) } detekt { toolVersion = "1.22.0" config = files("${rootDir}/config/detekt.yml") }

2. 多环境配置：

   interface BuildTypeExtension { val applicationIdSuffix: Property<String> val versionNameSuffix: Property<String> } val buildType = extensions.create<BuildTypeExtension>("buildType") android { buildTypes { getByName("debug") { applicationIdSuffix = buildType.applicationIdSuffix.getOrElse(".debug") versionNameSuffix = buildType.versionNameSuffix.getOrElse("-DEBUG") } } }

3. 动态特性模块支持：

   plugins { id("com.android.dynamic-feature") id("android-library") } android { defaultConfig { minSdk = 21 } }

约定插件特别适合以下场景：

• 模块化程度高的项目
• 跨团队协作开发
• 需要严格统一构建标准的组织
• 频繁创建新模块的项目