Вы уже неплохо разобрались с FastAPI: есть база данных, аутентификация, а теперь, вероятно, ваш проект разрастается. Появляется всё больше эндпоинтов, и файл main.py превращается в непонятную простыню. Знакомо? Самое время навести порядок с помощью роутеров!

Что такое роутеры и зачем они нужны?

Роутеры — это способ разделить ваш код на модули. Представьте, что каждый роутер — это отдельный «блок» маршрутов, которые объединены одной логикой. Например:

• users.py — маршруты для управления пользователями.
• tasks.py — маршруты для работы с задачами.
• auth.py — маршруты для аутентификации.

Такой подход упрощает поддержку и расширение проекта. Согласитесь, куда легче разобраться в компактных файлах, чем в монолитной махине на сотни строк.

Создаём первый роутер 🛠️

Начнём с простого примера. Допустим, у нас есть маршруты для пользователей.

Создаём файл routers/users.py:

from fastapi import APIRouter, HTTPException

# Создаём роутер
router = APIRouter()

# Простой эндпоинт для получения информации о пользователе
@router.get("/users/{user_id}")
def get_user(user_id: int):
    # Пока данные захардкожены
    fake_users_db = {1: "Alice", 2: "Bob", 3: "Charlie"}
    
    if user_id not in fake_users_db:
        raise HTTPException(status_code=404, detail="Пользователь не найден")
    
    return {"user_id": user_id, "username": fake_users_db[user_id]}

Что здесь происходит?

• Создаём экземпляр APIRouter.
• Описываем маршрут, используя @router.get().
• Функция принимает user_id из URL и возвращает имя пользователя из фейковой базы данных.

Подключаем роутер к основному приложению 🔌

Теперь нам нужно интегрировать роутер в main.py:

from fastapi import FastAPI
from routers import users  # Импортируем наш роутер

app = FastAPI()

# Подключаем роутер
app.include_router(users.router)

@app.get("/")
def read_root():
    return {"message": "Добро пожаловать в наше приложение!"}

Разберём ключевую строку:

app.include_router(users.router) — подключает маршруты из users.py к основному приложению. Теперь они доступны по адресу /users/{user_id}.

Добавляем префиксы и теги для красоты 🌟

Иногда хочется, чтобы все маршруты одного роутера имели общий префикс. Например, чтобы вместо /users/{user_id} был /api/v1/users/{user_id}.

Давайте настроим это:

# routers/users.py

router = APIRouter(
    prefix="/api/v1/users",  # Общий префикс для всех маршрутов в этом роутере
    tags=["users"]  # Тег для удобной группировки в документации Swagger
)

@router.get("/{user_id}")
def get_user(user_id: int):
    fake_users_db = {1: "Alice", 2: "Bob", 3: "Charlie"}
    
    if user_id not in fake_users_db:
        raise HTTPException(status_code=404, detail="Пользователь не найден")
    
    return {"user_id": user_id, "username": fake_users_db[user_id]}

Теперь наш маршрут будет доступен по адресу: http://localhost:8000/api/v1/users/1

Организуем маршруты по категориям 📂

Давайте создадим ещё один роутер для задач:

Файл routers/tasks.py:

from fastapi import APIRouter, HTTPException

router = APIRouter(
    prefix="/api/v1/tasks",
    tags=["tasks"]
)

# Фейковая база данных задач
fake_tasks_db = {
    1: {"title": "Купить молоко", "completed": False},
    2: {"title": "Написать статью", "completed": True}
}

@router.get("/")
def get_all_tasks():
    return fake_tasks_db

@router.get("/{task_id}")
def get_task(task_id: int):
    task = fake_tasks_db.get(task_id)
    if not task:
        raise HTTPException(status_code=404, detail="Задача не найдена")
    return task

Подключаем его в main.py:

from fastapi import FastAPI
from routers import users, tasks

app = FastAPI()

# Подключаем оба роутера
app.include_router(users.router)
app.include_router(tasks.router)

@app.get("/")
def read_root():
    return {"message": "Добро пожаловать в наше приложение!"}

Теперь маршруты выглядят логично и структурированно:

• http://localhost:8000/api/v1/users/1
• http://localhost:8000/api/v1/tasks/

Swagger: маршруты на ладони 📜

Не забывайте про встроенную документацию FastAPI! Она автоматически подхватывает наши роутеры, префиксы и теги.

Откройте: http://localhost:8000/docs

Видите разделы users и tasks? Всё структурировано и понятно!

Заключение

Разделение маршрутов на логические модули — это не просто прихоть, а необходимость для поддерживаемого и масштабируемого проекта. С роутерами в FastAPI вы держите код под контролем: каждый модуль отвечает за свою часть логики, и вам не нужно ломать голову, где искать нужный эндпоинт.

Следующий шаг? Погрузимся в зависимые роутеры и более сложные примеры маршрутизации.