Кейс · Бэкенд · Python

catalog-api: API каталога с поиском

API каталога товаров на Python 3.12 и FastAPI: SQLite с полнотекстовым поиском FTS5 (ранжирование bm25), фасеты по категории, цене, наличию, тегам и характеристикам, курсорная пагинация, ETag, импорт и экспорт CSV, история цен, API-ключи с ролями и аудит-лог. Витрина и админка без фреймворка отдаются самим приложением. Пет-проект.

  • Python
  • FastAPI
  • SQLite
  • FTS5
  • pytest
  • ruff
  • mypy
  • bandit
  • Docker
  • GitHub Actions
Код по запросу в Telegram

01 · Как выглядит

Скриншоты

Скриншот проекта «catalog-api: API каталога с поиском» на экране 1280 пикселей
Десктоп, 1280 px
Скриншот проекта «catalog-api: API каталога с поиском» на экране телефона, 390 пикселей
Телефон, 390 px

02 · О проекте

Что это и зачем

catalog-api — API каталога товаров на Python 3.12 и FastAPI с витриной и админкой, которые отдаёт само приложение. Пет-проект.

Хранилище SQLite: полнотекстовый поиск через FTS5 с ранжированием bm25, фасеты по категории, цене, наличию, тегам и характеристикам, пагинация курсором с подписью. Доступ по API-ключам с ролями admin, editor и reader: показывается один раз, в базе только хэш. Демо-режим SEED_DEMO=1 поднимает 300 синтетических товаров.

Ограничения

Живой версии нет: Cloudflare не запускает Python-сервер с SQLite. Запуск локально, в Docker или на своём VPS.

Лимитер запросов хранится в памяти процесса: при нескольких воркерах лимит умножается. SQLite рассчитан на один процесс записи. Нет морфологии русского языка и исправления опечаток.

Изображения не перекодируются, метаданные сохраняются как есть. Фасеты не дизъюнктивные; общее число считается точно на каждом запросе, на миллионах товаров это нужно заменять.

Демо-ключи публичны и работают только при SEED_DEMO=1. Не проверялись работа за реальным reverse proxy с TLS, браузеры кроме Chromium и скринридеры. Нагрузочный замер один, на одной машине.

Что внутри

  • Поиск FTS5 с bm25, фасеты, сортировки и курсорная пагинация; ETag для условных запросов
  • Импорт и экспорт CSV, история цен, загрузка изображений с проверкой сигнатуры и лимитов, аудит-лог
  • API-ключи с ролями, лимитер запросов, строгие заголовки безопасности; OpenAPI в dev-режиме и выключен в production
  • Витрина и админка без фреймворка, sitemap, robots, llms.txt и OG-теги
  • 511 тестов, покрытие 96%; ruff, mypy --strict, bandit, pip-audit и gitleaks без замечаний
  • Нагрузочный замер: 339 запросов/с, p95 50 мс при 8 соединениях (Windows, один процесс)
  • Docker-образ на python:3.12-slim, пользователь uid 10001, HEALTHCHECK, штатное завершение по SIGTERM

03 · Как запустить

Запуск одной командой

git clone <репозиторий по запросу> catalog-api
cd catalog-api
python -m venv .venv && .venv/bin/pip install --require-hashes -r requirements.lock
SEED_DEMO=1 python -m app   # http://127.0.0.1:8110, админка /admin

04 · Код

Репозиторий приватный

Исходники лежат в приватном репозитории. Напишите в Telegram, открою доступ.

Запросить код