Spring Boot에서 Lombok 기본 사용과 IDE 설정

소개

코드 보일러플레이트를 줄이기 위해 Lombok을 사용하면 개발 속도가 빨라진다. 하지만 설정이 누락되거나 IDE가 적절히 구성되지 않으면 컴파일이나 런타임에서 문제가 발생한다. 이 글은 처음 사용하는 사람도 이해하도록 Lombok의 설치, 주요 애노테이션, IntelliJ 설정과 흔한 문제 해결을 단계별로 설명한다.

Lombok을 사용하는 이유

Lombok은 자바에서 반복되는 게터/세터, 생성자, 빌더 코드를 자동 생성한다. 소스는 간결해지고 유지보수성이 좋아진다. Spring Boot와 함께 쓰면 엔티티와 DTO 정의가 훨씬 간단해진다.

프로젝트에 Lombok 추가하기

Maven 설정

<dependency>
  <groupId>org.projectlombok</groupId>
  <artifactId>lombok</artifactId>
  <version>1.18.26</version>
  <scope>provided</scope>
</dependency>

scope를 provided로 두면 런타임에 Lombok이 필요하지 않다. 컴파일 시 애노테이션 프로세서가 코드를 생성한다.

Gradle 설정 (Gradle Kotlin DSL 예시)

dependencies {
  compileOnly("org.projectlombok:lombok:1.18.26")
  annotationProcessor("org.projectlombok:lombok:1.18.26")
}

tasks.withType(JavaCompile).configureEach {
  options.annotationProcessorPath = configurations.annotationProcessor
}

자주 쓰는 Lombok 애노테이션

• @Getter / @Setter: 필드 접근자 자동 생성
• @RequiredArgsConstructor: final 필드를 인수로 받는 생성자 생성
• @AllArgsConstructor / @NoArgsConstructor: 모든 필드 또는 인자가 없는 생성자 생성
• @Data: @Getter, @Setter, @ToString, @EqualsAndHashCode, @RequiredArgsConstructor 통합
• @Builder: 빌더 패턴 생성

예시 엔티티

package com.example.demo.domain;

import lombok.*;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class User {
  private Long id;
  private String username;
  private String email;
}

IntelliJ에서 Lombok IDE 설정

IntelliJ에서 Lombok을 정상적으로 사용하려면 플러그인 설치와 애노테이션 프로세서 활성화가 필요하다. 아래 단계를 따라가면 대부분의 문제를 예방할 수 있다.

• 플러그인 설치: Settings(또는 Preferences) > Plugins > Marketplace에서 "Lombok" 검색 후 설치
• 애노테이션 프로세서 활성화: Settings > Build, Execution, Deployment > Compiler > Annotation Processors에서 "Enable annotation processing" 체크
• 프로젝트 재빌드: 플러그인 설치 후 인덱싱과 캐시 반영을 위해 Rebuild Project 실행

IDEA 설정 팁

멀티모듈 프로젝트라면 각 모듈의 애노테이션 프로세서 설정을 확인한다. Gradle 프로젝트는 Gradle이 컴파일을 담당하므로 IDE 빌드 설정과 Gradle 빌드 설정이 일치하는지 확인하면 문제를 줄일 수 있다.

자주 발생하는 문제와 해결

1) IDE에서 빨간 줄이 보이고 빌드는 통과되는 경우

이는 Lombok 플러그인이 설치되지 않았거나 애노테이션 프로세서가 비활성화된 경우다. 플러그인 설치와 "Enable annotation processing" 확인 후 프로젝트를 재빌드한다.

2) NoSuchMethodError 또는 런타임 관련 문제

Lombok을 provided 또는 compileOnly로 설정하고 실제로 생성된 코드가 런타임에 필요한 경우가 있다. 일반적으로 Lombok은 컴파일 타임에만 필요하므로 문제는 드물지만, 라이브러리 버전 충돌이 원인이 될 수 있다. 의존성 트리를 확인하고 중복된 Lombok 버전이 없는지 점검한다.

3) Gradle에서 annotationProcessor가 적용되지 않는 경우

Gradle 설정에서 compileOnly와 annotationProcessor를 함께 선언했는지 확인한다. Kotlin DSL과 Groovy DSL은 설정 방식이 다르므로 빌드 스크립트 문법에 맞게 설정한다.

실무에서의 권장 사용법

• 엔티티에는 @Data 대신 필요한 애노테이션만 사용해 불필요한 메서드 생성을 피한다.
• @Builder를 사용할 때는 불변 객체 패턴을 고려해 final 필드와 생성자 조합을 사용한다.
• 테스트 코드에서는 Lombok을 적극 활용해 테스트 데이터 객체를 간결하게 만든다.
• 팀 컨벤션으로 Lombok 사용 범위를 정해 예측 가능한 코드 스타일을 유지한다.

마무리

Lombok은 Spring Boot 개발에서 반복 작업을 줄여준다. 다만 IDE 설정과 빌드 설정이 일치하지 않으면 혼란이 생긴다. 플러그인 설치, 애노테이션 프로세서 활성화, Gradle/Maven 의존성 선언을 차근히 점검하면 대부분의 문제를 해결할 수 있다. 위 내용을 참고해 안정적인 Lombok 사용 환경을 구축하면 코드 품질과 생산성이 동시에 개선된다.