Шаблон приложения FastAPI с аутентификацией и авторизацией

Этот проект представляет собой готовый шаблон для разработки масштабируемых веб-приложений на основе FastAPI с полноценной системой аутентификации и авторизации. Проект включает модульную архитектуру, поддерживает гибкое логирование с loguru, и взаимодействие с базой данных через SQLAlchemy с асинхронной поддержкой. Система миграций Alembic упрощает работу со схемой базы данных.

Стек технологий

• Веб-фреймворк: FastAPI
• ORM: SQLAlchemy с асинхронной поддержкой через aiosqlite
• База данных: SQLite (легко заменяемая на другую SQL-СУБД)
• Система миграций: Alembic
• Авторизация/Аутентификация: bcrypt для хеширования паролей, python-jose для защиты данных с использованием JWT

Зависимости проекта

• fastapi[all]==0.115.0 - высокопроизводительный веб-фреймворк
• pydantic==2.9.2 - валидация данных
• uvicorn==0.31.0 - ASGI-сервер
• jinja2==3.1.4 - шаблонизатор
• SQLAlchemy==2.0.35 - ORM для работы с базами данных
• aiosqlite==0.20.0 - асинхронная поддержка SQLite
• alembic==1.13.3 - управление миграциями базы данных
• bcrypt==4.0.1 и passlib[bcrypt]==1.7.4 - хеширование паролей
• python-jose==3.3.0 - работа с JWT токенами
• loguru==0.7.2 - красивое и удобное логирование

Структура проекта

Проект построен с учётом модульной архитектуры, что позволяет легко расширять приложение и упрощает его поддержку. Каждый модуль отвечает за отдельные задачи, такие как авторизация или управление данными.

Основная структура проекта

├── app/
│   ├── auth/                   # Модуль авторизации и аутентификации
│   │   ├── dao.py              # Data Access Object для работы с БД
│   │   ├── models.py           # Модели данных для авторизации
│   │   ├── router.py           # Роутеры FastAPI для маршрутизации
│   │   ├── schemas.py          # Схемы для валидации данных
│   │   └── utils.py            # Вспомогательные функции для авторизации
│   ├── dao/                    # Общие DAO для приложения
│   │   ├── database.py         # Подключение к базе данных и управление сессиями
│   │   └── base.py             # Базовый класс DAO для работы с БД
│   ├── dependencies            # Зависимости в проекте
│   │   ├── auth_dep.py         # Зависимости для авторизации
│   │   └── dao_dep.py          # Зависимости для сессий SQLAlchemy
│   ├── migration/              # Миграции базы данных
│   │   ├── versions/           # Файлы миграций
│   │   ├── env.py              # Настройки среды для Alembic
│   │   ├── README              # Документация по миграциям
│   │   └── script.py.mako      # Шаблон для генерации миграций
│   ├── static/                 # Статические файлы приложения
│   │   └── .gitkeep            # Пустой файл для сохранения папки в Git
│   ├── config.py               # Конфигурация приложения
│   ├── exceptions.py           # Исключения для обработки ошибок
│   ├── main.py                 # Основной файл для запуска приложения
├── data/                       # Папка для хранения файла БД
│   └── db.sqlite3              # Файл базы данных SQLite
├── .env                        # Конфигурация окружения
├── alembic.ini                 # Конфигурация Alembic
├── README.md                   # Документация проекта
└── requirements.txt            # Зависимости проекта

Обновленный раздел с подробным описанием основных модулей:

---

Основные модули

app/auth - Модуль для аутентификации и авторизации

Модуль отвечает за управление процессами аутентификации (входа пользователей) и авторизации (проверки доступа).
Основные файлы:

• dao.py: Объект доступа к данным пользователей. Содержит методы для работы с базой данных (создание, обновление, поиск пользователей и т. д.).
• dependencies.py: Внедрение зависимостей, таких как проверка токенов и авторизация для защищённых маршрутов.
• models.py: Определяет ORM-модели данных для пользователей (например, таблица Users в базе данных).
• router.py: Роутер для маршрутизации запросов, связанных с аутентификацией. Определяет эндпоинты для входа, регистрации и проверки доступа.
• schemas.py: Определяет Pydantic-схемы для валидации входных данных и структуры ответов (например, формат данных для регистрации пользователей).
• utils.py: Вспомогательные функции для работы с токенами (создание, проверка JWT) и шифрование паролей.

---

app/dao - Базовый слой доступа к данным (Data Access Layer)

Модуль содержит абстракции для работы с базой данных. Используется для управления подключениями и реализации CRUD-операций.

• base.py: Базовый класс DAO, предоставляющий общие методы для работы с базой данных, такие как добавление, обновление, удаление и поиск записей.
• database.py: Отвечает за подключение к базе данных, управление сессиями SQLAlchemy, а также создание асинхронного подключения (например, через aiosqlite).

---

app/migration - Управление миграциями базы данных с Alembic

Модуль упрощает управление схемой базы данных и позволяет безопасно вносить изменения.

• versions/: Хранятся файлы миграций, автоматически создаваемые Alembic.
• env.py: Основной файл конфигурации для Alembic. Определяет подключение к базе данных и взаимодействие с ORM.
• script.py.mako: Шаблон для генерации новых файлов миграций.

---

app/dependencies - Управление миграциями базы данных с Alembic

Модуль содержит зависимости, которые используются в проекте.

• auth_dep.py: Зависимости, связанные с авторизацией пользователя в системе
• dao_dep.py: Зависимости, связанные с управллением сессией SQLAlchemy и с работой с дочерними классами BaseDao

---

config.py - Настройки и конфигурация приложения

• Определяет параметры приложения, загружаемые из файла .env. Например:
  • SECRET_KEY: Секретный ключ для подписания JWT.
  • ALGORITHM: Алгоритм хеширования токенов.
  • DATABASE_URL: URL для подключения к базе данных.
• Обеспечивает удобное управление конфигурацией для разных окружений (локальное, тестовое, продакшн).

---

main.py - Основной файл для запуска приложения

• Инициализация приложения: Настраивает FastAPI-приложение, включая параметры, такие как название, версия, и описание.
• Подключение роутеров: Регистрирует маршруты, определённые в модулях приложения, например:
  • app.auth.router для маршрутов авторизации.
  • Любые дополнительные модули (например, app.users.router).
• Настройка зависимостей: Внедряет глобальные зависимости, такие как подключение к базе данных или параметры конфигурации.
• Настройка middleware: Добавляет промежуточные слои для обработки запросов (например, CORS, сжатие, обработка ошибок).
• Обработка ошибок: Определяет глобальные обработчики исключений, чтобы возвращать понятные ответы при возникновении ошибок (например, 401 Unauthorized или 500 Internal Server Error).
• Запуск сервера: Используется для старта приложения с помощью ASGI-сервера (Uvicorn).

Настройка аутентификации и авторизации

Для аутентификации используется JSON Web Token (JWT) с bcrypt для хеширования паролей и python-jose для генерации и проверки токенов. Это обеспечивает безопасное хранение данных и защищает API-эндпоинты.

Запуск приложения

1. Клонируйте репозиторий:

   git clone https://github.com/Yakvenalex/FastApiWithAuthSample.git .

2. Установите зависимости:

   pip install -r requirements.txt

3. Создайте и настройте .env файл:

   SECRET_KEY=supersecretkey
   ALGORITHM=HS256

4. Запустите приложение с Uvicorn:

   uvicorn app.main:app --reload --port 8005

При необходимости замените port на нужный.

Миграции базы данных

1. Инициализируйте Alembic:

   cd app
   alembic init -t async migration

   Затем переместите alembic.ini в корень проекта.

2. В alembic.ini установите script_location как app/migration.

3. Создайте миграцию:

   alembic revision --autogenerate -m "Initial migration"

4. Примените миграции:

   alembic upgrade head

Лучшие практики

• Разделяйте функциональность приложения на модули для удобства тестирования и поддержки.
• Обрабатывайте ошибки с четкими ответами и HTTP-кодами.
• Проводите миграции с Alembic для управления схемой базы данных.
• Используйте переменные окружения для безопасного хранения конфиденциальных данных.

---

Этот шаблон является мощной и удобной основой для разработки приложений на FastAPI с поддержкой аутентификации, авторизации и структурированной архитектуры, готовой к масштабированию.