실무형 프로젝트 구조 예시 (Feature-First + DDD/Clean)

 

실무에서 대규모 NestJS 애플리케이션을 구축할 때는 단순히 controller-service-module로 나누는 계층형 구조를 넘어, 도메인 중심 설계(Domain-Driven Design, DDD) 또는 클린 아키텍처의 개념을 NestJS의 모듈(Module) 시스템에 통합하여 구조화하는 것이 일반적입니다.

이러한 접근 방식은 기능(Feature) 또는 도메인(Domain)을 기준으로 코드를 분리하여 확장성과 유지보수성을 극대화합니다.

 

728x90

1. 프로젝트 폴더 구조 (예시)

src/
├── app.module.ts            # 루트 모듈
├── main.ts                  # 애플리케이션 진입점
│
├── common/                  # 1. 공통 및 공유 자원 (Shared)
│   ├── filters/             # HTTP 예외 필터
│   ├── guards/              # 공통 가드 (예: JwtAuthGuard)
│   ├── interceptors/        # 공통 인터셉터
│   └── pipes/               # 공통 파이프
│
├── core/                    # 2. 핵심 서비스 및 설정
│   ├── config/              # 환경 설정 (ConfigModule, Joi 스키마)
│   └── database/            # DB 연결 및 TypeOrm 설정 등
│
├── modules/                 # 3. 도메인/기능별 모듈 (Feature Modules)
│   ├── auth/                # 인증 모듈
│   │   ├── auth.module.ts
│   │   └── ...
│   │
│   └── users/               # 사용자 도메인 모듈 (Clean/DDD 적용)
│       ├── users.module.ts
│       ├── application/     # Application Layer (Use Cases/Services)
│       │   ├── use-cases/   # Use Case (비즈니스 흐름 정의)
│       │   └── users.service.ts
│       ├── domain/          # Domain Layer (핵심 비즈니스, 프레임워크 독립적)
│       │   ├── entities/    # Entity (도메인 모델)
│       │   └── interfaces/  # Repository 인터페이스 정의 (계약)
│       └── infrastructure/  # Infrastructure Layer (외부 연동)
│           ├── controllers/ # HTTP 진입점 (프레젠테이션)
│           ├── repositories/ # Repository 실제 구현 (DB/ORM 의존성)
│           └── dto/         # DTO, VO (입출력 모델)
│
└── ...

728x90

2. 구조의 핵심 원칙

① 도메인/기능 중심 분리 (modules/)

• 코드를 user 관련 모든 로직(controller, service, repository, entity)을 users 폴더 안에 모아둡니다.
• 이는 프로젝트 규모가 커질수록 파일 찾기나 유지보수를 훨씬 쉽게 만듭니다.

② 클린 아키텍처/DDD 계층 적용 (users/ 내부)

• Domain (안쪽): 가장 중요한 곳이며, DB나 NestJS 프레임워크와 독립적입니다. 여기에 Entities와 Repository Interface (계약)가 위치합니다.
• Application (중간): Use Cases 또는 Service가 위치합니다. 이는 도메인 레이어의 Entity를 사용하고 비즈니스 로직을 실행합니다.
• Infrastructure (바깥쪽): 외부 요소(HTTP, DB, 파일 시스템)와 연결하는 영역입니다.
  • Controllers (HTTP 처리)와 Repositories (인터페이스를 구현하여 DB와 통신)가 이곳에 위치합니다.
  • 의존성 역전: infrastructure의 Repository 구현체는 domain의 Repository 인터페이스에 의존합니다. (바깥쪽이 안쪽을 알도록 설계)

③ 공통 모듈 분리 (common/, core/)

• common: 모든 기능에서 재사용되는 HTTP 관련 요소(Guard, Filter, Pipe 등)를 분리합니다.
• core: 애플리케이션의 핵심 인프라(DB 설정, 글로벌 설정)를 관리하여 다른 기능 모듈이 깔끔하게 유지되도록 합니다.

이러한 구조는 초기에는 설정이 복잡할 수 있으나, 프로젝트의 규모가 커지고 여러 개발자가 협업할 때 관심사의 분리를 명확하게 해주어 안정적인 확장을 가능하게 합니다.

---