## 기본 FastAPI 프로젝트 구조 (표준형)
### 📁 Project layout
```
app/
├── main.py # 앱 엔트리포인트
├── api/ # 라우터 모음
│ ├── deps.py # 공통 의존성
│ ├── v1/ # API 버저닝
│ │ ├── endpoints/ # 엔드포인트 단위로 파일 분리
│ │ │ ├── users.py
│ │ │ ├── auth.py
│ │ │ └── items.py
│ │ └── router.py # v1 라우터 통합
│ └── router.py
│
├── core/ # 설정, 환경
│ ├── config.py
│ ├── security.py
│ └── settings.py
│
├── models/ # ORM 모델
├── schemas/ # Pydantic 모델
├── services/ # 비즈니스 로직
│ ├── user_service.py
│ ├── auth_service.py
│ └── payment_service.py
│
├── repository/ # DB 접근 계층
├── db/ # DB 세션 관리
│ ├── session.py
│ └── base.py
│
├── middlewares/
├── utils/
└── tests/
```
---
# ✅ main.py (최소 예시)
```python
from fastapi import FastAPI
from app.api.router import api_router
app = FastAPI(title="My API Server")
app.include_router(api_router, prefix="/api")
@app.get("/")
def health():
return {"status": "OK"}
```
---
# ✅ api/router.py
```python
from fastapi import APIRouter
from app.api.v1.router import router as v1_router
api_router = APIRouter()
api_router.include_router(v1_router, prefix="/v1")
```
---
# ✅ api/v1/router.py
```python
from fastapi import APIRouter
from app.api.v1.endpoints import users, auth
router = APIRouter()
router.include_router(users.router, prefix="/users", tags=["Users"])
router.include_router(auth.router, prefix="/auth", tags=["Auth"])
```
---
# ✅ endpoint 예시
```python
# app/api/v1/endpoints/users.py
from fastapi import APIRouter, Depends
from app.schemas.user import UserCreate
from app.services.user_service import create_user
router = APIRouter()
@router.post("/")
def create(user: UserCreate):
return create_user(user)
```
---
# ✅ 역할별 디렉토리 개념 요약
|폴더|역할|
|---|---|
|api|HTTP 인터페이스|
|services|비즈니스 로직|
|repository|DB 접근|
|schemas|요청/응답 모델|
|models|ORM 모델|
|db|DB 세션|
|core|설정 관리|
|middlewares|인증/로깅|
|utils|공통 기능|
---
# ✅ 대규모 프로젝트 구조 (도메인 중심 설계)
많은 팀에서 실제로 쓰는 방식입니다.
```
app/
├── domain/
│ ├── user/
│ │ ├── model.py
│ │ ├── schema.py
│ │ ├── service.py
│ │ ├── repository.py
│ │ └── router.py
│ └── payment/
│
├── core/
├── db/
├── main.py
└── tests/
```
### → 장점:
- 도메인 단위 개발
- 파일 수가 많아져도 관리 쉬움
- 팀 협업 최적화
---
# ✅ 실전에서 꼭 들어가는 구성요소
### 1️⃣ 환경 변수 관리
```python
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
DB_URL: str
SECRET_KEY: str
settings = Settings()
```
---
### 2️⃣ DB 세션 관리
```python
from sqlalchemy.orm import sessionmaker
SessionLocal = sessionmaker(bind=engine)
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
```
---
### 3️⃣ 서비스 분리 원칙
🚫 controller에서 직접 DB query
✅ service → repository → model
---
# ✅ 개발 시 꼭 지키면 좋은 규칙
|항목|이유|
|---|---|
|Router와 logic 분리|테스트 쉬움|
|Schema 필수|Validation 자동|
|Service 계층|유지보수 핵심|
|Versioning|API 깨짐 방지|
|env 분리|안전성|
|main.py는 가볍게|config 역할만|
---
# ✅ 추천 추가 세팅
|목적|라이브러리|
|---|---|
|ORM|SQLAlchemy / SQLModel|
|Migration|Alembic|
|Auth|fastapi-users / jose|
|Validation|Pydantic|
|Async|asyncpg|
|Logging|loguru|
|Docs|swagger / redoc|
---
# ✅ FastAPI 프로젝트 템플릿 추천
- **tiangolo/full-stack-fastapi-postgresql**
- **fastapi-best-practice**
- **fastapi-realworld-example-app**
- **Netflix Dispatch 스타일 구조**