FastAPI 헬로 월드 튜토리얼

1 FastAPI 소개

FastAPI는 API 구축을 위한 현대적인 Python 웹 프레임워크입니다. 웹 계층은 Starlette를, 데이터 검증은 Pydantic을 사용합니다. 타입 힌트는 단순한 장식이 아니라 요청 파싱, 응답 직렬화, 자동화된 문서를 구동합니다.

빠름: Node 및 Go와 동등한 고성능을 제공합니다.
빠른 개발: 최소한의 보일러플레이트로 기능을 빠르게 구현할 수 있습니다.
적은 버그: 입력 및 출력을 자동으로 검증합니다.
표준 기반: OpenAPI, Swagger UI, ReDoc을 즉시 생성합니다.

준비되면 “다음”을 클릭하면 로컬에서 최소한의 앱을 실행할 수 있습니다.

2 사전 요구 사항: Python & Pip

Python 3.7+ 및 pip가 설치되어 있는지 확인하세요:

python --version
pip --version

python.org에서 설치하세요.

3 가상 환경 설정

가상 환경으로 종속성을 깔끔하게 관리하세요.

python -m venv .venv

활성화하세요:

# macOS/Linux
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate

활성화되면 (.venv)가 표시됩니다.

4 FastAPI 및 Uvicorn 설치

가상 환경 내에 FastAPI와 Uvicorn(ASGI 서버)을 설치하세요:

pip install "fastapi[all]" uvicorn[standard]

[all] 옵션은 Pydantic v2 및 표준 선택적 종속성을 포함합니다. 간결한 설치를 선호하는 경우 pip install fastapi uvicorn을 사용하세요.

5 main.py 파일 생성

main.py 파일을 만들고 기본 엔드포인트를 추가하세요:

from fastapi import FastAPI

app = FastAPI()


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

이것으로 끝입니다. import 하나, app 하나, route 하나. Docstring과 타입 힌트가 생성된 문서를 구동합니다.

6 Uvicorn으로 서버 실행

개발 중에는 핫 리로드를 사용하여 서버를 시작하세요:

uvicorn main:app --reload

http://127.0.0.1:8000/에서 JSON 응답을 확인하세요.

7 인터랙티브 문서 탐색

FastAPI는 Swagger UI와 ReDoc을 자동으로 제공합니다:

Swagger UI: /docs
ReDoc: /redoc
OpenAPI 스키마: /openapi.json

추가 설정 없이 문서에서 직접 엔드포인트를 테스트하고 요청/응답 모델을 볼 수 있습니다.

8 경로 매개변수가 있는 라우트 추가

main.py를 매개변수화된 라우트로 업데이트하세요:

from fastapi import FastAPI

app = FastAPI()


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


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

타입 힌트 덕분에 item_id는 정수로 검증되고 자동으로 문서화됩니다.

9 요청 본문 수락 (Pydantic)

모델을 정의하고 JSON 페이로드를 수락하세요:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float
    tags: list[str] = []


@app.post("/items/", response_model=Item)
def create_item(item: Item):
    # 보통은 저장하겠지만, 여기서는 단순히 에코합니다.
    return item


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


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

FastAPI는 JSON을 검증하고, 타입을 강제하며, 생성된 스키마에 모델을 문서화합니다.

10 오류 발생 및 처리

깔끔한 오류 응답을 위해 HTTPException을 사용하세요:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    price: float
    tags: list[str] = []


db: dict[int, Item] = {}


@app.post("/items/", response_model=Item)
def create_item(item: Item):
    new_id = len(db) + 1
    db[new_id] = item
    return item


@app.get("/items/{item_id}")
def read_item(item_id: int):
    item = db.get(item_id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")
    return {"item_id": item_id, **item.dict()}

존재하지 않는 ID를 요청하면 이제 깔끔한 404 JSON {"detail": "Item not found"}이 반환됩니다.

11 다음 단계 및 배포

종속성 고정: pip freeze > requirements.txt
프로덕션 모드 시도: uvicorn main:app --host 0.0.0.0 --port 8000
Render, Fly.io, Railway 또는 Gunicorn + Uvicorn 워커가 있는 VM에 배포
@app.exception_handler를 사용하여 오류 형식 중앙 집중화
fastapi.security를 통한 OAuth2/JWT로 엔드포인트 보안

이제 작동하는 API, 검증, 라이브 문서가 준비되었습니다. 여기에서 프레임워크를 변경하지 않고 라우트, 레이어, 테스트를 확장할 수 있습니다.