Как структурировать большое приложение с 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` работает как мини-приложение — вы определяете операции пути на нём с помощью тех же декораторов, а `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
```

Маршрутизаторы могут нести общие зависимости (например, требовать аутентификацию администратора для целой группы маршрутов) — применяемые ко всем их эндпоинтам сразу.

## Почему это важно

`APIRouter` необходим для создания любого приложения сверх тривиального FastAPI приложения — без него все эндпоинты жили бы в одном файле, что становится неуправляемым по мере роста API.

Понимание этого важно для **организации кода и поддерживаемости**: разделение эндпоинтов на модули маршрутизаторов на основе функций (пользователи, элементы, аутентификация) держит связанный код вместе, делает проект навигируемым и позволяет командам работать на разных областях независимо.

`prefix` и `tags` держат маршруты и документацию организованными, а **зависимости уровня маршрутизатора** (например, требование аутентификации администратора для целой группы) обеспечивают чистое, групповое поведение.

Такая модульная структура — стандартная практика для реальных FastAPI приложений, что делает `APIRouter` и паттерны организации проекта вокруг него важным, практически необходимым знанием для построения масштабируемых, поддерживаемых API.