Что такое `APIRouter` и как он помогает организовывать маршруты?

Question

Accepted Answer

Что такое APIRouter

APIRouter — это класс из пакета fastapi, который позволяет объявлять маршруты вне основного объекта FastAPI и затем подключать их через app.include_router(). Это основной инструмент разбиения монолитного файла на модули: каждый модуль (users, items, orders) создаёт свой роутер, а main.py только монтирует их.

Базовый пример

# routers/items.py
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.ext.asyncio import AsyncSession
from app.db import get_session
from app.models import Item
from app.schemas import ItemCreate, ItemRead

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

@router.get("/", response_model=list[ItemRead])
async def list_items(session: AsyncSession = Depends(get_session)):
    result = await session.execute(select(Item))
    return result.scalars().all()

@router.post("/", response_model=ItemRead, status_code=201)
async def create_item(
    body: ItemCreate,
    session: AsyncSession = Depends(get_session),
):
    item = Item(**body.model_dump())
    session.add(item)
    await session.commit()
    await session.refresh(item)
    return item

# main.py
from fastapi import FastAPI
from app.routers import items, users, orders

app = FastAPI()
app.include_router(items.router)
app.include_router(users.router, prefix="/users", tags=["users"])
app.include_router(orders.router)

Параметры include_router

При вызове app.include_router() можно переопределить или дополнить параметры роутера:

prefix — добавляет префикс URL ко всем маршрутам роутера.
tags — группирует эндпоинты в документации Swagger/ReDoc.
dependencies — список Depends(), применяемых ко всем маршрутам роутера (например, проверка JWT).
responses — общие ответы на уровне роутера (например, {401: {"description": "Unauthorized"}}).
default_response_class — переопределяет класс ответа (ORJSONResponse и т.п.).

Зависимости на уровне роутера

from fastapi import APIRouter, Depends
from app.auth import require_auth

router = APIRouter(
    prefix="/admin",
    tags=["admin"],
    dependencies=[Depends(require_auth)],  # применяется ко всем эндпоинтам
)

@router.delete("/users/{user_id}", status_code=204)
async def delete_user(user_id: int):
    ...

Вложенные роутеры

Роутеры можно вкладывать: parent_router.include_router(child_router). Это удобно для версионирования API: один роутер /api/v1 монтирует несколько доменных роутеров.

Подводные камни

Порядок маршрутов важен. FastAPI проверяет маршруты в порядке регистрации. Если /items/facets объявлен после /items/{item_id}, строка facets будет интерпретирована как UUID и вызовет ошибку валидации.
prefix дублируется. Если prefix указан и в конструкторе APIRouter(prefix="/items"), и в include_router(prefix="/items"), маршруты получат двойной префикс /items/items/....
dependencies на роутере не заменяют dependencies на эндпоинте — они объединяются. Это может привести к двойной проверке токена, если зависимость добавлена и там, и там.
response_model не наследуется с роутера на эндпоинт — его нужно указывать на каждом декораторе отдельно.
tags влияют только на документацию, а не на поведение роутинга или авторизацию.
Circular imports. При вложенных роутерах легко получить циклический импорт; решается выносом зависимостей в отдельный модуль deps.py.
Тестирование: при использовании TestClient из fastapi.testclient роутеры работают без дополнительных настроек, но зависимости нужно переопределять через app.dependency_overrides.

Что такое `APIRouter` и как он помогает организовывать маршруты?