FastAPI 딥다이브
— 타입 힌트만으로 API를 완성하는 파이썬 웹 프레임워크

Starlette — ASGI 웹 프레임워크

FastAPI 클래스 자체가 class FastAPI(Starlette):로 Starlette를 상속한다. 라우팅 트리, 미들웨어 체인, Request/Response 객체, WebSocket 지원, 예외 처리 미들웨어(ExceptionMiddleware, ServerErrorMiddleware)까지 전부 Starlette가 제공하는 것을 FastAPI가 그대로 쓰거나 살짝 확장한다. FastAPI 문서가 "우리는 Starlette 위의 얇은 레이어"라고 자주 표현하는 이유다.

Pydantic — 데이터 검증/직렬화

BaseModel을 상속한 클래스가 요청 바디, 응답 모델, 설정값의 스키마 역할을 한다. Pydantic v2부터 핵심 검증 로직이 Rust로 작성된 pydantic-core로 이전되어 순수 파이썬 대비 수배~수십 배 빠르다. FastAPI는 이 모델에서 JSON Schema를 뽑아 OpenAPI 문서를 만들고, 요청이 들어올 때 이 모델로 model_validate()를 호출해 검증한다.

Uvicorn — ASGI 서버

실제로 TCP 소켓을 열고 HTTP 요청을 받아 ASGI scope/receive/send 3종 세트로 변환해 FastAPI 앱(callable)에 넘기는 것이 Uvicorn의 역할이다. uvicorn[standard]는 libuv 기반 uvloop(이벤트 루프 가속)와 httptools(C로 작성된 HTTP 파서)를 포함해 순수 asyncio 대비 빠르다. fastapi dev main.py를 실행하면 내부적으로 Uvicorn을 자동 리로드 모드로 띄운다.

타입 힌트 인트로스펙션 (Dependant 그래프 빌드)

라우트 함수를 등록하는 시점에 FastAPI는 inspect.signature()로 함수의 모든 매개변수를 읽고, 각 매개변수의 타입 힌트와 기본값(Depends(), Query(), Body() 등)을 분석해 Dependant라는 데이터 구조를 만든다(fastapi/dependencies/models.py). 이 Dependant는 "이 함수를 실행하려면 어떤 하위 의존성들을 먼저 해결해야 하는지"를 트리 형태로 표현한다. 이 분석은 요청이 오기 전, 앱 시작 시 한 번만 수행되고, 이후 요청마다는 이미 만들어진 그래프를 순회하기만 하므로 빠르다.

의존성 주입(Dependency Injection) — Depends()

Depends(callable)는 "이 콜러블을 먼저 실행해서 나온 값을 이 매개변수에 넣어줘"라는 선언이다. 콜러블은 함수든 클래스든 상관없고, 그 콜러블 자체도 다시 Depends()를 매개변수로 가질 수 있어 의존성이 의존성을 부르는 트리 구조가 만들어진다. 요청마다 solve_dependencies()(fastapi/dependencies/utils.py)가 이 트리를 리프 노드부터 재귀적으로 해결하며, 기본적으로 같은 요청 안에서 동일한 의존성은 한 번만 호출하고 캐시한다(use_cache=True). yield를 쓰는 의존성은 컨텍스트 매니저처럼 동작해 응답 후 정리 코드(DB 세션 종료 등)를 실행한다.

# 의존성이 의존성을 부르는 전형적인 체인
def get_db():
    db = SessionLocal()
    try:
        yield db          # 여기까지가 "생성"
    finally:
        db.close()        # 응답 후 자동 실행되는 "정리"

def get_current_user(
    token: Annotated[str, Depends(oauth2_scheme)],
    db: Annotated[Session, Depends(get_db)],
):
    ...  # token과 db는 이미 해결된 상태로 주입됨
    return user

@app.get("/users/me")
def read_current_user(
    user: Annotated[User, Depends(get_current_user)]
):
    return user  # oauth2_scheme → get_db, get_current_user 순으로 자동 해결

FastAPI의 가장 근본적인 아이디어는 "타입 힌트를 정적 분석 도구용 장식이 아니라 런타임 동작을 결정하는 데이터로 쓴다"는 것이다. fastapi/dependencies/utils.py의 get_dependant()는 inspect.signature()와 typing.get_type_hints()를 조합해 함수의 각 매개변수 타입을 분석하고, 그것이 Pydantic 모델인지, Annotated[X, Query()]인지, Depends()인지 분류한다.

배울 것: inspect 모듈로 함수 시그니처 읽기, typing.Annotated로 타입에 메타데이터 부착하기, Pydantic BaseModel의 model_validate()/model_dump() 활용, pydantic-core(Rust 백엔드)가 왜 빠른지.

Java의 Spring이나 .NET의 DI 컨테이너 같은 무거운 프레임워크 없이, 파이썬 함수 매개변수 문법만으로 DI를 구현한 사례다. fastapi/dependencies/models.py의 Dependant 클래스와 fastapi/dependencies/utils.py의 solve_dependencies()를 함께 읽으면, "선언적 DI"를 데코레이터·클래스 없이 순수 함수 합성으로 구현하는 방법을 배울 수 있다.

배울 것: 의존성 그래프의 재귀적 해결, yield 기반 컨텍스트 매니저 패턴(생성-사용-정리), 요청 스코프 캐싱(use_cache), 서브 의존성 오버라이드(app.dependency_overrides)로 테스트 시 실제 DB 대신 목(mock) 주입하기.

FastAPI는 Starlette를 상속만 한 게 아니라, WSGI/ASGI의 차이, 미들웨어 체인이 요청을 어떻게 감싸는지, lifespan 이벤트(시작/종료 훅)가 어떻게 동작하는지를 배우는 좋은 교재다. fastapi/applications.py의 FastAPI.__init__가 ServerErrorMiddleware, ExceptionMiddleware, AsyncExitStackMiddleware를 쌓는 순서를 보면 미들웨어 체인 설계를 이해할 수 있다.

배울 것: ASGI 3-tuple(scope/receive/send) 프로토콜, 미들웨어 onion(양파) 구조, async def와 def 핸들러가 스레드풀로 자동 분기되는 이유, WebSocket과 HTTP를 하나의 인터페이스로 통합하는 설계.

fastapi/openapi/utils.py의 get_openapi()는 "코드에서 문서를 역생성"하는 대표 사례다. 라우트마다 이미 존재하는 Dependant(파라미터 정보)와 Pydantic 모델의 JSON Schema를 조합해 OpenAPI 3.1 스펙 전체를 조립한다. 문서를 별도로 유지보수할 필요 없이 코드 자체가 단일 진실원(source of truth)이 되는 설계를 배울 수 있다.

배울 것: OpenAPI 스펙 구조(paths/components/schemas), Pydantic 모델 → JSON Schema 변환, Swagger UI/ReDoc이 스펙을 어떻게 소비하는지, response_model로 응답 스키마와 실제 반환 객체를 분리하는 이유(민감 필드 제외 등).

fastapi/security/oauth2.py의 OAuth2PasswordBearer는 "보안 스킴도 결국 하나의 의존성"이라는 것을 보여준다. 이 클래스의 인스턴스 자체가 callable이라 Depends(oauth2_scheme)로 쓰이며, 동시에 OpenAPI 문서에 자물쇠 아이콘과 인증 방식을 자동으로 표시하는 메타데이터 역할도 겸한다.

배울 것: OAuth2 Password/Authorization Code 플로우의 파이썬 구현, __call__을 구현한 클래스를 Depends()에 넣는 패턴, JWT 토큰 검증을 의존성 체인으로 표현하기, Swagger UI의 "Authorize" 버튼이 동작하는 원리.

실습 1 — Hello World API + 자동 문서 확인

FastAPI를 설치하고 최소 앱을 실행한 뒤 자동 생성된 Swagger UI를 직접 눈으로 확인한다.

pip install "fastapi[standard]"

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello World"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

fastapi dev main.py
# http://127.0.0.1:8000/docs 에서 Swagger UI 확인
# http://127.0.0.1:8000/items/5?q=test 호출해보기
# http://127.0.0.1:8000/items/abc 호출 → 422 검증 에러 확인 (int가 아니라서)

확인 포인트: item_id: int인데 문자열을 넣으면 자동으로 422 에러가 나는 것을 관찰. /docs에서 각 파라미터 타입이 어떻게 표시되는지 확인.

실습 2 — Pydantic 모델로 POST 바디 검증하기

Pydantic BaseModel을 정의하고 POST 요청 바디로 받아, 검증 실패 시 에러 응답 형태를 관찰한다.

from pydantic import BaseModel
from fastapi import FastAPI

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float
    is_offer: bool | None = None

@app.post("/items/")
def create_item(item: Item):
    return {"name": item.name, "price_with_tax": item.price * 1.1}

확인 포인트: /docs에서 "Try it out"으로 price에 문자열("abc")을 넣어 422 에러의 상세 구조(loc, msg, type)를 확인. response_model=Item을 추가해 응답 스키마도 검증되는지 비교.

실습 3 — Depends()로 공통 쿼리 파라미터 + DB 세션 의존성 만들기

여러 라우트에서 재사용되는 공통 로직(페이지네이션 파라미터, 가짜 DB 세션)을 Depends()로 뽑아내 본다.

from typing import Annotated
from fastapi import Depends, FastAPI

app = FastAPI()

async def common_pagination(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

def get_fake_db():
    db = {"users": ["alice", "bob", "carol"]}
    try:
        yield db
    finally:
        print("DB 연결 정리 완료")  # 응답 후 자동 실행

@app.get("/users/")
def list_users(
    pagination: Annotated[dict, Depends(common_pagination)],
    db: Annotated[dict, Depends(get_fake_db)],
):
    users = db["users"][pagination["skip"]: pagination["skip"] + pagination["limit"]]
    return {"users": users, **pagination}

확인 포인트: 같은 common_pagination 의존성을 다른 라우트(/items/)에도 재사용해보고, yield 이후 코드가 응답 전송 이후 실행되는 시점을 print로 확인.

실습 4 — OAuth2PasswordBearer로 JWT 인증 라우트 만들기

FastAPI 보안 유틸리티로 로그인 → 토큰 발급 → 보호된 라우트 접근 흐름을 구현한다.

from typing import Annotated
from fastapi import Depends, FastAPI, HTTPException
from fastapi.security import OAuth2PasswordBearer

app = FastAPI()
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]):
    if token != "valid-token":
        raise HTTPException(status_code=401, detail="Invalid token")
    return {"username": "demo_user"}

@app.get("/users/me")
def read_users_me(
    current_user: Annotated[dict, Depends(get_current_user)]
):
    return current_user

확인 포인트: /docs에 자물쇠 아이콘이 자동으로 생기는 것을 확인. Authorization 헤더 없이 호출 시 401, 잘못된 토큰일 때의 에러 구조 비교. pyjwt를 추가해 실제 JWT 서명·검증으로 확장해본다.

실습 5 — FastAPI 소스 클론 + solve_dependencies 실행 흐름 디버깅

저장소를 직접 클론하고, 디버거로 solve_dependencies()가 실제로 호출되는 시점을 추적한다.

git clone https://github.com/fastapi/fastapi
cd fastapi
pip install -e ".[all]"
# fastapi/dependencies/utils.py의 solve_dependencies에 breakpoint() 삽입
# 아무 예제 앱이나 실행 후 요청을 보내 콜스택 관찰
python -m pytest tests/test_dependency_cache.py -v   # 의존성 캐싱 테스트 확인

확인 포인트: get_dependant()가 앱 시작(라우트 등록) 시 한 번만 호출되고, solve_dependencies()는 매 요청마다 호출된다는 시점 차이를 콜스택으로 직접 확인. app.dependency_overrides로 테스트에서 실제 의존성을 목으로 교체하는 코드(tests/ 디렉토리 다수)를 찾아 분석.

목표: PEP 484 타입 힌트 문법, Optional/Union/Annotated 이해.

자료: 파이썬 공식 typing 문서(docs.python.org/3/library/typing.html), FastAPI 공식 튜토리얼의 "Python Types Intro" 챕터.

실습: mypy로 타입 체크가 되는 간단한 함수 여러 개 작성.

목표: BaseModel, validator, model_dump()/model_validate(), JSON Schema 생성 이해.

자료: Pydantic 공식 문서(docs.pydantic.dev), pydantic-core가 Rust로 작성된 이유에 대한 블로그 글.

실습: 중첩 모델, 커스텀 검증자(@field_validator)로 이메일/전화번호 검증 로직 작성.

목표: 경로 연산, 쿼리/경로/바디 파라미터, response_model, 상태 코드 관리.

자료: FastAPI 공식 튜토리얼(fastapi.tiangolo.com/tutorial/) 전체.

실습: CRUD API 하나를 처음부터 끝까지 구현 (인메모리 dict 저장소로 충분).

목표: Depends(), 서브 의존성, yield 의존성, 클래스 기반 의존성, dependency_overrides.

자료: "Dependencies" 튜토리얼 섹션, fastapi/dependencies/utils.py 소스 직접 읽기.

실습: 실습 3~4를 확장해 DB 세션+인증+권한 검사를 의존성 체인으로 조합.

목표: ASGI 스펙, 미들웨어, lifespan, WebSocket, BackgroundTasks.

자료: Starlette 공식 문서(starlette.dev), ASGI 스펙(asgi.readthedocs.io).

실습: 커스텀 미들웨어 작성(요청 처리 시간 로깅), WebSocket 채팅 엔드포인트 구현.

목표: OAuth2/JWT, CORS, Uvicorn 워커 설정, Docker 배포.

자료: "Security" 튜토리얼 섹션, FastAPI 공식 "Deployment" 가이드.

실습: JWT 로그인 API를 Docker 컨테이너로 패키징하고 Gunicorn+Uvicorn 워커로 실행.

목표: FastAPI 저장소 구조 파악, 테스트 작성법 익히기, PR 프로세스 이해.

자료: CONTRIBUTING.md, tests/ 디렉토리의 기존 테스트 패턴.

실습: 문서 번역/개선 PR, 또는 이슈 트래커의 good-first-issue 라벨 항목에 도전.