Spring Boot 프로젝트 구조 이해하기: 실무 중심 가이드

Spring Boot는 빠르고 효율적인 웹 애플리케이션 개발을 위해 널리 사용되는 프레임워크입니다. 그러나 입문자나 프레임워크 전환을 고민하는 개발자에게는 Spring Boot 프로젝트의 디렉터리 구조가 다소 생소할 수 있습니다.

Spring Boot의 기본 프로젝트 구조를 상세히 설명하고, 각 디렉터리의 역할과 실무 팁을 함께 소개합니다.

 

1. 기본 프로젝트 구조 개요

Spring Initializr나 IntelliJ로 생성한 기본 구조는 다음과 같습니다.

src
 └── main
     ├── java
     │    └── com.example.demo
     │         ├── DemoApplication.java
     │         └── controller
     │         └── service
     │         └── repository
     ├── resources
     │    ├── application.yml
     │    ├── static
     │    ├── templates
     │    └── messages.properties
 └── test
     └── java
         └── com.example.demo
             └── DemoApplicationTests.java

이 구조는 Maven이나 Gradle 프로젝트에서도 거의 동일하게 유지됩니다. 각 폴더의 의미를 아래에서 자세히 살펴보겠습니다.

 

2. 주요 디렉터리 설명

2.1 src/main/java

Java 소스 코드가 위치하는 디렉터리입니다. 일반적으로 패키지 기준으로 도메인을 나누어 관리합니다.

• Application 클래스: @SpringBootApplication이 붙은 메인 클래스(DemoApplication.java)가 위치합니다.
• Controller: REST API나 Web Controller를 담당하며, @RestController 또는 @Controller를 사용합니다.
• Service: 비즈니스 로직을 구현하는 레이어로, 보통 @Service를 붙입니다.
• Repository: JPA, MyBatis 등 DB 연동과 관련된 코드가 위치합니다. @Repository 사용.

2.2 src/main/resources

설정 파일 및 정적 리소스, HTML 템플릿 등을 관리하는 디렉터리입니다.

• application.yml / application.properties: Spring Boot 설정 파일
• static: 정적 리소스(css, js, 이미지 등)
• templates: Thymeleaf, Mustache 등 템플릿 엔진이 HTML을 렌더링하는 곳
• messages.properties: 다국어 메시지를 관리하는 파일

2.3 src/test/java

테스트 코드가 들어가는 공간입니다. 기본적으로 JUnit 기반의 단위 테스트 또는 통합 테스트가 이곳에 작성됩니다.

• @SpringBootTest로 전체 애플리케이션 컨텍스트를 로딩한 통합 테스트 가능
• @MockBean, @WebMvcTest를 활용해 단위 테스트 분리 가능

 

3. 실무에서의 구조 확장 팁

기본 구조에서 프로젝트 규모가 커지면 다음과 같은 확장이 필요할 수 있습니다.

• 패키지 분리: domain, dto, config, exception 등의 패키지를 도입
• 모듈화: 멀티 모듈 구조로 core, api, batch 등을 분리
• API 버전 관리: controller.v1, controller.v2 등으로 REST 버전 구분

 

4. 구조를 이해하면 설계가 보인다

Spring Boot 프로젝트는 Convention over Configuration 철학에 따라 구조가 명확하게 정의되어 있습니다. 구조를 잘 이해하는 것이 유지보수성과 확장성에서 큰 차이를 만듭니다. 특히 팀 단위로 협업할 때는 구조를 표준화하는 것이 생산성을 높이는 핵심이 됩니다.