FastAPIにおける変数の型指定（初心者向け完全ガイド）
✅ はじめに：型指定の必要性
FastAPIはPythonの型ヒント（type hints）を活用することで、関数の引数や戻り値の自動検証やドキュメント生成を行います。変数に型を付けることで、IDEの補完機能やバグ防止にも役立ち、コードが読みやすく、保守しやすくなります。
1．Pythonの型ヒントとは？
Pythonは動的型付けの言語ですが、str, intなどの型ヒントを変数や関数に追加することで、静的解析ツール（MyPyやPyrightなど）によるバグ検出やIDEの補完機能が強化されます。
def greet(name: str, age: int) -> str:
return f"{name}さんは{age}歳です。"
2．FastAPIでの型活用①：Path / Query パラメータ
FastAPIのエンドポイントで型を指定すると、自動的に型変換とバリデーションが行われます。
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
return {"item_id": item_id, "q": q}
item_idは整数として処理され、誤った型（例：文字列）が来ると400エラーが返されます。q: str | None = Noneは任意の文字列として定義されており、省略も可能です。
3．FastAPIでの型活用②：PydanticモデルによるRequest Bodyの検証
リクエストボディを受け取る場合、PydanticのBaseModelを使ってデータ構造と型を定義します。
from fastapi import FastAPI
from pydantic import BaseModel
from typing import Optional
class Item(BaseModel):
name: str
price: float
is_offer: Optional[bool] = None
app = FastAPI()
@app.put("/items/{item_id}")
def update_item(item_id: int, item: Item):
return {"item_id": item_id, **item.dict()}
- 型に合わないデータが送られた場合、自動的に400エラーで応答します。
Optionalを使うことで、フィールドが省略可能になります。
4．型ヒントの利点まとめ ✨
| 利点 | 内容 |
|---|---|
| IDEの補完・静的解析 | 型指定により補完が効きやすく、MyPyやPyrightによるチェックが可能。 |
| 自動バリデーション | 型を元にFastAPIとPydanticが入力を検証し、不正な型を拒否。 |
| ドキュメント自動生成 | OpenAPI仕様に基づき、Swagger UIが自動生成される。 |
5．応用：リスト、辞書、Optional、Unionの活用
複雑なデータ構造やオプションの値も型指定可能です。
from typing import List, Dict, Optional, Union
def complex_example(ids: List[int], options: Dict[str, float]):
pass
value: Union[int, str] = 42
name: Optional[str] = None # str または None を許容
6．Pydanticでのstrict型とカスタムバリデーション
Pydanticでは、StrictStr や StrictInt を使って、厳格な型制約を設けることもできます。また、@validator デコレータで独自の検証ロジックも追加可能です。
from pydantic import BaseModel, StrictStr, validator
class Product(BaseModel):
title: StrictStr
price: float
@validator('price')
def price_must_be_positive(cls, v):
if v <= 0:
raise ValueError('価格は正の数でなければなりません')
return v
7．実践的な型運用の流れ
- 型ヒントを付ける：関数、パラメータ、戻り値に型指定
- Pydanticモデルで定義：複雑な構造にはBaseModelを活用
- 検証とテスト：Swagger UI やテストコードで型の動作を確認
- IDEや型チェックツールを併用：MyPyやPyrightで静的チェック
✅ まとめ
FastAPIでは型指定が非常に重要な役割を果たします。型を活用することで、コードの安全性と可読性が向上し、ユーザー入力の検証も自動化されます。初心者の方も、まずは簡単な型ヒントから始め、PydanticやOptional、Unionなどに徐々に慣れていくことで、堅牢でモダンなWebアプリケーションの構築が可能になります。
型指定を味方につけて、PythonとFastAPIの力を最大限に引き出していきましょう！