📁효율적인 개발을 위한 디렉토리 설계 가이드(FastAPI+Next.js)

이번 포스팅에서는 저의 로컬 환경 기준으로 구성한 프로젝트 구조를 바탕으로 각 디렉토리와 파일의 역할을 상세히 설명하겠습니다. 프로젝트 디렉토리 구조에는 정확한 정답은 없지만 올바른 설계 원칙을 이해하면 개발에 큰 도움이 됩니다.

---

📑 목차

1. 🛠 프로젝트 디렉토리 구조를 나누는 이유
2. 🖥 백엔드 디렉토리 구조와 의미
3. 🌐 프론트엔드 디렉토리 구조와 의미
4. 🐳 공통 설정 파일과 Docker
5. ✅ 프로젝트 구조의 장점
6. 📸 전체 프로젝트 구조 예시
7. 📌 참고

---

🛠 프로젝트 디렉토리 구조를 나누는 이유

대규모 애플리케이션일수록 디렉토리 구조를 체계적으로 나누는 것이 필수입니다.
주요 이유는 다음과 같습니다.

• 유지보수 용이성: 기능별로 디렉토리를 나누면 코드가 어디에 있는지 명확히 알 수 있어 수정이 쉽습니다.
• 협업 효율성: 백엔드, 프론트엔드, 테스트 코드를 분리하면 여러 개발자가 동시에 작업하기 편리합니다.
• 재사용성 향상: 공통 라이브러리, 컴포넌트, 모델 등을 구조화하면 재사용이 용이합니다.
• CI/CD 연계 편리: Docker, Git, 테스트 자동화 등과 연계할 때 구조화된 프로젝트가 파이프라인 설정에 유리합니다.

즉, 디렉토리 구조는 단순히 코드 정리를 위한 것이 아니라 개발 생산성과 유지보수 효율성을 높이는 설계 전략입니다.

---

🖥 백엔드 디렉토리 구조와 의미

백엔드 디렉토리는 FastAPI를 기준으로 다음과 같이 구성됩니다.

backend/
├── models/
├── routes/
├── schemas/
├── tests/
├── db.py
├── main.py
└── requirements.txt

📦 models/

• 데이터베이스 테이블 구조를 정의하는 ORM 모델 파일들을 모아둔 디렉토리입니다.
• 예: 사용자 테이블(User), 자산 테이블(Asset) 등
• 장점: DB 구조 변경 시 이 디렉토리만 수정하면 되어 관리가 편리합니다.

🔗 routes/

• API 엔드포인트를 정의하는 라우터 파일을 모아둡니다.
• 각 기능별로 파일을 나누어 REST API를 구현합니다.
• 예: user.py, asset.py, auth.py
• 장점: 기능별 API 관리가 용이하고, 테스트 및 유지보수가 쉽습니다.

📝 schemas/

• Pydantic을 활용한 데이터 검증 및 직렬화 스키마를 정의합니다.
• 예: UserCreate, AssetRead 등
• 장점: 데이터 검증을 중앙화하여 코드 안정성을 확보합니다.

🧪 tests/

• 단위 테스트와 통합 테스트 코드를 저장하는 디렉토리입니다.
• pytest 등으로 자동화된 테스트를 수행할 수 있습니다.
• 장점: 안정적인 코드 배포를 지원하고, 리팩토링 시 오류를 최소화합니다.

⚙️ db.py, models.py, main.py

• db.py: 데이터베이스 연결 설정 파일
• models.py: 모델을 통합 관리하거나 관계 정의
• main.py: FastAPI 앱 실행 진입점, 라우터 등록 및 서버 실행
• 장점: 핵심 설정과 진입점을 한눈에 파악할 수 있어 초기화와 배포가 용이합니다.

📃 requirements.txt

• 프로젝트에 필요한 Python 패키지 목록을 기록합니다.
• 장점: 개발 환경 일관성 유지와 배포 자동화에 필수입니다.

---

🌐 프론트엔드 디렉토리 구조와 의미

프론트엔드는 Next.js 기반으로 다음과 같이 구성됩니다.

frontend/
├── pages/
├── components/
├── lib/
├── styles/
├── package.json
└── tsconfig.json

📄 pages/

• Next.js 라우팅 기준 디렉토리로, URL과 페이지가 매핑됩니다.
• 예: /login → pages/login.tsx
• 장점: 파일 기반 라우팅으로 페이지 추가가 간단합니다.

🧩 components/

• UI 컴포넌트 모음 디렉토리
• 버튼, 모달, 폼, 레이아웃 등 재사용 가능한 컴포넌트를 저장합니다.
• 장점: UI 코드 재사용과 유지보수가 쉬워집니다.

🛠 lib/

• 공통 라이브러리나 유틸리티 함수를 모아둡니다.
• 예: Axios API 호출 모듈, 인증 함수, 포맷팅 유틸
• 장점: 공통 코드 집중 관리로 코드 중복 방지

🎨 styles/

• CSS, SCSS 또는 Tailwind 커스터마이징 파일
• 전역 스타일과 페이지별 스타일을 구분하여 관리
• 장점: 일관된 디자인 유지와 유지보수 편리

📦 package.json & tsconfig.json

• package.json: 프로젝트 종속성, 스크립트, 빌드 명령 정의
• tsconfig.json: TypeScript 설정 파일
• 장점: 프로젝트 빌드 및 개발 환경 통일성 확보

---

🐳 공통 설정 파일과 Docker

🐙 docker-compose.yml

• 백엔드(FastAPI), 프론트엔드(Next.js), DB(PostgreSQL)를 통합 실행
• 서비스별 포트, 볼륨, 네트워크 설정 가능
• 장점: 로컬 환경, 테스트 환경, 배포 환경을 동일하게 유지 가능

🔧 package-lock.json & 루트 package.json

• Node.js 패키지 버전 고정 및 종속성 관리
• 장점: 팀 개발 시 동일한 의존성 환경 유지

---

✅ 프로젝트 구조의 장점

1. 가독성 향상: 기능별로 코드가 분리되어 개발자가 쉽게 이해
2. 유지보수 용이: 기능 확장, 버그 수정, 리팩토링 시 영향 범위 최소화
3. 협업 최적화: FE/BE/DB 팀 간 작업 충돌 최소화
4. 배포 및 테스트 편리: Docker, CI/CD 연동이 수월
5. 재사용성 확보: 컴포넌트, 모듈, 유틸리티 재사용 가능

---

📸 전체 프로젝트 구조 예시

예시 구조:

PORTFOLIO-APP/
├── backend/
│   ├── models/
│   ├── routes/
│   ├── schemas/
│   ├── tests/
│   ├── db.py
│   ├── main.py
│   ├── models.py
│   └── requirements.txt
├── frontend/
│   ├── pages/
│   ├── components/
│   ├── lib/
│   ├── styles/
│   ├── package.json
│   └── tsconfig.json
├── docker-compose.yml
├── package-lock.json
└── package.json

---

📌 참고

• Next.js 공식 문서
• FastAPI 공식 문서
• PostgreSQL 공식 문서