Gradle、AGP、Plugin插件基本知识

一、第一原则

优先使用AI实现和修复Gradle配置问题

二、Gradle和AGP基本概念

1. Gradle是通用的自动化构建工具，提供基础的构建框架（依赖管理、任务编排），可用于各种构建场景，不局限于Android构建。

2. AGP是Android Gradle Plugin的缩写，是专门为Android开发设计的Gradle插件。

   • com.android.tools.build:gradle:版本号是AGP本身在代码仓库中的Maven坐标，用于安装整个AGP工具箱。

   • AGP工具箱中常用插件：com.android.application、com.android.library等

   • 依赖方式：旧版：项目根目录的build.gradle中，通过classpath依赖显式声明。新版方式：在plugins代码块中通过id和version声明后，Gradle会自动在后台处理这个坐标的解析，无需手动通过classpath显式生命依赖。

三、常见plugin插件的功能

四、自定义插件模块

1. 插件的module目录build.gradle.kts文件

// 插件项目版本（发布到仓库后，其他项目引用时使用的版本）version="1.0.0"group="com.example.asm"plugins{id("java-gradle-plugin")// java-gradle-plugin: Gradle 插件开发插件，提供 gradlePlugin DSL 配置块kotlin("jvm")version"1.8.10"// kotlin("jvm"): Kotlin JVM 支持，用于编译 Kotlin 代码id("maven-publish")// maven-publish: 用于发布 Maven 仓库的插件}// 插件声明配置gradlePlugin{plugins{// 创建一个插件声明，"asmMethodTimeCost" 是内部标识名，起什么名字都可以create("asmMethodTimeCost"){// 插件 ID: 在其他模块中使用这个插件时引用的 ID// 用法: plugins { id("com.example.asm.test") version "1.0.0" }id="com.example.asm.test"// 插件实现类的完整路径（包名 + 类名）// 必须实现 org.gradle.api.Plugin<Project> 接口implementationClass="com.example.asm.test.AsmPlugin"// 插件显示名称和描述（发布到 Gradle Plugin Portal 时使用）displayName="ASM Method Time Cost Plugin"description="A Gradle plugin to measure method execution time using ASM"tags.set(listOf("asm","android","bytecode","performance"))}}}dependencies{// gradleApi(): Gradle 核心 API，提供 Plugin、Project、Task 等基础接口implementation(gradleApi())// Android Gradle Plugin API: 访问 Android 编译流程，提供BaseVariant、Transform 等接口implementation("com.android.tools.build:gradle-api:7.4.2")// 非必须，这是 AGP 内部实现，除非访问未公开的内部APIimplementation("com.android.tools.build:gradle:7.4.2")// ASM 字节码操作库implementation("org.ow2.asm:asm:9.4")implementation("org.ow2.asm:asm-commons:9.4")}

2. 插件入口类定义

packagecom.example.asm.testimportorg.gradle.api.Pluginimportorg.gradle.api.ProjectclassAsmMethodTimeCostPlugin:Plugin<Project>{overridefunapply(project:Project){// TODO: 实现插件逻辑}}

3. 插件描述符文件

• 使用java-gradle-plugin自动生成，根据build.gradle.kts中的gradlePlugin{}闭包中的参数自动生成。
• 文件路径和命名遵循严格约定，位于 JAR 包内的META-INF/gradle-plugins/目录，并以<插件ID>.properties的格式命名。
• 使用者可以直接plugins { id("com.example.asm.test") }的方式引用
• 文件名称：com.example.asm.test.properties

implementation-class=com.example.asm.test.AsmMethodTimeCostPlugin

4. 插件发布

• 在build.gradle.kts文件中引用maven-publish插件，并且声明version和group字段
• 执行如下命令，发布插件后，就可以在其他模块（app、library）中使用插件id进行引用。
• 插件发布路径由mavenLocal()函数定义，mac电脑一般是~/.m2/repository/

./gradlew:asmtestplugin:publishToMavenLocal

5. 插件文件格式

• 插件的产物是jar包，例如asmtestplugin-1.0.0.jar

6. 工程内插件依赖方式

• 不想每次修改都需要发布，可以在app模块build.gradle中直接指定插件的类文件（插件入口）进行直接依赖

apply plugin:com.example.asm.test.AsmPlugin

五、Groovy和 Kotlin DSL语法

1. 背景

• Kotlin DSL现在已是 Gradle 官方默认推荐语言。
• Groovy DSL：动态语言，大量利用“方法调用省略括号”“属性自动生成 getter/setter”“元编程”等技巧，写起来更像自然语言，但 IDE 支持弱，出错往往在运行时报错。
• Kotlin DSL：静态类型，所有调用都有明确类型约束，IDE 能给出精确的代码提示和重构支持，编译阶段就能发现大部分错误，代价是语法更严谨、括号和引号不可省略。

2. 主要差异

• 无论是Groovy DSL还是Kotlin DSL，都兼容id("java")格式。

3. Kotlin DSL中使用等号赋值，使用括号进行函数调用怎么区分？

• 首选方法：看 IDE 自动补全（IntelliJ IDEA / Android Studio）

• 如果补全提示里是property标记（或直接显示类型，如String），那就是属性，用=赋值。

• 如果提示里是fun标记，那就是函数，用()调用。

六、其他

1. buildSrc目录

• buildSrc是 Gradle 项目根目录下的一个特殊模块，专门存放构建逻辑代码。只要目录存在，Gradle 就会自动把这个目录当作一个独立的子项目来编译，并把编译好的类自动加到整个项目的构建脚本 classpath 中。你可以在里面写自定义插件、任务、扩展，然后在根项目的build.gradle(.kts)里直接使用。
• 它是自动识别的，buildSrc是项目的保留字段。Gradle 的生命周期中，一但检测到buildSrc目录，会：
  1. 将其编译为 jar；
  2. 把 jar 和其依赖放到构建脚本的 classpath；
  3. 在所有模块的build.gradle.kts中可直接引用buildSrc里定义的类或对象，无需任何classpath声明。

2. gradlePluginPortal()

• Plugin插件专属的仓库。在项目根目录repositories{}闭包中配置。