APIRouterを使って大規模なアプリをどのように構造化しますか？

Question

Accepted Answer

**`APIRouter`** を使うことで、大規模なFastAPIアプリを複数のモジュールに分割できます。各ルーターは関連するエンドポイント（例えば、すべての `/users` ルート）をグループ化し、メインアプリがそれらを含めます。これにより、成長するコードベースを組織的で保守可能に保つことができます。

## 専用モジュール内でルーターを定義する

```python
# routers/users.py
from fastapi import APIRouter

router = APIRouter(
    prefix="/users",          # all routes here start with /users
    tags=["users"],           # grouped under "users" in the docs
)

@router.get("/")              # GET /users/
def list_users(): ...

@router.get("/{user_id}")     # GET /users/{user_id}
def get_user(user_id: int): ...
```

`APIRouter` は mini-app のように動作します。同じデコレータを使ってパス操作を定義し、`prefix` がすべてに適用されます。

## メインアプリにルーターを含める

```python
# main.py
from fastapi import FastAPI
from routers import users, items, auth

app = FastAPI()
app.include_router(users.router)     # mounts /users/* endpoints
app.include_router(items.router)
app.include_router(auth.router)
```

`app.include_router()` は各ルーターのエンドポイントをメインアプリにマウントします。モジュール化された部分からフル APIを組み立てます。

## 典型的なプロジェクト構造

```text
app/
  main.py              # creates the app, includes routers
  routers/
    users.py           # APIRouter for /users
    items.py           # APIRouter for /items
    auth.py            # APIRouter for /auth
  models.py            # Pydantic models
  database.py          # DB setup
  dependencies.py      # shared dependencies
```

各機能/ドメインが独自のルーターモジュールを持ちます。関連するルートを一箇所に保ち、コードベースがよく整理されます。

## ルーターレベルの依存関係と設定

```python
router = APIRouter(
    prefix="/admin",
    dependencies=[Depends(verify_admin)],   # apply a dependency to ALL routes in the router
)
# you can also nest routers via include_router on a router
```

ルーターは共有依存関係（例えば、ルートのグループ全体に対して admin 認証を必須にする）を持つことができます。すべてのエンドポイントに一度に適用されます。

## なぜ重要なのか

`APIRouter` は自明でない FastAPI アプリを構築するために不可欠です。これなしでは、すべてのエンドポイントが 1 つのファイルに存在することになり、API が成長するにつれ管理不能になります。

これを理解することは **コード組織と保守性** にとって重要です：エンドポイントを機能ベースのルーターモジュール（ユーザー、アイテム、認証）に分割することで、関連するコードを一箇所に保ち、プロジェクトを分かりやすくし、チームが異なる領域で独立して作業できるようになります。

`prefix` と `tags` はルートとドキュメントを整理し、**ルーターレベルの依存関係**（グループ全体に admin 認証を要求するなど）はクリーンなグループ全体の動作を提供します。

このモジュラー構造は実際の FastAPI アプリケーションの標準的な実践であり、`APIRouter` とその周りのプロジェクト組織パターンを理解することは、スケーラブルで保守可能な API を構築するための実質的に不可欠な知識です。