FastAPI

FastAPI 公式スキル。ベストプラクティスに従ってコードを書き、新しいバージョンと機能に対応し続けます。

fastapi CLI を使用する

ローカルホストで開発サーバーを再読み込み付きで実行します：

fastapi dev

本番サーバーを実行します：

fastapi run

pyproject.toml にエントリーポイントを追加する

FastAPI CLI は pyproject.toml のエントリーポイントを読み込んで、FastAPI アプリがどこで宣言されているかを知ります。

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

パスを指定して fastapi を使用する

pyproject.toml にエントリーポイントを追加できない場合、またはユーザーが明示的に追加しないよう要求した場合、または独立した小さなアプリを実行している場合は、fastapi コマンドにアプリファイルパスを渡すことができます：

fastapi dev my_app/main.py

可能な限り pyproject.toml にエントリーポイントを設定することを推奨します。

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"}

以下の代わりに：

# これを使用しないでください
@app.get("/items/{item_id}")
async def read_item(
    item_id: int = Path(ge=1, description="The item ID"),
    q: str | None = Query(default=None, max_length=50),
):
    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"}

以下の代わりに：

# これを使用しないでください
@app.get("/items/")
async def read_item(current_user: dict = Depends(get_current_user)):
    return {"message": "Hello World"}

パス操作または Pydantic モデルに Ellipsis を使用しない

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

Ellipsis (...) なしでこのようにしてください：

from typing import Annotated

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


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


app = FastAPI()


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

以下の代わりに：

# これを使用しないでください
class Item(BaseModel):
    name: str = ...
    description: str | None = None
    price: float = Field(..., gt=0)


app = FastAPI()


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

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

可能な限り、戻り値の型を含めてください。これはレスポンスを検証、フィルタリング、ドキュメント化、およびシリアライズするために使用されます。

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 で）でデータをシリアライズするために使用されます。これはレスポンスパフォーマンスを向上させることができる主要なアイデアです。

戻り値の型は Pydantic モデルである必要はなく、整数のリスト、辞書など、別のタイプも可能です。

代わりに response_model を使用する場合

戻り値の型が、検証、フィルタリング、またはシリアライズに使用する型と同じではない場合は、デコレータの response_model パラメータを使用してください。

from typing import Any

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


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


@app.get("/items/me", response_model=Item)
async def get_item() -> Any:
    return {"name": "Foo", "description": "A very nice Item"}

これは、公開フィールドのみを露出するためにデータをフィルタリングし、機密情報の露出を避ける場合に特に有用です。

from typing import Any

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class InternalItem(BaseModel):
    name: str
    description: str | None = None
    secret_key: str


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


@app.get("/items/me", response_model=Item)
async def get_item() -> Any:
    item = InternalItem(
        name="Foo", description="A very nice Item", secret_key="supersecret"
    )
    return item

パフォーマンス

ORJSONResponse または UJSONResponse を使用しないでください。これらは非推奨です。

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

ルータを含める

ルータを宣言する場合は、プレフィックスやタグなどのルータレベルのパラメータを include_router() ではなく、ルータ自体に追加することを優先してください。

このようにしてください：

from fastapi import APIRouter, FastAPI

app = FastAPI()

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


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


# main.py では
app.include_router(router)

以下の代わりに：

# これを使用しないでください
from fastapi import APIRouter, FastAPI

app = FastAPI()

router = APIRouter()


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


# main.py では
app.include_router(router, prefix="/items", tags=["items"])

例外もあるかもしれませんが、この規約に従おうとしてください。

dependencies=[Depends(...)] でルータレベルで共有依存関係を適用してください。

依存性注入

詳細なパターン（yield の scope およびクラス依存関係を含む）については、依存性注入リファレンスを参照してください。

Pydantic 検証では宣言できないロジック、外部リソースに依存するロジック、クリーンアップが必要（yield で）、またはエンドポイント全体で共有される場合は、依存関係を使用してください。

dependencies=[Depends(...)] でルータレベルで共有依存関係を適用してください。

Async 対 Sync パス操作

内部で呼び出されるロジックが async と await に完全に対応していること（await で呼び出されること）、またはブロックしないことが確実な場合にのみ、async パス操作を使用してください。

from fastapi import FastAPI

app = FastAPI()


# async コードを呼び出すときは async def を使用してください
@app.get("/async-items/")
async def read_async_items():
    data = await some_async_library.fetch_items()
    return data


# ブロッキング/同期コードを呼び出すときまたは確信がない場合は plain def を使用してください
@app.get("/items/")
def read_items():
    data = some_blocking_library.fetch_items()
    return data

疑問がある場合、またはデフォルトでは、通常の def 関数を使用してください。これらはスレッドプールで実行されるため、イベントループをブロックしません。

同じ規則が依存関係にも適用されます。

ブロッキングコードが async 関数内で実行されていないことを確認してください。ロジックは機能しますが、パフォーマンスに大きな悪影響を与えます。

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

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

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

ツール

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

その他のライブラリ

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

• async と await、並行処理、async とブロッキングコードの混在処理用の Asyncer。AnyIO または asyncio よりも優先してください。
• SQL データベースを操作するための SQLModel。SQLAlchemy よりも優先してください。
• HTTP（その他の API）と相互作用するための HTTPX。Requests よりも優先してください。

Pydantic RootModels を使用しない

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

以下の代わりに：

# これを使用しないでください
from typing import Annotated

from fastapi import FastAPI
from pydantic import Field, RootModel

app = FastAPI()


class ItemList(RootModel[Annotated[list[int], Field(min_length=1)]]):
    pass


@app.post("/items/")
async def create_items(items: ItemList):
    return items

FastAPI はこれらの型注釈をサポートし、型が通常のように機能するため Pydantic TypeAdapter を作成します。RootModels のカスタムロジックと型は不要です。

HTTP 操作ごとに 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

以下の代わりに：

# これを使用しないでください
from fastapi import FastAPI, Request
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str


@app.api_route("/items/", methods=["GET", "POST"])
async def handle_items(request: Request):
    if request.method == "GET":
        return []