はじめに
最初の 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 での実行
app インスタンス '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/list を返すと、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/{user_id} のような動的パターンの前に、/users/me のような具体的なパスを宣言しましょう — さもないと動的ルートが具体ルートを覆い隠します。
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 のクエリパラメータは多くの真値を受け付けます: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 でもないときだけです。省略可能な nullable フィールドの標準パターンは 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"]}パス・クエリと共に使う Body
パス、クエリ、ボディのパラメータは 1 つの操作に共存できます。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 は、新しいモデルを定義せずにルートごとにフィールドをホワイト/ブラックリストできます。フィールド名のセットを渡します。これらは 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/list を返すと自動で JSON へシリアライズされます。デフォルトのレスポンス型を変えるには response_class を使います(HTMLResponse、PlainTextResponse)。完全な制御には 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)は混在できません — コンテンツタイプは 1 つ選びましょう。
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] を宣言すると、1 つのリクエストで複数のファイルを受け付けられます。各ファイルは同じフィールド名で送られます。リスト内のファイルの順序は送信順と一致します。
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 セッション)は 1 箇所に置かれ、エンドポイント間で再利用されます。依存関係のパラメータも 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 は 1 つだけにしましょう。
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"},
)パスワードのハッシュ化
平文のパスワードを保存してはいけません。bcrypt(または argon2)を使う passlib がソルトとハッシュ化を処理します。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 パスワードフロー)から 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') がすべてのリクエストを包む関数を登録します。レスポンスを得るには await call_next(request) しなければならず、その後、返す前に検査や修正ができます。ミドルウェアはすべてのルートで動きます。
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)Trusted Host
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 は早めに(プリフライトが機能するように)加え、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 で、ブラウザがクロスオリジンで Cookie と 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 は文字列、辞書、リストにできます — 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}検証エラーの上書き
RequestValidationError は入力が Pydantic の検証に失敗したときに発生します。@app.exception_handler(RequestValidationError) でハンドラを上書きし、422 レスポンスの形状をカスタマイズしましょう(会社全体のエラーエンベロープに合わせるなど)。
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 ハンドラを上書きすれば、発生するすべての HTTPException で一貫したエラー JSON 形状が強制されます。ハンドラを再束縛するときは、クラスを fastapi.exceptions.HTTPException(raise で使うものと同じ)としてインポートしましょう。
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 はレスポンス送信後に関数を実行します — ロギング、メール送信、キャッシュ無効化のような発火後放置の作業に最適です。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}Background と 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 接続にカスタムヘッダーを設定できないため、認証トークンは通常クエリパラメータ(または Cookie)で渡されます。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 エンドポイントでも使えますが、意味があるのは初期ハンドシェイク(ヘッダー、クエリパラメータ、Cookie)から読む依存関係だけです — ボディはありません。通常どおり 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()セッションの依存関係
DB セッションを提供する正統な方法は yield 依存関係です:各リクエストが新しいセッションを受け取り、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 など)でインスタンスを再読み込みします。複数の書き込みはトランザクションで包み、最後に 1 回 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