JPA 엔티티 스캔 경로 설정 방법

@EntityScan의 설명과 사용

@EntityScan은 Spring Data JPA에서 엔티티(Entity) 클래스를 검색할 위치를 명시적으로 지정하는 데 사용합니다.

핵심 기능

Spring Boot 애플리케이션은 보통 메인 클래스가 위치한 패키지와 그 하위 패키지만 자동으로 스캔합니다. 만약 @Entity 어노테이션이 붙은 엔티티 클래스가 메인 애플리케이션의 패키지 외부에 존재하면, Spring Data JPA는 이 엔티티를 자동으로 찾지 못합니다.

이러한 상황에서 @EntityScan을 메인 애플리케이션 클래스에 붙여 엔티티 클래스가 실제로 위치하는 패키지 경로를 알려줍니다. 이 설정을 통해 애플리케이션은 외부 패키지에 있는 엔티티도 인식하고 정상적으로 데이터베이스 작업에 사용할 수 있습니다.

엔티티를 스캔할 경로를 지정할 때는 주로 basePackages 속성을 사용합니다.

사용 예제

다음은 메인 애플리케이션과 엔티티 클래스의 패키지 위치가 다를 때 @EntityScan을 적용하는 예시입니다.

1. 엔티티 클래스 위치

엔티티 클래스가 com.project.domain 패키지에 있습니다.

// 패키지: com.project.domain

@Entity
public class Product {
    @Id
    @GeneratedValue
    private Long id;
    private String name;

    // ... 생략
}

---

2. 메인 애플리케이션 클래스에 적용

메인 애플리케이션 클래스는 com.project.app 패키지에 있습니다. 엔티티를 찾을 수 있도록 @EntityScan으로 com.project.domain 패키지를 지정합니다.

// 패키지: com.project.app

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.autoconfigure.domain.EntityScan;

@SpringBootApplication
// 엔티티가 있는 'com.project.domain' 패키지를 명시적으로 스캔하도록 지정합니다.
@EntityScan(basePackages = "com.project.domain")
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

@EntityScan 사용 시 주의할 점 및 장점

사용할 때 주의할 점

구분	주의 사항	설명
패키지 경로 정확성	경로를 잘못 지정하지 않아야 합니다.	basePackages 속성에 지정한 경로가 실제로 엔티티 클래스가 존재하는 최상위 패키지와 정확히 일치해야 합니다. 경로가 틀리면 엔티티를 찾지 못해 애플리케이션 시작 시 오류가 발생합니다.
중복 스캔 방지	기본 스캔 범위와 중복되지 않게 설정합니다.	@SpringBootApplication의 기본 스캔 범위(메인 클래스 패키지 및 하위) 내에 엔티티가 있다면 @EntityScan을 사용할 필요가 없습니다. 불필요한 스캔 경로를 추가하면 시작 시간이 길어질 수 있습니다.
클래스 지정 사용	클래스 배열 지정 옵션을 고려합니다.	basePackages 대신 basePackageClasses 속성을 사용해 엔티티가 포함된 특정 클래스를 지정할 수 있습니다. 이는 패키지 전체 스캔 대신 필요한 엔티티만 로드하여 성능을 최적화할 수 있습니다.

---

@EntityScan을 사용하면 좋은 점

장점	설명
엔티티 분리 및 구조화	프로젝트의 모듈화에 유리합니다.
스캔 범위 명확화	엔티티 검색의 투명성을 높입니다.
기본 스캔 범위 조정	@ComponentScan과 함께 사용해 시작 성능을 개선합니다.