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

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

# 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)

Что такое APIRouter

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

Параметры 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 только как термин и не показывать механизм на минимальном примере.
• Игнорировать ошибки, пустые данные, конкурентный доступ или границы транзакции.
• Не связывать поведение с официальным контрактом FastAPI и реальной эксплуатацией.

• Объясняет apirouter через последовательность действий, а не через набор ключевых слов.
• Приводит короткий кодовый пример или production-сценарий с ожидаемым поведением.
• Называет хотя бы один риск: производительность, безопасность, транзакции, память или сопровождение.