API Layer Architecture — Route / Service / Schema / Core 정리
백엔드 구조를 정리할 때 가장 먼저 등장하는 레이어 개념이 있다.
Route(Controller) / Service / Schema(DTO) / Core(Domain)
각 레이어의 역할만 정확히 알고 있어도 코드 구조가 훨씬 깔끔해진다.
1. Route Layer (Controller, Router)
HTTP 요청을 받고, 어떤 서비스 함수로 보낼지 “매핑”하는 레이어.
하는 일
-
URL + HTTP 메서드 정의 (GET /users/{id})
-
요청 데이터를 Schema(DTO)로 변환
-
예외 처리 → HTTP 응답 포맷 작성
-
Service 호출 → 결과 받아서 반환
하지 말아야 하는 일
-
비즈니스 로직
-
DB 접근
-
트랜잭션 처리
Route는 얇게, Service는 두껍게가 유지보수에 유리하다.
2. Service Layer (Application Service)
“요청 단위의 유스케이스”를 실행하는 레이어.
하는 일
-
여러 도메인 객체(Core)를 조합해 기능 수행
-
Repository(DB) 접근을 순서대로 오케스트레이션
-
트랜잭션 처리
-
권한/검증 등의 애플리케이션 규칙 처리
예시
회원가입 → 중복검사 → 비밀번호 해싱 → DB 저장
주문 생성 → 재고 차감 → 결제 요청 → 기록 저장Service 레이어가 전체 플로우를 총괄 지휘한다.
3. Schema Layer (DTO, Pydantic Model)
API 입력/출력 구조 + 유효성 검증을 담당.
하는 일
-
요청/응답의 필드 정의
-
타입 검증, 형식 검증
-
도메인 모델과 분리된 “I/O 전용” 데이터 모델
Schema는 “외부 세계와 내부 도메인 사이의 방화벽 역할”을 한다.
API 스펙이 바뀌어도 Core (도메인)을 바로 건드리지 않아도 된다.
4. Core Layer (Domain)
비즈니스 핵심 규칙을 포함하는 레이어.
해야하는 일
-
Entity, Value Object (User, Product, Money 등)
-
순수 비즈니스 로직 (할인 계산, 위험 점수 계산 등)
-
Repository 인터페이스 (구현체는 infra에서)
Core는 웹 프레임워크나 DB 종류에 의존하면 안된다.
이렇게 해야 FastAPI → Spring Boot로 갈아타도 Core를 그대로 재사용 가능하다.
전체 구조 요약
레이어 역할
Route HTTP 라우팅, 요청/응답 구성
Service 유스케이스 실행, 비즈니스 흐름 조립
Schema 요청·응답 포맷 관리, 유효성 검증
Core 순수 도메인 규칙, 핵심 모델Spring Boot vs FastAPI — 기술적인 차이
1. 언어/생태계
Spring Boot
Java/Kotlin 기반
대규모 엔터프라이즈 백엔드 표준
보안/트랜잭션/배치/메시징 등 인프라 스택 완비FastAPI
Python 기반
AI/데이터 생태계와 결합이 매우 쉬움
가볍고 개발 속도가 빠름2. 프레임워크 성격
Spring Boot = Full-stack 백엔드 프레임워크
기업 서비스 전체 운영을 위한 종합 프레임워크
FastAPI = Lightweight 웹 프레임워크
빠른 개발, 확장성 확보, ML·AI 모델 API화에 적합
3. IO/비동기 처리 방식
Spring Boot
기본은 동기식
WebFlux(Reactor)가 필요 시 고성능 비동기 처리 가능
장기간 운영 시 JVM 최적화가 강력FastAPI
애초에 async/await 기반
IO-bound API에 유리 (ML inference, 외부 API 호출 등)ESG 물리 기후 예측 프로젝트는 왜 Spring Boot + FastAPI를 둘 다 썼는가?
1. 전체 구조가 “AI 모델 운영(ModelOps) + 백엔드 서비스”로 분리된 구조였기 때문
해당 프로젝트는 단순 CRUD API가 아니라 다음과 같이 2계층 구조였다:
백엔드 서비스 계층 (Spring Boot)
회원관리
인증(JWT)
채팅 로그 저장
안정적인 API 스펙 제공
트래픽 대응
DB 트랜잭션 및 보안 담당AI/모델 연산 계층 (FastAPI, Python)
ChatGPT API 연동
Pre/Post-processing
간단한 LLM 라우팅
분석/ML 로직과 Python 생태계 필요Python의 강점은 다음과 같음:
NLP, AI 라이브러리(PyTorch, Transformers 등)
빠른 개발 속도
ML 추론/전처리에 최적화
반면 Spring Boot는 다음이 강함:
서비스 운영 안정성
인증/보안
구조화된 레이어드 아키텍처
대규모 트래픽 처리
그래서 각 기술의 장점을 그대로 사용한 것임.
2. 프론트(Android/React Native)에서 호출하는 메인 API는 Spring이 더 적합했기 때문
Spring은 다음이 강력하다:
엄격한 타입 검증
명확한 패키지 구조
스케일링 및 운영 안정성
기업용 API 스펙에 익숙한 구조
반면 FastAPI는:
AI inference API
실험용/내부용 API
비동기 요청 처리
이런 용도로 더 잘 맞는다.
→ 즉, 서비스 API와 모델 API를 분리해서 의존성을 줄이는 구조로 운영한 것.
3. 단일 프레임워크로 모든 것을 처리하려고 하면 오히려 손해였기 때문
FastAPI로 회원가입/로그인/JWT/DB 관리까지 하려면
결국:
ORM 설정
인증 체계
계층 구조
배포 파이프라인등을 전부 별도로 만들어야 한다.
Spring Boot는 이미 이 기능셋이 정교하게 갖춰져 있으므로
백엔드 메인 API는 Spring을 쓰는 것이 더 효율적이었다.
반대로,
Spring Boot로 AI inference API를 만들면, Python 기반 라이브러리를 쓰기 어려워지고
LLM 처리 속도, 유연성, 개발 효율이 크게 떨어진다.
마무리
Route–Service–Schema–Core 구조는 “역할을 명확하게 분리해 유지보수를 쉽게 하는 방법”이다.
이 구조를 적용하면 코드가 복잡해질수록 더 깔끔해지고, 팀 개발에서도 충돌이 줄어든다.
또한, Spring Boot와 FastAPI를 동시에 사용한 이유는 단순히 기술 욕심이 아니라,
각 프레임워크가 잘하는 영역이 명확히 달랐기 때문이다.
Spring Boot → 인증, 트랜잭션, 안정적인 서비스 운영
FastAPI → AI 모델 연산, Python 기반 전처리/후처리, 비동기 IO즉, 해당 프로젝트는 “하나로 다 해결하는 프레임워크”를 고른 것이 아니라, 역할에 따라 옳은 도구를 선택한 것이다.
두 기술을 조합하면 서비스 안정성과 AI 처리 성능을 동시에 확보할 수 있으며,
앞으로 기능을 확장할 때도 각 계층을 독립적으로 개선할 수 있다.
결국 중요한 것은 기술 스택이 아니라 구조화된 설계와 역할 분리다.
