⚡
FastAPI 치트시트

Python 비동기(ASGI) REST API, Uvicorn 실행, Pydantic v2 모델 검증, 경로/쿼리 파라미터, 의존성 주입(Depends), SQLAlchemy 2.0 비동기 DB 연동, JWT 인증, 라우터 모듈화 및 프로덕션 배포 레퍼런스
#fastapi#python#pydantic#uvicorn#rest-api#backend#async#jwt#sqlalchemy#swagger최종 업데이트: 2026-10-05
FastAPI 치트시트 핵심 명령어 및 실전 가이드

## 1. 프로젝트 시작 & 구조 (Project Setup & Architecture)
```bash
# ⚡ [1] uv 패키지 매니저로 프로젝트 초기화 및 FastAPI 설치 (가장 권장)
uv init my-fastapi-app
cd my-fastapi-app
uv add "fastapi[standard]"   # FastAPI, Uvicorn, Pydantic, Email-validator 등 표준 번들 일괄 설치
uv add "sqlalchemy>=2.0" asyncpg aiosqlite pydantic-settings pyjwt passlib[bcrypt]

# 📦 [2] pip 또는 pipenv 환경 설치
pip install "fastapi[standard]" uvicorn
```
```text
my-fastapi-app/
├── app/
│   ├── main.py                  # FastAPI 인스턴스 초기화 & 미들웨어 & lifespan 진입점
│   ├── core/
│   │   ├── config.py            # Pydantic Settings 환경 변수 (.env) 로드
│   │   ├── database.py          # SQLAlchemy 2.0 비동기 엔진 & 세션 팩토리
│   │   └── security.py          # JWT 토큰 인코딩/디코딩 & 패스워드 해싱
│   ├── api/
│   │   ├── v1/
│   │   │   ├── api.py           # v1 라우터 통합 묶음 (APIRouter)
│   │   │   └── endpoints/
│   │   │       ├── auth.py      # 로그인, 토큰 발급 엔드포인트
│   │   │       ├── users.py     # 사용자 CRUD API
│   │   │       └── items.py     # 비즈니스 리소스 API
│   │   └── deps.py              # 전역 의존성 주입 (get_db, get_current_user)
│   ├── models/                  # SQLAlchemy ORM 테이블 매핑 클래스
│   │   ├── user.py
│   │   └── item.py
│   ├── schemas/                 # Pydantic v2 Request/Response DTO 스키마
│   │   ├── user.py
│   │   └── item.py
│   └── services/                # 비즈니스 비동기 처리 로직
├── tests/                       # pytest 및 TestClient 테스트 스위트
├── .env                         # 개발 환경 비밀키 및 DB 접속 URI
├── Dockerfile                   # 프로덕션 컨테이너 빌드 파일
└── pyproject.toml               # 의존성 및 프로젝트 메타데이터
```

---

## 2. 기본 앱 & 실행 (Basic App & Uvicorn CLI)
```python
# app/main.py
from fastapi import FastAPI, status

# FastAPI 인스턴스 생성 및 메타데이터 정의 (Swagger UI 자동 반영)
app = FastAPI(
    title="LuckyTech API Service",
    description="FastAPI 0.115+ 기반 고성능 비동기 REST API 백엔드",
    version="1.0.0",
    docs_url="/docs",      # Swagger UI 엔드포인트 (운영 환경에서는 None으로 비활성화 가능)
    redoc_url="/redoc",    # ReDoc 엔드포인트
    openapi_url="/api/v1/openapi.json"
)

# 헬스체크 & 기본 GET 엔드포인트
@app.get("/", tags=["Health"], summary="서비스 헬스체크")
async def health_check():
    return {"status": "healthy", "service": "LuckyTech API", "version": "1.0.0"}

# HTTP 메서드별 기본 라우팅 예시
@app.get("/items", tags=["Items"])
async def list_items():
    return [{"id": 1, "name": "Keyboard"}]

@app.post("/items", status_code=status.HTTP_201_CREATED, tags=["Items"])
async def create_item(payload: dict):
    return {"message": "Created", "data": payload}
```
```bash
# 🚀 Uvicorn 개발 서버 실행 명령어
# 1) FastAPI CLI (FastAPI 0.111+ 내장 표준 명령어)
fastapi dev app/main.py               # 개발 모드 (자동 리로드, 로컬 주소 바인딩)
fastapi run app/main.py --port 8000   # 프로덕션 모드

# 2) Uvicorn 직접 실행
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 📚 대화형 문서 브라우저 접속
# http://localhost:8000/docs   (Swagger UI - 테스트 실행 가능)
# http://localhost:8000/redoc  (ReDoc - 명세서 뷰어)
```

---

## 3. 요청 파라미터 (Path, Query & Header)
```python
from typing import Annotated
from fastapi import APIRouter, Path, Query, Header, Cookie, HTTPException, status

router = APIRouter(prefix="/products", tags=["Products"])

# [1] 경로 파라미터 (Path Parameter) + 유효성 검증
@router.get("/{product_id}")
async def get_product(
    product_id: Annotated[int, Path(title="상품 고유 ID", ge=1, le=999999, description="1 이상의 정수값")]
):
    return {"product_id": product_id, "name": f"Product-{product_id}"}

# [2] 쿼리 파라미터 (Query Parameter) + 기본값 + 선택적 필터
@router.get("/")
async def search_products(
    keyword: Annotated[str | None, Query(min_length=2, max_length=50, description="검색 키워드")] = None,
    page: Annotated[int, Query(ge=1, description="페이지 번호")] = 1,
    size: Annotated[int, Query(ge=1, le=100, description="페이지 당 항목 수")] = 20,
    tags: Annotated[list[str], Query(description="다중 태그 필터 (?tags=tech&tags=python)")] = []
):
    return {
        "page": page,
        "size": size,
        "keyword": keyword,
        "tags": tags,
        "items": []
    }

# [3] 요청 헤더 및 쿠키 수신
@router.get("/user-agent/check")
async def inspect_request(
    user_agent: Annotated[str | None, Header(description="클라이언트 User-Agent")] = None,
    x_custom_token: Annotated[str | None, Header(alias="X-Custom-Token")] = None,
    session_id: Annotated[str | None, Cookie()] = None
):
    return {
        "user_agent": user_agent,
        "token": x_custom_token,
        "has_session": session_id is not None
    }
```

---

## 4. Pydantic v2 요청 & 응답 모델 (Request Body & Validation)
```python
from datetime import datetime
from pydantic import BaseModel, Field, EmailStr, field_validator, model_validator, ConfigDict

# [1] 기본 요청 DTO 스키마
class UserCreateRequest(BaseModel):
    # Field: 기본값, 제약조건, 메타데이터 설정
    username: str = Field(..., min_length=3, max_length=30, pattern=r"^[a-zA-Z0-9_-]+$", description="알파벳, 숫자, _, - 허용")
    email: EmailStr = Field(..., description="유효한 이메일 주소")
    password: str = Field(..., min_length=8, description="8자 이상의 비밀번호")
    confirm_password: str = Field(..., min_length=8)
    age: int | None = Field(default=None, ge=1, le=150)
    is_active: bool = Field(default=True)

    # 개별 필드 유효성 검증 (@field_validator)
    @field_validator("username")
    @classmethod
    def validate_username(cls, v: str) -> str:
        forbidden = ["admin", "root", "system"]
        if v.lower() in forbidden:
            raise ValueError(f"'{v}'는 예약어로 사용할 수 없습니다.")
        return v.lower()

    # 모델 전체 단위 검증 (비밀번호 일치 확인 등)
    @model_validator(mode="after")
    def verify_password_match(self):
        if self.password != self.confirm_password:
            raise ValueError("비밀번호와 비밀번호 확인이 일치하지 않습니다.")
        return self

# [2] 응답 DTO 스키마 (민감한 비밀번호 제외 및 ORM 호환 설정)
class UserResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True) # SQLAlchemy 모델 객체를 Pydantic 모델로 자동 변환 (v1의 orm_mode=True)

    id: int
    username: str
    email: EmailStr
    age: int | None
    is_active: bool
    created_at: datetime

# [3] 엔드포인트 적용 (자동 역직렬화 & 유효성 검증)
from fastapi import APIRouter
user_router = APIRouter(prefix="/users", tags=["Users"])

@user_router.post("/", response_model=UserResponse, status_code=201)
async def register_user(payload: UserCreateRequest):
    # payload 유효성 검증 실패 시 FastAPI가 자동으로 422 Unprocessable Entity 반환
    return {
        "id": 101,
        "username": payload.username,
        "email": payload.email,
        "age": payload.age,
        "is_active": payload.is_active,
        "created_at": datetime.now()
    }
```

---

## 5. 응답 모델 & 상태 코드 & 예외 처리 (Response & Error Handling)
```python
from fastapi import FastAPI, HTTPException, status, Request
from fastapi.responses import JSONResponse, StreamingResponse, RedirectResponse
from pydantic import BaseModel

app = FastAPI()

# [1] 표준 HTTPException 발생
@app.get("/items/{item_id}")
async def read_item(item_id: int):
    if item_id == 404:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail={"error_code": "ITEM_NOT_FOUND", "message": f"ID {item_id} 상품이 존재하지 않습니다."},
            headers={"X-Error-Reason": "Resource Missing"}
        )
    return {"id": item_id, "name": "Super Item"}

# [2] 커스텀 비즈니스 예외 & 전역 핸들러 등록
class BusinessException(Exception):
    def __init__(self, code: str, message: str, status_code: int = 400):
        self.code = code
        self.message = message
        self.status_code = status_code

@app.exception_handler(BusinessException)
async def business_exception_handler(request: Request, exc: BusinessException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "success": False,
            "code": exc.code,
            "message": exc.message,
            "path": str(request.url.path)
        }
    )

@app.post("/orders/pay")
async def process_payment(amount: int):
    if amount <= 0:
        raise BusinessException(code="INVALID_PAYMENT_AMOUNT", message="결제 금액은 0원보다 커야 합니다.")
    return {"success": True, "amount": amount}

# [3] 파일 스트리밍 응답 (대용량 로그 or CSV 내보내기)
async def fake_csv_generator():
    yield "id,username,score\n"
    for i in range(1, 100):
        yield f"{i},user_{i},{i*10}\n"

@app.get("/export/csv")
async def export_csv():
    return StreamingResponse(
        fake_csv_generator(),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=report.csv"}
    )
```

---

## 6. 의존성 주입 시스템 (Dependency Injection: Depends)
```python
from typing import Annotated
from fastapi import Depends, Header, HTTPException, status

# [1] 단순 함수 기반 의존성 (공통 헤더 검증)
async def verify_api_key(x_api_key: Annotated[str | None, Header()] = None):
    if not x_api_key or x_api_key != "secret-lucky-token":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="유효하지 않거나 누락된 API 키입니다."
        )
    return x_api_key

# [2] 클래스 기반 공통 쿼리 페이지네이션 의존성
class PaginationParams:
    def __init__(self, page: int = 1, size: int = 20):
        self.page = max(1, page)
        self.size = min(max(1, size), 100)
        self.offset = (self.page - 1) * self.size

# [3] yield 기반 리소스 라이프사이클 의존성 (DB 연결/반환 등에 활용)
async def get_db_session():
    # 1. 진입 시: 리소스 할당
    print("⚡ [DB] 비동기 세션 연결 생성")
    session = {"connected": True}
    try:
        yield session  # 엔드포인트 핸들러로 세션 객체 전달
    finally:
        # 2. 핸들러 완료 또는 예외 발생 시: 리소스 안전 해제
        print("🔒 [DB] 비동기 세션 커밋/롤백 후 종료")

# [4] 엔드포인트에서 의존성 주입 활용
@app.get("/secure-data")
async def get_secure_data(
    api_key: Annotated[str, Depends(verify_api_key)],
    paging: Annotated[PaginationParams, Depends()],
    db: Annotated[dict, Depends(get_db_session)]
):
    return {
        "status": "authorized",
        "page": paging.page,
        "offset": paging.offset,
        "limit": paging.size
    }
```

---

## 7. SQLAlchemy 2.0 비동기 DB 연동 (Async Database ORM)
```python
# app/core/database.py
from collections.abc import AsyncGenerator
from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from sqlalchemy import String, Integer, DateTime, func, select

DATABASE_URL = "sqlite+aiosqlite:///./test.db"
# PostgreSQL 비동기 접속 시: "postgresql+asyncpg://user:password@localhost:5432/mydb"

# 1. 비동기 엔진 생성
engine = create_async_engine(
    DATABASE_URL,
    echo=False,           # 프로덕션에서는 SQL 로그를 끄고, 디버그 시 True
    pool_size=10,         # 커넥션 풀 크기 (SQLite는 무시됨)
    max_overflow=20
)

# 2. 세션 팩토리 생성
AsyncSessionLocal = async_sessionmaker(
    bind=engine,
    class_=AsyncSession,
    expire_on_commit=False,
    autoflush=False
)

# 3. Base 엔티티 모델 선언
class Base(DeclarativeBase):
    pass

class Item(Base):
    __tablename__ = "items"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    title: Mapped[str] = mapped_column(String(100), nullable=False)
    price: Mapped[int] = mapped_column(Integer, default=0)
    created_at: Mapped[DateTime] = mapped_column(DateTime, server_default=func.now())

# 4. FastAPI용 세션 주입 의존성 함수
async def get_async_db() -> AsyncGenerator[AsyncSession, None]:
    async with AsyncSessionLocal() as session:
        try:
            yield session
            await session.commit()   # 정상 완료 시 자동 커밋
        except Exception:
            await session.rollback() # 에러 발생 시 자동 롤백
            raise
```
```python
# 엔드포인트에서 비동기 DB 쿼리 실행
from fastapi import APIRouter, Depends
from typing import Annotated

db_router = APIRouter(prefix="/db-items", tags=["Database Items"])

@db_router.get("/")
async def list_items(db: Annotated[AsyncSession, Depends(get_async_db)]):
    stmt = select(Item).order_by(Item.id.desc()).limit(10)
    result = await db.execute(stmt)
    items = result.scalars().all()
    return [{"id": item.id, "title": item.title, "price": item.price} for item in items]

@db_router.post("/")
async def create_item(title: str, price: int, db: Annotated[AsyncSession, Depends(get_async_db)]):
    new_item = Item(title=title, price=price)
    db.add(new_item)
    await db.flush()  # DB에 전송하여 new_item.id 채번
    await db.refresh(new_item)
    return {"id": new_item.id, "title": new_item.title}
```

---

## 8. 인증 & 보안 (OAuth2 & JWT Token)
```python
# app/core/security.py
from datetime import datetime, timedelta, timezone
from typing import Annotated
import jwt
from passlib.context import CryptContext
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from pydantic import BaseModel

SECRET_KEY = "your-super-secret-jwt-key-change-in-production"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 60

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login") # Swagger UI에 자물쇠 버튼 자동 활성화

def hash_password(password: str) -> str:
    return pwd_context.hash(password)

def verify_password(plain_password: str, hashed_password: str) -> bool:
    return pwd_context.verify(plain_password, hashed_password)

def create_access_token(data: dict, expires_delta: timedelta | None = None) -> str:
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + (expires_delta or timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES))
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

# 토큰 페이로드 검증 및 사용자 식별 의존성
async def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="자격 증명을 확인할 수 없습니다.",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str | None = payload.get("sub")
        if username is None:
            raise credentials_exception
        return {"username": username, "role": payload.get("role", "user")}
    except jwt.PyJWTError:
        raise credentials_exception
```
```python
# app/api/v1/endpoints/auth.py
from fastapi import APIRouter

auth_router = APIRouter(prefix="/auth", tags=["Auth"])

# 1. 로그인 및 JWT 발급 엔드포인트 (Swagger 양식 호환)
@auth_router.post("/login")
async def login(form_data: Annotated[OAuth2PasswordRequestForm, Depends()]):
    # 실제 환경: DB에서 form_data.username 조회 및 verify_password 검증
    if form_data.username != "admin" or form_data.password != "password123":
        raise HTTPException(status_code=400, detail="아이디 또는 비밀번호가 잘못되었습니다.")

    access_token = create_access_token(data={"sub": form_data.username, "role": "admin"})
    return {"access_token": access_token, "token_type": "bearer"}

# 2. 인증된 사용자 전용 엔드포인트
@auth_router.get("/me")
async def get_my_profile(current_user: Annotated[dict, Depends(get_current_user)]):
    return {"user": current_user}
```

---

## 9. 미들웨어 & CORS & Lifespan 수명주기
```python
import time
from contextlib import asynccontextmanager
from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware

# [1] 현대적 비동기 수명주기 매니저 (startup / shutdown 이벤트 대체)
@asynccontextmanager
async def lifespan(app: FastAPI):
    # 앱 구동(Startup) 시 실행: DB 커넥션 풀 초기화, 캐시 워밍업
    print("🚀 [Startup] 데이터베이스 커넥션 풀 초기화 완료")
    yield
    # 앱 종료(Shutdown) 시 실행: 커넥션 풀 종료, 외부 리소스 정리
    print("🛑 [Shutdown] 리소스 안전 해제 및 서버 정상 종료")

app = FastAPI(lifespan=lifespan)

# [2] CORS(Cross-Origin Resource Sharing) 설정
app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:3000",
        "https://myapp.luckytech.com"
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "PATCH"],
    allow_headers=["*"],
    expose_headers=["X-Process-Time"]
)

# [3] 응답 압축 GZip 미들웨어
app.add_middleware(GZipMiddleware, minimum_size=1000)

# [4] 커스텀 HTTP 실행 시간 측정 미들웨어
@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.perf_counter()
    response = await call_next(request)
    process_time = time.perf_counter() - start_time
    response.headers["X-Process-Time"] = f"{process_time * 1000:.2f}ms"
    return response
```

---

## 10. APIRouter 모듈화 & 백그라운드 태스크 (Modularization & Background Tasks)
```python
# app/api/v1/endpoints/notifications.py
from fastapi import APIRouter, BackgroundTasks
import asyncio

router = APIRouter(prefix="/notify", tags=["Notifications"])

# 무거운 비동기 작업 함수 (이메일 발송, 감사 로그 전송, 통계 집계 등)
def send_email_task(email: str, message: str):
    # 실제로는 smtplib, aiosmtplib 또는 Celery/Redis Queue 호출
    print(f"📧 [Email Sent] 수신자: {email}, 본문: {message}")

async def write_audit_log(user_id: int, action: str):
    await asyncio.sleep(1) # 비동기 I/O 시뮬레이션
    print(f"📝 [Audit Log] User {user_id} - Action: {action}")

# BackgroundTasks 주입
@router.post("/send")
async def trigger_notification(
    email: str,
    background_tasks: BackgroundTasks
):
    # 1. 즉시 HTTP 202 Accepted 응답 반환
    # 2. 클라이언트 응답 전송 완료 후 백그라운드에서 작업 순차 실행
    background_tasks.add_task(send_email_task, email=email, message="회원가입을 환영합니다!")
    background_tasks.add_task(write_audit_log, user_id=42, action="SEND_WELCOME_EMAIL")
    
    return {"status": "accepted", "message": "알림 작업이 백그라운드에 등록되었습니다."}
```
```python
# app/main.py 에서 라우터 통합 등록
from fastapi import FastAPI
from app.api.v1.endpoints import auth, users, notifications

app = FastAPI()

# API 버전별 접두사(prefix) 및 태그 계층 분리
api_v1_router = APIRouter(prefix="/api/v1")
api_v1_router.include_router(auth.auth_router)
api_v1_router.include_router(notifications.router)

app.include_router(api_v1_router)
```

---

## 11. 테스트 & 프로덕션 배포 (Testing & Docker Deployment)
```python
# tests/test_api.py - FastAPI 공식 TestClient (HTTPX 기반)
import pytest
from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_health_check():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json()["status"] == "healthy"

def test_create_user_validation_error():
    # 필수 필드 누락 시 Pydantic 422 상태 코드 반환 확인
    response = client.post("/api/v1/users/", json={"username": "ab"}) # min_length=3 위반
    assert response.status_code == 422
    assert "detail" in response.json()
```
```dockerfile
# Dockerfile - 멀티 스테이지 프로덕션 경량 컨테이너
FROM python:3.12-slim AS builder

WORKDIR /app
RUN pip install --no-cache-dir uv

COPY pyproject.toml .
RUN uv pip install --system --no-cache "fastapi[standard]" "uvicorn[standard]"

# 최종 런타임 이미지
FROM python:3.12-slim

WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY ./app ./app

# 보안을 위한 비-루트 사용자 실행
RUN useradd -m appuser && chown -R appuser:appuser /app
USER appuser

EXPOSE 8000

# Gunicorn + UvicornWorker를 활용한 멀티 프로세스 고성능 프로덕션 실행
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4", "--proxy-headers"]
```
💬
FastAPI 치트시트

의견 및 질문

댓글 수정

댓글 삭제
