IntelliJ에서 프로젝트 세팅하기 (Gradle, Spring Boot)

Gradle 기반 스프링 부트 프로젝트를 세팅해보자.

프로젝트 만들기

실습환경 : IntelliJ IDEA 2025.2
경로 : File > New > Project...

프로젝트 세팅

File > Project Structure

Project SDK

프로젝트에서 사용할 JDK 버전을 지정

• 프로젝트 내 모든 모듈이 공통으로 사용할 기본 SDK
• 빌드 결과물의 실행 환경(Java Runtime)과 맞춰야 런타임 오류를 방지할 수 있음

Language level

Java 문법을 어느 버전까지 사용할지 결정

JDK21부터 지원하는 문법 사용해보기

• JDK 21 + Language level 17

• JDK 17 + Language level 21

※ 모듈 단위로 SDK, Language level 설정 가능

• 예 : 멀티모듈 프로젝트에서 각 모듈의 Java 버전이 다를 수 있음
  • core 모듈 → Java 17
  • admin 모듈 → Java 21
  • api 모듈 → Java 11

Compiler output

컴파일한 .class 파일을 어디에 저장할지 정하는 경로

• Maven/Gradle 빌드 출력(target/, build/)이 아니라 IntelliJ 자체 빌드 했을 때 .class 파일을 저장하는 디렉터리.

Platform Settings > SDKs

IntelliJ 전체(IDE 차원)에서 사용할 수 있는 JDK 목록을 등록/관리하는 공간

• 즉, 프로젝트에 적용하기 전에 IntelliJ가 인식할 수 있는 JDK들을 등록해두는 곳
  • 이곳에 등록되어야 프로젝트, 모듈에서 SDK 선택할 수 있음

IDE 설정

IntelliJ IDEA > settings

Project bytecode version

컴파일된 .class 파일의 버전(바이트코드 타겟)을 지정

• 예를 들어:
  • Language level: 21
  • SDK: JDK 21
  • Project bytecode version: 11
• 하지만 Java 21 문법을 Java 11 bytecode로 다운그레이드할 수 없음.
• 그래서, 대부분의 경우 Language Level = SDK = Bytecode Version을 맞춘다.

Build Tool > Gradle

IntelliJ에서 Gradle로 프로젝트 관리시 두 가지 컴파일 방식이 있음

• Spring Boot + Gradle 프로젝트에서는 Gradle이 모든 빌드/실행을 담당하게 설정하는게 안정적이라고 한다.
• IntelliJ Build시, 다음과 같은 문제가 생길 수도 있음:
  • IntelliJ에서는 빌드 성공 → Gradle 빌드는 실패
  • 테스트는 IntelliJ에서 되는데 Gradle에서는 안 됨
  • Java 21 기능을 썼는데 실제 빌드 산출물은 Java 17 바이트코드로 나오는 문제

Gradle

Toolchain

공식문서
코드를 컴파일 할 때 어떤 JDK를 사용할지를 Gradle이 직접 다운받아 지정하는 기능

1
2
3
4
5
6

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

• Toolchain이 다운로드한 모든 JDK는 ~/.gradle/jdks/<jdk-version>/에 있음
• Gradle Toolchain이 JDK를 다운받는 기본 저장소 : Adoptium / Eclipse Temurin (기본값)
• Gradle은 다음 순서로 JDK를 찾는다:
  • 환경변수 JAVA_HOME
  • SDKMAN 설치 JDK
  • ASDF 설치 JDK
  • /usr/lib/jvm 같은 시스템 JDK
  • Windows 레지스트리의 JDK
  • 그래도 없으면 기본 저장소에서 다운로드

예시 상황

• 사람마다 / 서버마다 JDK 버전이 다르면, 빌드 결과와 에러도 다르게 나올 수 있다.
• 예시:
  • 개발자 A: Java 21로 빌드 → 성공
  • 개발자 B: Java 17로 빌드 → 실패
  • Jenkins: Java 11로 빌드 → 실패
• “로컬은 되는데 서버에서는 안된다” 문제 발생

정리

• IntelliJ 빌드, Gradle 빌드, 런타임 모두 JDK 21로 통일되므로 예상치 못한 빌드 오류, bytecode mismatch, IDE/Gradle 충돌 문제 등을 방지 할 수 있음