🐘
Gradle 치트시트

Gradle Wrapper(gradlew) 명령어, Kotlin/Groovy DSL, 의존성 스코프, 멀티 모듈 및 성능 최적화 레퍼런스
#gradle#build#java#kotlin#spring#wrapper#dependencies#jvm최종 업데이트: 2026-09-26
Gradle 치트시트 핵심 명령어 및 실전 가이드

Gradle Wrapper(gradlew) 명령어, Kotlin/Groovy DSL, 의존성 스코프, 멀티 모듈 및 성능 최적화 레퍼런스
## 1. Gradle Wrapper (gradlew) 핵심 명령어
```bash
# 1. 빌드 및 클린
./gradlew build                 # 프로젝트 전체 컴파일, 테스트 및 JAR 아티팩트 빌드
./gradlew clean build           # build/ 디렉토리 완전 삭제 후 새로 빌드
./gradlew build -x test         # 테스트 실행을 건너뛰고 빠른 빌드 수행

# 2. 실행 및 컴파일만 수행
./gradlew bootRun               # Spring Boot 애플리케이션 로컬 실행
./gradlew classes testClasses   # 실행/패키징 없이 소스 코드 컴파일만 검증

# 3. 데몬(Daemon) 프로세스 관리
./gradlew --status              # 실행 중인 Gradle 데몬 상태 및 PID 확인
./gradlew --stop                # 백그라운드에 상주하는 모든 Gradle 데몬 종료 (메모리 정리)

# 4. 성능 & 트러블슈팅 옵션
./gradlew build --parallel      # 멀티 모듈 병렬 빌드로 빌드 시간 대폭 단축
./gradlew build --refresh-dependencies # 원격 저장소 의존성 캐시 강제 재다운로드
./gradlew build --info --stacktrace   # 에러 발생 시 상세 스택트레이스 출력
```

## 2. 의존성 스코프 (Dependency Configurations)
```groovy
dependencies {
  // 1. implementation: 내부 구현용 (컴파일 클래스패스 전파 X, 빌드 속도 및 캡슐화 최적)
  implementation 'org.springframework.boot:spring-boot-starter-web'

  // 2. api: 외부 노출용 (이 프로젝트를 참조하는 다른 모듈로 의존성 전이 전파)
  api 'com.google.guava:guava:33.0.0-jre'

  // 3. compileOnly: 컴파일 시에만 필요, 최종 런타임/배포 JAR에서는 제외
  compileOnly 'org.projectlombok:lombok'
  annotationProcessor 'org.projectlombok:lombok' // 어노테이션 프로세서 등록

  // 4. runtimeOnly: 컴파일 시점에는 불필요하고 런타임에만 동적 로드 (DB 드라이버 등)
  runtimeOnly 'com.mysql:mysql-connector-j'
  runtimeOnly 'com.h2database:h2'

  // 5. testImplementation: 테스트 코드(src/test) 컴파일 및 실행 시에만 사용
  testImplementation 'org.springframework.boot:spring-boot-starter-test'
  testImplementation 'org.junit.jupiter:junit-jupiter:5.10.2'
}
```

## 3. Kotlin DSL vs Groovy DSL 문법 비교
```kotlin
// ==================== Kotlin DSL (build.gradle.kts) ====================
plugins {
    java
    id("org.springframework.boot") version "3.2.4"
    id("io.spring.dependency-management") version "1.1.4"
}

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

repositories {
    mavenCentral()
}

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

```groovy
// ==================== Groovy DSL (build.gradle) ====================
plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.4'
    id 'io.spring.dependency-management' version '1.1.4'
}

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

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
}
```

## 4. 의존성 분석 & 충돌 해결 (Dependency Insight)
```bash
# 1. 프로젝트 전체 의존성 트리 출력
./gradlew dependencies

# 2. 특정 빌드 구성의 의존성만 필터링하여 출력
./gradlew dependencies --configuration compileClasspath
./gradlew dependencies --configuration runtimeClasspath

# 3. 특정 라이브러리가 왜 포함되었는지, 충돌 및 버전 선택 경로 추적
./gradlew dependencyInsight --dependency log4j-core
./gradlew dependencyInsight --dependency jackson-databind --configuration compileClasspath
```

```groovy
// 4. 특정 전이 의존성(Transitive Dependency) 강제 제외(Exclude)
dependencies {
    implementation('org.springframework.boot:spring-boot-starter-web') {
        // 내장 Tomcat을 제외하고 다른 WAS(Undertow 등)를 쓸 때
        exclude group: 'org.springframework.boot', module: 'spring-boot-starter-tomcat'
    }
}
```

## 5. 태스크(Task) 관리 & 커스텀 태스크 작성
```bash
# 실행 가능한 모든 태스크 목록 및 설명 확인
./gradlew tasks
./gradlew tasks --all          # 하위 세부 태스크까지 모두 나열
./gradlew help --task build    # 특정 태스크 상세 도움말
```

```kotlin
// Kotlin DSL (build.gradle.kts) 커스텀 태스크 등록
tasks.register("printProjectInfo") {
    group = "custom"
    description = "프로젝트 기본 메타정보를 콘솔에 출력합니다."
    doLast {
        println("프로젝트 이름: ${project.name}")
        println("현재 버전: ${project.version}")
    }
}

// 태스크 의존 관계 지정 (A 실행 전 B 반드시 선행)
tasks.named("build") {
    dependsOn("printProjectInfo")
}
```

## 6. 테스트(Test) 실행 & 리포트
```bash
# 1. 모든 테스트 실행
./gradlew test

# 2. 특정 테스트 클래스 또는 메서드만 지정 실행
./gradlew test --tests UserServiceTest
./gradlew test --tests UserServiceTest.findUserById_Success
./gradlew test --tests *ServiceTest      # 와일드카드 패턴 매칭

# 3. 테스트 실패 시 나머지 테스트 즉시 중단
./gradlew test --fail-fast

# 4. 테스트 성공 여부와 상관없이 무조건 재실행 (캐시 무시)
./gradlew test --rerun-tasks
```

```groovy
// JUnit 5 (Jupiter) 플랫폼 활성화 및 테스트 로깅 설정
tasks.named('test') {
    useJUnitPlatform()
    testLogging {
        events 'passed', 'skipped', 'failed'
        showStandardStreams = true // System.out 출력 콘솔 표시
    }
}
// 테스트 완료 후 HTML 리포트 생성 위치:
// build/reports/tests/test/index.html
```

## 7. JAR 패키징 & 아티팩트 빌드
```groovy
// Spring Boot 환경에서 실행 가능한 Fat-JAR vs 순수 JAR 제어
bootJar {
    archiveBaseName = 'my-service'       // 생성될 파일명: my-service-1.0.0.jar
    archiveVersion = '1.0.0'
}

// 라이브러리가 아닌 일반 웹 애플리케이션의 경우 plain jar 비활성화 권장
jar {
    enabled = false                      // my-service-1.0.0-plain.jar 생성 방지
}

// 소스 코드 및 javadoc JAR 함께 생성하기
java {
    withSourcesJar()
    withJavadocJar()
}
```

## 8. 멀티 모듈 프로젝트 구성 (Multi-Project)
```groovy
// settings.gradle (루트 설정 파일에서 하위 모듈 등록)
rootProject.name = 'ecommerce-platform'
include 'core-domain'
include 'api-server'
include 'admin-server'
include 'batch-worker'
```

```groovy
// 루트 build.gradle (모든 서브 모듈 공통 설정)
subprojects {
    apply plugin: 'java'
    apply plugin: 'io.spring.dependency-management'

    repositories {
        mavenCentral()
    }

    dependencies {
        testImplementation 'org.junit.jupiter:junit-jupiter:5.10.2'
    }
}

// 서브 모듈(api-server/build.gradle)에서 다른 모듈 참조
dependencies {
    implementation project(':core-domain') // 로컬 모듈 의존성 주입
}
```

## 9. 빌드 속도 최적화 (gradle.properties)
```properties
# 프로젝트 루트 또는 ~/.gradle/gradle.properties 에 추가

# 1. JVM 힙 메모리 및 Metaspace 확장
org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m -XX:+HeapDumpOnOutOfMemoryError

# 2. 멀티코어 CPU 병렬 태스크 실행 (멀티 모듈 시 필수)
org.gradle.parallel=true

# 3. 빌드 캐시 활성화 (변경되지 않은 태스크 결과 재사용)
org.gradle.caching=true

# 4. 파일 시스템 감시 기능 활성화 (파일 변경 추적 시간 단축)
org.gradle.vfs.watch=true

# 5. 설정 캐시 활성화 (Gradle 8+ 빌드 시작 시간 획기적 단축)
org.gradle.configuration-cache=true
```

## 10. 실무 트러블슈팅 & 꿀팁 (Gotchas)
```bash
# 1. Gradle Wrapper 자체 버전 업그레이드 (최신 8.x 적용)
./gradlew wrapper --gradle-version 8.7 --distribution-type bin

# 2. "Could not find or load main class org.gradle.wrapper.GradleWrapperMain"
# -> gradlew 실행 스크립트만 있고 gradle/wrapper/gradle-wrapper.jar 파일이 gitignore 등으로 유실된 경우
gradle wrapper # 시스템에 설치된 로컬 gradle로 wrapper 복구

# 3. Windows 환경 gradlew 실행 권한 부여 (Linux/Mac/CI)
git update-index --chmod=+x gradlew

# 4. 꼬인 의존성 로컬 캐시 디렉토리 수동 삭제 (최후의 수단)
# Mac/Linux: rm -rf ~/.gradle/caches/
# Windows: Remove-Item -Recurse -Force ~/.gradle/caches/
```
💬
Gradle 치트시트

의견 및 질문

댓글 수정

댓글 삭제
