Skip to content

FastAPI 치트시트

API 구축을 위한 현대적이고 빠른 Python 웹 프레임워크입니다.

01

시작하기

첫 API

FastAPI는 Starlette과 Pydantic 위에 만들어졌습니다. uvicorn이 ASGI 서버입니다. --reload는 개발 중 자동 리로드를 켭니다.

fastapi
# install FastAPI and uvicorn
pip install fastapi uvicorn

# main.py
from fastapi import FastAPI

app = FastAPI()

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

# run: uvicorn main:app --reload

Uvicorn으로 실행

앱 인스턴스 'main:app'은 모듈 'main'의 변수 'app'을 뜻합니다. --reload는 개발에서만 쓰세요; 프로덕션에서는 없이 실행하고 프로세스 매니저를 쓰세요.

fastapi
# development with auto-reload
uvicorn main:app --reload

# specify host and port
uvicorn main:app --host 0.0.0.0 --port 8000

# run programmatically
import uvicorn
if __name__ == "__main__":
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

비동기 경로 연산

경로 연산은 'def'(스레드풀에서 실행)나 'async def'로 선언할 수 있습니다. 함수가 비동기 라이브러리로 I/O를 수행할 때 async def를 쓰세요; async def 안에서 블로킹 호출을 섞으면 이벤트 루프를 막습니다.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "hello"}

@app.get("/sync")
def read_sync():
    return {"message": "sync also works"}

# use async when calling async libs (httpx, databases)
@app.get("/data")
async def fetch_data():
    import httpx
    async with httpx.AsyncClient() as client:
        r = await client.get("https://api.example.com")
    return r.json()

경로 연산 데코레이터

FastAPI는 모든 HTTP 메서드를 지원합니다: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD. 각각이 데코레이터에 매핑됩니다. 데코레이터의 status_code=으로 기본 성공 상태를 덮어쓰세요.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def list_items(): ...

@app.post("/items")
def create_item(): ...

@app.put("/items/{item_id}")
def replace_item(item_id: int): ...

@app.patch("/items/{item_id}")
def update_item(item_id: int): ...

@app.delete("/items/{item_id}")
def delete_item(item_id: int): ...

@app.options("/items")
def options_items(): ...

@app.head("/items")
def head_items(): ...

JSON 응답 & 상태

dict/리스트를 반환하면 200(또는 지정한 status_code)으로 자동 JSON 변환됩니다. 상태, 헤더, 콘텐츠를 완전히 제어하려면 JSONResponse나 Response를 직접 반환하세요.

fastapi
from fastapi import FastAPI, status
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/plain")
def plain():
    return {"key": "value"}  # auto JSON, 200 OK

@app.post("/created", status_code=status.HTTP_201_CREATED)
def created():
    return {"id": 1}

@app.get("/custom")
def custom():
    return JSONResponse(
        status_code=418,
        content={"error": "I'm a teapot"},
        headers={"X-Custom": "yes"},
    )

프로젝트 구조

자라는 앱을 APIRouter로 모듈에 나누고 app.include_router()로 등록하세요. 유지보수성을 위해 Pydantic 스키마, DB 셋업, 의존성은 별도 파일에 두세요.

fastapi
myapp/
  main.py              # creates the FastAPI app
  routers/
    users.py           # APIRouter for /users
    items.py           # APIRouter for /items
  models/
    schemas.py         # Pydantic models
    database.py        # DB engine & session
  dependencies.py      # shared Depends functions
  tests/
    test_main.py

# main.py
from fastapi import FastAPI
from routers import users, items
app = FastAPI()
app.include_router(users.router)
app.include_router(items.router, prefix="/items")
02

경로 매개변수

기본 경로 매개변수

경로에서 캡처된 값은 타입 어노테이션을 붙이기 전까지는 문자열입니다. 경로의 매개변수 이름은 함수 인수 이름과 정확히 일치해야 합니다.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id):
    return {"item_id": item_id}

# GET /items/42 -> {"item_id": "42"}  (string by default)

타입 변환

타입 어노테이션(int, float, bool, str, Enum)을 붙이면 FastAPI가 경로 값을 검증·변환합니다. 무효한 값은 명확한 오류 메시지와 함께 422 응답을 반환합니다.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

# GET /items/3   -> {"item_id": 3}
# GET /items/abc -> 422 Validation Error (not an integer)

경로 검증

Path()가 경로 매개변수에 메타데이터와 제약을 더합니다. 숫자 제약: ge(>=), gt(>), le(<=), lt(<). 경로 매개변수는 항상 필수이므로 Path()는 기본값을 설정할 수 없습니다.

fastapi
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(
    item_id: int = Path(
        title="The ID of the item",
        description="Must be a positive integer",
        ge=1,
        le=1000,
    ),
):
    return {"item_id": item_id}

숫자 제약

int나 float 경로 매개변수에 ge/gt/le/lt를 써 숫자 범위를 강제하세요. 제약을 결합하면 자동 422 오류와 함께 정밀한 경계 검증이 됩니다.

fastapi
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/ratio/{value}")
def ratio(
    value: float = Path(gt=0, lt=1),  # 0 < value < 1
):
    return {"value": value}

@app.get("/page/{page}")
def page(
    page: int = Path(ge=1),       # >= 1
    size: int = Path(le=100),     # <= 100
):
    return {"page": page, "size": size}

라우트 순서가 중요

라우트는 선언 순서대로 매칭됩니다. /users/me 같은 특정 경로를 /users/{user_id} 같은 동적 패턴보다 먼저 선언하세요 — 아니면 동적 라우트가 특정 라우트를 가립니다.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/users/me")
def read_current_user():
    return {"user": "me"}

@app.get("/users/{user_id}")
def read_user(user_id: str):
    return {"user_id": user_id}

# /users/me MUST be declared before /users/{user_id}
# otherwise 'me' would match the {user_id} pattern

Enum 경로 매개변수

경로 매개변수에 Enum 타입을 쓰면 사전 정의된 값으로 제한되고 OpenAPI 문서에 enum 스키마가 생성됩니다. 값이 문자열로 직렬화되도록 (str, Enum)을 서브클래싱하세요.

fastapi
from enum import Enum
from fastapi import FastAPI

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

app = FastAPI()

@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model": model_name, "layers": 5}
    return {"model": model_name}

# GET /models/resnet -> {"model": "resnet"}
03

쿼리 매개변수

기본 쿼리 매개변수

경로에 없는 함수 매개변수가 쿼리 매개변수가 됩니다. 기본값을 주면 선택이 되고, 쿼리 키가 없을 때 기본값이 쓰입니다.

fastapi
from fastapi import FastAPI

app = FastAPI()

fake_items = [{"item": "a"}, {"item": "b"}, {"item": "c"}]

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10):
    return fake_items[skip : skip + limit]

# GET /items?skip=0&limit=2
# GET /items                -> skip=0, limit=10

선택적 쿼리 매개변수

생략될 수 있는 쿼리 매개변수에는 Optional[str] = None(Python 3.10+에서는 str | None = None)을 쓰세요. 필수 매개변수는 그냥 기본값이 없으면 됩니다.

fastapi
from typing import Optional
from fastapi import FastAPI

app = FastAPI()

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

# GET /items/1?q=hello
# GET /items/1            (q is None)

쿼리 검증

Query()가 검증을 더합니다: 문자열에는 min_length/max_length, 숫자에는 ge/gt/le/lt, 문자열 형식에는 pattern(정규식). 제약을 적용하면서 값을 설정하려 default=를 쓰세요.

fastapi
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/search")
def search(q: str = Query(min_length=3, max_length=50, pattern="^[a-zA-Z]+$")):
    return {"q": q}

@app.get("/page")
def page(limit: int = Query(default=10, ge=1, le=100)):
    return {"limit": limit}

불리언 변환

Bool 쿼리 매개변수는 많은 truthy 값을 받습니다: true, 1, yes, on(대소문자 무시). 그 외는 false로 해석됩니다. ?active=maybe 같은 무효 타입은 422를 반환합니다.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/flags")
def flags(active: bool = False):
    return {"active": active}

# GET /flags?active=true   -> {"active": true}
# GET /flags?active=1      -> {"active": true}
# GET /flags?active=yes    -> {"active": true}
# GET /flags?active=off    -> {"active": false}

리스트 쿼리 매개변수

List[str] 매개변수는 쿼리 문자열에서 같은 키가 반복되는 것을 받습니다. 기본 빈 리스트에는 Query(default=[]), 빠진 값을 허용하려 Query(default=None)를 쓰세요.

fastapi
from typing import List
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def list_items(q: List[str] = Query(default=[])):
    return {"q": q}

# GET /items?q=a&q=b&q=c  -> {"q": ["a", "b", "c"]}
# declare default=None to accept a list or null

필수 쿼리 매개변수

검증 메타데이터를 유지하면서 필수 쿼리 매개변수를 선언하려 Query(...)(Ellipsis)를 쓰세요. 기본값도 Query(...)도 없으면 일반 어노테이션 매개변수도 필수입니다.

fastapi
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def read_item(q: str = Query(...)):
    return {"q": q}

# GET /items?q=hello   -> ok
# GET /items           -> 422 (q is required)
# Query(...) (Ellipsis) marks a parameter as required
04

요청 본문 (Pydantic)

BaseModel 기본

함수 매개변수로 선언된 Pydantic BaseModel이 JSON 요청 본문이 됩니다. FastAPI가 페이로드를 검증하고 타입을 변환하며 무효한 데이터에 422를 반환합니다. 기본값이 있는 필드는 선택입니다.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    in_stock: bool = True

app = FastAPI()

@app.post("/items")
def create_item(item: Item):
    return item

# POST /items  body: {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5, "in_stock": true}

필드 타입 & 제약

Field()가 모델 속성에 제약과 메타데이터를 더합니다: 문자열에는 min_length/max_length, 숫자에는 gt/ge/lt/le, 가변 기본값에는 default_factory. json_schema_extra가 있는 model_config가 문서에 예제를 더합니다.

fastapi
from pydantic import BaseModel, Field
from typing import Optional

class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0, description="must be positive")
    tax: Optional[float] = None
    tags: list[str] = Field(default_factory=list)

    model_config = {
        "json_schema_extra": {
            "examples": [{"name": "Apple", "price": 0.5, "tags": ["fruit"]}]
        }
    }

중첩 모델

모델은 중첩될 수 있습니다: 다른 BaseModel을 필드 타입으로 선언하세요. FastAPI가 전체 중첩 구조를 재귀적으로 검증하고 생성된 OpenAPI 스키마가 중첩 객체를 반영합니다.

fastapi
from pydantic import BaseModel
from typing import Optional

class Image(BaseModel):
    url: str
    name: str

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    image: Optional[Image] = None
    images: list[Image] = []

# valid body:
# {"name": "Phone", "image": {"url": "http://x/a.png", "name": "a"}}

필드 검증

필드별 커스텀 검증 로직에는 @field_validator(Pydantic v2)를 쓰세요. 입력을 거부하려 ValueError를 발생시키세요(FastAPI가 이를 422로 표면화합니다). 유지하려 (변환된) 값을 반환하세요.

fastapi
from pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str
    email: str

    @field_validator("email")
    @classmethod
    def email_must_contain_at(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError("must contain @")
        return v.lower()

    @field_validator("name")
    @classmethod
    def name_stripped(cls, v: str) -> str:
        return v.strip()

선택 & 기본 필드

필드는 기본값이 없고 Optional이 아니어야만 필수입니다. 선택적 널러블 필드의 표준 패턴은 Optional[str] = None이며, 0.0 같은 일반 기본값은 그 값으로 필드를 선택적으로 만듭니다.

fastapi
from pydantic import BaseModel
from typing import Optional

class Item(BaseModel):
    name: str                       # required
    description: Optional[str] = None  # optional, defaults to None
    price: float = 0.0              # optional, defaults to 0.0
    tags: list[str] = []            # optional, defaults to empty list

# All of these are valid:
# {"name": "X"}
# {"name": "X", "price": 9.99, "tags": ["a"]}

경로 & 쿼리와 본문

경로, 쿼리, 본문 매개변수가 하나의 연산에 공존할 수 있습니다. FastAPI가 판단합니다: 경로에 있으면 경로 매개변수, 본문은 Pydantic 모델(또는 Body()), 그 외에는 쿼리. 선택적 본문에는 None 기본값이 필요합니다.

fastapi
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.put("/items/{item_id}")
def update_item(
    item_id: int = Path(ge=1),
    q: Optional[str] = Query(default=None),
    item: Item = None,
):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result["q"] = q
    return result
05

Response Model

response_model 기본

response_model이 반환된 데이터를 모델에 정의된 필드로만 필터링합니다 — 여분 필드가 있는 객체를 반환해도 그렇습니다. 비밀번호 같은 민감 필드를 숨기는 표준 방법입니다.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class User(BaseModel):
    username: str
    email: str
    hashed_password: str

class UserOut(BaseModel):
    username: str
    email: str

app = FastAPI()

@app.get("/users/me", response_model=UserOut)
def read_user():
    return User(username="bob", email="[email protected]", hashed_password="secret")

# response: {"username": "bob", "email": "[email protected]"}  (no password)

필드 제외

response_model_include와 response_model_exclude가 새 모델을 정의하지 않고 라우트별로 필드를 화이트/블랙리스트하게 합니다. 필드 이름의 set을 전달하세요. 이들은 response_model에 추가로 적용됩니다.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    secret: str

app = FastAPI()

@app.get("/items/{id}", response_model=Item, response_model_exclude={"secret"})
def read_item(id: int):
    return {"name": "Apple", "price": 0.5, "secret": "hidden"}

@app.get("/items", response_model=list[Item], response_model_include={"name", "price"})
def list_items():
    return [{"name": "Apple", "price": 0.5, "secret": "x"}]

리스트 응답

엔드포인트가 객체 배열을 반환한다고 선언하려 response_model=list[Model](또는 List[Model])을 쓰세요. FastAPI가 목록의 각 항목을 검증·직렬화합니다.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.get("/items", response_model=list[Item])
def list_items():
    return [
        {"name": "Apple", "price": 0.5},
        {"name": "Banana", "price": 0.3},
    ]

# response: [{"name": "Apple", "price": 0.5}, {"name": "Banana", "price": 0.3}]

미설정/기본값 제외

exclude_unset은 클라이언트가 보내지 않은 필드를 생략합니다(명시적으로 설정된 것만 나타남). exclude_defaults는 기본값과 같은 필드를, exclude_none은 None인 필드를 생략합니다. 희소 응답에 유용합니다.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float = 0.0
    tax: float = 0.0

app = FastAPI()

@app.get("/items/{id}", response_model=Item, response_model_exclude_unset=True)
def read_item(id: int):
    return {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5}   (description, tax omitted)

# also: response_model_exclude_defaults=True
#       response_model_exclude_none=True

별칭으로 응답

Field(alias=...)가 들어오는 JSON이 Python 속성과 다른 키 이름을 쓰게 합니다. response_model_by_alias=True는 출력에도 별칭을 씁니다. populate_by_name=True는 입력에서 원래 속성 이름도 허용합니다.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict, Field

class Item(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    name: str = Field(alias="itemName")
    price: float

app = FastAPI()

@app.post("/items", response_model=Item, response_model_by_alias=True)
def create(item: Item):
    return item

# input:  {"itemName": "Apple", "price": 0.5}
# output: {"itemName": "Apple", "price": 0.5}

일반 dict 응답

dict/리스트를 반환하면 JSON으로 자동 직렬화됩니다. 기본 응답 타입(HTMLResponse, PlainTextResponse)을 바꾸려 response_class를 쓰거나, 완전한 제어를 위해 Response 서브클래스를 직접 반환하세요.

fastapi
from fastapi import FastAPI
from fastapi.responses import JSONResponse, PlainTextResponse

app = FastAPI()

@app.get("/dict")
def dict_resp():
    return {"a": 1, "b": 2}      # auto JSON

@app.get("/text", response_class=PlainTextResponse)
def text_resp():
    return "plain text response"

@app.get("/raw")
def raw_resp():
    return JSONResponse(content={"a": 1}, status_code=200)
06

폼 & UploadFile

폼 데이터

Form()은 application/x-www-form-urlencoded나 multipart 폼 데이터에서 파싱되는 매개변수를 선언합니다. 같은 연산에서 Form()을 JSON 본문(BaseModel)과 섞을 수는 없습니다 — 콘텐츠 타입을 하나 고르세요.

fastapi
from fastapi import FastAPI, Form

app = FastAPI()

@app.post("/login")
def login(username: str = Form(), password: str = Form()):
    return {"username": username}

# Content-Type: application/x-www-form-urlencoded
# body: username=bob&password=secret

UploadFile 기본

UploadFile은 .filename, .content_type, .read(), .write(), .close()를 갖춘 스트리밍 파일 표현입니다. async def 안에서는 'await file.read()'를 쓰세요. 큰 파일에는 메모리에 전부 올리지 않도록 file.file(SpooledTemporaryFile)을 권합니다.

fastapi
from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
    contents = await file.read()
    return {
        "filename": file.filename,
        "size": len(contents),
        "content_type": file.content_type,
    }

여러 파일

하나의 요청에서 여러 파일을 받으려 list[UploadFile]을 선언하세요. 각 파일이 같은 필드 이름으로 전송됩니다. 목록의 파일 순서가 전송 순서와 일치합니다.

fastapi
from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/uploads")
async def upload_many(files: list[UploadFile]):
    return [
        {"filename": f.filename, "size": len(await f.read())}
        for f in files
    ]

# curl: curl -F "[email protected]" -F "[email protected]" http://localhost:8000/uploads

파일과 폼 함께

Form()과 UploadFile(File())은 둘 다 multipart/form-data를 쓰므로 같은 엔드포인트에서 결합할 수 있습니다. JSON BaseModel 본문과는 여전히 결합할 수 없습니다.

fastapi
from fastapi import FastAPI, UploadFile, File, Form

app = FastAPI()

@app.post("/items")
async def create_item(
    name: str = Form(),
    description: str = Form(),
    file: UploadFile = File(),
):
    return {
        "name": name,
        "description": description,
        "file": file.filename,
    }

업로드 파일 저장

작은 파일에는 shutil.copyfileobj가 SpooledTemporaryFile을 효율적으로 디스크로 스트리밍합니다. 매우 큰 파일에는 메모리를 낮게 유지하려 청크로(예: 1MB) 읽으세요. 경로 트래버설을 피하려 file.filename을 항상 정제하세요.

fastapi
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/save")
async def save_file(file: UploadFile):
    dest = Path("uploads") / file.filename
    dest.parent.mkdir(exist_ok=True)
    with dest.open("wb") as buf:
        shutil.copyfileobj(file.file, buf)
    return {"saved_to": str(dest)}

# async alternative for large files:
# async with dest.open("wb") as buf:
#     while chunk := await file.read(1024 * 1024):
#         buf.write(chunk)

파일 메타데이터 & 크기

처리 전에 file.content_type과 크기를 검증하세요. read() 뒤에는 커서가 끝에 있으므로 다시 읽어야 하면 'await file.seek(0)'으로 되감으세요. 진짜 타입 검사는 헤더만이 아니라 매직 바이트를 검사해야 합니다.

fastapi
from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/validate")
async def validate(file: UploadFile = File(...)):
    # allowed types
    allowed = {"image/png", "image/jpeg"}
    if file.content_type not in allowed:
        return {"error": "unsupported type"}

    contents = await file.read()
    max_size = 5 * 1024 * 1024  # 5 MB
    if len(contents) > max_size:
        return {"error": "file too large"}

    await file.seek(0)  # rewind so later reads work
    return {"filename": file.filename, "size": len(contents)}
07

헤더 & 쿠키

헤더 매개변수

Header()가 요청 헤더에서 읽는 매개변수를 선언합니다. FastAPI가 Python 이름의 언더스코어를 하이픈으로 바꿉니다(x_token → X-Token). 이 동작을 끄려 convert_underscores=False를 설정하세요.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/items")
def read_items(user_agent: str | None = Header(default=None)):
    return {"User-Agent": user_agent}

# Header names are case-insensitive; an underscore in the
# parameter (x_token) is converted to a hyphen (X-Token) automatically.
@app.get("/secure")
def secure(x_token: str = Header()):
    return {"x-token": x_token}

쿠키 매개변수

Cookie()가 요청의 Cookie 헤더에서 값을 읽습니다. 쿼리 매개변수처럼 기본값이 없는 쿠키는 필수이며, 검증(min_length, max_length 등)을 적용할 수 있습니다.

fastapi
from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/session")
def read_session(session_id: str | None = Cookie(default=None)):
    if session_id:
        return {"session_id": session_id}
    return {"message": "no session"}

# Reads the 'session_id' cookie from the Cookie header.

응답에 쿠키 설정

Response를 주입해 set_cookie()를 호출하면 나가는 응답에 쿠키를 씁니다. CSRF를 완화하려 httponly=True(JS 접근 차단), secure=True(HTTPS 전용), samesite='lax'/'strict'를 쓰세요. 응답 본문은 여전히 정상적으로 반환됩니다.

fastapi
from fastapi import FastAPI, Response

app = FastAPI()

@app.post("/login")
def login(response: Response):
    response.set_cookie(
        key="session_id",
        value="abc123",
        httponly=True,
        max_age=1800,
        secure=True,
        samesite="lax",
    )
    return {"message": "logged in"}

@app.post("/logout")
def logout(response: Response):
    response.delete_cookie("session_id")
    return {"message": "logged out"}

커스텀 응답 헤더

주입된 Response에 헤더를 설정하면 FastAPI가 만드는 JSON 응답에 추가되고, Response 서브클래스를 직접 반환할 때는 headers=를 전달하세요. 커스텀 헤더는 레이트 리밋 정보와 처리 시간에 흔히 쓰입니다.

fastapi
from fastapi import FastAPI, Response
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/data")
def get_data(response: Response):
    response.headers["X-Process-Time"] = "0.05"
    response.headers["X-Custom-Header"] = "hello"
    return {"data": 1}

@app.get("/direct")
def direct():
    return JSONResponse(
        content={"data": 1},
        headers={"X-Source": "direct"},
    )

표준 헤더

Host, Accept, Authorization, If-None-Match 같은 흔한 헤더는 Header()로 접근합니다. Authorization에는 파싱과 OpenAPI 문서화를 대신 처리해 주는 내장 보안 유틸리티(HTTPBearer, OAuth2)를 권합니다.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/info")
def info(
    host: str | None = Header(default=None),
    accept: str | None = Header(default=None),
    authorization: str | None = Header(default=None),
    if_none_match: str | None = Header(default=None),
):
    return {"host": host, "accept": accept}

중복 헤더 값

Header 매개변수에 리스트 타입을 선언하면 반복된 모든 헤더 값이 목록으로 수집됩니다. Set-Cookie(응답)나 여러 번 나타날 수 있는 커스텀 헤더에 유용합니다.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/multi")
def multi(x_token: list[str] | None = Header(default=None)):
    return {"x_token": x_token}

# Request with:
#   X-Token: a
#   X-Token: b
# -> {"x_token": ["a", "b"]}
08

의존성 주입

기본 Depends

Depends()가 함수의 반환 값을 경로 연산에 주입합니다. 공유 로직(페이징, 파싱, DB 세션)이 한 곳에 살고 엔드포인트 전반에서 재사용됩니다. 의존성의 매개변수도 OpenAPI에 문서화됩니다.

fastapi
from fastapi import FastAPI, Depends

app = FastAPI()

def common_params(q: str | None = None, skip: int = 0, limit: int = 10):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/items")
def list_items(commons: dict = Depends(common_params)):
    return commons

@app.get("/users")
def list_users(commons: dict = Depends(common_params)):
    return commons

클래스 의존성

__init__이 있는 클래스도 의존성이 될 수 있습니다; FastAPI가 함수처럼 호출합니다. Depends(CommonQueryParams)나 매개변수가 클래스로 어노테이션되어 있으면 축약 Depends()를 쓰세요. 인스턴스가 주입됩니다.

fastapi
from fastapi import FastAPI, Depends

class CommonQueryParams:
    def __init__(self, q: str | None = None, skip: int = 0, limit: int = 10):
        self.q = q
        self.skip = skip
        self.limit = limit

app = FastAPI()

@app.get("/items")
def list_items(commons: CommonQueryParams = Depends(CommonQueryParams)):
    return {"q": commons.q, "skip": commons.skip, "limit": commons.limit}

# shorthand: commons = Depends() infers the type

중첩 의존성

의존성은 다른 의존성에 의존해 그래프를 이룰 수 있습니다. FastAPI가 전체 트리를 해석하고 각 결과를 요청별로 캐시하며 예외를 전파합니다. 계층화된 인증(토큰 → 사용자 → 권한)에 이상적입니다.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def get_token(authorization: str = Header()):
    if not authorization.startswith("Bearer "):
        raise HTTPException(status_code=401, detail="invalid header")
    return authorization.removeprefix("Bearer ")

def get_current_user(token: str = Depends(get_token)):
    if token != "admin-token":
        raise HTTPException(status_code=403, detail="forbidden")
    return {"username": "admin"}

app = FastAPI()

@app.get("/me")
def me(user: dict = Depends(get_current_user)):
    return user

yield 의존성 (정리)

yield 의존성 제너레이터가 정리가 필요한 리소스에 완벽합니다: DB 세션, 파일 핸들, 트랜잭션. yield 뒤의 코드는 라우트가 예외를 발생시켜도 파이널라이저로 실행됩니다. 의존성당 yield는 하나뿐입니다.

fastapi
from fastapi import FastAPI, Depends

def get_db():
    db = open_db_session()       # acquire resource
    try:
        yield db                 # injected into the route
    finally:
        db.close()               # always runs after the request

app = FastAPI()

@app.get("/items")
def list_items(db = Depends(get_db)):
    return db.query("SELECT * FROM items")

전역 의존성

FastAPI()(또는 APIRouter)에 dependencies=[...]를 전달하면 반환 값을 주입하지 않고 모든 라우트에 강제됩니다. 전역 인증, 레이트 리밋, 요청 로깅에 유용합니다.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "supersecret":
        raise HTTPException(status_code=400, detail="X-Token missing")

def verify_key(x_key: str = Header()):
    if x_key != "realkey":
        raise HTTPException(status_code=400, detail="X-Key missing")

# applied to every route in the app
app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])

@app.get("/items")
def list_items():
    return [{"item": "a"}]   # token & key already checked

라우트별 의존성

데코레이터(또는 APIRouter)에 dependencies=[Depends(...)]를 쓰면 반환 값을 쓰지 않으면서 특정 라우트에 의존성을 요구합니다. 검사를 강제하면서 라우트 시그니처를 깔끔하게 유지합니다.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "secret":
        raise HTTPException(status_code=401, detail="bad token")

app = FastAPI()

@app.get("/public")
def public():
    return {"open": True}

@app.get("/private", dependencies=[Depends(verify_token)])
def private():
    return {"secret": "data"}
09

보안 (HTTPBasic / OAuth2 / JWT)

HTTP Basic 인증

HTTPBasic이 Authorization: Basic 헤더를 username/password로 파싱합니다. 타이밍 공격을 막으려 ==가 아니라 secrets.compare_digest를 쓰세요. 브라우저가 자격 증명을 요청하도록 항상 WWW-Authenticate: Basic과 함께 401을 반환하세요.

fastapi
import secrets
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

security = HTTPBasic()
app = FastAPI()

def get_current_user(credentials: HTTPBasicCredentials = Depends(security)):
    correct_user = secrets.compare_digest(credentials.username, "admin")
    correct_pass = secrets.compare_digest(credentials.password, "secret")
    if not (correct_user and correct_pass):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid credentials",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username

@app.get("/profile")
def profile(user: str = Depends(get_current_user)):
    return {"user": user}

OAuth2 Password Bearer

OAuth2PasswordBearer가 라우트가 Bearer 토큰을 기대한다고 선언하며, 의존성이 Authorization 헤더에서 이를 추출합니다. tokenUrl이 문서 UI에 자격 증명을 보낼 곳을 알립니다. 검증하기 전까지 토큰은 그냥 문자열입니다.

fastapi
from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordBearer

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

@app.get("/me")
def me(token: str = Depends(oauth2_scheme)):
    return {"token": token}

# client POSTs username+password to /token, receives an access token,
# then sends it as: Authorization: Bearer <token>

JWT 토큰 생성

토큰 서명에는 python-jose(또는 PyJWT)를 쓰세요. 'sub'(subject) 클레임이 관례상 사용자명이나 사용자 id를 담고, 'exp'가 만료를 정합니다. SECRET_KEY는 길고 무작위이며 환경에서 로드하세요 — 절대 커밋하지 마세요.

fastapi
from datetime import datetime, timedelta, timezone
from jose import jwt

SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"

def create_access_token(data: dict, expires_minutes: int = 30) -> str:
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + timedelta(minutes=expires_minutes)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

# token = create_access_token({"sub": "alice"})
# -> eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

JWT 토큰 디코드

jwt.decode가 서명과 'exp' 클레임을 자동 검증하며 실패 시 JWTError를 발생시킵니다. 클라이언트가 유효한 토큰을 제공하도록 알 수 있게 의존성을 WWW-Authenticate: Bearer와 함께 401로 매핑하세요.

fastapi
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"

def get_current_user(token: str = Depends(oauth2_scheme)) -> str:
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str | None = payload.get("sub")
        if username is None:
            raise credentials_exception
        return username
    except JWTError:
        raise credentials_exception

credentials_exception = HTTPException(
    status_code=status.HTTP_401_UNAUTHORIZED,
    detail="Could not validate credentials",
    headers={"WWW-Authenticate": "Bearer"},
)

비밀번호 해싱

평문 비밀번호를 절대 저장하지 마세요. salt와 해싱은 passlib의 bcrypt(또는 argon2)가 처리합니다. verify()가 평문 입력을 저장된 해시와 비교합니다. bcrypt 백엔드는 pip install passlib[bcrypt]로 받으세요.

fastapi
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def hash_password(plain: str) -> str:
    return pwd_context.hash(plain)

def verify_password(plain: str, hashed: str) -> bool:
    return pwd_context.verify(plain, hashed)

# usage when issuing tokens:
def authenticate_user(username: str, password: str):
    user = fake_db.get(username)
    if not user or not verify_password(password, user.hashed_password):
        return False
    return user

OAuth2 로그인 플로우

OAuth2PasswordRequestForm이 폼 인코딩된 POST(표준 OAuth2 password 플로우)에서 username/password를 읽습니다. access_token과 token_type: 'bearer'를 반환하세요. 이 엔드포인트가 OAuth2PasswordBearer의 tokenUrl이 가리키는 곳입니다.

fastapi
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm

app = FastAPI()

@app.post("/token")
def login(form: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form.username, form.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
        )
    token = create_access_token({"sub": user.username})
    return {"access_token": token, "token_type": "bearer"}

# OAuth2PasswordRequestForm parses username+password from form data
# and powers the 'Authorize' button in the Swagger UI.
10

미들웨어

미들웨어 추가

@app.middleware('http')가 모든 요청을 감싸는 함수를 등록합니다. 응답을 얻으려 call_next(request)를 await해야 하며, 반환 전에 검사하거나 수정할 수 있습니다. 미들웨어는 모든 라우트에 대해 실행됩니다.

fastapi
import time
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_process_time(request: Request, call_next):
    start = time.perf_counter()
    response = await call_next(request)
    duration = time.perf_counter() - start
    response.headers["X-Process-Time"] = f"{duration:.4f}"
    return response

커스텀 헤더 미들웨어

모든 응답에 있어야 하는 헤더(보안 헤더, 서버 배너, 트레이싱 ID)를 붙이는 적합한 자리가 미들웨어입니다. call_next를 await한 뒤 응답 객체를 변형하세요.

fastapi
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_banner(request: Request, call_next):
    response = await call_next(request)
    response.headers["X-Powered-By"] = "FastAPI"
    response.headers["X-Frame-Options"] = "DENY"
    return response

# every response now carries these headers

BaseHTTPMiddleware

재사용 가능하고 설정 가능한 미들웨어에는 BaseHTTPMiddleware를 서브클래싱해 app.add_middleware(MyMiddleware, **options)로 등록하세요. 내장 CORS, GZip, TrustedHost 미들웨어도 이렇게 추가됩니다.

fastapi
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import FastAPI, Request

class TimingMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        start = time.perf_counter()
        response = await call_next(request)
        response.headers["X-Duration"] = str(time.perf_counter() - start)
        return response

app = FastAPI()
app.add_middleware(TimingMiddleware)

# class-based middleware is reusable and configurable

HTTPS 리다이렉트

HTTPSRedirectMiddleware가 어떤 HTTP 요청이든 HTTPS 버전으로 308 리다이렉트합니다. TLS를 종료하는 로드밸런서 뒤에서 이를 써 클라이언트가 안전한 연결로 업그레이드하도록 하세요.

fastapi
from fastapi import FastAPI
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware

app = FastAPI()
app.add_middleware(HTTPSRedirectMiddleware)

# all HTTP requests are redirected to HTTPS (308)

신뢰 호스트

TrustedHostMiddleware가 Host 헤더가 허용 목록에 없는 요청을 거부해 Host 헤더 주입 공격을 막습니다. '*.example.com' 같은 와일드카드가 지원됩니다. 로컬 개발을 위해 'localhost'를 항상 포함하세요.

fastapi
from fastapi import FastAPI
from fastapi.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["example.com", "*.example.com", "localhost"],
)

# requests with a disallowed Host header get a 400 response

미들웨어 순서

Starlette은 들어오는 요청에 대해 LIFO 순서로 미들웨어를 실행합니다: 마지막에 추가된 것이 먼저 실행됩니다. CORS를 이르게(preflight가 동작하도록) 추가하고 GZip은 뒤에 추가하세요. 어떤 미들웨어가 설정한 헤더를 다른 미들웨어가 못 보는 이유를 디버깅할 때 이를 기억하세요.

fastapi
from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Middleware runs in REVERSE order of registration for requests,
# and in registration order for responses.
app.add_middleware(GZipMiddleware, minimum_size=1000)
app.add_middleware(CORSMiddleware, allow_origins=["*"])

# request flow:  CORS -> GZip -> route
# response flow: route -> GZip -> CORS
11

CORS

CORSMiddleware 설정

CORSMiddleware가 CORS 프리플라이트(OPTIONS)를 처리하고 Access-Control-* 헤더를 추가합니다. allow_origins에는 허용되는 정확한 오리진을 나열해야 하며, 프로덕션에서는 ['*']가 아니라 특정 URL 목록을 쓰세요.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com", "https://www.example.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/api/data")
def data():
    return {"data": 1}

모든 오리진 허용 (개발 전용)

allow_origins=['*']는 어떤 오리진이든 허용하지만 allow_credentials=True와 결합할 수 없습니다(브라우저가 거부합니다). 완전히 공개된 API를 개발할 때만 쓰고, 프로덕션에서는 실제 오리진을 나열하세요.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
    # allow_credentials=True CANNOT be combined with allow_origins=["*"]
)

자격 증명 허용

allow_credentials=True가 브라우저가 교차 출처로 쿠키와 Authorization 헤더를 보내게 합니다. 특정 오리진이 필요합니다(절대 '*' 불가). 브라우저가 응답에 Access-Control-Allow-Credentials: true를 설정합니다.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_credentials=True,    # send cookies / Authorization
    allow_methods=["GET", "POST"],
    allow_headers=["Authorization", "Content-Type"],
)

# needed when the frontend sends cookies or credentials with requests

허용 메서드 & 헤더

allow_methods/allow_headers가 브라우저가 보낼 수 있는 것을 제한합니다. expose_headers는 프런트엔드 JavaScript가 읽을 수 있는 응답 헤더를 나열합니다(브라우저는 그 외 커스텀 헤더를 숨깁니다). 프리플라이트 응답은 브라우저가 캐시합니다.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
    allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
    expose_headers=["X-Total-Count", "X-Process-Time"],
)

# expose_headers lets the frontend JS read these response headers

프리플라이트 요청

'단순하지 않은' 요청(예: 커스텀 헤더, PUT/DELETE, JSON 콘텐츠 타입)에 브라우저가 OPTIONS 프리플라이트를 보냅니다. CORSMiddleware가 OPTIONS를 가로채 허용된 메서드/헤더로 응답합니다. max_age가 브라우저가 그 답을 캐시하는 기간을 제어합니다.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_methods=["*"],
    allow_headers=["*"],
    max_age=600,   # browser caches preflight result for 600s
)

# Browser sends OPTIONS preflight for non-simple requests;
# CORSMiddleware answers automatically with the right headers.

동적 오리진 검증

동적 허용 목록에는 정적 목록 대신 allow_origin_regex(요청의 Origin과 매칭)를 쓰세요. 유효한 오리진이 패턴을 따를 때(예: example.com의 모든 서브도메인) 편리합니다.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

VALID_DOMAINS = {"example.com", "staging.example.com"}

def origin_check(origin: str) -> str | None:
    if origin and origin.replace("https://", "").replace("http://", "") in VALID_DOMAINS:
        return origin
    return None

app.add_middleware(
    CORSMiddleware,
    allow_origin_regex=r"https://.*\.example\.com",
    allow_methods=["*"],
    allow_headers=["*"],
)
12

예외 처리

HTTPException 발생

라우트나 의존성 어디에서든 raise HTTPException으로 조기 종료하고 오류 응답을 반환하세요. detail은 문자열, dict, 목록이 될 수 있습니다 — JSON의 'detail' 필드가 됩니다. headers는 선택적으로 응답 헤더를 더합니다.

fastapi
from fastapi import FastAPI, HTTPException, status

app = FastAPI()

items = {1: "Apple", 2: "Banana"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id not in items:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
            headers={"X-Error": "missing"},
        )
    return {"item": items[item_id]}

커스텀 예외

@app.exception_handler(MyException)로 핸들러를 등록하면 어떤 커스텀 예외든 HTTP 응답으로 변환됩니다. 핸들러가 요청과 예외를 받습니다. 앱의 도메인 오류 형식이 중앙화됩니다.

fastapi
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name

app = FastAPI()

@app.exception_handler(UnicornException)
async def unicorn_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops, {exc.name} did it again"},
    )

@app.get("/unicorns/{name}")
def read_unicorn(name: str):
    if name == "yolo":
        raise UnicornException(name=name)
    return {"name": name}

검증 오류 오버라이드

입력이 Pydantic 검증에 실패하면 RequestValidationError가 발생합니다. 422 응답 모양을 커스터마이징하려(예: 회사 전역 오류 봉투에 맞추려) @app.exception_handler(RequestValidationError)로 핸들러를 오버라이드하세요.

fastapi
from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={
            "success": False,
            "errors": exc.errors(),
            "body": exc.body,
        },
    )

HTTPException 핸들러 오버라이드

발생하는 모든 HTTPException에 걸쳐 일관된 오류 JSON 모양을 강제하려 기본 HTTPException 핸들러를 오버라이드하세요. 핸들러를 다시 바인딩할 때는 raise에서 쓰는 것과 같은 fastapi.exceptions.HTTPException 클래스를 임포트하세요.

fastapi
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException as FastAPIHTTPException

app = FastAPI()

@app.exception_handler(FastAPIHTTPException)
async def custom_http_handler(request, exc: FastAPIHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "success": False,
            "status": exc.status_code,
            "message": exc.detail,
        },
        headers=exc.headers,
    )

흔한 상태 코드

status 모듈이 모든 HTTP 상태 코드의 이름 붙은 상수를 제공해 마법 숫자를 피합니다. FastAPI 앱에서 가장 흔한 것: 200(기본 GET), 201(생성됨), 204(콘텐츠 없음), 422(검증).

fastapi
from fastapi import FastAPI, status

app = FastAPI()

@app.get("/ok", status_code=status.HTTP_200_OK)
def ok(): return {"ok": True}

@app.post("/create", status_code=status.HTTP_201_CREATED)
def create(): return {"id": 1}

@app.get("/no-content", status_code=status.HTTP_204_NO_CONTENT)
def no_content(): return None

@app.get("/not-found")
def missing():
    # raise HTTPException(status.HTTP_404_NOT_FOUND, "nope")
    ...

# Other common: 400 BAD_REQUEST, 401 UNAUTHORIZED,
# 403 FORBIDDEN, 409 CONFLICT, 422 UNPROCESSABLE_ENTITY, 500 INTERNAL_SERVER_ERROR

일반 예외 핸들러

기반 Exception에 대한 핸들러를 등록하면 아직 처리되지 않은 모든 것을 잡아 스택트레이스가 클라이언트로 새는 것을 막습니다. 전체 트레이스백은 항상 서버 측에 로그하고, 클라이언트에는 일반적인 500을 반환하세요.

fastapi
import logging
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

logger = logging.getLogger("uvicorn.error")
app = FastAPI()

@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception):
    logger.exception("Unhandled error on %s", request.url.path)
    return JSONResponse(
        status_code=500,
        content={"detail": "Internal Server Error"},
    )

@app.get("/boom")
def boom():
    raise RuntimeError("something exploded")
13

백그라운드 작업

기본 BackgroundTasks

BackgroundTasks가 응답이 전송된 뒤 함수를 실행합니다 — 로깅, 이메일, 캐시 무효화 같은 fire-and-forget 작업에 완벽합니다. add_task가 응답을 막지 않고 함수(와 인수)를 예약합니다.

fastapi
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def write_log(message: str):
    with open("log.txt", "a") as f:
        f.write(message + "\n")

@app.post("/send")
def send_notification(background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, "notification sent")
    return {"message": "notification queued"}

여러 작업

원하는 만큼 작업을 추가하세요; 응답이 반환된 뒤 추가된 순서대로 순차 실행됩니다. 같은 프로세스에서 실행되므로 빠르고 논블로킹으로 유지하거나 진짜 큐(Celery, RQ, Dramatiq)로 옮기세요.

fastapi
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def send_email(to: str, subject: str): ...
def update_cache(key: str): ...
def notify_slack(msg: str): ...

@app.post("/signup")
def signup(background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, "[email protected]", "Welcome")
    background_tasks.add_task(update_cache, "user_count")
    background_tasks.add_task(notify_slack, "new signup")
    return {"status": "ok"}

의존성이 있는 작업

BackgroundTasks는 어떤 의존성처럼 주입됩니다. 작업 함수는 요청 시점에 캡처된 값(예: DB 세션)을 받을 수 있습니다. 작업이 요청 라이프사이클 스코프 안에서 실행되므로, 의존성에서 yield/닫힌 리소스는 작업이 끝난 뒤 닫힙니다.

fastapi
from fastapi import FastAPI, BackgroundTasks, Depends

app = FastAPI()

def get_db_session():
    db = "session"
    yield db

def write_log(db, message: str):
    print(db, message)

@app.get("/items")
def list_items(background_tasks: BackgroundTasks, db = Depends(get_db_session)):
    background_tasks.add_task(write_log, db, "list called")
    return {"items": []}

비동기 작업 함수

백그라운드 작업 함수는 동기(스레드풀에서 실행)나 비동기(이벤트 루프에서 await)가 될 수 있습니다. 스스로 비동기 라이브러리를 쓰는 I/O 바운드 작업에는 비동기 작업을, CPU/블로킹 작업에는 동기 작업을 쓰세요.

fastapi
from fastapi import FastAPI, BackgroundTasks
import httpx

app = FastAPI()

async def fetch_url(url: str):
    async with httpx.AsyncClient() as client:
        r = await client.get(url)
        return r.status_code

@app.post("/webhook")
def webhook(url: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(fetch_url, url)
    return {"queued": url}

백그라운드 vs Celery

재시작 시 잃어버려도 괜찮은 가볍고 중요하지 않은 작업에는 BackgroundTasks를 쓰세요. 크래시를 살아남거나 재시도하거나 기기들에 걸쳐 확장해야 하는 작업에는 Redis나 RabbitMQ 같은 브로커가 있는 진짜 작업 큐(Celery, RQ, Dramatiq, Arq)를 쓰세요.

fastapi
# BackgroundTasks: in-process, no broker, lost if process crashes
@app.post("/quick")
def quick(tasks: BackgroundTasks):
    tasks.add_task(small_job)
    return {"ok": True}

# Celery/RQ/Dramatiq: separate workers, persistent, retryable
# from celery import Celery
# @celery.task
# def big_job(payload): ...
#
# @app.post("/heavy")
# def heavy(payload: dict):
#     big_job.delay(payload)
#     return {"queued": True}

이메일 전송 예제

이메일 전송이 클래식한 BackgroundTasks 활용 사례입니다: 느리고 사용자가 기다리지 말아야 합니다. 응답이 즉시 돌아오고 이메일은 그 뒤에 발송됩니다. 대량 전송에는 재시도가 있는 큐와 이메일 서비스 SDK를 권합니다.

fastapi
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel, EmailStr

class Message(BaseModel):
    to: EmailStr
    subject: str
    body: str

app = FastAPI()

def send_email(to: str, subject: str, body: str):
    # smtplib or your provider's SDK
    import smtplib
    with smtplib.SMTP("localhost") as s:
        s.sendmail("[email protected]", to, f"Subject: {subject}\n\n{body}")

@app.post("/contact")
def contact(msg: Message, tasks: BackgroundTasks):
    tasks.add_task(send_email, msg.to, msg.subject, msg.body)
    return {"status": "queued", "to": msg.to}
14

WebSocket

WebSocket 기본

WebSocket 엔드포인트 정의에는 @app.websocket()을 쓰세요. 전송/수신 전에 반드시 accept()해야 합니다. 함수는 보통 메시지를 읽는 루프를 돌며, receive_text/receive_bytes/receive_json이 모두 클라이언트의 데이터를 await합니다.

fastapi
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        data = await ws.receive_text()
        await ws.send_text(f"echo: {data}")

# client (browser):
# const ws = new WebSocket("ws://localhost:8000/ws");
# ws.onmessage = (e) => console.log(e.data);

JSON 전송

send_json()과 receive_json()이 직렬화를 대신 처리해 소켓 위에서 JSON 객체를 교환합니다. 바이너리 데이터에는 send_bytes/receive_bytes를 쓰세요. 각 send/receive가 WebSocket의 별개 프레임입니다.

fastapi
import json
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        msg = await ws.receive_json()
        await ws.send_json({"reply": msg.get("text", "").upper()})

# send_text / send_bytes / send_json helpers are available

WebSocket 종료

클라이언트가 연결을 닫으면 WebSocketDisconnect가 발생합니다 — 정리하려 이를 잡으세요. 정상 종료에는 ws.close(code=1000)를 호출하세요; 흔한 코드: 1000(정상), 1008(정책 위반), 1011(서버 오류).

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

app = FastAPI()

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    await ws.accept()
    try:
        while True:
            data = await ws.receive_text()
            if data == "quit":
                await ws.close(code=1000)
                break
            await ws.send_text(data)
    except WebSocketDisconnect:
        print("client disconnected")

연결 매니저

ConnectionManager가 활성 소켓을 추적해 연결된 모든 클라이언트로 방송할 수 있게 합니다(예: 채팅방). 닫힌 연결로 전송하는 것과 메모리 경계를 유지하기 위해 연결이 끊기면 항상 소켓을 제거하세요.

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

class ConnectionManager:
    def __init__(self):
        self.active: list[WebSocket] = []

    async def connect(self, ws: WebSocket):
        await ws.accept()
        self.active.append(ws)

    def disconnect(self, ws: WebSocket):
        self.active.remove(ws)

    async def broadcast(self, message: str):
        for ws in self.active:
            await ws.send_text(message)

manager = ConnectionManager()
app = FastAPI()

@app.websocket("/chat")
async def chat(ws: WebSocket):
    await manager.connect(ws)
    try:
        while True:
            msg = await ws.receive_text()
            await manager.broadcast(msg)
    except WebSocketDisconnect:
        manager.disconnect(ws)

쿼리 매개변수 WebSocket 인증

브라우저는 WebSocket 연결에 커스텀 헤더를 설정할 수 없으므로, 인증 토큰은 보통 쿼리 매개변수(또는 쿠키)로 전달됩니다. accept() 호출 전에 검증하고, 미인증이면 코드 1008(정책 위반)로 닫으세요.

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException

app = FastAPI()

async def authenticate(token: str) -> str:
    if token != "secret":
        raise HTTPException(status_code=401)
    return "alice"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    token = ws.query_params.get("token")
    if not token:
        await ws.close(code=1008)
        return
    user = await authenticate(token)
    await ws.accept()
    try:
        while True:
            data = await ws.receive_text()
            await ws.send_text(f"{user}: {data}")
    except WebSocketDisconnect:
        pass

의존성이 있는 WebSocket

의존성은 HTTP 라우트처럼 WebSocket 엔드포인트에서도 쓸 수 있지만, 초기 핸드셰이크에서 읽는 의존성(헤더, 쿼리 매개변수, 쿠키)만 의미가 있습니다 — 본문이 없습니다. 평소처럼 Depends()로 주입하세요.

fastapi
from fastapi import FastAPI, WebSocket, Depends, Header

app = FastAPI()

def token_validator(token: str = Header(default="")):
    # for WS, headers come from the initial HTTP handshake
    return token == "valid"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket, valid: bool = Depends(token_validator)):
    if not valid:
        await ws.close(code=1008)
        return
    await ws.accept()
    while True:
        msg = await ws.receive_text()
        await ws.send_text(msg)
15

데이터베이스 (SQLAlchemy)

SQLAlchemy 설정

create_engine이 DB 연결 풀을 세팅하고, SessionLocal이 세션 팩토리이며, Base가 모델용 선언적 베이스입니다. FastAPI와의 SQLite는 요청이 다른 스레드에서 실행될 수 있으므로 check_same_thread=False를 설정하세요.

fastapi
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"
# postgresql: "postgresql://user:pass@localhost:5432/dbname"

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    connect_args={"check_same_thread": False},  # sqlite only
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()

세션 의존성

yield 의존성이 DB 세션을 제공하는 정석 방법입니다: 각 요청이 새 세션을 받아 finally 블록에서 닫힙니다. 라우트가 예외를 발생시켜도 정리가 보장됩니다.

fastapi
from fastapi import Depends
from sqlalchemy.orm import Session

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get("/items")
def list_items(db: Session = Depends(get_db)):
    return db.query(Item).all()

# each request gets its own session, closed automatically afterward

모델 정의

테이블은 Base를 상속하는 SQLAlchemy ORM 모델로 정의합니다. 프로덕션 스키마 마이그레이션에는 create_all()보다 Alembic을 쓰세요. 컬럼은 인덱싱·nullable 가능하며 DB나 Python 수준에서 기본값을 가질 수 있습니다.

fastapi
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.orm import declarative_base

Base = declarative_base()

class Item(Base):
    __tablename__ = "items"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True, nullable=False)
    price = Column(Integer, default=0)
    in_stock = Column(Boolean, default=True)

# create tables (for dev; use Alembic migrations in prod)
Base.metadata.create_all(bind=engine)

레코드 생성

add()가 새 행을 스테이징하고, commit()이 DB에 기록하며, refresh()가 인스턴스를 서버 생성 값(자동 증가 id 등)으로 다시 불러옵니다. 여러 쓰기는 트랜잭션으로 감싸 마지막에 한 번 commit하세요.

fastapi
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session

app = FastAPI()

@app.post("/items", status_code=201)
def create_item(payload: ItemCreate, db: Session = Depends(get_db)):
    item = Item(name=payload.name, price=payload.price)
    db.add(item)
    db.commit()
    db.refresh(item)        # load generated id
    return item

레코드 조회

db.query(Model)가 쿼리를 시작합니다; .filter()가 WHERE 조건을 적용하고, .offset()/.limit()가 페이징하며, .first()가 한 행이나 None을, .all()이 목록을 반환합니다. 단순 동등 조건에는 .filter_by(name=x)를 쓰세요.

fastapi
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session

app = FastAPI()

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
    return db.query(Item).offset(skip).limit(limit).all()

@app.get("/items/{item_id}")
def get_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    return item

업데이트 & 삭제

부분 업데이트는 model_dump(exclude_unset=True)를 순회해 제공된 필드만 바뀌게 하세요. delete()가 제거를 스테이징하고, commit()이 확정합니다. 성공한 DELETE에는 204 No Content를 반환하세요.

fastapi
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session

app = FastAPI()

@app.put("/items/{item_id}")
def update_item(item_id: int, payload: ItemUpdate, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    for k, v in payload.model_dump(exclude_unset=True).items():
        setattr(item, k, v)
    db.commit()
    db.refresh(item)
    return item

@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if item:
        db.delete(item)
        db.commit()
16

데이터베이스 (Tortoise ORM)

Tortoise 설정

Tortoise ORM은 async 네이티브로 FastAPI와 잘 어울립니다. 시작 시 db_url과 모델이 담긴 모듈(들)로 초기화하세요. 개발에는 generate_schemas()가 괜찮고, 프로덕션 마이그레이션에는 Aerich를 쓰세요. 새 코드에는 on_event 대신 lifespan 핸들러를 쓰세요.

fastapi
from fastapi import FastAPI
from tortoise import Tortoise

app = FastAPI()

async def init():
    await Tortoise.init(
        db_url="sqlite://db.sqlite3",
        modules={"models": ["app.models"]},
    )
    await Tortoise.generate_schemas()

@app.on_event("startup")
async def startup():
    await init()

@app.on_event("shutdown")
async def shutdown():
    await Tortoise.close_connections()

모델 정의

Tortoise 모델은 Model을 상속하고 tortoise.fields로 필드를 선언합니다. 필드 타입이 DB 컬럼 타입에 매핑됩니다. 테이블 이름은 안쪽 Meta 클래스에 설정합니다. 관계는 ForeignKeyField, ManyToManyField 등을 씁니다.

fastapi
from tortoise import fields
from tortoise.models import Model

class Item(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=100)
    price = fields.FloatField(default=0.0)
    created_at = fields.DatetimeField(auto_now_add=True)

    class Meta:
        table = "items"

    def __str__(self):
        return self.name

레코드 생성

Item.create()는 새 행을 삽입하고 반환하는 코루틴입니다. Pydantic 응답을 반환하려 from_tortoise_orm()(tortoise.contrib.pydantic 경유)으로 BaseModel을 만드세요 — Tortoise가 비동기 로드된 관계를 올바르게 직렬화합니다.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel
from .models import Item

app = FastAPI()

class ItemIn(BaseModel):
    name: str
    price: float

@app.post("/items", response_model=ItemOut, status_code=201)
async def create_item(payload: ItemIn):
    item = await Item.create(name=payload.name, price=payload.price)
    return await ItemOut.from_tortoise_orm(item)

비동기 쿼리

Tortoise 쿼리는 await됩니다: .all()이 queryset을 반환하고, .filter()가 조건을 더하며, .get_or_none()이 한 행이나 None을, .first()가 첫 매칭을 반환합니다. 정확히 한 행을 기대하지 않는 한 .get()은 피하세요(없으면 예외).

fastapi
from fastapi import FastAPI, HTTPException
from .models import Item

app = FastAPI()

@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
    return await Item.all().offset(skip).limit(limit)

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    item = await Item.get_or_none(id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    return item

업데이트 & 삭제

모델 속성을 수정한 뒤 행을 갱신하려 await save(), 대량 갱신에는 await Item.filter(id=...).update(name=x)를 쓰세요. 행 제거는 await item.delete()입니다. 각 메서드가 코루틴이므로 반드시 await하세요.

fastapi
from fastapi import FastAPI, HTTPException
from .models import Item

app = FastAPI()

@app.put("/items/{item_id}")
async def update_item(item_id: int, name: str):
    item = await Item.get_or_none(id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    item.name = name
    await item.save()
    return item

@app.delete("/items/{item_id}", status_code=204)
async def delete_item(item_id: int):
    item = await Item.get_or_none(id=item_id)
    if item:
        await item.delete()

Tortoise Pydantic 스키마

tortoise.contrib.pydantic이 Tortoise 모델에서 직접 Pydantic 모델을 생성하므로 스키마를 두 벌 유지할 필요가 없습니다. 단일 객체에는 pydantic_model_creator를, 목록 응답에는 pydantic_queryset_creator를 쓰세요.

fastapi
from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
from .models import Item

ItemOut = pydantic_model_creator(Item, name="ItemOut")
ItemList = pydantic_queryset_creator(Item)

@app.get("/items", response_model=ItemList)
async def list_items():
    return await Item.all()

# auto-generates a Pydantic model from the Tortoise model,
# including types and docstrings.
17

테스트 (TestClient)

TestClient 기본

TestClient가 앱을 감싸 프로세스 내에서(실제 소켓 없이) 요청을 보내게 합니다. httpx 기반이며 pytest와 바로 동작합니다. 프로덕션에서 실행하는 것과 같은 앱 인스턴스를 임포트하세요.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"Hello": "World"}

# TestClient is based on httpx; no network is involved —
# it calls the ASGI app directly in-process.

GET & POST 테스트

JSON 본문에는 json=, 쿼리 매개변수에는 params=, 헤더에는 headers=, multipart 업로드에는 files=를 전달하세요. 검증 실패는 422를 반환합니다 — status_code와 오류 'detail'의 구조를 단언하세요.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_create_item():
    response = client.post(
        "/items",
        json={"name": "Apple", "price": 0.5},
    )
    assert response.status_code == 201
    assert response.json()["name"] == "Apple"

def test_validation_error():
    response = client.post("/items", json={"name": "Apple"})  # missing price
    assert response.status_code == 422

Pytest 픽스처

TestClient를 반환하는 pytest 픽스처가 테스트를 DRY하게 유지하고 각 테스트가 새 클라이언트를 얻게 합니다. DB 기반 테스트에는 테이블을 만들/지우거나 테스트마다 트랜잭션 롤백을 써 격리하는 픽스처를 추가하세요.

fastapi
import pytest
from fastapi.testclient import TestClient
from main import app

@pytest.fixture
def client():
    return TestClient(app)

def test_read(client):
    r = client.get("/items")
    assert r.status_code == 200

def test_create(client):
    r = client.post("/items", json={"name": "X"})
    assert r.status_code == 201

# run: pytest -v

의존성 오버라이드

app.dependency_overrides가 테스트 동안 의존성(실제 DB 세션이나 인증 같은)을 목/가짜로 교체하며, 라우트는 바꾸지 않습니다. 외부 서비스로부터 격리해 엔드포인트를 테스트하는 정석 방법입니다. 테스트 뒤에는 지우세요.

fastapi
from fastapi.testclient import TestClient
from main import app, get_db

def get_test_db():
    # return a test session or mock
    yield FakeSession()

app.dependency_overrides[get_db] = get_test_db

client = TestClient(app)

def test_items():
    r = client.get("/items")
    assert r.status_code == 200

# restore afterwards:
app.dependency_overrides.clear()

인증 테스트

OAuth2PasswordRequestForm은 폼 인코딩 데이터(json=이 아니라 data=)를 기대합니다. 이후 보호된 요청에는 반환된 토큰을 Authorization: Bearer 헤더로 쓰세요. 인증을 완전히 우회하려 get_current_user 의존성을 대신 오버라이드하세요.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def get_token():
    r = client.post(
        "/token",
        data={"username": "admin", "password": "secret"},
    )
    return r.json()["access_token"]

def test_protected():
    token = get_token()
    r = client.get(
        "/me",
        headers={"Authorization": f"Bearer {token}"},
    )
    assert r.status_code == 200
    assert r.json()["username"] == "admin"

WebSocket 테스트

TestClient.websocket_connect()가 컨텍스트 매니저 안에서 WebSocket을 엽니다. 메시지 교환에는 send_text/receive_text(json/bytes 변형 포함)를 쓰세요. 닫힌 연결에서 수신하면 WebSocketDisconnect가 발생합니다.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_websocket():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("hello")
        data = ws.receive_text()
        assert data == "echo: hello"

def test_websocket_close():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("quit")
        # the server closes the connection
18

OpenAPI 문서

Swagger UI

FastAPI가 라우트, 타입, 독스트링으로부터 /docs에 인터랙티브 Swagger UI를 자동 생성합니다. 앱에 title/description/version을 설정하고, UI를 풍부하게 하려 각 라우트에 독스트링이나 summary/description을 추가하세요.

fastapi
from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="Sample API with auto docs",
    version="1.0.0",
)

@app.get("/items", summary="List items", description="Returns all items")
def list_items():
    """Get every item in the catalog."""
    return [{"id": 1}]

# interactive docs at: http://localhost:8000/docs

ReDoc

/redoc의 ReDoc은 Swagger의 읽기 전용 문서 중심 대안입니다. raw OpenAPI 스키마는 /openapi.json에 있으며 다른 도구에 먹일 수 있습니다. 문서 비활성화는 docs_url=None, redoc_url=None, openapi_url=None입니다(예: 프로덕션).

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"hello": "world"}

# ReDoc (alternative docs UI) at: http://localhost:8000/redoc
# raw OpenAPI JSON at: http://localhost:8000/openapi.json

# disable docs entirely:
# app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

태그 & 그룹핑

태그가 문서 UI에서 라우트를 그룹화합니다. 태그 메타데이터(이름, 설명, externalDocs)를 openapi_tags에 미리 선언하면 어떤 라우트가 쓰기 전에도 그룹이 나타납니다. 문서에서 엔드포인트를 폐기 표시하려 deprecated=True를 설정하세요.

fastapi
from fastapi import FastAPI

app = FastAPI(openapi_tags=[
    {"name": "users", "description": "User management"},
    {"name": "items", "description": "Item operations"},
])

@app.get("/users", tags=["users"])
def list_users(): ...

@app.post("/items", tags=["items"])
def create_item(): ...

@app.get("/items/{id}", tags=["items"], deprecated=True)
def get_item(id: int): ...

라우트 메타데이터

데코레이터가 OpenAPI로 흐르는 메타데이터를 받습니다: summary(짧은 제목), description(긴 텍스트), response_description, tags, deprecated, status_code. 명시적으로 전달하지 않으면 독스트링이 설명으로 쓰입니다.

fastapi
from fastapi import FastAPI, status
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.post(
    "/items",
    response_model=Item,
    status_code=status.HTTP_201_CREATED,
    summary="Create an item",
    description="Creates a new item and returns it.",
    tags=["items"],
    response_description="The created item",
)
def create_item(item: Item):
    """Create endpoint docstring — also shown in docs."""
    return item

필드 예제

Field(examples=[...])와 Body(examples=[...])가 Swagger UI의 'Try it out'과 예제 드롭다운에 예제 페이로드를 추가합니다. 본문 예제는 요약과 함께 유효/무효 입력을 보여주는 여러 케이스를 포함할 수 있습니다.

fastapi
from pydantic import BaseModel, Field
from fastapi import FastAPI, Body

class Item(BaseModel):
    name: str = Field(examples=["Apple"])
    price: float = Field(examples=[0.5], gt=0)

app = FastAPI()

@app.post("/items")
def create_item(item: Item):
    return item

@app.post("/manual")
def manual(
    item: Item = Body(
        examples=[
            {"summary": "valid", "value": {"name": "Apple", "price": 0.5}},
            {"summary": "invalid", "value": {"name": "Apple", "price": -1}},
        ],
    ),
):
    return item

커스텀 OpenAPI 스키마

생성된 스키마를 커스터마이징하려 app.openapi를 오버라이드하세요 — 로고, 추가 메타데이터, 연산 제거/변형. 결과는 app.openapi_schema에 캐시해 한 번만 생성되게 하세요. /openapi.json이 서빙하는 것이 이 스키마입니다.

fastapi
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title="Custom API",
        version="2.0.0",
        routes=app.routes,
    )
    schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
    app.openapi_schema = schema
    return schema

app.openapi = custom_openapi
19

배포 (Uvicorn / Gunicorn)

Uvicorn 프로덕션

프로덕션에서는 리버스 프록시(Nginx, Caddy, 클라우드 로드밸런서) 뒤에서 Uvicorn을 실행하세요. 앱이 X-Forwarded-For/X-Forwarded-Proto로 클라이언트의 실제 IP/호스트를 보도록 --proxy-headers를 쓰세요. 프로덕션에서는 --reload를 피하세요.

fastapi
# Run directly with uvicorn (single worker)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1

# Recommended: behind a reverse proxy (nginx) on port 8000
# Use --proxy-headers so X-Forwarded-* is trusted
uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'

Uvicorn 워커가 있는 Gunicorn

Gunicorn이 여러 Uvicorn 워커 프로세스를 관리해 우아한 리로드, 크래시 시 재시작, 사전 포크 스케일링을 줍니다. UvicornWorker 클래스를 쓰세요. workers는 출발점으로 (2 * CPU 코어 + 1)로 두고 벤치마크하세요.

fastapi
# install the uvicorn worker class
pip install "uvicorn[standard]" gunicorn

# run 4 worker processes managed by gunicorn
gunicorn main:app \
    -w 4 \
    -k uvicorn.workers.UvicornWorker \
    -b 0.0.0.0:8000 \
    --timeout 120

# -w workers (commonly 2*CPU+1), -k worker class

Docker 배포

슬림 Python 베이스 이미지가 이미지를 작게 유지합니다. Docker의 레이어 캐시를 활용하려 코드 복사 전에 의존성을 설치하세요. 컨테이너 안에서 gunicorn+uvicorn 워커로 실행하고, 호스트나 오케스트레이터에 8000 포트를 노출하세요.

fastapi
# Dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["gunicorn", "main:app", "-w", "4", \
     "-k", "uvicorn.workers.UvicornWorker", \
     "-b", "0.0.0.0:8000"]

# build & run:
# docker build -t myapi .
# docker run -p 8000:8000 myapi

환경 설정

pydantic-settings(구 pydantic.BaseSettings)가 타입 검증과 함께 환경 변수와 .env 파일에서 설정을 로드합니다. 이로써 같은 이미지가 env var만 바꿔 다른 환경(개발/스테이징/운영)에서 실행됩니다.

fastapi
import os
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str = "sqlite:///./app.db"
    secret_key: str = "change-me"
    debug: bool = False
    allowed_origins: list[str] = ["http://localhost:3000"]

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

# .env file:
# DATABASE_URL=postgresql://user:pass@db:5432/app
# SECRET_KEY=long-random-string
# DEBUG=false

Nginx 리버스 프록시

Nginx가 HTTP(S)를 종료하고 localhost:8000의 Uvicorn으로 전달합니다. 앱이 실제 클라이언트 IP와 스킴을 보도록 X-Forwarded-* 헤더를 설정하세요(Uvicorn에는 --proxy-headers 사용). Upgrade/Connection 줄이 WebSocket 지원을 켭니다.

fastapi
# /etc/nginx/conf.d/api.conf
server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

스케일링 & 동시성

스케일은 두 가지입니다: 기기당 더 많은 Uvicorn 워커 프로세스(CPU 바운드)와 로드밸런서 뒤의 더 많은 기기(수평). 비동기 앱에서는 이벤트 루프가 워커당 많은 동시 I/O 요청을 처리합니다. 오케스트레이터(k8s, ECS)가 라이브니스를 검사하도록 /health 엔드포인트를 추가하세요.

fastapi
# Workers = process count (vertical scaling); pick ~2*CPU
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

# Inside async app: concurrency is cooperative via the event loop.
# CPU-bound work blocks it — offload to a threadpool or task queue.

# Horizontal scaling: run several containers behind a load balancer.
# Use a shared store (Redis) for session state and rate limits.

# Health check endpoint for the balancer:
@app.get("/health")
def health():
    return {"status": "ok"}
20

고급 주제

Lifespan 이벤트

lifespan 컨텍스트 매니저가 폐기된 on_event('startup'/'shutdown') 핸들러를 대체합니다. yield 전 코드가 시작 시 실행되고, yield 뒤 코드가 — 시작이 실패해도 — 종료 시 실행됩니다. DB 연결, ML 모델, 캐시 초기화에 쓰세요.

fastapi
from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # runs at startup
    print("starting up")
    app.state.cache = {}
    yield
    # runs at shutdown
    print("shutting down")
    await app.state.cache.clear()

app = FastAPI(lifespan=lifespan)

# the old @app.on_event("startup") / "shutdown" are deprecated
# in favor of the lifespan handler above.

서브 애플리케이션 (마운트)

app.mount()가 경로 접두사 아래 서브 애플리케이션을 붙입니다 — 버저닝된 API나 여러 앱 결합에 유용합니다. 각 서브 앱이 자체 라우트와 OpenAPI 스키마를 가지며, 부모의 문서에는 기본적으로 자식의 라우트가 포함되지 않습니다.

fastapi
from fastapi import FastAPI

app = FastAPI()

api_v1 = FastAPI()
api_v2 = FastAPI()

@api_v1.get("/items")
def v1_items():
    return {"version": 1}

@api_v2.get("/items")
def v2_items():
    return {"version": 2}

app.mount("/v1", api_v1)
app.mount("/v2", api_v2)

# GET /v1/items -> {"version": 1}
# GET /v2/items -> {"version": 2}

APIRouter

APIRouter가 관련 라우트를 공유 접두사, 태그, 의존성, 응답을 가진 모듈로 묶습니다. app.include_router(router)로 포함하세요(자체 접두사나 태그와 함께도 가능). 단순하지 않은 앱을 구조화하는 표준 패턴입니다.

fastapi
from fastapi import APIRouter, Depends

router = APIRouter(
    prefix="/items",
    tags=["items"],
    dependencies=[Depends(verify_token)],
    responses={404: {"description": "Not found"}},
)

@router.get("/")
def list_items():
    return []

@router.get("/{item_id}")
def get_item(item_id: int):
    return {"id": item_id}

# in main.py: app.include_router(router)

정적 파일

StaticFiles가 정적 자산(이미지, CSS, JS)의 디렉터리를 URL 접두사로 서빙합니다. 디렉터리마다 한 번 마운트하세요. SPA 프런트엔드에는 index.html을 가리키는 마지막 catch-all 라우트를 마운트하세요. 정적 파일이 속도를 위해 라우팅 시스템을 우회합니다.

fastapi
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

# serve files from ./static at /static
app.mount("/static", StaticFiles(directory="static"), name="static")

# /static/logo.png -> ./static/logo.png
# /static/css/app.css -> ./static/css/app.css

스트리밍 응답

StreamingResponse가 전체 본문을 메모리에 만드는 대신 청크로(제너레이터/이터레이터) 생성되는 응답을 보냅니다 — 큰 CSV 내보내기, 파일 스트리밍, SSE에 이상적입니다. 클라이언트가 스트림을 올바르게 처리하도록 media_type을 적절히 설정하세요.

fastapi
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import csv, io

app = FastAPI()

def iter_csv():
    output = io.StringIO()
    writer = csv.writer(output)
    writer.writerow(["id", "name"])
    for i in range(1000):
        writer.writerow([i, f"name-{i}"])
        yield output.getvalue()
        output.seek(0)
        output.truncate(0)

@app.get("/export.csv")
def export():
    return StreamingResponse(
        iter_csv(),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=export.csv"},
    )

커스텀 라우트 클래스

APIRoute를 서브클래싱하면 각 엔드포인트를 건드리지 않고 모든 라우트 핸들러를 커스텀 로직(로깅, 트레이싱, 타이밍)으로 감쌀 수 있습니다. app.router.route_class를 설정하거나 APIRouter에 route_class를 전달하세요. 핸들러가 매칭되는 각 요청에 대해 실행됩니다.

fastapi
from fastapi import FastAPI, Request, Response
from fastapi.routing import APIRoute
from typing import Callable

class LoggingRoute(APIRoute):
    def get_route_handler(self) -> Callable:
        original = super().get_route_handler()
        async def handler(request: Request) -> Response:
            print(f"-> {request.method} {request.url.path}")
            response = await original(request)
            print(f"<- {response.status_code}")
            return response
        return handler

app = FastAPI()
app.router.route_class = LoggingRoute

@app.get("/items")
def items():
    return {"items": []}

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.