gradle配置使用详解

一、Gradle 基础结构

Gradle 的核心配置文件通常有两个：

• build.gradle：项目的构建脚本（Groovy 或 Kotlin DSL）。
• settings.gradle：多模块项目的设置文件。

常见结构如下：

project/
├── build.gradle
├── settings.gradle
└── src/

---

二、build.gradle 基本组成

plugins {
    id 'java' // 应用 Java 插件
}

group = 'com.example'
version = '1.0.0'

repositories {
    mavenCentral() // 依赖仓库
}

dependencies {
    implementation 'org.apache.commons:commons-lang3:3.12.0'
    testImplementation 'junit:junit:4.13.2'
}

tasks.withType(JavaCompile) {
    options.encoding = 'UTF-8'
}

主要部分说明

1. plugins
   应用插件，常见的有 java、application、kotlin、groovy 等。

2. group/version
   项目的组织和版本号。

3. repositories
   指定依赖的仓库来源，如 mavenCentral()、jcenter()、google() 等。

4. dependencies
   依赖管理，常见的依赖类型有：

   • implementation：主代码依赖
   • api：对外暴露依赖（多模块项目用得多）
   • compileOnly：仅编译时依赖
   • runtimeOnly：仅运行时依赖
   • testImplementation：测试代码依赖

5. tasks
   自定义或配置任务。

---

三、常用配置详解

1. 指定 JDK 版本

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

2. 自定义任务

task hello {
    doLast {
        println 'Hello, Gradle!'
    }
}

或使用更现代的写法：

tasks.register('hello') {
    doLast {
        println 'Hello, Modern Gradle!'
    }
}

3. 多模块项目配置

settings.gradle

rootProject.name = 'my-multi-project'
include 'moduleA', 'moduleB'

根目录 build.gradle

可以统一管理所有模块的公共配置。

---

四、依赖管理进阶

1. 依赖传递

• implementation：只在本模块可用，不会传递到依赖它的模块。
• api：会传递到依赖它的模块。

2. 依赖排除

implementation('org.example:lib:1.0') {
    exclude group: 'org.unwanted', module: 'unwanted-lib'
}

3. 本地 jar 依赖

implementation files('libs/some-lib.jar')

---

五、常用任务

• gradle build：编译项目并打包
• gradle clean：清理构建目录
• gradle test：运行测试
• gradle tasks：查看所有可用任务

---

六、Gradle Wrapper

建议使用 Gradle Wrapper（gradlew、gradlew.bat），保证团队成员使用同一版本 Gradle 构建项目。

初始化 Wrapper：

gradle wrapper --gradle-version 8.0

---

七、Groovy 与 Kotlin DSL

Gradle 支持 Groovy（build.gradle）和 Kotlin（build.gradle.kts）两种 DSL，语法略有不同。Kotlin DSL 更适合有 Kotlin 基础的开发者。

---

八、Android 项目中的 Gradle

Android 项目有专用插件和 DSL，配置略有不同。比如：

android {
    compileSdkVersion 34
    defaultConfig {
        applicationId "com.example.app"
        minSdkVersion 21
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
    }
    ...
}

---

九、常见问题

1. 依赖冲突
   使用 ./gradlew dependencies 查看依赖树，排查冲突。

2. 加速构建
   配置本地缓存、并行构建等。

十、Gradle 高级特性

1. 属性与变量

可以在 build.gradle 中定义变量，或使用 gradle.properties 文件进行全局配置。

build.gradle 示例：

def myVersion = '1.2.3'
version = myVersion

gradle.properties 示例：

myVersion=1.2.3

在 build.gradle 中引用：

version = project.findProperty('myVersion') ?: '1.0.0'

---

2. 环境区分与多环境构建

比如区分开发、测试、生产环境，常用于 Android 项目或后端项目。

Android 示例：

buildTypes {
    debug {
        minifyEnabled false
        applicationIdSuffix ".debug"
    }
    release {
        minifyEnabled true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}

Java 项目多环境：

可以用不同的 profile 或通过命令行参数：

./gradlew build -Penv=prod

在 build.gradle 中读取：

def env = project.hasProperty('env') ? project.getProperty('env') : 'dev'
println "当前环境: $env"

---

3. 自定义插件

如果有很多重复的构建逻辑，可以将其封装为插件。

本地插件（buildSrc）结构：

在项目根目录新建 buildSrc 文件夹，里面写插件代码，Gradle 会自动加载。

简单插件示例：

class MyPlugin implements Plugin<Project> {
    void apply(Project project) {
        project.task('myTask') {
            doLast {
                println 'Hello from MyPlugin!'
            }
        }
    }
}

---

4. 依赖版本统一管理

在多模块项目中，建议统一管理依赖版本，避免版本冲突。

使用 ext 属性：

ext {
    junitVersion = '4.13.2'
}

dependencies {
    testImplementation "junit:junit:$junitVersion"
}

---

5. 多模块项目依赖管理

模块间依赖：

dependencies {
    implementation project(':moduleA')
}

---

6. 条件依赖

根据环境或参数动态添加依赖：

if (project.hasProperty('useGuava')) {
    dependencies {
        implementation 'com.google.guava:guava:31.1-jre'
    }
}

---

7. 发布到本地/远程仓库

发布 jar 到本地 maven 仓库：

apply plugin: 'maven-publish'

publishing {
    publications {
        mavenJava(MavenPublication) {
            from components.java
        }
    }
    repositories {
        maven {
            url = uri("$buildDir/repo")
        }
    }
}

---

8. 常用命令总结

• ./gradlew build：编译并打包
• ./gradlew clean：清理
• ./gradlew test：执行测试
• ./gradlew assemble：只打包，不测试
• ./gradlew dependencies：查看依赖树
• ./gradlew <taskName>：执行自定义任务
• ./gradlew --info 或 --debug：显示详细日志

---

十一、常见问题解决方案

1. 依赖冲突解决

使用 dependencyInsight 命令：

./gradlew dependencyInsight --dependency guava

2. 构建加速

• 使用 Gradle Daemon
• 并行构建：org.gradle.parallel=true（在 gradle.properties 配置）
• 配置本地/远程缓存

3. Gradle Wrapper 升级

./gradlew wrapper --gradle-version 8.5

---

十二、最佳实践建议

• 始终使用 Gradle Wrapper，保证团队构建环境一致。
• 模块化项目结构，便于依赖管理和复用。
• 统一依赖版本，减少冲突。
• 合理使用自定义任务和插件，提升自动化水平。
• 定期升级 Gradle 版本和插件，获得最新特性和性能优化。

十三、Gradle 实战技巧

1. 依赖版本管理最佳实践

对于大型项目，建议使用 版本约束 或 版本管理平台（Platform）统一依赖版本。

示例：创建一个依赖版本平台

在 build.gradle 或专门的 platform 子模块：

javaPlatform {
    allowDependencies()
}

dependencies {
    constraints {
        api 'org.apache.commons:commons-lang3:3.12.0'
        api 'com.google.guava:guava:31.1-jre'
    }
}

然后在其他模块中：

dependencies {
    implementation enforcedPlatform(project(':platform'))
    implementation 'org.apache.commons:commons-lang3'
    implementation 'com.google.guava:guava'
}

这样可以保证所有模块使用统一版本。

---

2. 多项目构建（Multi-project Build）

典型结构如下：

rootProject/
├── settings.gradle
├── build.gradle
├── moduleA/
│   └── build.gradle
└── moduleB/
    └── build.gradle

settings.gradle

rootProject.name = 'my-multi-project'
include 'moduleA', 'moduleB'

根 build.gradle

可以定义所有子项目的公共配置：

subprojects {
    apply plugin: 'java'
    repositories {
        mavenCentral()
    }
    dependencies {
        testImplementation 'junit:junit:4.13.2'
    }
}

模块间依赖

// moduleB/build.gradle
dependencies {
    implementation project(':moduleA')
}

---

3. Gradle 与 CI/CD 集成

常见如 Jenkins、GitHub Actions、GitLab CI 等，均可直接调用 Gradle Wrapper (./gradlew build)。

GitHub Actions 简单示例：

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up JDK 17
        uses: actions/setup-java@v3
        with:
          java-version: '17'
      - name: Build with Gradle
        run: ./gradlew build

---

4. 自定义任务与钩子

依赖其他任务

task prepare {
    doLast {
        println 'Preparing...'
    }
}

task buildApp(dependsOn: 'prepare') {
    doLast {
        println 'Building App...'
    }
}

常用生命周期钩子

• doFirst {}：任务执行前
• doLast {}：任务执行后

任务分组与描述

task hello {
    group = 'Custom'
    description = 'Prints a greeting'
    doLast {
        println 'Hello!'
    }
}

---

5. 常用插件扩展

• application：用于 Java 应用，自动生成可运行的 jar。
• maven-publish：用于发布到 Maven 仓库。
• checkstyle、spotbugs、pmd：代码质量检查。
• jacoco：测试覆盖率。
• shadow：打包 fat jar（包含所有依赖）。

application 插件示例：

plugins {
    id 'application'
}
mainClassName = 'com.example.Main'

---

6. Gradle 性能优化

• 并行构建：org.gradle.parallel=true（gradle.properties）
• 配置缓存：org.gradle.configuration-cache=true
• 增量构建：合理配置输入输出，Gradle 可自动跳过未变更任务。
• 本地/远程缓存服务器：适合大型团队和 CI。

---

7. 调试和诊断

• ./gradlew build --info 或 --debug：输出详细日志，定位问题。
• ./gradlew tasks：查看所有可用任务。
• ./gradlew properties：查看项目属性。

---

8. 与 IDE 集成

Gradle 与 IntelliJ IDEA、Eclipse、Android Studio 深度集成，支持自动导入项目、依赖和插件。

• 自动同步：修改 build.gradle 后，IDE 会自动同步依赖和项目结构。
• 调试支持：IDE 可直接运行和调试 Gradle 任务。

---

十四、常见问题与解决方法

1. 依赖下载慢或失败

• 尝试更换国内镜像仓库（如阿里云 Maven）。
• 检查网络代理设置。

国内镜像配置：

repositories {
    maven { url 'https://maven.aliyun.com/repository/public' }
    mavenCentral()
}

---

2. Gradle 版本兼容性问题

• 查看 Gradle Release Notes。
• 升级时建议先在测试分支验证。

---

3. 自定义插件开发

Gradle 支持用 Java、Groovy、Kotlin 编写插件，并发布到本地或远程仓库，便于团队复用。

官方教程：Plugin Development

---

十五、总结

Gradle 作为现代构建工具，具有强大的灵活性和扩展性。掌握其配置和用法可以大大提升开发效率和项目管理能力。无论是 Java、Kotlin、Groovy 还是 Android 项目，都能通过 Gradle 实现自动化构建、依赖管理、测试、发布等全流程支持。