python-api-endpoint-creator

Python API エンドポイント作成ツール

厳格なレイヤードアーキテクチャのパターンに従って、完全な FastAPI エンドポイントを作成します。

使用する場面

• REST API エンドポイントをゼロから新規作成する
• 新しいドメインエンティティに CRUD 操作を追加する
• Router → Service → Repository → Tests のフルスタックを構築する
• 新しいドメインモジュールをスキャフォールディングする

プロセス

1. Pydantic スキーマ — schemas.py に Create/Update/Response を作成します
2. SQLAlchemy モデル — models.py に SoftDeleteMixin を使用して作成します
3. リポジトリ — repository.py にソフトデリート対応の非同期 CRUD を実装します
4. サービス — service.py にビジネスロジックとエラー用の HTTPException を実装します
5. 依存関係 — dependencies.py に get_db、get_service を定義します
6. ルーター — router.py に薄いエンドポイントを作成し、すべてに Depends() を使用します
7. テスト — tests/ に httpx AsyncClient テストを作成します

各ファイルの完全なテンプレートについては、code-patterns.md を参照してください。

アーキテクチャ

Router (APIRouter)  →  Service  →  Repository  →  Database
      ↓                  ↓            ↓
  Depends()        Business logic  SQLAlchemy
  Pydantic schemas HTTPException   AsyncSession
  Status codes     Validation      Soft delete

厳守するルール

• すべての変更操作に POST を使用する — 読み取りには GET、作成／更新／削除には POST を使用します
• ID にはクエリパラメーターを使用する — ?id=xxx を使用し、パスパラメーター /{id} は使用しません
• ルーターは薄く保つ — 委譲のみとし、ビジネスロジックを含めません
• サービスで HTTPException を発生させる — 想定されるエラー（404、409、422）に対して使用します
• リポジトリでソフトデリートを処理する — すべてのクエリで deleted_at.is_(None) によるフィルタリングを行います
• すべてのエンドポイントに async def を使用する — CPU バウンドの場合を除きます

注意点

• response_model を忘れると、API から内部フィールドが漏えいします。 エンドポイントには必ず response_model=YourSchema を設定してください。設定しない場合、FastAPI は戻り値をそのままシリアライズするため、SQLAlchemy モデルの hashed_password、deleted_at などの内部フィールドが含まれる可能性があります。

• Depends() はリクエストごとに新しいインスタンスを作成します。シングルトンではありません。 サービスが状態を保持する場合、リクエスト間でその状態は失われます。サービスはステートレスにしてください。共有状態が必要な場合は、アプリの状態またはキャッシュを使用します。

• await db.commit() はリポジトリではなく依存関係内で実行してください。 get_db 依存関係がコミットとロールバックを処理します。リポジトリ内でもコミットすると、二重コミットのバグや、すべての操作が完了する前の早すぎるコミットが発生します。

• Pydantic の 422 エラーは、デフォルトでは詳細が不明瞭です。 RequestValidationError ハンドラーをオーバーライドして、フィールドごとのエラーを返すようにします。デフォルトでは「validation error」とだけ表示され、フロントエンドにとって有用な詳細情報がありません。

• 作成エンドポイントに status_code=201 を設定し忘れないでください。 FastAPI のデフォルトは 200 です。POST の作成ルートには status_code=status.HTTP_201_CREATED を、削除ルートには status_code=status.HTTP_204_NO_CONTENT を明示的に設定してください。