# 2계층에서 3계층 아키텍처로 전환하기: 모듈러 모놀리쓰와 GraphQL 마이그레이션 여정

---

# # 서론 – 왜 아키텍처를 바꿔야 할까?

많은 스타트업과 중소기업이 **2계층 아키텍처**(클라이언트‑서버)로 서비스를 시작합니다. 초기 개발 속도가 빠르고 구현이 간단해 보이지만, 프로젝트가 성장하면서 데이터 처리량, 보안 요구사항, 팀 규모가 확대됩니다. 이때 기존 구조는 **성능 병목**, **코드 복잡도 증가**, **배포 위험** 등 여러 문제를 일으키게 됩니다.

이러한 한계를 극복하기 위해 **3계층 아키텍처**(프레젠테이션‑비즈니스‑데이터)로 전환하는 것이 일반적인 해결책입니다. 하지만 갑작스러운 전환은 서비스 중단 위험을 동반하므로, **모듈러 모놀리쓰**와 **GraphQL**을 활용한 단계적 마이그레이션 전략이 필요합니다.

---

# # 1️⃣ 2계층 아키텍처의 구조와 한계

| 요소 | 설명 | 문제점 |

|------|------|--------|

| **클라이언트** | 웹·모바일 UI가 직접 비즈니스 로직과 DB에 접근 | 로직 중복, 보안 취약 |

| **서버** | 하나의 애플리케이션이 모든 기능을 담당 | 코드베이스 비대해짐, 테스트 어려움 |

| **데이터베이스** | 단일 DB에 모든 테이블이 존재 | 스키마 변경 시 전체 서비스 영향 |

- **성능 병목**: 모든 요청이 하나의 서버를 통과해 DB를 직접 호출하므로 트래픽이 급증하면 응답 시간이 급격히 늘어납니다.

- **팀 협업 어려움**: 프론트엔드와 백엔드가 같은 코드베이스를 공유하면, 작은 변경에도 전체 빌드·배포가 필요합니다.

---

# # 2️⃣ 3계층 아키텍처로의 첫 발 – 모듈러 모놀리쓰 도입

## # 2-1. 모듈러 모놀리쓰란?

- **단일 배포 단위**이지만, 내부를 **독립적인 모듈**(도메인)로 나누어 관리합니다.

- 각 모듈은 자체 DB 스키마와 비즈니스 로직을 갖고, 인터페이스(예: 서비스 레이어)만 공개합니다.

## # 2-2. 마이그레이션 단계

1. **도메인 식별**: 기존 코드에서 사용자 관리, 주문 처리, 결제 등 기능별로 경계를 정의합니다.

2. **패키지 구조 재조정**: `src/users`, `src/orders` 등 폴더 단위로 모듈을 분리합니다.

3. **내부 API 정의**: 모듈 간 호출은 **인터페이스**(예: `UserService`)를 통해 수행해 의존성을 최소화합니다.

## # 2-3. 기대 효과

- **코드 가독성 향상**: 모듈당 파일 수가 감소해 유지보수가 쉬워집니다.

- **점진적 배포**: 하나의 모듈만 수정해도 전체 서비스 재배포 없이 독립적으로 롤아웃 가능.

---

# # 3️⃣ GraphQL로 프레젠테이션‑비즈니스 층 분리

## # 3-1. 왜 GraphQL인가?

- **클라이언트가 필요한 데이터만 요청** → 오버페치/언더페치 문제 해결.

- **단일 엔드포인트** → API 관리가 간편해지고, 버전 관리가 필요 없어집니다.

## # 3-2. GraphQL 도입 절차

| 단계 | 내용 |

|------|------|

| **스키마 설계** | 도메인 별 타입(`User`, `Order`)과 쿼리/뮤테이션 정의 |

| **리졸버 구현** | 각 타입에 대한 데이터 로직을 모듈러 서비스(`UserService`)와 연결 |

| **게이트웨이 구축** | Apollo Server 등으로 GraphQL 엔드포인트 제공, 인증·권한 부여 미들웨어 적용 |

| **프론트엔드 연동** | Apollo Client 등으로 기존 REST 호출을 GraphQL로 교체 |

## # 3-3. 마이그레이션 팁

- **점진적 전환**: 기존 REST API와 병행 운영하면서, 새로운 기능부터 GraphQL로 개발합니다.

- **데이터 로더(DataLoader) 활용**: N+1 문제를 방지해 성능을 최적화합니다.

---

# # 4️⃣ 실제 마이그레이션 사례 – 단계별 체크리스트

1. **현황 분석**

   - 현재 2계층 API 엔드포인트와 DB 스키마 문서화

2. **모듈 정의**

   - 핵심 도메인 3~5개 선정, 각각 별도 패키지로 분리

3. **GraphQL 스키마 초안 작성**

   - 주요 쿼리·뮤테이션을 정의하고, 리졸버와 연결

4. **CI/CD 파이프라인 업데이트**

   - 모듈 단위 테스트와 GraphQL 스키마 검증을 자동화

5. **점진적 배포 & 모니터링**

   - Canary 배포로 새로운 모듈과 GraphQL 엔드포인트를 검증

6. **레거시 정리**

   - 사용되지 않는 REST 엔드포인트와 DB 테이블을 차례로 제거

---

# # 결론 – 오늘부터 시작하는 3계층 전환

2계층에서 3계층 아키텍처로의 이동은 **성능 향상**, **보안 강화**, **팀 협업 효율**을 동시에 가져옵니다. 핵심은 **모듈러 모놀리쓰**로 코드를 정리하고, **GraphQL**을 통해 프레젠테이션 층을 깔끔히 분리하는 단계적 접근입니다.

> **지금 바로**

> 1. 프로젝트 루트에서 도메인 별 폴더 구조를 검토하고, 최소 1개의 모듈을 분리해 보세요.

> 2. 간단한 GraphQL 쿼리를 작성해 기존 REST API와 비교해 성능을 체감해 보세요.

작은 시도라도 꾸준히 이어가면, 곧 **안정적인 3계층 서비스**를 운영할 수 있습니다. 여러분의 마이그레이션 성공을 응원합니다! 🚀

---

**SEO 키워드**: 2계층 아키텍처, 3계층 아키텍처, GraphQL 마이그레이션