python-best-practices

Python + FastAPI のベストプラクティス — クイックリファレンス

レイヤードアーキテクチャ

ルーター → サービス → リポジトリ → データベース。各レイヤーは、1つ下のレイヤーのみを呼び出します。

プロジェクト構造全体とレイヤーの例については、code-patterns.md を参照してください。

Pydantic v2

Create／Update／Response のスキーマを分けます。ORM との連携には ConfigDict(from_attributes=True) を使用します。Optional[str] ではなく、str | None の構文を使用します。

スキーマの例については、code-patterns.md を参照してください。

非同期パターン

I/O を行うルートには async def を、CPU 負荷の高い処理には通常の def を使用します。on_event ではなく、ライフスパンのコンテキストマネージャーを使用します。外部への HTTP 呼び出しには httpx.AsyncClient を使用します。

非同期処理の例については、code-patterns.md を参照してください。

論理削除

SQLAlchemy モデルで SoftDeleteMixin を使用します。すべてのクエリで where(Model.deleted_at.is_(None)) によるフィルタリングを行います。

Mixin とリポジトリのパターンについては、code-patterns.md を参照してください。

設定

すべての設定に pydantic-settings を使用します。シークレット、URL、マジックナンバーをハードコードしないでください。

Settings クラスのパターンについては、code-patterns.md を参照してください。

ページネーション

すべてのリストエンドポイントで、汎用の PaginatedResponse[T] を使用します。必ず total、page、limit、has_more を返します。

パターンについては、code-patterns.md を参照してください。

注意点

• パフォーマンスにおいて、async def と def の使い分けは重要です。 ブロッキング処理（time.sleep() や同期 DB ドライバーなど）を呼び出す async def ルートは、イベントループ全体をブロックします。CPU 負荷の高い処理には通常の def を使用してください。FastAPI がスレッドプールで実行します。async def は、何かを await する場合にのみ使用してください。

• datetime.utcnow() は Python 3.12 から非推奨です。 代わりに datetime.now(UTC) を使用してください。以前の関数はタイムゾーン情報のない naive datetime を返すため、比較時の不具合につながります。新しい関数は、タイムゾーン情報を持つ UTC の値を返します。

• Pydantic の可変なデフォルト引数は安全に見えますが、注意が必要です。 tags: list[str] = [] は Pydantic では機能します（デフォルト値がコピーされます）。ただし、tags: list[str] = Field(default_factory=list) と明示する方が、ネストされたモデルでは安全です。単純なフィールドでは、どちらでも問題ありません。複雑なネストされたデフォルト値には、必ず default_factory を使用してください。

• from_attributes=True は orm_mode=True に代わるものです。 Pydantic v2 では設定 API が変更されました。以前の orm_mode を使用しても何も起きず、ORM オブジェクトが正しくシリアライズされません。

• SQLAlchemy の Column() はレガシーです。 SQLAlchemy 2.0 では、mapped_column() と Mapped[type] を使用してください。以前の Column(String) も引き続き動作しますが、型チェッカーのサポートと IDE の自動補完が失われます。