시작하기
첫 API
FastAPI는 Starlette과 Pydantic 위에 만들어졌습니다. uvicorn이 ASGI 서버입니다. --reload는 개발 중 자동 리로드를 켭니다.
# 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 --reloadUvicorn으로 실행
앱 인스턴스 'main:app'은 모듈 'main'의 변수 'app'을 뜻합니다. --reload는 개발에서만 쓰세요; 프로덕션에서는 없이 실행하고 프로세스 매니저를 쓰세요.
# 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 안에서 블로킹 호출을 섞으면 이벤트 루프를 막습니다.
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=으로 기본 성공 상태를 덮어쓰세요.
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를 직접 반환하세요.
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 셋업, 의존성은 별도 파일에 두세요.
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")경로 매개변수
기본 경로 매개변수
경로에서 캡처된 값은 타입 어노테 이션을 붙이기 전까지는 문자열입니다. 경로의 매개변수 이름은 함수 인수 이름과 정확히 일치해야 합니다.
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 응답을 반환합니다.
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()는 기본값을 설정할 수 없습니다.
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 오류와 함께 정밀한 경계 검증이 됩니다.
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} 같은 동적 패턴보다 먼저 선언하세요 — 아니면 동적 라우트가 특정 라우트를 가립니다.
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} patternEnum 경로 매개변수
경로 매개변수에 Enum 타입을 쓰면 사전 정의된 값으로 제한되고 OpenAPI 문서에 enum 스키마가 생성됩니다. 값이 문자열로 직렬화되도록 (str, Enum)을 서브클래싱하세요.
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"}쿼리 매개변수
기본 쿼리 매개변수
경로에 없는 함수 매개변수가 쿼리 매개변수가 됩니다. 기본값을 주면 선택이 되고, 쿼리 키가 없을 때 기본값이 쓰입니다.
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)을 쓰세요. 필수 매개변수는 그냥 기본값이 없으면 됩니다.
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=를 쓰세요.
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를 반환합니다.
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)를 쓰세요.
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(...)도 없으면 일반 어노테이션 매개변수도 필수입니다.
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요청 본문 (Pydantic)
BaseModel 기본
함수 매개변수로 선언된 Pydantic BaseModel이 JSON 요청 본문이 됩니다. FastAPI가 페이로드를 검증하고 타입을 변환하며 무효한 데이터에 422를 반환합니다. 기본값이 있는 필드는 선택입니다.
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가 문서에 예제를 더합니다.
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 스키마가 중첩 객체를 반영합니다.
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로 표면화합니다). 유지하려 (변환된) 값을 반환하세요.
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 같은 일반 기본값은 그 값으로 필드를 선택적으로 만듭니다.
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 기본값이 필요합니다.
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 resultResponse Model
response_model 기본
response_model이 반환된 데이터를 모델에 정의된 필드로만 필터링합니다 — 여분 필드가 있는 객체를 반환해도 그렇습니다. 비밀번호 같은 민감 필드를 숨기는 표준 방법입니다.
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에 추가로 적용됩니다.
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가 목록의 각 항목을 검증·직렬화합니다.
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인 필드를 생략합니다. 희소 응답에 유용합니다.
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는 입력에서 원래 속성 이름도 허용합니다.
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 서브클래스를 직접 반환하세요.
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)폼 & UploadFile
폼 데이터
Form()은 application/x-www-form-urlencoded나 multipart 폼 데이터에서 파싱되는 매개변수를 선언합니다. 같은 연산에서 Form()을 JSON 본문(BaseModel)과 섞을 수는 없습니다 — 콘텐츠 타입을 하나 고르세요.
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=secretUploadFile 기본
UploadFile은 .filename, .content_type, .read(), .write(), .close()를 갖춘 스트리밍 파일 표현입니다. async def 안에서는 'await file.read()'를 쓰세요. 큰 파일에는 메모리에 전부 올리지 않도록 file.file(SpooledTemporaryFile)을 권합니다.
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]을 선언하세요. 각 파일이 같은 필드 이름으로 전송됩니다. 목록의 파일 순서가 전송 순서와 일치합니다.
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 본문과는 여전히 결합할 수 없습니다.
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을 항상 정제하세요.
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)'으로 되감으세요. 진짜 타입 검사는 헤더만이 아니라 매직 바이트를 검사해야 합니다.
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)}의존성 주입
기본 Depends
Depends()가 함수의 반환 값을 경로 연산에 주입합니다. 공유 로직(페이징, 파싱, DB 세션)이 한 곳에 살고 엔드포인트 전반에서 재사용됩니다. 의존성의 매개변수도 OpenAPI에 문서화됩니다.
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()를 쓰세요. 인스턴스가 주입됩니다.
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가 전체 트리를 해석하고 각 결과를 요청별로 캐시하며 예외를 전파합니다. 계층화된 인증(토큰 → 사용자 → 권한)에 이상적입니다.
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 useryield 의존성 (정리)
yield 의존성 제너레이터가 정리가 필요한 리소스에 완벽합니다: DB 세션, 파일 핸들, 트랜잭션. yield 뒤의 코드는 라우트가 예외를 발생시켜도 파이널라이저로 실행됩니다. 의존성당 yield는 하나뿐입니다.
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=[...]를 전달하면 반환 값을 주입하지 않고 모든 라우트에 강제됩니다. 전역 인증, 레이트 리밋, 요청 로깅에 유용합니다.
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(...)]를 쓰면 반환 값을 쓰지 않으면서 특정 라우트에 의존성을 요구합니다. 검사를 강제하면서 라우트 시그니처를 깔끔하게 유지합니다.
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"}보안 (HTTPBasic / OAuth2 / JWT)
HTTP Basic 인증
HTTPBasic이 Authorization: Basic 헤더를 username/password로 파싱합니다. 타이밍 공격을 막으려 ==가 아니라 secrets.compare_digest를 쓰세요. 브라우저가 자격 증명을 요청하도록 항상 WWW-Authenticate: Basic과 함께 401을 반환하세요.
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에 자격 증명을 보낼 곳을 알립니다. 검증하기 전까지 토큰은 그냥 문자열입니다.
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는 길고 무작위이며 환경에서 로드하세요 — 절대 커밋하지 마세요.
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로 매핑하세요.
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]로 받으세요.
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 userOAuth2 로그인 플로우
OAuth2PasswordRequestForm이 폼 인코딩된 POST(표준 OAuth2 password 플로우)에서 username/password를 읽습니다. access_token과 token_type: 'bearer'를 반환하세요. 이 엔드포인트가 OAuth2PasswordBearer의 tokenUrl이 가리키는 곳입니다.
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.미들웨어
미들웨어 추가
@app.middleware('http')가 모든 요청을 감싸는 함수를 등록합니다. 응답을 얻으려 call_next(request)를 await해야 하며, 반환 전에 검사하거나 수정할 수 있습니다. 미들웨어는 모든 라우트에 대해 실행됩니다.
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한 뒤 응답 객체를 변형하세요.
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 headersBaseHTTPMiddleware
재사용 가능하고 설정 가능한 미들웨어에는 BaseHTTPMiddleware를 서브클래싱해 app.add_middleware(MyMiddleware, **options)로 등록하세요. 내장 CORS, GZip, TrustedHost 미들웨어도 이렇게 추가됩니다.
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 configurableHTTPS 리다이렉트
HTTPSRedirectMiddleware가 어떤 HTTP 요청이든 HTTPS 버전으로 308 리다이렉트합니다. TLS를 종료하는 로드밸런서 뒤에서 이를 써 클라이언트가 안전한 연결로 업그레이드하도록 하세요.
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'를 항상 포함하세요.
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은 뒤에 추가하세요. 어떤 미들웨어가 설정한 헤더를 다른 미들웨어가 못 보는 이유를 디버깅할 때 이를 기억하세요.
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 -> CORSCORS
CORSMiddleware 설정
CORSMiddleware가 CORS 프리플라이트(OPTIONS)를 처리하고 Access-Control-* 헤더를 추가합니다. allow_origins에는 허용되는 정확한 오리진을 나열해야 하며, 프로덕션에서는 ['*']가 아니라 특정 URL 목록을 쓰세요.
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를 개발할 때만 쓰고, 프로덕션에서는 실제 오리진을 나열하세요.
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를 설정합니다.
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가 읽을 수 있는 응답 헤더를 나열합니다(브라우저는 그 외 커스텀 헤더를 숨깁니다). 프리플라이트 응답은 브라우저가 캐시합니다.
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가 브라우저가 그 답을 캐시하는 기간을 제어합니다.
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의 모든 서브도메인) 편리합니다.
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=["*"],
)예외 처리
HTTPException 발생
라우트나 의존성 어디에서든 raise HTTPException으로 조기 종료하고 오류 응답을 반환하세요. detail은 문자열, dict, 목록이 될 수 있습니다 — JSON의 'detail' 필드가 됩니다. headers는 선택적으로 응답 헤더를 더합니다.
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 응답으로 변환됩니다. 핸들러가 요청과 예외를 받습니다. 앱의 도메인 오류 형식이 중앙화됩니다.
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)로 핸들러를 오버라이드하세요.
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 클래스를 임포트하세요.
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(검증).
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을 반환하세요.
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")백그라운드 작업
기본 BackgroundTasks
BackgroundTasks가 응답이 전송된 뒤 함수를 실행합니다 — 로깅, 이메일, 캐시 무효화 같은 fire-and-forget 작업에 완벽합니다. add_task가 응답을 막지 않고 함수(와 인수)를 예약합니다.
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)로 옮기세요.
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/닫힌 리소스는 작업이 끝난 뒤 닫힙니다.
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/블로킹 작업에는 동기 작업을 쓰세요.
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)를 쓰세요.
# 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를 권합니다.
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}WebSocket
WebSocket 기본
WebSocket 엔드포인트 정의에는 @app.websocket()을 쓰세요. 전송/수신 전에 반드시 accept()해야 합니다. 함수는 보통 메시지를 읽는 루프를 돌며, receive_text/receive_bytes/receive_json이 모두 클라이언트의 데이터를 await합니다.
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의 별개 프레임입니다.
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 availableWebSocket 종료
클라이언트가 연결을 닫으면 WebSocketDisconnect가 발생합니다 — 정리하려 이를 잡으세요. 정상 종료에는 ws.close(code=1000)를 호출하세요; 흔한 코드: 1000(정상), 1008(정책 위반), 1011(서버 오류).
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가 활성 소켓을 추적해 연결된 모든 클라이언트로 방송할 수 있게 합니다(예: 채팅방). 닫힌 연결로 전송하는 것과 메모리 경계를 유지하기 위해 연결이 끊기면 항상 소켓을 제거하세요.
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(정책 위반)로 닫으세요.
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()로 주입하세요.
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)데이터베이스 (SQLAlchemy)
SQLAlchemy 설정
create_engine이 DB 연결 풀을 세팅하고, SessionLocal이 세션 팩토리이며, Base가 모델용 선언적 베이스입니다. FastAPI와의 SQLite는 요청이 다른 스레드에서 실행될 수 있으므로 check_same_thread=False를 설정하세요.
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 블록에서 닫힙니다. 라우트가 예외를 발생시켜도 정리가 보장됩니다.
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 수준에서 기본값을 가질 수 있습니다.
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하세요.
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)를 쓰세요.
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를 반환하세요.
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()데이터베이스 (Tortoise ORM)
Tortoise 설정
Tortoise ORM은 async 네이티브로 FastAPI와 잘 어울립니다. 시작 시 db_url과 모델이 담긴 모듈(들)로 초기화하세요. 개발에는 generate_schemas()가 괜찮고, 프로덕션 마이그레이션에는 Aerich를 쓰세요. 새 코드에는 on_event 대신 lifespan 핸들러를 쓰세요.
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 등을 씁니다.
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가 비동기 로드된 관계를 올바르게 직렬화합니다.
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()은 피하세요(없으면 예외).
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하세요.
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를 쓰세요.
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.테스트 (TestClient)
TestClient 기본
TestClient가 앱을 감싸 프로세스 내에서(실제 소켓 없이) 요청을 보내게 합니다. httpx 기반이며 pytest와 바로 동작합니다. 프로덕션에서 실행하는 것과 같은 앱 인스턴스를 임포트하세요.
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'의 구조를 단언하세요.
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 == 422Pytest 픽스처
TestClient를 반환하는 pytest 픽스처가 테스트를 DRY하게 유지하고 각 테스트가 새 클라이언트를 얻게 합니다. DB 기반 테스트에는 테이블을 만들/지우거나 테스트마다 트랜잭션 롤백을 써 격리하는 픽스처를 추가하세요.
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 세션이나 인증 같은)을 목/가짜로 교체하며, 라우트는 바꾸지 않습니다. 외부 서비스로부터 격리해 엔드포인트를 테스트하는 정석 방법입니다. 테스트 뒤에는 지우세요.
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 의존성을 대신 오버라이드하세요.
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가 발생합니다.
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 connectionOpenAPI 문서
Swagger UI
FastAPI가 라우트, 타입, 독스트링으로부터 /docs에 인터랙티브 Swagger UI를 자동 생성합니다. 앱에 title/description/version을 설정하고, UI를 풍부하게 하려 각 라우트에 독스트링이나 summary/description을 추가하세요.
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/docsReDoc
/redoc의 ReDoc은 Swagger의 읽기 전용 문서 중심 대안입니다. raw OpenAPI 스키마는 /openapi.json에 있으며 다른 도구에 먹일 수 있습니다. 문서 비활성화는 docs_url=None, redoc_url=None, openapi_url=None입니다(예: 프로덕션).
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를 설정하세요.
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. 명시적으로 전달하지 않으면 독스트링이 설명으로 쓰입니다.
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'과 예제 드롭다운에 예제 페이로드를 추가합니다. 본문 예제는 요약과 함께 유효/무효 입력을 보여주는 여러 케이스를 포함할 수 있습니다.
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이 서빙하는 것이 이 스키마입니다.
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배포 (Uvicorn / Gunicorn)
Uvicorn 프로덕션
프로덕션에서는 리버스 프록시(Nginx, Caddy, 클라우드 로드밸런서) 뒤에서 Uvicorn을 실행하세요. 앱이 X-Forwarded-For/X-Forwarded-Proto로 클라이언트의 실제 IP/호스트를 보도록 --proxy-headers를 쓰세요. 프로덕션에서는 --reload를 피하세요.
# 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)로 두고 벤치마크하세요.
# 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 classDocker 배포
슬림 Python 베이스 이미 지가 이미지를 작게 유지합니다. Docker의 레이어 캐시를 활용하려 코드 복사 전에 의존성을 설치하세요. 컨테이너 안에서 gunicorn+uvicorn 워커로 실행하고, 호스트나 오케스트레이터에 8000 포트를 노출하세요.
# 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만 바꿔 다른 환경(개발/스테이징/운영)에서 실행됩니다.
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=falseNginx 리버스 프록시
Nginx가 HTTP(S)를 종료하고 localhost:8000의 Uvicorn으로 전달합니다. 앱이 실제 클라이언트 IP와 스킴을 보도록 X-Forwarded-* 헤더를 설정하세요(Uvicorn에는 --proxy-headers 사용). Upgrade/Connection 줄이 WebSocket 지원을 켭니다.
# /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 엔드포인트를 추가하세요.
# 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"}고급 주제
Lifespan 이벤트
lifespan 컨텍스트 매니저가 폐기된 on_event('startup'/'shutdown') 핸들러를 대체합니다. yield 전 코드가 시작 시 실행되고, yield 뒤 코드가 — 시작이 실패해도 — 종료 시 실행됩니다. DB 연결, ML 모델, 캐시 초기화에 쓰세요.
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 스키마를 가지며, 부모의 문서에는 기본적으로 자식의 라우트가 포함되지 않습니다.
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)로 포함하세요(자체 접두사나 태그와 함께도 가능). 단순하지 않은 앱을 구조화하는 표준 패턴입니다.
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 라우트를 마운트하세요. 정적 파일이 속도를 위해 라우팅 시스템을 우회합니다.
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을 적절히 설정하세요.
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를 전달하세요. 핸들러가 매칭되는 각 요청에 대해 실행됩니다.
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": []}관련 FastAPI 스니펫
Copy-paste ready code for common tasks.
Path Parameters
Capture typed path segments with validation.
Query Parameters
Parse query strings with defaults and validation.
Pydantic Request Body
Validate JSON bodies with Pydantic models.
Dependency Injection
Share logic via Depends and yield-based dependencies.
Response Model
Shape and filter responses with response_model.
JWT Auth
Issue and verify JSON Web Tokens with OAuth2.
Async and Await
Define async handlers and run blocking work in a thread.
Middleware
Add CORS, timing, and custom middleware.
Was this helpful?