python-backend-fastapi

Python Backend Development Guide (FastAPI)

Python FastAPI 백엔드 개발을 위한 종합 가이드.

적용 시점

다음 작업 시 이 가이드를 참조:

• Python 파일 생성/수정
• FastAPI 엔드포인트 작성
• Pydantic 스키마 정의
• 데이터베이스 모델 설계
• 비동기 함수 작성

---

핵심 원칙

1. 파일/모듈 책임 분리 ⚠️ CRITICAL

• 하드 제한 줄 수가 아니라 기능/책임 단위로 모듈을 나눈다
• 한 파일이 여러 유스케이스, 계층, 엔티티 책임을 섞으면 분리한다
• 대형 파일은 자동 실패가 아니라 분리 검토 신호로만 사용한다

2. 함수 크기 제한

• 최대 50줄
• 권장 20줄 이하
• 하나의 함수는 하나의 작업만

3. 모듈화 & 재사용성

• 공통 로직은 utils/ 또는 core/로 분리
• 비즈니스 로직은 서비스 레이어에
• 데이터 접근은 리포지토리 패턴

---

프로젝트 구조

backend/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI 앱 초기화 (< 100줄)
│   ├── api/                    # API 엔드포인트
│   │   ├── __init__.py
│   │   ├── deps.py            # 의존성 주입
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── auth.py        # 인증 API (< 300줄)
│   │       ├── users.py       # 사용자 API (< 300줄)
│   │       └── forms.py       # 폼 빌더 API (< 400줄)
│   ├── core/                   # 핵심 설정 및 보안
│   │   ├── config.py          # 환경 설정 (< 200줄)
│   │   ├── security.py        # JWT, 암호화 (< 300줄)
│   │   └── database.py        # DB 연결 (< 100줄)
│   ├── models/                 # SQLAlchemy 모델
│   │   ├── user.py            # User 모델만 (< 150줄)
│   │   └── form.py            # Form 모델만 (< 200줄)
│   ├── schemas/                # Pydantic 스키마
│   │   ├── user.py            # User 스키마 (< 150줄)
│   │   └── form.py            # Form 스키마 (< 200줄)
│   ├── services/               # 비즈니스 로직
│   │   ├── auth_service.py    # 인증 로직 (< 300줄)
│   │   └── user_service.py    # 사용자 관리 (< 400줄)
│   ├── repositories/           # 데이터 접근 레이어
│   │   ├── base.py            # BaseRepository (< 200줄)
│   │   └── user_repository.py # User CRUD (< 250줄)
│   └── utils/                  # 유틸리티
│       ├── validators.py      # 검증 함수 (< 200줄)
│       └── file_handler.py    # 파일 처리 (< 300줄)
├── tests/
│   ├── conftest.py
│   └── test_users.py
├── alembic/                    # DB 마이그레이션
├── requirements.txt
└── .env.example

---

코딩 규칙