[Spring Boot] 프로젝트 구조 이해: Todo API로 배우는 5단계 아키텍처

📌 소개

Spring Boot를 처음 배울 때 가장 헷갈리는 것이 "어떤 폴더에 어떤 파일을 넣어야 하는가?" 이다.
이 글은 Todo API 프로젝트를 통해 Controller, Service, Repository, Entity, DTO의 역할과 각 파일이 왜 그 위치에 있어야 하는지 명확하게 설명한다. 코드보다 구조와 개념 이해에 집중해보자.

 

프로젝트: 간단한 할 일 관리 (Todo) API

[프로젝트 구조]

todo-api/
├── src/
│   └── main/
│       ├── java/
│       │   └── com/
│       │       └── example/
│       │           └── todo/
│       │               ├── TodoApplication.java
│       │               ├── controller/
│       │               │   └── TodoController.java
│       │               ├── service/
│       │               │   └── TodoService.java
│       │               ├── repository/
│       │               │   └── TodoRepository.java
│       │               ├── entity/
│       │               │   └── Todo.java
│       │               ├── dto/
│       │               │   ├── TodoCreateRequest.java
│       │               │   ├── TodoResponse.java
│       │               │   └── ErrorResponse.java
│       │               └── exception/
│       │                   ├── TodoNotFoundException.java
│       │                   └── GlobalExceptionHandler.java
│       └── resources/
│           └── application.yml
└── pom.xml

 

각 단계별 설명

1단계: Hello World 실행 확인

파일명	역할	상세 설명
TodoApplication.java	스프링부트 시작점	@SpringBootApplication이 선언된 메인 클래스로, 애플리케이션 실행 진입점
application.yml	환경 설정	MySQL 연결 정보 설정 → 서버 실행 시 DB 자동 연동
TodoController.java	API 컨트롤러	서버 동작 확인용 Hello World API 제공

 

2단계: Controller-Service-Repository 패턴

파일명	구분	역할	상세 설명
Todo.java	Entity	DB 매핑	@Entity로 MySQL 테이블과 매핑, 컬럼 정의
TodoRepository.java	Repository	DB 접근	JpaRepository 상속 → CRUD 자동 제공
TodoService.java	Service	비즈니스 로직	트랜잭션 처리, 핵심 로직 캡슐화
TodoController.java	Controller	HTTP 요청 처리	REST API 제공 (CRUD 완성)

 

3단계: Entity 대신 DTO 사용하기

파일명	구분	역할	상세 설명
TodoCreateRequest.java	Request DTO	요청 데이터 수신	클라이언트 입력 전용 DTO, 검증(@Valid) 대상
TodoResponse.java	Response DTO	응답 데이터 반환	필요한 필드만 노출하여 응답 구조 안정화
TodoService.java	Service	변환 책임	Entity ↔ DTO 변환 로직 담당 (비즈니스 계층에 캡슐화)
TodoController.java	Controller	DTO 입출력	Entity 직접 사용 금지, DTO로만 요청·응답 처리

 

4단계: JPA 쿼리 메서드

파일명	구분	역할	상세 설명
TodoRepository.java	Repository	findBy..., @Query	메서드 쿼리 및 JPQL/Native Query로 다양한 조회 조건 지원
TodoService.java	Service	검색·필터링 로직	상태, 키워드, 기간 등 조건 조합 처리
TodoController.java	Controller	검색 API	조건 파라미터 기반 조회 엔드포인트 제공

 

5단계: 예외 처리와 유효성 검증

파일명	구분	역할	상세 설명
TodoNotFoundException.java	Exception	커스텀 예외	Todo 미존재 시 명확한 도메인 예외 정의
ErrorResponse.java	DTO	에러 응답	에러 코드·메시지·타임스탬프 등 표준화된 응답 구조
GlobalExceptionHandler.java	Handler	전역 예외 처리	@ControllerAdvice로 예외 일괄 처리
TodoCreateRequest.java	DTO	요청 검증	@NotBlank, @Size 등 @Valid 기반 입력값 검증
TodoController.java	Controller	검증 적용	@Valid 적용으로 잘못된 요청 사전 차단

 

왜 이렇게 나누는가?

Spring Boot 프로젝트를 Controller, Service, Repository로 나누는 이유는 간단하다.

각 계층이 자기 일만 하도록 만들기 위해서다.

 

모든 것을 Controller에 작성 (나쁜 예)	책임별로 분리 (좋은 예)
TodoController.java ├─ HTTP 요청 처리 ├─ 비즈니스 로직 ├─ 데이터베이스 접근 ├─ 예외 처리 └─ 데이터 검증	TodoController.java └─ HTTP 요청/응답만 처리 TodoService.java └─ 비즈니스 로직만 처리 TodoRepository.java └─ 데이터베이스 접근만 처리 GlobalExceptionHandler.java └─ 예외 처리만 담당
→ 한 파일이 너무 많은 책임! → 수정할 때마다 위험 → 어디서 문제가 생겼는지 찾기 어려움	→ 각자 자기 일만 함!

 

1. 단일 책임 원칙 (Single Responsibility Principle)

한 파일은 한 가지 일만 해야 한다.
모든 코드를 TodoController 하나에 작성하면 HTTP 요청 처리, 비즈니스 로직, 데이터베이스 접근이 한 파일에 뒤섞이게 된다. 그 결과 수백 줄짜리 거대한 파일이 만들어지고, 문제가 발생했을 때 원인을 찾기 어려워진다.

계층을 분리하면 각 파일은 자신의 역할만 수행한다. Controller는 HTTP 요청과 응답만 처리하고, Service는 비즈니스 로직만 담당하며, Repository는 데이터베이스 접근만 책임진다. 문제가 발생하면 어떤 계층을 확인해야 하는지가 즉시 명확해진다.

 

2. 유지보수성

코드는 나중에 고치기 쉬워야 한다.
실제 개발 현장에서는 새 코드를 작성하는 시간보다 기존 코드를 수정하는 시간이 훨씬 더 많이 소요된다. 따라서 변경에 강한 구조를 갖는 것이 중요하다.

예를 들어 데이터베이스를 MySQL에서 PostgreSQL로 변경해야 한다고 가정한다. 계층 분리가 되어 있지 않다면 Controller 곳곳에 작성된 SQL을 모두 수정해야 하며, 이 과정에서 실수가 발생할 가능성이 높다.
반면 Repository로 분리되어 있다면 데이터베이스 설정은 application.yml과 Repository 계층에 국한된다. 수정 범위가 극도로 줄어든다.

또 다른 예로 “완료된 할 일은 수정할 수 없다”라는 비즈니스 규칙을 추가해야 하는 경우를 생각해본다. Service 계층에 로직이 모여 있다면 TodoService의 수정 로직 한 곳만 변경하면 모든 API에 동일하게 적용된다. 그러나 Controller마다 로직이 흩어져 있다면 동일한 코드를 여러 파일에 반복해서 추가해야 한다.

 

3. 테스트 용이성

코드는 자동으로 검증할 수 있어야 한다.
테스트가 없는 개발 환경에서는 수정할 때마다 Postman으로 모든 API를 수동으로 호출해야 한다. 기능이 많아질수록 검증 비용은 기하급수적으로 증가하며, 실수로 확인하지 못하는 경우도 발생한다.

계층이 분리되어 있으면 Service 계층만 독립적으로 테스트할 수 있다. HTTP 서버나 실제 데이터베이스 없이도 비즈니스 로직을 빠르게 검증할 수 있으며, 테스트는 몇 초 안에 끝난다.
반대로 모든 로직이 Controller에 섞여 있다면 테스트를 위해 서버 실행, 요청 생성, 데이터베이스 준비가 필요해지고, 테스트 하나에 몇 분이 걸리게 된다. 이런 구조에서는 테스트 자체가 외면받게 된다.

 

결론

Controller–Service–Repository 패턴으로 나누는 이유는 결국 개발자를 편하게 만들기 위해서다.
초기에는 파일 수가 늘어나 복잡해 보일 수 있지만, 프로젝트 규모가 커질수록 이 구조의 장점이 분명해진다.

각 계층이 자기 역할만 수행하므로 코드를 찾기 쉽고, 수정하기 쉽고, 테스트하기 쉽다. 이것이 실무에서 이 패턴이 표준처럼 사용되는 이유다.