Spring Boot 프로젝트 구조 완벽 분석: 어디에 무엇을 작성할까?

안녕하세요.

Spring Boot 프로젝트 구조 완벽 분석: 어디에 무엇을 작성할까? 이미지 1

드디어 첫 번째 Spring Boot 프로젝트를 생성했습니다! 그런데 IntelliJ 왼쪽의 프로젝트 탐색기를 보니 폴더와 파일이 꽤 많아 보입니다. src, main, resources, build.gradle… 도대체 내 비즈니스 로직은 어디에 짜야 하고, 설정 파일은 어디에 두어야 할까요?

프로젝트 구조를 제대로 이해하지 못하면 엉뚱한 곳에 파일을 만들게 되고, 이는 결국 컴파일 에러나 설정 오류로 이어집니다. 오늘은 Spring Boot 프로젝트의 표준 디렉토리 구조를 한눈에 이해하기 쉽게 정리해 드리겠습니다. 이 가이드만 읽으시면 어떤 스프링 부트 프로젝트를 만나도 당황하지 않으실 겁니다!

1. 최상위 폴더 및 파일

프로젝트 루트 디렉토리에는 프로젝트 전체를 관리하는 파일들이 있습니다.

  • build.gradle: 프로젝트의 심장입니다. 어떤 라이브러리를 사용할지(의존성), 어떤 자바 버전을 쓸지 등을 정의하는 빌드 설정 파일입니다.
  • settings.gradle: 프로젝트의 이름이나 멀티 모듈 설정을 관리합니다.
  • .gitignore: Git에 올리지 말아야 할 파일들(빌드 결과물, 개인 설정 등)을 정의합니다.
  • gradlew / gradlew.bat: 서버에 자바나 그레이들이 설치되어 있지 않아도 프로젝트를 빌드할 수 있게 해주는 실행 스크립트입니다.

2. src/main 디렉토리: 실제 코드가 사는 곳

가장 핵심이 되는 공간입니다.

2.1 src/main/java

실제 자바 소스 코드가 위치하는 곳입니다. 패키지 경로를 따라 들어가면 다음과 같은 구성이 일반적입니다.

  • …Application.java: 프로젝트의 메인 클래스입니다. 여기서 프로그램이 시작됩니다.
  • controller/: 사용자의 요청을 받는 컨트롤러 클래스들을 모아둡니다.
  • service/: 실제 비즈니스 로직이 구현되는 서비스 클래스들이 위치합니다.
  • domain (또는 entity)/: DB 테이블과 매핑되는 엔티티 클래스들이 위치합니다.
  • repository/: DB와 소통하는 인터페이스들을 모아둡니다.

2.2 src/main/resources

자바 파일이 아닌 ‘자원’들이 위치합니다.

  • static/: CSS, JavaScript, 이미지 파일 등 정적 리소스를 둡니다.
  • templates/: Thymeleaf 같은 템플릿 엔진 파일(HTML)을 둡니다.
  • application.properties (또는 .yml): 프로젝트의 모든 설정(DB 접속 정보, 서버 포트 등)을 관리하는 매우 중요한 파일입니다.

3. src/test 디렉토리: 품질을 보장하는 곳

현대 개발에서 테스트 코드는 필수입니다. src/main의 구조를 그대로 본떠서 테스트 클래스들을 작성합니다. JUnit이나 AssertJ를 활용해 내가 짠 코드가 잘 작동하는지 검증하는 공간입니다.

4. 실무 팁: 패키지 구조 설계

초보자분들이 가장 많이 하는 실수 중 하나가 메인 클래스(Application.java)보다 상위 폴더나 외부 폴더에 패키지를 만드는 것입니다.

코드 예제 1: 올바른 패키지 위치

스프링 부트는 메인 클래스가 위치한 패키지부터 하위 패키지까지를 모두 훑으며 빈(Bean)을 등록합니다(Component Scan).

// 올바른 구조
com.example.demo
  ├── DemoApplication.java (메인 클래스)
  ├── controller/
  ├── service/
  └── repository/

만약 com.example.other라는 전혀 다른 패키지에 컨트롤러를 만들면, 스프링 부트는 그 컨트롤러를 찾지 못해 404 에러가 발생하게 됩니다.

코드 예제 2: application.yml 활용하기

최근에는 가독성이 좋은 YAML 형식을 선호합니다. src/main/resources/application.yml 파일의 예시입니다.

server:
  port: 8081 # 기본 8080 포트를 변경할 때

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
    username: sa
    password: 
  jpa:
    hibernate:
      ddl-auto: update # 엔티티 변경 시 테이블 자동 업데이트
    show-sql: true # 실행되는 SQL을 콘솔에 출력
Spring Boot 프로젝트 구조 완벽 분석: 어디에 무엇을 작성할까? 이미지 2

결론

Spring Boot 프로젝트 구조는 엄격한 규칙이 있는 것 같지만, 사실 개발자의 편의와 협업의 효율성을 위해 최적화된 표준입니다. 이 구조에 익숙해지면 다른 사람의 코드를 볼 때도 “아, 서비스 로직은 여기 있겠구나”라고 즉시 파악할 수 있는 눈이 생깁니다.

이제 구조를 알았으니, 마지막 단계로 넘어가 볼까요? 다음 시간에는 우리가 Run 버튼을 눌렀을 때, 내부적으로 스프링 부트가 어떤 순서로 실행되는지 그 신비로운 과정을 파헤쳐 보겠습니다.

궁금한 폴더가 더 있다면 언제든 질문해 주세요! 감사합니다.

관련 글 보기