[Spring Boot] 멀티-모듈 프로젝트 build시 common 모듈의 의존성 받지 못하는 문제 해결

Spring Boot 프로젝트에서 공통 모듈(common)을 사용하여 엔티티와 DTO를 관리하는 것은 코드 재사용성을 높이고 유지 보수를 용이하게 하는 좋은 방법입니다. 그러나 이 방식에서 발생할 수 있는 문제가 있습니다. 바로 common 모듈에 정의된 JPA 엔티티를 다른 모듈(예: producer나 consumer)에서 사용할 때 발생하는 오류입니다.

IDE에서는 정상적으로 인식되지만, 빌드 후에는 엔티티를 찾을 수 없다는 오류가 발생할 수 있습니다. (그래서 당황해서 삽질을 많이 합니다.)

 

예시 파일 구조

Roomie/
├── common/                   # 공통 모듈 (엔티티, DTO 등)
│   ├── build.gradle
│   ├── src/
│   │   └── main/
│   │       └── java/
│   │           └── entity/
│   │           └── dto/
├── producer/                 # Producer 모듈
│   ├── build.gradle
│   ├── src/
│   │   └── main/
│   │       └── java/
│   │           └── producer/
│   │               └── ProducerApplication.java  # @SpringBootApplication
│   │               └── producerService/
├── consumer/                 # Consumer 모듈
│   ├── build.gradle
│   ├── src/
│   │   └── main/
│   │       └── java/
│   │           └── consumer/
│   │               └── ConsumerApplication.java  # @SpringBootApplication
│   │               └── consumerService/
├── settings.gradle           # 프로젝트 전체 설정
└── build.gradle              # 루트 프로젝트 빌드 설정

 

이 오류의 원인과 해결 방법을 자세히 살펴보겠습니다.

---

원인

Spring Boot는 기본적으로 애플리케이션 클래스의 위치를 기준으로 JPA 엔티티를 스캔합니다. 즉, @SpringBootApplication 어노테이션이 선언된 클래스가 위치한 패키지와 그 하위 패키지에 있는 엔티티만 자동으로 스캔됩니다.

 

@SpringBootApplication은 다음과 같은 어노테이션을 포함하고 있습니다:

1. @Configuration: Spring 설정 파일로 동작하도록 지정

2. @EnableAutoConfiguration: Spring Boot의 자동 구성 기능 활성화

3. @ComponentScan: 기본적으로 애플리케이션 클래스가 위치한 패키지 및 그 하위 패키지를 스캔

 

따라서 common 프로젝트에 있는 엔티티는 producer 또는 consumer 프로젝트의 하위 패키지가 아니기 때문에 기본적으로 컴포넌트 스캔에서 제외됩니다. 이로 인해 common 프로젝트에서 정의한 엔티티가 제대로 인식되지 않아 entity not found 오류가 발생합니다.

---

해결 방법

 

이 문제를 해결하려면 @EntityScan 어노테이션을 사용하여 Spring Boot가 명시적으로 엔티티를 스캔할 패키지를 지정해줘야 합니다.

 

@EntityScan은 Spring Boot가 JPA 엔티티를 스캔할 위치를 명시적으로 설정할 수 있는 기능을 제공합니다. 이를 통해 common 패키지에 위치한 엔티티들을 producer나 consumer에서 사용할 수 있게 됩니다.

 

 

producer 프로젝트의 애플리케이션 클래스에 @EntityScan을 추가하여 common 패키지의 엔티티를 스캔하도록 설정합니다.

@EntityScan(basePackages = "com.example.common.entity") // common 프로젝트의 엔티티 위치 지정
@SpringBootApplication
public class ProducerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ProducerApplication.class, args);
    }
}

 

위와 같이 @EntityScan을 추가함으로써, common 프로젝트에 있는 모든 JPA 엔티티를 producer 프로젝트에서도 사용할 수 있도록 설정할 수 있습니다.

 

요약

• 문제: common 프로젝트의 JPA 엔티티를 producer나 consumer 프로젝트에서 인식하지 못하는 오류
• 원인: Spring Boot의 기본 설정에서는 애플리케이션 클래스 패키지와 하위 패키지만 JPA 엔티티를 스캔함
• 해결: @EntityScan을 사용하여 엔티티를 스캔할 패키지를 명시적으로 지정