Java 插件详解

java 插件是 Gradle 构建 Java 项目的基础，提供编译、测试、打包等完整功能。

应用 Java 插件

plugins {
    java           // 基础 Java 插件
    // 或
    `java-library` // 区分 api/implementation（推荐库项目使用）
    // 或
    application    // 可执行应用程序（继承 java）
}

插件提供的任务

compileJava          → 编译 src/main/java
processResources     → 处理 src/main/resources
classes              → 编译+资源（compileJava + processResources）
compileTestJava      → 编译 src/test/java
processTestResources → 处理 src/test/resources
testClasses          → 测试编译+资源
test                 → 运行测试
jar                  → 打包 JAR
assemble             → 所有打包任务（jar 等）
check                → 所有验证任务（test 等）
build                → assemble + check
clean                → 删除 build/
javadoc              → 生成 JavaDoc

Java 版本配置

// 方式一：sourceCompatibility（简单，推荐）
java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
}

// 方式二：Toolchain（更精确，跨 JDK 构建）
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17))
        vendor.set(JvmVendorSpec.ADOPTIUM)
    }
}

编译参数

tasks.withType<JavaCompile> {
    options.encoding = "UTF-8"
    options.isDeprecation = true          // 显示废弃警告
    options.isWarnings = true
    options.compilerArgs.addAll(listOf(
        "-Xlint:all",                     // 所有 lint 警告
        "-parameters"                     // 保留方法参数名（Spring 需要）
    ))
}

完整配置示例

plugins {
    java
}

group = "com.example"
version = "1.0.0"

java {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
    
    // 生成 sources JAR
    withSourcesJar()
    
    // 生成 javadoc JAR
    withJavadocJar()
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.slf4j:slf4j-api:2.0.9")
    runtimeOnly("ch.qos.logback:logback-classic:1.4.11")
    compileOnly("org.projectlombok:lombok:1.18.30")
    annotationProcessor("org.projectlombok:lombok:1.18.30")
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.1")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.named<Test>("test") {
    useJUnitPlatform()
    maxHeapSize = "1g"
    
    testLogging {
        events("passed", "skipped", "failed")
        showStandardStreams = false
    }
}

tasks.named<Jar>("jar") {
    manifest {
        attributes(
            "Main-Class" to "com.example.Main",
            "Implementation-Version" to project.version
        )
    }
}

java-library 插件（库项目专用）

plugins {
    `java-library`
}

dependencies {
    // api：暴露给消费者（影响编译 classpath）
    api("org.slf4j:slf4j-api:2.0.9")
    
    // implementation：不暴露给消费者（内部使用）
    implementation("ch.qos.logback:logback-classic:1.4.11")
    
    // compileOnlyApi：仅编译时暴露
    compileOnlyApi("org.jetbrains:annotations:24.0.1")
}

application 插件（可执行程序）

plugins {
    application
}

application {
    mainClass.set("com.example.Application")
    applicationName = "my-app"
    
    // JVM 参数
    applicationDefaultJvmArgs = listOf("-Xmx512m", "-Dfile.encoding=UTF-8")
}

// 任务：
// ./gradlew run          ← 直接运行
// ./gradlew distZip      ← 打包发行版（含启动脚本）
// ./gradlew installDist  ← 安装到 build/install/

下一步

• 源码集 - 自定义源码目录
• 单元测试配置 - 测试框架配置
• 打包 JAR - JAR 详细配置