NestJS REST API 폴더 구조 추천

NestJS 프로젝트의 폴더 구조는 애플리케이션의 규모와 복잡성에 따라 달라질 수 있지만, 일반적으로는 모듈 기반(Feature-based) 구조를 채택하는 것이 가장 유지보수와 확장성 면에서 좋은 베스트 프랙티스로 권장됩니다.

---

1. 모듈 기반 폴더 구조 (Feature-based)

애플리케이션의 각 도메인이나 기능(Feature)을 하나의 모듈로 묶는 방식입니다. 이 구조는 규모가 커질수록 명확한 관심사 분리(Separation of Concerns)를 제공합니다.

src/
├── app.module.ts       // Root Module
├── main.ts             // Entry point
│
├── common/             // 공통/전역(Global)에서 사용되는 요소
│   ├── filters/        // 전역 예외 필터
│   ├── guards/         // 전역 가드 (인증/권한)
│   ├── interceptors/   // 전역 인터셉터 (Response Wrapping, Logging 등)
│   ├── pipes/          // 전역 파이프 (유효성 검사, 변환 등)
│   └── dtos/           // 공통 DTO (예: Pagination, Success/Error response)
│
├── auth/               // 인증(Auth) 모듈
│   ├── auth.controller.ts
│   ├── auth.service.ts
│   ├── auth.module.ts
│   └── dtos/
│       ├── login.dto.ts
│       └── register.dto.ts
│
├── users/              // 사용자(Users) 모듈
│   ├── users.controller.ts
│   ├── users.service.ts
│   ├── users.module.ts
│   ├── entities/       // TypeORM 엔터티 (선택 사항, 별도 폴더 가능)
│   │   └── user.entity.ts
│   └── dtos/           // 사용자 관련 DTO
│       ├── create-user.dto.ts
│       └── update-user.dto.ts
│
└── products/           // 제품(Products) 모듈
    ├── products.controller.ts
    ├── products.service.ts
    ├── products.module.ts
    └── dtos/
        └── create-product.dto.ts

• src/: 모든 소스 코드가 위치하는 루트 디렉토리입니다.
• main.ts / app.module.ts: 애플리케이션의 시작점 및 루트 모듈 파일입니다.
• common/: 애플리케이션의 여러 모듈에서 재사용되는 전역적인 코드를 모읍니다. (예: 커스텀 데코레이터, 유틸리티 함수, 전역 설정)
• [feature]/ (예: users, auth): 각 기능별/도메인별 모듈 디렉토리입니다. 이 안에 해당 모듈의 Controller, Service, Module, DTO, Entity 등을 함께 둡니다.

---

728x90

2. 세부 구성 요소 폴더 (Component-based)

일부 개발팀에서는 기능별 분리(Feature-based) 내에서도 각 구성 요소별(Component-based)로 세분화하여 폴더를 구성하기도 합니다.

src/
├── modules/
│   ├── auth/
│   ├── users/
│   └── products/
│
├── controllers/          // 모든 모듈의 Controller 파일만 모음 (비추천)
├── services/             // 모든 모듈의 Service 파일만 모음 (비추천)
│
├── dtos/                 // 모든 DTO 파일만 모음
│   ├── users/
│   └── products/
│
└── entities/             // 모든 Entity 파일만 모음

✅ 조언:

모든 모듈의 Controller, Service 등을 각각 controllers/, services/ 폴더에 모으는 방식은 프로젝트 규모가 커질수록 관련 파일을 찾기 어렵고 기능 간의 경계가 모호해지기 때문에 권장되지 않습니다.

모듈 기반(Feature-based) 구조를 채택하고, 그 안에서 필요하다면 dtos/나 entities/처럼 구성 요소별로 폴더를 한 단계 더 구성하는 것이 가장 효율적입니다.

---

728x90

💡 NestJS 폴더 구조 요약

폴더	역할	예시
Feature 폴더	특정 도메인/기능 관련 모든 파일 (핵심)	users/, products/
common/	여러 Feature에서 재사용되는 전역 코드/로직	filters/, guards/, utils/
[feature]/dtos/	해당 Feature의 Request/Response 데이터 스키마	create-user.dto.ts
[feature]/entities/	해당 Feature의 DB 엔터티 정의	product.entity.ts