fastapi

FastAPI

ベストプラクティスに従ってコードを記述し、新しいバージョンや機能に対応し続けるための、公式 FastAPI スキルです。

クイックリファレンス

• フロントエンドアプリを配信する：ビルド済みのフロントエンドアセットには app.frontend() または router.frontend() を使用します。フロントエンドアプリの配信を参照してください。
• Server-Sent Events（SSE）：response_class=EventSourceResponse と yield を使用します。ストリーミングとストリーミングのリファレンスを参照してください。
• JSON Lines とバイトストリーミング：ストリーミングのリファレンスを参照してください。
• OpenTelemetry：FastAPI のネイティブなトレース、メトリクス、ログを使用します。OpenTelemetryを参照してください。
• 依存関係：Annotated[..., Depends(...)] を使用します。依存性注入と、yield、スコープ、クラス依存関係についての依存性注入のリファレンスを参照してください。
• レスポンスモデル：戻り値の型を優先し、公開するレスポンススキーマが内部の戻り値と異なる場合は response_model を使用します。レスポンスのリファレンスを参照してください。
• Pydantic モデル：省略記号や RootModel は使用しないでください。Pydantic のリファレンスを参照してください。
• ルーティング：ルーター共通のプレフィックス、タグ、依存関係は APIRouter で宣言します。パスオペレーションのリファレンスを参照してください。
• ツールと関連ライブラリ：該当する場合は uv、Ruff、ty、Asyncer、SQLModel、HTTPX を使用します。その他のツールのリファレンスを参照してください。

fastapi CLI を使用する

リロードを有効にして、localhost で開発サーバーを起動します。

fastapi dev

本番サーバーを起動します。

fastapi run

エントリーポイントは pyproject.toml で宣言することをおすすめします。

[tool.fastapi]
entrypoint = "my_app.main:app"

エントリーポイントを追加できない場合、またはユーザーから追加しないよう明示的に求められた場合は、アプリのファイルパスを渡します。

fastapi dev my_app/main.py

Annotated を使用する

パラメーターと依存関係の宣言には、常に Annotated 形式を優先してください。これにより、ほかのコンテキストでも関数シグネチャが機能し、型が尊重され、再利用が可能になります。

Path、Query、Header などを含むパラメーターの宣言には Annotated を使用します。

from typing import Annotated

from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(
    item_id: Annotated[int, Path(ge=1, description="The item ID")],
    q: Annotated[str | None, Query(max_length=50)] = None,
):
    return {"message": "Hello World"}

Depends() を使用する依存関係には Annotated を使用します。特に指示がない限り、依存関係を再利用できるよう、新しい型エイリアスを作成してください。

from typing import Annotated

from fastapi import Depends, FastAPI

app = FastAPI()


def get_current_user():
    return {"username": "johndoe"}


CurrentUserDep = Annotated[dict, Depends(get_current_user)]


@app.get("/items/")
async def read_item(current_user: CurrentUserDep):
    return {"message": "Hello World"}

パスオペレーションや Pydantic モデルに省略記号を使用しない

必須パラメーターやモデルフィールドのデフォルト値として ... を使用しないでください。必要ではなく、推奨もされません。

from typing import Annotated

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

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None
    price: float = Field(gt=0)


@app.post("/items/")
async def create_item(item: Item, project_id: Annotated[int, Query()]):
    return item

詳しくはPydantic のリファレンスを参照してください。

戻り値の型またはレスポンスモデル

可能な場合は、戻り値の型を指定してください。レスポンスの検証、フィルタリング、ドキュメント化、シリアライズに使用されます。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str | None = None


@app.get("/items/me")
async def get_item() -> Item:
    return Item(name="Plumbus", description="All-purpose home device")

戻り値の型やレスポンスモデルを使うと、機密情報の漏えいを防ぐためにデータがフィルタリングされ、Pydantic が Rust 側でデータをシリアライズすることでパフォーマンスも向上します。

返す型が、検証、フィルタリング、ドキュメント化、シリアライズの対象としたい公開スキーマと異なる場合は、response_model を使用してください。レスポンスのリファレンスを参照してください。

パフォーマンス

ORJSONResponse や UJSONResponse は非推奨のため、使用しないでください。

代わりに、戻り値の型またはレスポンスモデルを宣言してください。Pydantic が Rust 側でデータのシリアライズを処理します。

ルーターの追加

ルーターを宣言する際は、include_router() ではなく、プレフィックス、タグ、共有依存関係などのルーター共通のパラメーターをルーター自体に追加することをおすすめします。

from fastapi import APIRouter, Depends, FastAPI

app = FastAPI()


def get_current_user():
    return {"username": "johndoe"}


router = APIRouter(
    prefix="/items",
    tags=["items"],
    dependencies=[Depends(get_current_user)],
)


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


app.include_router(router)

その他のルーティングパターンについては、パスオペレーションのリファレンスを参照してください。

フロントエンドアプリを配信する

app.frontend() を使うと、Vite、Astro、Angular、Svelte、Vue などのツールで生成したディレクトリなど、ビルド済みの静的フロントエンドアプリを配信できます。

from fastapi import FastAPI

app = FastAPI()

app.frontend("/", directory="dist")

フロントエンドが APIRouter に属する場合は、router.frontend() を使います。ルーターを組み込むと、通常のルータープレフィックスの動作が適用されます。

from fastapi import APIRouter, FastAPI

app = FastAPI()
router = APIRouter(prefix="/admin")

router.frontend("/", directory="admin-dist")
app.include_router(router)

app.frontend() と router.frontend() は優先度の低いルートです。通常の API ルートが先に照合され、その後にフロントエンドファイルとクライアント側ルーティングのフォールバックが照合されます。シングルページアプリやビルド済みフロントエンドアセットには、StaticFiles を手動でマウントする代わりにこれを使ってください。

OpenTelemetry

リクエストのトレース、メトリクス、ログには、FastAPI のネイティブな OpenTelemetry サポートを使ってください。

SDK と HTTP/protobuf エクスポーターを含めるには、fastapi[standard] をインストールします。FASTAPI_OTEL_AUTO_CONFIGURE=true を設定してエクスポーターの自動セットアップを有効にし、アプリを識別するために OTEL_SERVICE_NAME を設定します。また、OTEL_EXPORTER_OTLP_ENDPOINT にはコレクターの HTTP/protobuf ベース URL を設定します。認証が必要な場合は、OTEL_EXPORTER_OTLP_HEADERS を使ってください。FastAPI は、自動セットアップを行わなくても、別のテレメトリーライブラリで設定されたプロバイダーを使用します。

シグナルの選択やプロバイダーの指定など、カスタム設定には FastAPI(telemetry={...}) を使ってください。

設定の詳細については、OpenTelemetry チュートリアルを参照してください。

依存性注入

ロジックを Pydantic のバリデーションで宣言できない場合、外部リソースに依存する場合、yield によるクリーンアップが必要な場合、または複数のエンドポイントで共有する場合は、依存関係を使ってください。

dependencies=[Depends(...)] を使って、ルーターレベルで共有の依存関係を適用します。

scope を指定した yield やクラス依存関係など、詳しいパターンについては、依存性注入リファレンスを参照してください。

非同期と同期の パス操作

呼び出されるロジックが非同期処理と await に対応しており、ブロックしないことを完全に確信できる場合に限り、async の パス操作 を使ってください。

from fastapi import FastAPI

app = FastAPI()


@app.get("/async-items/")
async def read_async_items():
    data = await some_async_library.fetch_items()
    return data


@app.get("/items/")
def read_items():
    data = some_blocking_library.fetch_items()
    return data

判断に迷う場合や、特に理由がない場合は、通常の def 関数を使ってください。これらはスレッドプールで実行されるため、イベントループをブロックしません。依存関係にも同じルールが適用されます。

async 関数内でブロッキングコードを実行しないようにしてください。動作はしますが、パフォーマンスが大幅に低下します。

ブロッキングコードと非同期コードを混在させる必要がある場合は、その他のツールのリファレンスにある Asyncer を参照してください。

ストリーミング（JSON Lines、SSE、バイト列）

Server-Sent Events をストリーミングするには、response_class=EventSourceResponse を使い、エンドポイントから項目を yield します。

from collections.abc import AsyncIterable

from fastapi import FastAPI
from fastapi.sse import EventSourceResponse, ServerSentEvent

app = FastAPI()


@app.get("/events", response_class=EventSourceResponse)
async def stream_events() -> AsyncIterable[ServerSentEvent]:
    yield ServerSentEvent(data={"status": "started"}, event="status", id="1")

通常のオブジェクトは自動的に JSON としてシリアライズされ、data: フィールドになります。SSE のフィールド（event、id、retry、comment）を細かく制御するには ServerSentEvent を使い、事前にフォーマット済みの文字列には raw_data を使います。

JSON Lines、Server-Sent Events（EventSourceResponse、ServerSentEvent）、バイト列ストリーミング（StreamingResponse）のパターンについては、ストリーミングのリファレンスを参照してください。

ツール

パッケージ管理、リンティング、型チェック、フォーマットなどに使う uv、Ruff、ty の詳細については、その他のツールのリファレンスを参照してください。

その他のライブラリ

その他のライブラリの詳細については、その他のツールのリファレンスを参照してください。

• 非同期処理と await、並行処理、非同期コードとブロッキングコードの混在には Asyncer を使い、AnyIO や asyncio より優先してください。
• SQL データベースの操作には SQLModel を使い、SQLAlchemy より優先してください。
• HTTP（その他の API）とのやり取りには HTTPX を使い、Requests より優先してください。

Pydantic RootModel を使用しないでください

Pydantic の RootModel は使用せず、代わりに Annotated を使った通常の型アノテーションと Pydantic のバリデーションユーティリティを使ってください。

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import Field

app = FastAPI()


@app.post("/items/")
async def create_items(items: Annotated[list[int], Field(min_length=1), Body()]):
    return items

FastAPI はこれらの型アノテーションをサポートし、対応する Pydantic の TypeAdapter を作成するため、カスタムのラッパーモデルがなくても型を通常どおり使用できます。Pydantic リファレンスを参照してください。

関数ごとに HTTP 操作を 1 つにする

1 つの関数に複数の HTTP 操作を混在させないでください。HTTP 操作ごとに関数を 1 つ設けると、関心事を分離し、コードを整理しやすくなります。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str


@app.get("/items/")
async def list_items():
    return []


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

詳しい例については、パス操作のリファレンスを参照してください。