백엔드 기초집: Python FastAPILESSON 10

프로젝트 폴더 구조와 Router 분리

난이도초급

예상 시간35분

선수지식이전 강의

10강. 프로젝트 폴더 구조와 Router 분리

1. 이번 강의에서 해결할 문제

모델과 모든 endpoint가 main.py에 모이면 변경 충돌과 순환 import가 늘어납니다. HTTP 경로와 도메인별 코드를 패키지로 나눕니다.

2. 학습 목표

3. 핵심 개념

Router는 경로와 HTTP 변환을 담당하고 schema는 입출력 계약을 담당합니다. service는 점수 기록 같은 도메인 동작을 맡습니다. main.py는 FastAPI 객체 생성, middleware, router 연결에 집중합니다. 폴더마다 __init__.py를 두어 Python 패키지로 import합니다.

4. 단계별 코드 예시

파일 경로: game-ranking-api/

프로젝트 구조
game-ranking-api/
├─ app/
│  ├─ __init__.py
│  ├─ main.py
│  ├─ schemas/
│  │  ├─ __init__.py
│  │  └─ record.py
│  ├─ routers/
│  │  ├─ __init__.py
│  │  └─ records.py
│  └─ services/
│     ├─ __init__.py
│     └─ records.py
└─ requirements.txt

파일 경로: game-ranking-api/app/routers/records.py

app/routers/records.py
from fastapi import APIRouter

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


@router.get("")
def list_records() -> dict[str, list[object]]:
    return {"items": []}

파일 경로: game-ranking-api/app/main.py

app/main.py
from fastapi import FastAPI

from app.routers import records

app = FastAPI(title="Game Ranking API", version="0.2.0")
app.include_router(records.router)


@app.get("/health", tags=["system"])
def health() -> dict[str, str]:
    return {"status": "ok"}

실행 위치: game-ranking-api/

python -m uvicorn app.main:app --reload
Invoke-RestMethod http://127.0.0.1:8000/records

5. 코드가 동작하는 이유

APIRouter는 작은 FastAPI처럼 path operation을 모읍니다. prefix가 각 경로 앞에 붙고 include_router가 최종 앱의 route 목록에 포함합니다. main은 records 내부 구현을 몰라도 router 객체만 연결합니다.

6. 자주 하는 실수와 해결법

7. 직접 실습

8. 이해 점검 질문 3개

9. 핵심 요약

MINI QUIZ