이 글은 척척학사 백엔드 구조를 Spring Boot로 전환하면서 얻은 경험을 정리한 회고입니다.
초기 MVP 구조가 궁금하다면 이 글을 함께 보시는 걸 추천드려요.
🚀 Next.js → Spring Boot 백엔드 마이그레이션 회고
"Next.js로 돌아가는 서버를 Spring으로 전부 갈아엎어야 합니다"
2025년 3월, 척척학사 팀에 합류하면서 처음 맡은 과제가 백엔드 서버 마이그레이션이었어요.
기존 서버는 Next.js API Routes 기반으로 작성되어 있었고, MVP 단계에서는 빠르게 만들기엔 딱 좋았죠.
실제로 서비스 오픈 초기에는 큰 문제 없이 잘 작동했어요.
하지만 시간이 지나면서 문제가 생기기 시작했어요.
졸업 요건 계산, 포털 데이터 크롤링, 수강 정보 동기화처럼 복잡한 로직이 늘어나면서 Next.js 구조로는 트랜잭션 관리가 어렵고, 서버 코드와 프론트 코드가 얽혀 있어서 유지보수가 쉽지 않았어요.
결국 선택은 하나였어요.
백엔드를 Java + Spring Boot로 완전히 분리하고, 아키텍처를 새롭게 설계해보자.
2개월간의 리팩토링과 마이그레이션 끝에 4월 말, 드디어 Spring 기반 백엔드로 전환을 마쳤습니다.
이 글은 그 과정에서 겪었던 주요 변화와 느낀 점을 정리한 회고입니다.
🧭 마이그레이션 배경
기존 척척학사 서버는 수강신청 시즌(2~3월)에 맞춰 빠르게 기능을 완성하는 것을 목표로 했습니다.
Next.js API Routes 기반의 초기 구조는 MVP 개발에는 적합했지만, 다음과 같은 문제들이 있었습니다:
- 서버 코드가 프론트엔드와 강하게 결합되어 있었고
- 복잡한 데이터 조작 및 트랜잭션 처리에 구조적 제약이 존재했으며
- 유지보수성과 확장성이 떨어졌습니다
이에 따라 백엔드 서버를 Spring Boot 기반으로 리팩토링하면서, 명확한 계층 구조와 유연한 아키텍처를 구축하고자 했습니다.
🧱 초기 서버 환경의 한계
- 복잡한 데이터 처리 및 트랜잭션/동시성 제어의 어려움
- Playwright 기반 크롤링 로직에 필요한 실행 환경 미지원
- 서버리스 배포(Vercel) 환경에서는 브라우저 바이너리 등 의존성 문제로 실행 불가
🔧 마이그레이션 과정에서 개선한 점
1. 중복 코드 제거 및 구조화
- API 공통 로직을
UseCase/Service단으로 분리 - DTO, Mapper, Entity 간 책임을 명확히 구분하여 유지보수성 향상
2. JPA 기반 리팩토링
fetch join,LAZY전략 조정 등을 통해 N+1 문제 해결- Entity 연관관계 정비로 데이터 흐름 최적화
- 불필요한 연관 제거
- 단방향/양방향 관계 정비
3. RESTful API 구조 개선
- 기능 중심 라우트에서 리소스 중심 API 설계로 전환
- Swagger(OpenAPI 3.0) 기반 자동 문서화 적용
4. 소셜 로그인 로직 이관
- OIDC 검증 로직을 프론트 → 백엔드(Spring)로 이전
KakaoOidcService를 통해id_token,nonce검증 수행
5. 공통 응답 포맷 적용
ApiResponse<T>도입으로 모든 응답 포맷 통일- Swagger 문서에서도 일관된 응답 스키마 적용
6. 환경 분리 및 인프라 개선
dev/prod환경을 명확히 분리하고,.env+application-{profile}.yml로 설정 관리- DB는 Supabase PostgreSQL 유지하되, Spring JPA로 접근 방식 변경
📌 앞으로 적용할 계획
1. 크롤링 로직 비동기 처리
- Spring의
@Async또는@Scheduled기반 비동기화 예정 - Redis Lock 또는 Queue 활용 검토 중
2. 무중단 배포
- 현재는 수동 배포 방식
- 추후 Blue-Green → Rolling 배포 방식 전환 예정
3. AWS 아키텍처 비용 최적화
- IPv6, Auto Scaling, Fargate 도입 고려
- CloudWatch 기반 모니터링 및 알람 설정
📊 마이그레이션 성과 요약
| 항목 | 변경 전 (MVP) | 변경 후 (Spring 기반) |
|---|---|---|
| 서버 구조 | Next.js API Routes | Java + Spring Boot |
| 인증 처리 | 프론트 OIDC 검증 | 백엔드 검증 수행 |
| API 구조 | 기능별 라우트 | RESTful + Swagger |
| 응답 포맷 | 비표준/불일치 | ApiResponse<T> 통일 |
| DB 접근 방식 | Supabase 호출 | Spring Data JPA |
| 환경 구성 | 단일 환경 | dev/prod 분리 |
💬 느낀 점
이번 마이그레이션은 단순한 기술 전환이 아니라, 아키텍처 전환의 시작점이었다.
빠르게 기능을 구현하던 구조에서 벗어나, 유지보수성과 확장성을 고려한 체계적인 백엔드 아키텍처를 경험할 수 있었다.
Spring의 계층 구조, JPA의 ORM, Spring Security의 인증 방식 등을 프로젝트에 적용하면서
코드의 역할 분리와 계층화가 가져다주는 안정성과 가독성의 장점을 뼈저리게 느낀 경험이었다.
🔗 Related
