AgentSkillsCN

gradle-spring-boot-integration

为 Spring Boot 项目配置 Gradle，包括插件设置、可启动 JAR 的创建、为 Docker 优化的分层 JAR，以及多模块 Spring Boot 配置。 适用于被要求“使用 Gradle 设置 Spring Boot”、“创建可执行 JAR”、“配置 Docker 分层”或“设置 Spring Boot 微服务”时使用。

SKILL.md
--- frontmatter
name: gradle-spring-boot-integration
description: |
  Configures Gradle with Spring Boot projects including plugin setup, bootable JAR creation,
  layered JARs for Docker optimization, and multi-module Spring Boot configurations.
  Use when asked to "set up Spring Boot with Gradle", "create executable JARs",
  "configure Docker layering", or "set up Spring Boot microservices".

Works with build.gradle.kts, application.yml, and Dockerfile configurations.

Gradle Spring Boot Integration

Table of Contents

Purpose

Set up and configure Spring Boot projects in Gradle with proper JAR creation, Docker optimization, and multi-module support. This skill covers bootable JAR setup, layered JARs for optimal Docker caching, and Spring Boot-specific task configuration.

When to Use

Use this skill when you need to:

  • •Set up new Spring Boot projects with Gradle
  • •Create executable JAR files for Spring Boot applications
  • •Configure layered JARs for optimized Docker builds
  • •Set up multi-module projects with shared libraries
  • •Configure Spring Boot DevTools for hot reload
  • •Inject build information into application.yml
  • •Set up Spring Boot Actuator for monitoring
  • •Configure testing with Spring Boot test starters

Quick Start

Minimal Spring Boot setup in build.gradle.kts:

kotlin
plugins {
    id("java")
    id("org.springframework.boot") version "3.5.5"
    id("io.spring.dependency-management") version "1.1.7"
}

group = "com.example"
version = "0.0.1-SNAPSHOT"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

tasks.test {
    useJUnitPlatform()
}

Run and build:

bash
./gradlew bootRun                                    # Run locally
./gradlew bootJar                                    # Create executable JAR
./gradlew bootRun --args='--spring.profiles.active=dev'  # Run with profile

Instructions

Step 1: Apply Spring Boot Plugin

Configure the Spring Boot Gradle plugin for your project type:

kotlin
// build.gradle.kts - Web Service (creates bootable JAR)
plugins {
    id("java")
    id("org.springframework.boot") version "3.5.5"
    id("io.spring.dependency-management") version "1.1.7"
}

Key plugins:

  • •org.springframework.boot: Creates executable JARs, provides bootRun task
  • •io.spring.dependency-management: Automatically imports Spring Boot BOM

Step 2: Configure Java Toolchain

Specify Java version for consistency:

kotlin
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

Step 3: Add Spring Boot Dependencies

Use the BOM automatically imported by the plugin:

kotlin
dependencies {
    // Spring Boot starter (no version needed - from BOM)
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-actuator")
    implementation("org.springframework.boot:spring-boot-starter-data-jpa")

    // Development only (DevTools for hot reload)
    developmentOnly("org.springframework.boot:spring-boot-devtools")

    // Test dependencies
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

// Enable JUnit 5
tasks.test {
    useJUnitPlatform()
}

Step 4: Configure Bootable JAR Creation

For services (executable JARs):

kotlin
tasks.bootJar {
    enabled = true
    archiveClassifier = ""  // No classifier for main artifact
}

tasks.jar {
    enabled = false  // Disable plain JAR
}

For libraries (plain JARs):

kotlin
tasks.bootJar {
    enabled = false  // Not executable
}

tasks.jar {
    enabled = true  // Create library JAR
}

Step 5: Enable Layered JARs for Docker Optimization

Layered JARs separate dependencies by change frequency for better Docker caching:

kotlin
tasks.bootJar {
    enabled = true

    layered {
        enabled = true
        application {
            enabled = true
        }
        dependencies {
            enabled = true
        }
        springBootLoader {
            enabled = true
        }
        snapshot {
            enabled = true
        }
    }
}

Layers (in order):

  1. •dependencies: Rarely-changing external dependencies
  2. •spring-boot-loader: Spring Boot loader classes
  3. •snapshot-dependencies: Snapshot/SNAPSHOT versions (changing)
  4. •application: Application classes (most frequently changing)

Extract layers in Dockerfile:

dockerfile
FROM eclipse-temurin:21-jre-alpine AS builder
WORKDIR /builder
COPY build/libs/app.jar .
RUN java -Djarmode=layertools -jar app.jar extract

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY --from=builder /builder/dependencies ./
COPY --from=builder /builder/spring-boot-loader ./
COPY --from=builder /builder/snapshot-dependencies ./
COPY --from=builder /builder/application ./
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

Step 6: Configure Application Properties

Inject build information into application.yml:

kotlin
tasks.processResources {
    filesMatching("application.yml") {
        expand(
            "version" to project.version,
            "name" to project.name,
            "timestamp" to System.currentTimeMillis()
        )
    }
}

In application.yml:

yaml
spring:
  application:
    name: ${name}

info:
  app:
    name: ${name}
    version: ${version}
    build-timestamp: ${timestamp}

Step 7: Set Up Spring Boot DevTools for Local Development

Enable hot reload during development:

kotlin
dependencies {
    developmentOnly("org.springframework.boot:spring-boot-devtools")
}

Trigger reload:

  • •IntelliJ: Build Project (Cmd/Ctrl + F9)
  • •Eclipse: Save file
  • •CLI: Run ./gradlew compileJava in separate terminal

Step 8: Configure Actuator for Monitoring

Add actuator endpoints and metrics:

kotlin
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-actuator")
    implementation("io.micrometer:micrometer-registry-prometheus")
}

In application.yml:

yaml
management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus,metrics,env
  metrics:
    export:
      prometheus:
        enabled: true
  endpoint:
    health:
      show-details: always

Examples

Example 1: Simple Web Service

kotlin
// build.gradle.kts
plugins {
    id("java")
    id("org.springframework.boot") version "3.5.5"
    id("io.spring.dependency-management") version "1.1.7"
}

group = "com.waitrose"
version = "1.0.0"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-actuator")

    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

tasks.test {
    useJUnitPlatform()
}

tasks.bootJar {
    enabled = true
}

tasks.jar {
    enabled = false
}

Build and run:

bash
./gradlew bootJar              # Create JAR: build/libs/app-1.0.0.jar
java -jar build/libs/app-1.0.0.jar  # Run JAR

For advanced examples including multi-module setups, layered JARs with Docker, build info injection, and testing configurations, see examples/advanced-examples.md.

Commands Reference

See references/commands-and-troubleshooting.md for complete command reference and troubleshooting guide.

See Also