CLAUDE.md — FastAPI REST API

Overview

Python FastAPI 기반 REST API 서버. SQLAlchemy ORM + PostgreSQL.

Commands

uvicorn app.main:app --reload   # 개발 서버
pytest                           # 테스트 실행
alembic upgrade head             # DB 마이그레이션
docker compose up                # 전체 스택 실행

Conventions

• 파일명: snake_case
• 클래스: PascalCase
• 라우터 파일: app/routers/{resource}.py
• 스키마 파일: app/schemas/{resource}.py
• 모델 파일: app/models/{resource}.py
• 응답 형식: {"data": ..., "message": "...", "status": "success"}

Architecture

app/
  main.py              # FastAPI 앱 + 미들웨어 설정
  config.py            # 환경변수 (pydantic-settings)
  routers/             # API 엔드포인트
  models/              # SQLAlchemy 모델
  schemas/             # Pydantic 스키마
  services/            # 비즈니스 로직
  middleware/           # 인증, 로깅, CORS
tests/
  conftest.py          # pytest fixtures
  test_routers/        # 라우터별 테스트

Error Handling

• HTTPException으로 API 에러 반환
• 커스텀 예외 클래스: app/exceptions.py
• 에러 코드 체계: AUTH_001, USER_001, ...

Testing

• pytest + httpx.AsyncClient 사용
• 테스트 DB: SQLite in-memory
• 최소 커버리지: 80%