FastAPI и PostgreSQL: система бронирования «Окно»
В 16 уроках создаём «Окно» — систему бронирования вымышленных кабинетов «Лён» и «Клён». Один проект развивается от чтения каталога до PostgreSQL, проверки времени, запрета конкурентных пересечений, идемпотентности, ownership, отмены, постраничной истории, outbox и OpenAPI. Это учебное расписание без платежей, действующих посетителей и внешних уведомлений.
Нужны основы Python, функций, классов, списков и словарей; понимание JSON и HTTP. SQL изучается на конкретной схеме, но знакомство с SELECT и INSERT поможет. Документационный профиль: Python 3.14, Pydantic 2, pydantic-settings 2, SQLAlchemy 2.0, Psycopg 3, PostgreSQL 18; FastAPI с поддержкой Pydantic 2. Диапазоны requirements.txt не являются разрешённым lockfile или проверенной совместимостью. Пакеты не устанавливались, сервер, SQL, миграции и сценарии не запускались: example_execution = not_run. Все показанные ответы являются ожидаемыми.
Последовательность результатов
| Урок | Что вы сможете объяснить и получить |
|---|---|
| 1. Запрос и ответ FastAPI: каталог кабинетов | Различать адрес ресурса, HTTP-операцию и JSON-ответ проекта «Окно». |
| 2. Модели Pydantic для запроса и ответа | Описать входной интервал и внешнюю карточку отдельными моделями. |
| 3. Ошибки API и граница неверного ввода | Возвращать различимые ошибки маршрута, схемы и предметной операции. |
| 4. Конфигурация FastAPI из окружения | Отделить настройки процесса от данных бронирования и кода маршрута. |
| 5. Зависимость FastAPI как источник ресурса | Подключать каталог через Depends и подготовить замену его хранилища. |
| 6. Схема PostgreSQL и история миграций | Создать договор хранения кабинетов и броней в последовательной SQL-миграции. |
| 7. Создание брони и граница транзакции | Записать бронь и вернуть внешнюю модель после успешной фиксации. |
| 8. Время брони: смещение и нормализация UTC | Принимать только даты со смещением и сравнивать их как моменты времени. |
| 9. Пересечения броней и exclusion constraint | Запретить пересекающиеся подтверждённые интервалы одного кабинета в PostgreSQL. |
| 10. Ключ повторного запроса на бронирование | Связать один ключ с одной сохранённой операцией и её первоначальным ответом. |
| 11. Личность и право на свою бронь | Получать владельца на сервере и ограничивать доступ его записью. |
| 12. Отмена брони как переход состояния | Отменять свою бронь без удаления истории и освобождать её интервал. |
| 13. Фильтр и постраничный список своих броней | Читать ограниченные страницы с курсором по id и условием владельца. |
| 14. Событие бронирования и транзакционный outbox | Сохранить событие вместе с бронью и отделить его обработку от HTTP-ответа. |
| 15. OpenAPI как описание договора «Окна» | Согласовать схему маршрутов с моделями, заголовками и известными ошибками. |
| 16. Готовность и передача учебного FastAPI-проекта | Описать границы запуска, проверку схемы и завершение ресурсов процесса. |
Состояния проекта и границы
Уроки 01–05 используют данные процесса. Шаг 06 вводит схему и чтение PostgreSQL. Шаги 07–08 позволяют локальную запись, но ещё не защищают многопользовательское расписание. С шага 09 exclusion constraint запрещает пересекающиеся confirmed-интервалы одного ресурса. Настоящие даты всегда содержат смещение и нормализуются к UTC; интервалы полуоткрытые, начало включено, конец исключён.
С шага 11 маршруты бронирования используют отдельный учебный провайдер двух вымышленных участников. Он выключен по умолчанию, предназначен для localhost и не является production-входом. actor_id никогда не принимается из тела намерения. Список, карточка и отмена проверяют владельца на сервере. Ключ создания принадлежит владельцу и возвращает первоначальный ответ даже после последующего изменения объекта.
Outbox фиксирует событие вместе с бронью. Получатель пишет только в stdout и может реагировать повторно после сбоя; гарантии «ровно один раз» нет. BackgroundTasks лишь предлагает прочитать сохранённые события и не заменяет отдельный надёжный процесс обработки. /ready проверяет доступ к базе и известные имена миграций, а не доставку уведомлений.
Скачать шестнадцать полных состояний. Выбирайте один lesson-NN целиком. Миграции применяются только к собственной учебной базе; runner не предназначен для произвольных SQL-функций с внутренними точками с запятой. Последний снимок содержит RELEASE.md с договором самостоятельной проверки. Публикация, установка зависимостей и действия с реальными аккаунтами в ходе подготовки не выполнялись.