Opus claude-opus-5-5 · effort xhigh срез: 2026-10-01 источников: 133 слов: 21296 complete

Django для API-серверов: производительность, гибкость, наблюдаемость и поддерживаемость без оверинжиниринга

Справочник рациональных практик Django API-серверов на 2026-10-01: 17 практик базового набора с автоматическими проверками CI, 16 расширений по сигналу с порогами, 17 типовых задач с вариантами, сравнение философий Kraken, Sentry, PostHog, Zulip, Instagram, HackSoft, Беннетта и Планта. Главный вывод: качество определяют машинно проверяемые правила, а не число слоёв; монолит на Django 5.2 LTS или 6.1 с DRF или Ninja подтверждён масштабом. Ограничение: доказательная база — документация, опросы и кейсы, пороги сигналов — ориентиры автора.

Вердикт

Справочник описывает рациональный способ строить API-серверы на Django на 2026-10-01: Django 5.2 LTS или 6.1, DRF или Django Ninja, PostgreSQL с PostGIS, Redis, одна очередь фоновых задач и минимальная наблюдаемость факт [S1, S2]. Для небольшой команды, где значительную часть кода пишут ИИ-агенты, главный вывод: качество определяет не число слоёв, а базовый набор из 17 практик, закреплённых автоматическими проверками CI гипотеза.

  • Базовый набор. Явные схемы API, контроль числа SQL-запросов, ограничения в базе, миграции expand/contract, доступ к данным только через scoped-менеджеры компании, постановка задач после фиксации транзакции.
  • По сигналу. ASGI, пулеры, реплики, кэш данных, OpenTelemetry, границы модулей, JWT и схемы на арендатора добавляются только после пересечения порогов из карточек Р01–Р16.
  • Подтверждение масштабом. Kraken, Sentry, PostHog и Zulip сохраняют Django-монолит, растут через машинно проверяемые границы и выносят горячие пути точечно; Instagram остаётся одним из крупнейших деплоев Django и улучшает рантайм, а не меняет фреймворк факт [S3, S4, S5, S6, S7].
  • Регионы и установки у клиентов. Рациональна схема «один образ, отличия в окружении и фича-флагах» с self-hosted GlitchTip там, где SaaS недопустим гипотеза.
  • Ключевое ограничение. Доказательная база — документация, опросы и кейсы; контролируемых сравнений практик нет, пороги сигналов — ориентиры автора.
  • Самая сильная альтернатива. В устройстве кода — модульный монолит с контрактами импортов, окупающийся примерно от 15–20 приложений или 8–10 параллельных авторов; в API-слое — Django Ninja вместо DRF для нового проекта, где сквозные типы важнее экосистемы пакетов гипотеза.
  • Уверенность. Высокая для фактов о версиях и механизмах Django и PostgreSQL (первоисточники), средняя для архитектурных рекомендаций (мнения и кейсы больших организаций), низкая для численных порогов.

Что это и как работает

Определение

Django API-сервер — это Django-проект, который отвечает клиентам машиночитаемыми данными (обычно JSON по HTTP) и не рендерит HTML-страницы. Предмет справочника — не сам Django, а набор решений вокруг него: как устроены API-слой, доменный код, работа с PostgreSQL, фоновые задачи, наблюдаемость, тесты, типы и рантайм. Практика в справочнике считается полезной, только если она двигает хотя бы одну метрику проекта: стабильность, скорость разработки, гибкость, производительность, наблюдаемость, поддерживаемость или функциональность.

Составные части типичного проекта:

Часть Назначение Выбор по умолчанию на 2026-10 Добавлять по сигналу
Сервер приложений Принимает HTTP, держит процессы и потоки Gunicorn (WSGI, sync/gthread) ASGI-сервер (Uvicorn, Granian и др.) при долгих соединениях
Django core Middleware, URL, ORM, миграции, auth, cache, settings Django 5.2 LTS или 6.1 —
API-слой Разбор и проверка входа, права, сериализация, OpenAPI DRF или Django Ninja Собственный тонкий слой, GraphQL
Доменный код Бизнес-правила и операции Методы моделей и QuerySet, функции для сценариев Фасады и контракты между доменами
PostgreSQL Данные, ограничения, транзакции, поиск, PostGIS Одна основная база Реплики чтения, пул на стороне сервера
Redis Кэш, брокер, rate limit Один экземпляр Отдельные экземпляры под кэш и брокер
Фоновые задачи Работа вне цикла запрос-ответ Одна очередь с воркером Расширенная маршрутизация, отдельные пулы
Наблюдаемость Ошибки, логи, метрики, трассировки Sentry SDK или совместимый self-hosted, JSON-логи OpenTelemetry, Prometheus

Механизм: путь запроса

  1. Сервер приложений принимает соединение и передаёт его Django через WSGI или ASGI. Django документирует ASGI-серверы Daphne, Granian, Hypercorn и Uvicorn факт [S8].
  2. Запрос проходит цепочку middleware, затем URL-резолвер выбирает представление.
  3. API-слой выполняет аутентификацию, проверку прав, ограничение частоты и разбор тела. В DRF это классы authentication, permission и throttle, в Django Ninja — параметры операции и схемы Pydantic факт [S9, S10].
  4. Доменный код читает и меняет данные через ORM внутри транзакции.
  5. Ответ сериализуется в JSON.
  6. После фиксации транзакции срабатывают хуки transaction.on_commit, которые ставят фоновые задачи. Документация Django прямо предупреждает, что воркер может начать задачу раньше фиксации и не увидеть объект, если ставить её внутри транзакции факт [S11, S12].

Модель процессов и соединений

Производительность и стабильность Django API-сервера в первую очередь определяет не код представлений, а арифметика процессов, потоков и соединений с базой гипотеза. Правила Django:

  • Без пула соединение открывается при первом запросе к базе и живёт до CONN_MAX_AGE секунд; значение 0 закрывает его в конце каждого запроса, None держит без ограничения факт [S13].
  • CONN_HEALTH_CHECKS = True проверяет переиспользуемое соединение один раз за запрос, что спасает после перезапуска PostgreSQL факт [S13].
  • Встроенный пул (только psycopg 3, с Django 5.1) создаётся отдельно для каждого алиаса базы в каждом процессе; при включённом пуле CONN_MAX_AGE обязан быть 0 факт [S13, S14].
  • Под ASGI постоянные соединения нужно отключать и использовать пул факт [S13].
  • В режиме transaction pooling PgBouncer нужно отключить server-side cursors (DISABLE_SERVER_SIDE_CURSORS = True), иначе iterator() ломается на чужом соединении факт [S13].

Отсюда следует оценка верхней границы соединений, которую стоит держать в README проекта гипотеза:

соединения ≈ Σ по типам процессов (экземпляры × процессы × потоки_или_размер_пула)
условие:    соединения ≤ max_connections − резерв на миграции, админов и репликацию

Пример, иллюстрация: 3 контейнера × 4 процесса Gunicorn × 4 потока = 48 соединений; плюс 2 воркера задач × concurrency 8 = 16; итого 64 при max_connections = 100. Удвоение числа контейнеров при автоскейлинге даст 112 и отказ новых соединений; это сигнал для пула или PgBouncer, а не для переписывания кода.

Границы понятия

  • Не HTML-представления. Шаблоны, формы и обычные представления Django для страниц в предмет не входят.
  • Не FastAPI и не другие фреймворки. Django Ninja похож на FastAPI синтаксисом, но интегрирован с Django: ORM, auth через request, несколько версий API в одном проекте факт [S10].
  • django.tasks — не очередь задач. В Django 6.0 появился общий API для задач, но Django «не предоставляет механизм воркера», а встроенные бэкенды предназначены для разработки и тестов факт [S15, S11].
  • «API-сервер» не равно «микросервис». Большинство подтверждённых нагрузкой проектов в этом справочнике — монолиты: Kraken, Zulip, Sentry, PostHog факт [S3, S6, S5].

Версии на дату среза

Компонент Версия Дата Срок поддержки или замечание Источник
Django 5.2 LTS 5.2.17 релиз 2025-04-02 расширенная поддержка до апреля 2028 [S1, S16]
Django 6.0 6.0.8 релиз 2025-12-03 расширенная поддержка до апреля 2027 [S1, S15]
Django 6.1 6.1.1 релиз 2026-08-05 основная до апреля 2027, расширенная до декабря 2027; Python 3.12–3.14; PostgreSQL 15+ [S1, S2]
Django 6.2 LTS план апрель 2027 расширенная поддержка до апреля 2030 [S1]
Django 2028 план январь 2028 годовой цикл, каждая версия 3 года поддержки [S17, S1]
DRF 3.18.1 2026-09-07 3.18 поддерживает только Django 5.2+ [S18]
Django Ninja 1.7.1 2026-09-19 поддержка Django до 6.1 [S19]
Celery 5.6.3 2026-03-26 Python 3.9+, 3.14 поддерживается [S20]
Gunicorn 26.2.2 2026-09-06 ASGI-воркер стабилен с 25.1.0 [S21]
django-stubs 6.1.1 без даты Django 6.1, 6.0, 5.2 [S22]

Варианты API-слоя

Вариант Механизм Типичный пользователь
DRF Классы APIView/ViewSet, сериализаторы, роутеры, пакеты расширений addons-server от Mozilla, PostHog факт [S23, S5]
Django Ninja Операции-функции с аннотациями типов, схемы Pydantic, встроенный OpenAPI, sync и async проекты, которым нужен schema-first без отдельного генератора схемы факт [S10]
Собственный тонкий слой Декоратор над обычным представлением, валидация через Pydantic Zulip: typed_endpoint на Pydantic v2 факт [S24]
GraphQL поверх Django Graphene или Strawberry Saleor (подписки GraphQL задают payload вебхуков), NetBox (read-only GraphQL на Strawberry Django рядом с REST) факт [S25, S26]

Актуальность и доказательная база на дату среза

Распространённость и тренд

Главный количественный источник — ежегодный опрос DSF и JetBrains. Django для API — основной, а не нишевый сценарий: 53 % респондентов 2026 года делают API-only приложения эмпирика [S27].

Показатель Значение Год опроса Источник
Респондентов около 3 500 из 40+ стран 2026 [S27]
API-only приложения 53 % 2026 [S27]
DRF среди пользователей API-фреймворков 73 % 2026 [S28]
Django Ninja среди пользователей API-фреймворков 17 % 2026 [S28]
Собственный API-слой / GraphQL 13 % / 9 % 2026 [S28]
Используют async-возможности Django / планируют 33 % / 40 % 2026 [S28]
PostgreSQL 76–79 %, пять лет подряд 2026 [S27]
Redis как кэш 53 % 2026 [S28]
На Django 6.0 / 5.x / 4.x / старше 43 % / 44 % / 6 % / 3 % 2026 [S28]
Монолит / self-hosted или VPS 54 % / 44 % 2026 [S28]
Используют аннотации типов / mypy / Pyright / ty 57 % / 32 % / 22 % / 12 % 2026 [S27]
Ruff / pytest / pytest-django / нет автотестов 43 % / 45 % / 34 % / 19 % 2026 [S27]
Claude Code / ChatGPT / Copilot; без ИИ-инструментов 35 % / 33 % / 23 %; 10 % 2026 [S27]
Celery (django-celery) 26 % 2025 [S29]

Ограничения опроса: выборка самоотобранная через каналы DSF и JetBrains, JetBrains — заинтересованная сторона в теме инструментов, формулировки вопросов меняются между годами, поэтому DRF «49 %» в 2025 году эмпирика [S29] и «73 %» в 2026 году считаются от разных знаменателей и не образуют тренд.

Тренды с основаниями:

  • DRF — стабилен и заморожен по функциям. Проект объявлен «feature-complete», принимаются только изменения для новых версий Django и Python, безопасность и документация факт [S30, S31]. Релизы при этом выходят регулярно: 3.17.0 в марте 2026, 3.18.0 в августе 2026 с поддержкой Django 6.1 факт [S18].
  • Django Ninja — растёт. Десять релизов с ноября 2025 по сентябрь 2026 факт [S19]; в 2024 году пользователи поднимали вопрос о единственном сопровождающем, автор ответил, что проект финансируется и обязан поддерживаться по графику LTS Django факт [S32].
  • Async — интерес выше практики. 33 % используют, 40 % планируют эмпирика [S28]; документированные случаи пользы — долгие соединения и параллельные внешние вызовы факт [S33, S34].
  • Фоновые задачи — переходный период. django.tasks задаёт общий API с Django 6.0, но без воркера и production-бэкенда в ядре факт [S15]; официального бэкенда Celery для него нет, запрос открыт с января 2026 факт [S35].
  • Цикл релизов Django меняется. С 2028 года — одна версия в год, каждая с тремя годами поддержки; 5.2 LTS и 6.2 LTS сохраняют прежние обязательства факт [S17].

Научная и эмпирическая база

Контролируемых исследований или рецензируемых сравнений архитектурных практик Django не найдено; вывод о «лучшей» структуре проекта на экспериментах не опирается гипотеза. Имеющаяся эмпирика — это измерения отдельных механизмов и кейсы проектов с числами:

Наблюдение Дизайн и ограничения Источник
Загрузка 32 500 строк: 128,8 с поштучно, 1,47 с execute_values, 0,46 с COPY из итератора один набор данных, один стенд, 2019 год, psycopg2 эмпирика [S36]
COUNT(*) занимал 781 мс из 786 мс загрузки страницы списка одна большая таблица, админка Django, 2018 год эмпирика [S37]
migrate_schemas при ~1780 схемах: 5–14 с CPU базы на арендатора даже без изменений один отчёт пользователя django-tenants, сентябрь 2026 эмпирика [S38]
Детектор N+1 django-zeal даёт 3–5 % накладных расходов бенчмарк автора библиотеки вендор [S39]
FETCH_PEERS сводит цикл с N+1 к двум запросам пример из документации, не нагрузочный тест факт [S40]
Пул psycopg снижает задержку на 50–70 мс одна статья без описания методики, managed PostgreSQL эмпирика [S41]
Immortal Objects в Instagram: регрессия около 2 % при росте разделяемой памяти внутреннее измерение Meta эмпирика [S42]
Healthchecks.io: CPU уходил на Python-код приёма пингов, после переноса обработчика на Go основная нагрузка — TLS наблюдение автора соло-проекта, 2016–2017 эмпирика [S43]

Кейсы с подтверждённым масштабом:

  • Kraken (Octopus Energy): 27 637 модулей и около 400 разработчиков в 2023 году факт [S3]; около 9 млн строк Python, более 100 выкладок в день в 25+ окружений, более 100 000 тестов за время до получаса факт [S44]; 5 млн строк под mypy, 2000+ моделей, 2,5 года до нуля неаннотированного кода факт [S45].
  • Instagram: «один из крупнейших в мире деплоев Django» вендор [S7]; pre-fork-процессы с разделяемой памятью факт [S42].
  • Zulip: тесты бэкенда параллельно укладываются менее чем в 30 секунд, новый код требует 100 % покрытия, каждый ответ API в тестах сверяется с OpenAPI факт [S46, S47].

Мнение отрасли

Спорная позиция Сторонники Критики Суть спора
Отдельный сервисный слой (services/selectors) HackSoft мнение [S48]; Kraken: интерфейс делает один вызов в домен факт [S49] Джеймс Беннетт, Люк Плант мнение [S50, S51] Слой даёт явные точки входа, но в Active Record ORM превращается в «собственный приватный ORM»
Принудительные границы модулей PostHog (tach + import-linter, baseline только вниз) факт [S5]; Kraken (40+ контрактов Import Linter) факт [S3] — Цена — инверсия зависимостей и локальная сложность, признают сами авторы мнение [S3]
Async Django документация Django для долгих соединений факт [S33] Kraken: для большинства задач очереди проще мнение [S34] Выигрыш только при параллельном вводе-выводе
django.tasks как основной инструмент Тим Шиллинг для малых проектов мнение [S52] Kevin Renskers: нет воркера, ретраев, расписания мнение [S53] Стандарт API против зрелости экосистемы
JWT для своего клиента — django-allauth: JWT ошибочно называют stateless, отзыв требует состояния мнение [S54] Сложность без выигрыша в монолите
Библиотеки фабрик тестовых данных HackSoft рекомендует factory_boy мнение [S48] Люк Плант: простые функции понятнее и лучше типизируются мнение [S55] Удобство против прозрачности

Главные споры

  1. Где живёт бизнес-логика и сколько слоёв нужно.
  2. DRF или Django Ninja для нового проекта.
  3. Нужен ли ASGI и async-код API-серверу без долгих соединений.
  4. Celery, более простая очередь или django.tasks с бэкендом.
  5. Сессии, непрозрачные токены или JWT.
  6. Мультиарендность общей базой, схемами или отдельными базами.
  7. Насколько строгая типизация окупается в Django.

Что изменилось за последние 2–3 года

Изменение Версия и дата Влияние на практики Источник
db_default, GeneratedField Django 5.0, 2023-12-04 Значения по умолчанию на стороне базы, безопасные для выкладки миграций; вычисляемые поля для поиска [S56]
Встроенный пул соединений PostgreSQL Django 5.1, 2024-08-07 PgBouncer перестаёт быть обязательным для малого числа хостов [S14]
CompositePrimaryKey, async-методы auth Django 5.2 LTS, 2025-04-02 Таблицы связей и унаследованные схемы без суррогатного ключа [S16]
API задач, CSP, BigAutoField по умолчанию, AsyncPaginator, Python 3.12+ Django 6.0, 2025-12-03 Код задач можно писать против стандартного API; новые модели сразу с 64-битным ключом [S15]
Fetch modes, DB_CASCADE, MAILERS, UUID7(), PostgreSQL 15+ Django 6.1, 2026-08-05 N+1 гасится режимом FETCH_PEERS, а FETCH_RAISE ловит лишние запросы; каскад в базе быстрее, но без сигналов [S2]
Годовой цикл и календарные версии DEP 20, 2026-08-10 Обновление раз в год вместо прыжков между LTS [S17]
DRF объявлен feature-complete, coreapi удалён 2024–2026 Новых функций в DRF ждать не стоит, расширения — сторонние пакеты [S31, S18]
Ninja: cursor pagination, стриминг JSONL и SSE, Retry-After 1.6–1.7, 2026 Закрывает типовые задачи без самописного кода [S57]
Gunicorn: ASGI-воркер стабилен, eventlet удалён 25.1.0 и 26.0.0, 2026 Один сервер для WSGI и ASGI, но с оговорками по обработке ошибок парсера [S21, S58]
Celery: soft shutdown, quorum queues, лимит ETA-задач 5.5–5.6, 2025 Меньше потерь задач при выкладке [S20]
Регресс памяти incremental GC в Python 3.14, откат в 3.14.5 2026 Обновлять Python до патч-версии с откатом [S59]
Стабилизация HTTP semantic conventions OpenTelemetry 2025–2026 По умолчанию инструментации Python всё ещё пишут старые экспериментальные атрибуты; переход включается OTEL_SEMCONV_STABILITY_OPT_IN=http или http/dup [S60, S61]
AGENTS.md под Agentic AI Foundation 2025–2026 Единый файл правил для ИИ-агентов вместо разрозненных конфигураций [S62]

Где применимо и где нет, плюсы и минусы

Предмет раздела — Django как основа API-сервера вместе с рациональным набором практик из раздела 5. Сравнение с другими фреймворками сознательно не проводится.

Подходит, когда

  • Домен реляционный и богат правилами: компании, пользователи, права, документы, справочники. ORM, миграции, ограничения базы и админка закрывают большую часть инфраструктурного кода; PostgreSQL выбирают 76–79 % пользователей Django эмпирика [S27].
  • Команда небольшая, а часть кода пишут ИИ-агенты. Один общепринятый способ делать типовые вещи сокращает число решений, которые агент может принять неверно; 35 % респондентов уже работают с Claude Code эмпирика [S27].
  • Один код развёрнут во многих окружениях: регионы, клиенты, установки у заказчика. Kraken обслуживает 17 компаний одним кодом со слоями clients и territories факт [S3] и выкладывает более 100 версий в день в 25+ окружений факт [S44]; Sentry разделил регионы внутри того же Django-монолита через silo факт [S4].
  • Тяжёлая фоновая обработка на тех же моделях. Воркеры используют те же модели и транзакции, что и API, без второго слоя доступа к данным; Celery документирует транзакционную постановку задач для Django факт [S12].
  • Нужны геоданные. GeoDjango поставляется с Django, PostGIS — рекомендованный бэкенд факт [S63].
  • Код должен жить годами. LTS-версии получают три года поддержки, с 2028 года — каждая версия факт [S17, S1].

Не подходит, когда

  • Один горячий эндпоинт с минимальной работой и очень высоким RPS. Накладные расходы Python и Django на запрос становятся главной статьёй CPU; Healthchecks.io вынес только приём пингов на Go, оставив остальное в Django эмпирика [S43].
  • Нужны десятки тысяч долгих соединений в процессах приложения. Zulip держит их в отдельном Tornado-сервере и запрещает там блокирующие запросы к базе факт [S6]; Django Channels сопровождается в режиме best-effort с гарантией только для исправлений безопасности факт [S64].
  • Запрос состоит из множества параллельных внешних вызовов внутри одной транзакции. Транзакции в async-режиме Django не работают, их приходится оборачивать в sync_to_async факт [S33, S34].
  • Основная нагрузка — тяжёлые вычисления на CPU внутри запроса. Процессная модель с GIL масштабируется копиями процесса, а не потоками; Instagram для экономии памяти дошёл до доработки самого рантайма Python факт [S42].

Плюсы

  • Готовые auth, админка, миграции, ORM, кэш, CSP. Меньше кода собственной инфраструктуры, который нужно поддерживать и ревьюить факт [S15].
  • Предсказуемые обновления. Годовой цикл с 2028 года и три года поддержки каждой версии факт [S17].
  • Зрелый API-слой. DRF стабилен и сопровождается под новые версии Django факт [S18]; Django Ninja даёт schema-first с Pydantic и встроенным OpenAPI факт [S10].
  • Подтверждённый масштаб монолита. Kraken: около 9 млн строк Python в одном репозитории факт [S44]; Instagram — один из крупнейших деплоев Django вендор [S7].
  • Встроенные средства против типовых проблем производительности. FETCH_PEERS/FETCH_RAISE против N+1, пул соединений, db_default, DB_CASCADE факт [S2, S14, S56].

Минусы

  • Ленивые загрузки ORM порождают скрытые запросы. Цикл по списку легко превращается в N+1; нужна проверка числа запросов в тестах или режим fetch modes факт [S40, S46].
  • Асинхронность неполная. Нет транзакций в async-режиме, есть цена переключения контекстов, синхронные middleware в ASGI вынуждают переключения факт [S33].
  • Типизация ограничена. Плагин mypy для django-stubs использует рантайм Django, Pyright поддержан базово факт [S22]; Kraken отмечает привязку к mypy как издержку факт [S45].
  • Миграции могут блокировать таблицы. Без дисциплины expand/contract и таймаутов блокировок выкладка останавливает запись факт [S65, S66].
  • Риски экосистемы API-слоя. DRF не принимает новые функции факт [S30]; у Django Ninja вопрос единственного сопровождающего поднимался публично факт [S32].
  • Память процессов. Масштабирование процессами множит память и соединения с базой; это видно и в формуле соединений из раздела 1, и в опыте Instagram факт [S42].

Альтернативы и дерево решений

Альтернативные подходы к устройству кода

Предмет сравнения — подход, рекомендуемый этим справочником: идиоматичный Django с явными схемами API и доменными функциями, которые появляются только для сценариев, затрагивающих несколько моделей или внешние эффекты. Это синтез позиций Беннетта и Планта, HackSoft и конвенций Kraken; как целое он нигде не измерен гипотеза.

Подход Где живёт логика Слоёв Скорость старта Защита от связности Удобство для ИИ-агентов Цена отката Подтверждение
Предмет: идиоматичный Django + явные схемы + доменные функции по сигналу Методы модели и QuerySet для одной сущности; функции services.py для сценариев с несколькими моделями, задачами и внешними вызовами 2–3 Высокая Средняя; import-linter добавляется по сигналу Высокое: одна точка входа на сценарий, схемы явные Низкая Синтез источников ниже гипотеза
«Толстые модели» (Беннетт, Плант) Модели, менеджеры, QuerySet 2 Максимальная Низкая Среднее: сценарии из нескольких моделей не имеют своего места Низкая Мнение авторов мнение [S50, S51]
Services/selectors (HackSoft) services для записи, selectors для чтения; не в views, serializers, save(), сигналах 3 Средняя Средняя Высокое, но много однотипных файлов Средняя Руководство компании-разработчика, масштаб не опубликован мнение [S48]
Модульный монолит с контрактами (Kraken, PostHog) Доменные пакеты с фасадами и DTO; линтер импортов в CI 3–4 Низкая Высокая, автоматическая Высокое в большой команде Высокая 400 разработчиков Kraken факт [S3]; PostHog факт [S5]
CRUD-first DRF ModelSerializer, perform_create, сигналы 1–2 Максимальная на старте Низкая Низкое при росте: логика спрятана в хуках Средняя Распространённая практика без опубликованных кейсов гипотеза
Собственный тонкий слой (Zulip) Функции + декоратор typed_endpoint на Pydantic v2 2 Средняя Средняя Высокое: типы в сигнатуре Высокая: свой мини-фреймворк Zulip факт [S24]

Когда альтернатива целесообразнее предмета:

  • «Толстые модели» — соло-проект или домен из 5–10 моделей без сложных сценариев.
  • Плюсы: меньше файлов, полное использование ORM и DRF без прослоек.
  • Минусы: сценарий «создать заказ, списать лимит, отправить вебхук» не принадлежит ни одной модели и оседает в представлении.
  • Services/selectors — команда со смешанным опытом, которой нужен один шаблон на всё.
  • Плюсы: предсказуемость; задачи Celery вызывают сервисы, а не наоборот мнение [S48].
  • Минусы: тонкие сервисы-прокладки над Model.objects.create; сами авторы называют подход «не единственным» мнение [S48]; Беннетт называет это написанием «собственного приватного ORM» мнение [S50].
  • Модульный монолит с контрактами — от 20–30 разработчиков или от 15–20 доменных приложений с циклическими импортами (порог — ориентир гипотеза).
  • Плюсы: границы проверяются машиной; PostHog запрещает рост счётчика пересечений моделей в CI факт [S5].
  • Минусы: инверсия зависимостей и локальная сложность, которые признаёт сам Kraken мнение [S3].
  • CRUD-first DRF — прототип, внутренняя админ-API, срок жизни меньше года.
  • Плюсы: минимум кода.
  • Минусы: бизнес-правила в perform_create и сигналах не видны из точки вызова и не переиспользуются задачами.
  • Собственный слой — только при масштабе и сроке жизни уровня Zulip.
  • Плюсы: полный контроль, OpenAPI как источник истины с проверкой каждого ответа в тестах факт [S47].
  • Минусы: своя библиотека, которую поддерживает команда.

Философии знаковых проектов и людей

Кто Подтверждение Логика и слои Тесты Типы Фоновые задачи Наблюдаемость и эксплуатация Обновления Сознательно избегают
Instagram «Один из крупнейших деплоев Django» вендор [S7] Не опубликовано в прочитанных источниках Не опубликовано Не опубликовано Не опубликовано Pre-fork-процессы с разделяемой памятью; доработки рантайма (Cinder, Immortal Objects) факт [S42] Не опубликовано Смены фреймворка: вкладываются в рантайм Python гипотеза
Kraken ~9 млн строк, 100+ выкладок в день, 25+ окружений факт [S44] Слои clients → territories → core, 40+ контрактов Import Linter факт [S3]; интерфейс делает один вызов в домен факт [S49] 100 000+ тестов менее чем за 30 минут факт [S44] mypy на 5 млн строк, свой плагин факт [S45] Celery на RabbitMQ факт [S67] Один /health/ для трёх проб; миграции до выкладки факт [S68] Непрерывная выкладка, фича-флаги, обратно совместимые миграции факт [S44] Неявного ordering в Meta, ModelForm, валидаторов полей, запросов в @property факт [S49]
Sentry 35 000 тестов, прогон в двух режимах факт [S4] Монолит с silo: control и регионы, RPC и outbox факт [S4, S69] Симуляция границ silo в CI через ORM факт [S4] Не проверено Outbox и tombstones для межрегиональных изменений факт [S69] Свой продукт Двухфазное удаление колонок, post-deploy миграции факт [S66] Переименований колонок, межрегиональных внешних ключей факт [S66, S69]
PostHog Открытый монорепозиторий Вертикальные продукты: facade + frozen dataclasses, DRF в presentation факт [S5] Выборочный прогон по изменённым контрактам факт [S5] Контракты без импортов Django факт [S5] Celery в tasks/ факт [S5] Не проверено Не проверено Выдачи моделей через фасады, роста пересечений факт [S5]
Zulip Открытый проект с долгой историей Django + отдельный Tornado для push факт [S6] < 30 с параллельно, 100 % покрытия нового кода, проверка числа запросов факт [S46] typed_endpoint на Pydantic v2 факт [S24] RabbitMQ-очереди факт [S6] OpenAPI сверяется с каждым ответом факт [S47] Не проверено Блокирующих вызовов в Tornado факт [S6]
Healthchecks.io Один человек с июля 2015 года, доступность выше 99,9 % вендор [S70]; ~€274 в месяц на железо в 2019 факт [S71] Обычный Django Не проверено Не проверено Нет очереди: sendalerts, sendreports как systemd-сервисы факт [S71] Внешние пинги, агрегатор логов факт [S71] Не проверено Контейнеров, автоскейлинга, serverless факт [S71]; горячий путь вынесен в Go факт [S43]
addons-server (Mozilla) Бэкенд addons.mozilla.org DRF факт [S23] Не проверено Не проверено Не проверено Не проверено DRF 3.18.1 влит через 16 дней после выхода, Dependabot факт [S23, S18] Не проверено
NetBox Широко используемый open source REST плюс read-only GraphQL на Strawberry факт [S26] Не проверено Не проверено RQ-воркер факт [S72] Лимит страницы 1000, хешированные токены v2 факт [S73] PostgreSQL 15+, Python 3.12+ факт [S72] Не проверено
HackSoft Руководство без метрик масштаба services/selectors, Input/OutputSerializer внутри API мнение [S48] Фабрики, тесты бьют в базу, мокаются внешние вызовы мнение [S48] Аннотации у сервисов мнение [S48] Задача вызывает сервис, постановка через on_commit мнение [S48] Не входит в руководство Не входит Логики в сериализаторах, save(), сигналах мнение [S48]
Джеймс Беннетт Многолетний участник Django Модели и QuerySet, без service layer мнение [S50] — — — — — Слоёв «на всякий случай» (YAGNI) мнение [S50]
Люк Плант Автор «Django Views — The Right Way» Тонкие представления, цепочки QuerySet мнение [S51] Фабрики-функции вместо factory_boy мнение [S55] Типы через обычные функции мнение [S55] — — — filter() прямо в представлении мнение [S51]
Адам Джонсон Участник Django, автор инструментов Автоматизация рутины: линейные миграции, быстрый JSON мнение [S74, S75] — — — — Обходит регрессию рантайма до патча Python: gc.collect() после миграций факт [S59] Ручных merge-миграций мнение [S74]
Хаки Бенита Автор разборов ORM и PostgreSQL Работу переносить в базу: F-выражения, UPDATE … RETURNING, COPY мнение [S76, S36] — — — Измерять запрос, а не гадать эмпирика [S37] — Блокировок, где хватает атомарных операций мнение [S76]
Сопровождающие DRF Самый массовый API-слой Django Узкий объём ядра, расширения снаружи факт [S31] — — — — Только поддержка новых Django и безопасность факт [S30] Новых функций в ядре факт [S30]
Автор Django Ninja Используется в критичных проектах автора мнение [S32] Схемы Pydantic, auth через request факт [S10] — Аннотации — основа API факт [S10] — — Поддержка по графику LTS Django мнение [S32] Многословного dependency injection мнение [S10]

Что объединяет подтверждённые масштабом проекты: монолит сохраняется, а при росте добавляются машинно проверяемые границы (Kraken, PostHog, Sentry), а не новые слои абстракций. Горячие пути выносят точечно (Healthchecks, Zulip), рантайм улучшают вместо смены фреймворка (Instagram) гипотеза.

Книга «Two Scoops of Django» в последнем издании 3.x закрыта и не прочитана; её позиция в сравнение не включена факт [S77].

Сравнение инструментов по вариантам

API-слой

Критерий DRF Django Ninja Собственный слой
Статус Feature-complete, релизы под новые Django факт [S30, S18] Активное развитие, 1.7.1 от 2026-09-19 факт [S19] Поддерживает команда
Доля среди пользователей API-фреймворков 73 % эмпирика [S28] 17 % эмпирика [S28] 13 % эмпирика [S28]
OpenAPI Через drf-spectacular Встроен Вручную или как у Zulip
Валидация Сериализаторы DRF Pydantic Pydantic или своя
Async Синхронный в ядре; async только через сторонние пакеты гипотеза sync и async факт [S10] Как напишете
Пагинация и ограничение частоты Встроены факт [S78, S79] Встроены, cursor pagination и Retry-After с 1.6–1.7 факт [S57] Своё
Когда выбирать Нужна экосистема (фильтры, права на объект, viewsets) или код уже на DRF Новый проект, типы и схема важнее экосистемы, есть async-эндпоинты Масштаб и срок жизни уровня Zulip

Надёжного независимого бенчмарка DRF против Ninja не найдено; аргумент о скорости Pydantic v2 остаётся непроверенным для реальных эндпоинтов, где доминирует время базы гипотеза.

WSGI или ASGI

Вариант Когда Плюсы Минусы
WSGI: Gunicorn sync/gthread или uWSGI По умолчанию Простая модель, транзакции и ORM без оговорок Долгие соединения занимают поток
ASGI: Uvicorn, Granian, Daphne, Hypercorn SSE, WebSocket, параллельные внешние вызовы Сотни соединений без потоков факт [S33] Нет async-транзакций, постоянные соединения отключаются факт [S33, S13]
Gunicorn с ASGI-воркером Один сервер для обоих режимов Стабилен с 25.1.0 факт [S21] Обрабатывает не все исключения парсера факт [S58]
Два деплоя: WSGI для API и ASGI для стриминга Нужен realtime, но основная часть синхронная Изоляция рисков Два конфига выкладки гипотеза

Фоновые задачи

Вариант Инфраструктура Ретраи и расписание Транзакционная постановка Когда
Celery Брокер Redis или RabbitMQ Есть: autoretry_for, retry_backoff, beat факт [S12] delay_on_commit факт [S12] Много очередей, маршрутизация, большие объёмы
django.tasks + django-tasks-db Только PostgreSQL и db_worker факт [S52] В ядре нет факт [S53] on_commit факт [S11] Малый объём, разовые задачи
Procrastinate Только PostgreSQL Ретраи, periodic, блокировки факт [S80] Да, в той же транзакции факт [S80] Нужны надёжность и periodic без отдельного брокера
RQ Redis Не проверялось Нет данных Пример: NetBox факт [S72]
Management command в цикле под systemd Ничего Своё — 1–3 постоянных фоновых цикла, соло-проект факт [S71]

Генерация OpenAPI

Вариант Версия OpenAPI Статус Вердикт
drf-spectacular 3.0.3, 3.1, 3.2 факт [S81] Активен, сознательно ниже 1.0 факт [S81] Брать для DRF
drf-yasg Только 2.0 факт [S82] Сам рекомендует drf-spectacular для новых проектов факт [S82] Не брать в новые проекты
Django Ninja Встроен факт [S10] — Брать вместе с Ninja

Аутентификация

Вариант Когда Плюсы Минусы
Сессии + CSRF SPA на том же домене факт [S9] Мгновенный отзыв, нет хранения токена в JS Не подходит мобильному клиенту без cookie
DRF TokenAuthentication Внутренние интеграции Просто Один токен на пользователя, без срока жизни факт [S9]
Knox или session token allauth headless Мобильное приложение, несколько устройств Токен на клиента, отзыв факт [S9, S54] Запрос к базе на каждый вызов
JWT (simplejwt, allauth JWT) Несколько сервисов проверяют токен без центра факт [S54] Проверка без запроса к базе Отзыв требует состояния, «stateless» — заблуждение мнение [S54]
OAuth 2.0 (Django OAuth Toolkit) Сторонние интеграторы Стандарт факт [S9] Сложность сервера авторизации

Наблюдаемость

Вариант Что даёт Цена входа Вердикт
Sentry SDK + Sentry SaaS Ошибки, трассировки, профили; автоспаны middleware, SQL, кэша вендор [S83] Платный SaaS с бесплатным уровнем (тарифы не проверялись) Брать, если SaaS допустим
Sentry self-hosted То же 4 CPU, 16 GB RAM + 16 GB swap; лицензия FSL факт [S84] По сигналу: большая команда эксплуатации
GlitchTip (self-hosted, принимает данные от SDK Sentry вендор [S85]) Ошибки, базовая производительность, uptime вендор [S85] 256–512 MB RAM, PostgreSQL факт [S86] Брать для установок у клиентов и регионов
OpenTelemetry Вендор-нейтральные трассировки, sqlcommenter факт [S87] Коллектор и бэкенд трассировок По сигналу: несколько сервисов или требование нейтральности
Prometheus Метрики и алерты Multiprocess-режим с ограничениями факт [S88] По сигналу: SLO-алерты, уже есть Prometheus

Мультиарендность

Вариант Изоляция Цена Когда
Общая база + company_id + scoped QuerySet Логическая, в коде Минимальная По умолчанию
Общая база + PostgreSQL RLS В базе; владелец таблицы обходит RLS без FORCE факт [S89] Политики в миграциях, сброс контекста на пуле Требование аудиторов или высокий риск утечки
Схема на арендатора (django-tenants) Сильная Миграции растут с числом схем: 5–14 с CPU на схему при ~1780 схемах эмпирика [S38] Десятки арендаторов с требованием физического разделения
Отдельная база или экземпляр на клиента Полная Отдельный деплой Регионы, установки у клиентов; так работают Kraken и Sentry факт [S3, S4]

Соединения с базой

Вариант Когда Ограничения
CONN_MAX_AGE + CONN_HEALTH_CHECKS WSGI, соединений с запасом Соединение держит каждый поток факт [S13]
Пул Django (psycopg 3) Соединения дорогие (TLS, managed PostgreSQL) или ASGI Пул на процесс; CONN_MAX_AGE = 0 факт [S13]
PgBouncer в transaction mode Сумма соединений превышает лимит базы Отключить server-side cursors факт [S13]

Дерево решений

  • Если нужно решить, где писать бизнес-логику→применить правила ниже
    • Если правило касается одного объекта или одного набора строк→метод модели или метод QuerySet
    • Если сценарий меняет несколько моделей, ставит задачи или зовёт внешний API→функция в <app>/services.py с transaction.atomic
    • Если приложений больше 15–20 или есть циклические импорты→добавить Import Linter с контрактами слоёв и независимости
    • Иначе→не вводить отдельный слой селекторов; чтение через методы QuerySet
  • Если выбирается API-слой→применить правила ниже
    • Если в проекте уже есть DRF-код→DRF, без второго фреймворка
    • Если нужны готовые пакеты фильтров, прав на объект и viewsets→DRF + drf-spectacular
    • Если проект новый и важнее сквозные типы и встроенный OpenAPI→Django Ninja
    • Иначе→DRF + drf-spectacular
  • Если выбирается сервер приложений→применить правила ниже
    • Если нет SSE, WebSocket и долгих запросов→Gunicorn WSGI с потоками
    • Если долгие соединения нужны только части эндпоинтов→отдельный ASGI-деплой (Uvicorn) для них, остальное на WSGI
    • Иначе→ASGI-сервер с пулом соединений Django
  • Если нужны фоновые задачи→применить правила ниже
    • Если задач мало и нужен один-два постоянных цикла→management command под systemd или контейнер-воркер
    • Если нужны ретраи, расписание и не хочется брокера→Procrastinate
    • Если нужны несколько очередей, маршрутизация, высокие объёмы→Celery с Redis, а при требованиях к надёжности доставки → Celery с RabbitMQ
    • Иначе→Celery с Redis
  • Если выбирается аутентификация→применить правила ниже
    • Если клиент — браузерный SPA на том же домене→сессии + CSRF
    • Если клиент — мобильное приложение→непрозрачные токены на устройство (Knox или allauth headless session token)
    • Если токен проверяют несколько независимых сервисов→JWT с коротким сроком жизни и проверкой отзыва
    • Иначе→сессии
  • Если данные разделяются по компаниям→применить правила ниже
    • Если требуется физическое разделение или размещение в стране клиента→отдельный экземпляр с отдельной базой
    • Если аудит требует гарантии на уровне базы→общая база + RLS c FORCE ROW LEVEL SECURITY
    • Иначе→общая база с company_id и обязательным scoped-менеджером
  • Если суммарных соединений больше 70–80 % max_connections (ориентир)→применить правила ниже
    • Если хостов приложения немного и соединения дорогие→пул Django
    • Иначе→PgBouncer в transaction mode с DISABLE_SERVER_SIDE_CURSORS = True
  • Если выбирается наблюдаемость→применить правила ниже
    • Если данные можно отправлять во внешний SaaS→Sentry SDK + Sentry SaaS
    • Если нужна установка у клиента или в регионе с ограничениями→Sentry SDK + GlitchTip
    • Если сервисов несколько или требуется вендор-нейтральность→OpenTelemetry + коллектор
    • Иначе→Sentry SDK + JSON-логи с request_id

Практическое применение

Раздел — главный каталог справочника. Практики делятся на базовый набор (Б01–Б17), который окупается в любом проекте, и расширения по сигналу (Р01–Р16), которые добавляются только после пересечения порога. Пороги без ссылки на источник — ориентиры автора, их стоит калибровать на своих метриках гипотеза.

Порядок внедрения

  1. Зафиксировать версии: Python 3.12+, Django 5.2 LTS или 6.1, lock-файл зависимостей (Б01).
  2. Создать скелет проекта и настройки из раздела 6, прогнать manage.py check --deploy с боевыми настройками (Б02, Б15).
  3. До первой фичи включить проверки CI: форматер и линтер, проверку типов в мягком режиме, makemigrations --check, линтер миграций, тесты с подсчётом запросов, сверку OpenAPI (Б04, Б07, Б09, Б16, Б17).
  4. Описать модели с ограничениями в базе и scoped-менеджерами арендатора (Б08, Б13).
  5. Написать API с явными схемами, общей пагинацией и единым форматом ошибок (Б03, Б05, Б06).
  6. Подключить минимум наблюдаемости: ошибки, JSON-логи с request_id, health-эндпоинты (Б12).
  7. Добавить фоновые задачи с постановкой после фиксации транзакции (Б11).
  8. Выкладывать миграции по схеме expand/contract (Б09).
  9. Всё остальное — только по сигналам из карточек Р01–Р16.

Карточки базового набора

Б01. Версии, зависимости и обновления

  • Суть. Django 5.2 LTS (поддержка до апреля 2028) или актуальная 6.x; обновление по одной feature-версии, сначала зависимости, перед прыжком — ноль предупреждений об устаревании (python -Wa manage.py test) факт [S90, S1]. Зависимости в lock-файле; uv используют 43 % респондентов эмпирика [S27]. Бот обновлений открывает PR, CI решает: addons-server влил DRF 3.18.1 через 16 дней после выхода факт [S23, S18].
  • Метрики. Стабильность, поддерживаемость, безопасность.
  • Когда. Всегда. Для установок у клиентов, которые обновляются редко, выгоднее LTS с трёхлетним окном гипотеза.
  • Плюсы. Маленькие шаги обновления; патчи безопасности приходят без авралов.
  • Минусы. Регулярные затраты времени; Python 3.14 до патча с откатом incremental GC давал OOM при migrate факт [S59].
  • Цена внедрения и отката. Часы на настройку бота; откат — вернуть пин версии.
  • Признаки оверинжиниринга. Собственный форк Django или DRF; вендоринг библиотек; ручное ведение транзитивных пинов без lock-инструмента.
  • Недоинжиниринг (встречается чаще). Неподдерживаемая версия: 3 % респондентов сидят на версиях старше 4.x эмпирика [S28].
  • Как обнаружить. Тесты с -W error::DeprecationWarning в CI; django-upgrade с целевой версией в pre-commit; скрипт, который падает, если до конца поддержки установленной версии Django меньше 90 дней гипотеза.
  • Как упростить. Одна политика: «последний патч текущей LTS или текущей feature-версии», без исключений.

Б02. Структура проекта и место бизнес-логики

  • Суть. Один Django-проект; config/ для настроек, URL и точек входа; 5–15 приложений по бизнес-возможностям. Правило одной сущности — метод модели или QuerySet мнение [S50, S51]; сценарий из нескольких моделей, задач и внешних вызовов — функция в services.py с явными аргументами. Интерфейсы (представление, задача, команда) делают один вызов в домен факт [S49]. Логика не живёт в сериализаторах, save() и сигналах мнение [S48, S49].
  • Метрики. Скорость разработки, поддерживаемость, гибкость.
  • Когда нет. Прототип со сроком жизни меньше квартала — допустим CRUD-first.
  • Плюсы. Одна точка входа на сценарий удобна людям и агентам; задачи и команды переиспользуют те же функции.
  • Минусы. Требует ревью дисциплины: границу «одна сущность или сценарий» каждый понимает по-своему.
  • Цена. Внедрение — соглашение в AGENTS.md и ревью; откат — встроить функции обратно, дёшево.
  • Признаки оверинжиниринга. Сервис-прокладка, вызывающий ровно один Model.objects.create; селектор на каждый filter(); Repository поверх ORM; абстрактные классы с единственной реализацией; DTO между функциями одного приложения.
  • Как обнаружить. AST-скрипт: доля функций в services.py, чьё тело — один вызов ORM; число ABC-классов с одним наследником; grep -rn "class .*Repository".
  • Недоинжиниринг. Представления по 100+ строк, create() сериализатора с бизнес-правилами, post_save для бизнес-процессов. Обнаружение: правила сложности Ruff (C901, PLR0915) на модулях API, подсчёт post_save.connect и @receiver.
  • Как упростить. Встроить сервисы-прокладки в вызывающий код; правила одной сущности перенести в методы модели.

Б03. Явные схемы ввода и вывода, тонкие представления

  • Суть. У каждого эндпоинта явная схема входа и выхода; при различии — две схемы (InputSerializer/OutputSerializer у HackSoft мнение [S48], Schema в Ninja). Запрещены fields = "__all__" и exclude: перечень полей защищает от API3 OWASP «Broken Object Property Level Authorization» факт [S91].
  • Метрики. Стабильность контракта, безопасность, скорость ревью.
  • Плюсы. Изменение модели не меняет API незаметно; агенту видно, что принимает эндпоинт.
  • Минусы. Больше кода, чем с ModelSerializer на всё.
  • Цена. Низкая на старте, высокая при переделке готового API.
  • Признаки оверинжиниринга. Отдельные DTO, мапперы и сериализаторы на один и тот же набор полей; метапрограммирование «фабрик сериализаторов».
  • Как обнаружить. grep -rn '__all__\|exclude =' */api*/ в CI; Ruff DJ007 ловит __all__ только в ModelForm факт [S92], поэтому для сериализаторов нужна своя проверка.
  • Как упростить. Одна схема, если вход и выход совпадают.

Б04. Контракт OpenAPI в CI

  • Суть. Схема генерируется из кода (drf-spectacular или Ninja), снимок openapi.yaml лежит в репозитории, CI перегенерирует, валидирует (spectacular --validate) и показывает diff факт [S81]. Ответы в тестах сверяются со схемой, как в Zulip факт [S47], либо Schemathesis генерирует запросы по схеме факт [S93].
  • Метрики. Стабильность для мобильного клиента, скорость разработки клиентов.
  • Плюсы. Ломающее изменение видно в PR; генерация клиента для мобильного приложения.
  • Минусы. Нужно поддерживать аннотации там, где генератор ошибается.
  • Цена. День на настройку; откат — удалить шаг CI.
  • Признаки оверинжиниринга. Рукописная схема отдельно от кода при одном потребителе; контрактные тесты со стороны потребителя (consumer-driven) для одного внутреннего клиента гипотеза.
  • Как обнаружить. Число переопределений @extend_schema растёт быстрее числа эндпоинтов — генератор не понимает код гипотеза.
  • Недоинжиниринг. Схемы нет, мобильное приложение узнаёт об изменениях из падений в проде.

Б05. Единый формат ошибок

  • Суть. Все ошибки в одном формате, лучше RFC 9457 application/problem+json с полями type, title, status, detail, instance и расширением для ошибок полей факт [S94]; альтернатива — {"message", "extra"} HackSoft мнение [S48]. Стек-трейсы наружу не отдаются факт [S94].
  • Метрики. Скорость разработки клиентов, наблюдаемость.
  • Признаки оверинжиниринга. Иерархия из десятков классов исключений с кодами, которые клиент не различает; перевод машинных сообщений.
  • Как обнаружить. Тест обходит эндпоинты с заведомо неверным вводом и проверяет Content-Type: application/problem+json; grep -rn 'Response({"error"'.
  • Недоинжиниринг. Смесь {"detail": ...} DRF и самописных словарей.

Б06. Пагинация, фильтры и сортировка по умолчанию

  • Суть. Каждый список пагинирован, у размера страницы есть максимум (в NetBox MAX_PAGE_SIZE = 1000 по умолчанию факт [S73]); сортировка только по белому списку полей, иначе возможна утечка через сортировку по чувствительному полю факт [S95]. Подробности — в типовой задаче 1.
  • Как обнаружить. Тест-обход роутера: каждый list-эндпоинт без ?limit возвращает не больше страницы; ordering_fields задан явно.

Б07. Контроль числа запросов

  • Суть. Тест каждого списка проверяет, что число запросов не растёт с числом объектов: assertNumQueries факт [S96], как assert_database_query_count в Zulip факт [S46]. В тестах включён django-zeal, падающий на N+1 факт [S39]. На Django 6.1 в критичном коде включается FETCH_RAISE, а для унаследованного кода — FETCH_PEERS через менеджер по умолчанию факт [S40].
  • Метрики. Производительность, стабильность под нагрузкой.
  • Плюсы. Самая частая причина медленных Django API ловится до прода.
  • Минусы. zeal даёт 3–5 % накладных расходов вендор [S39], поэтому только в тестах.
  • Признаки оверинжиниринга. Кэш поверх N+1 вместо исправления запроса; денормализация «на всякий случай».
  • Как обнаружить. Тест с 1 и 10 объектами сравнивает число запросов; pg_stat_statements по calls показывает запросы с аномальным числом вызовов факт [S97].
  • Замечание. В 6.1 вызов select_related() без аргументов объявлен устаревшим факт [S2].

Б08. Целостность и конкурентные изменения в базе

  • Суть. Инварианты — ограничениями базы (UniqueConstraint, CheckConstraint), а не проверками в Python факт [S49]. Счётчики и балансы — F()-выражениями и условными UPDATE; уникальность — попыткой вставки с перехватом IntegrityError мнение [S76]. Чтение-изменение-запись — select_for_update() внутри транзакции, иначе Django бросает TransactionManagementError факт [S98]. Внешняя бизнес-транзакция — atomic(durable=True) факт [S99].
  • Метрики. Стабильность, корректность данных.
  • Признаки оверинжиниринга. Распределённые блокировки в Redis для того, что решает база; поле версии для оптимистичной блокировки на каждой модели; SERIALIZABLE глобально без обработки ошибок сериализации факт [S13].
  • Как обнаружить. grep -rn "lock(" по коду с клиентом Redis; поиск isolation_level в настройках.
  • Недоинжиниринг (встречается чаще). obj.balance += x; obj.save() без блокировки; уникальность только в валидаторе сериализатора. Обнаружение: AST-проверка «атрибут модели изменён +=, затем .save()» гипотеза.

Б09. Миграции без простоя

  • Суть. Изменения схемы и кода выкладываются раздельно и совместимы в обе стороны факт [S44]. Правила Sentry: новая колонка nullable или с db_default; переименование только в Django через db_column/db_table; удаление в две фазы; индексы CONCURRENTLY вне транзакции, а дольше 10 секунд — post-deploy миграцией; данные — пачками факт [S66]. Таймауты блокировок и запрет опасных операций даёт django-pg-zero-downtime-migrations факт [S65]. Миграции идут до раскатки кода, у Kraken — Helm pre-upgrade hook факт [S68].
  • Метрики. Стабильность выкладок, частота выкладок.
  • Признаки оверинжиниринга. Blue/green-клоны базы на каждую выкладку; собственный фреймворк миграций.
  • Как обнаружить. CI: makemigrations --check --dry-run; для новых миграций sqlmigrate → Squawk с правилами adding-not-nullable-field, require-concurrent-index-creation, require-lock-timeout факт [S100]; ZERO_DOWNTIME_MIGRATIONS_RAISE_FOR_UNSAFE = True факт [S65]; django-linear-migrations против конфликтов веток факт [S74].
  • Недоинжиниринг (встречается чаще). AddField с NOT NULL без значения по умолчанию на большой таблице; удаление поля в той же выкладке, что и кода.

Б10. Рантайм и соединения

  • Суть. Gunicorn в режиме WSGI с потоками; число процессов, потоков и экземпляров считается по формуле соединений из раздела 1. Для WSGI — CONN_MAX_AGE с CONN_HEALTH_CHECKS = True факт [S13]; постоянные соединения ускоряют ответ, когда соединение с базой дорогое факт [S101].
  • Метрики. Производительность, стабильность.
  • Признаки оверинжиниринга. Тонкая настройка автоскейлинга до первого пользователя; несколько видов серверов приложений в одном проекте.
  • Как обнаружить. Сравнить SELECT count(*) FROM pg_stat_activity с max_connections и формулой из README гипотеза.
  • Недоинжиниринг. CONN_MAX_AGE = 0 при managed PostgreSQL с TLS; таймауты запросов не заданы.

Б11. Фоновые задачи: надёжный минимум

  • Суть. Один инструмент очереди; постановка после фиксации (delay_on_commit или on_commit); в задачу передаются ID, а не объекты; задачи идемпотентны, acks_late включается только для идемпотентных; ретраи с retry_backoff только для временных ошибок; таймауты на внешних вызовах факт [S12, S11]. Задача вызывает доменную функцию мнение [S48]. Для Redis-брокера visibility timeout больше самой длинной ETA, иначе задача повторяется по кругу факт [S102].
  • Метрики. Стабильность, производительность ответа.
  • Признаки оверинжиниринга. Canvas-цепочки и chord для линейной работы; отдельная очередь на каждый тип задачи; Kafka для внутренних задач одного монолита.
  • Как обнаружить. Число очередей больше числа пулов воркеров; AST-поиск .delay( внутри with transaction.atomic() без on_commit; grep -rn "delay(self\|delay(obj" — передача объектов.
  • Тест. captureOnCommitCallbacks(execute=True) проверяет, что задача ставится после фиксации факт [S96].
  • Недоинжиниринг. Отправка почты, пушей и HTTP-вебхуков внутри запроса.

Б12. Наблюдаемость: минимальный набор

  • Суть. 1. Ошибки и выборочные трассировки — Sentry SDK: автоспаны middleware, SQL, Redis и кэша вендор [S83]; для установок без SaaS — GlitchTip на 256–512 MB RAM факт [S86]. 2. JSON-логи с request_id и user_id в каждой строке (django-structlog, поддерживает DRF и Ninja) факт [S103]. 3. Health-эндпоинты: живость без зависимостей, готовность с проверкой базы; Kraken использует один /health/ с полной проверкой подсистем на старте факт [S68]. 4. pg_stat_statements на базе факт [S97]. 5. py-spy для разового профилирования живого процесса без перезапуска факт [S104].
  • Метрики. Наблюдаемость, стабильность (время обнаружения и восстановления).
  • Признаки оверинжиниринга. Полный стек OpenTelemetry + Prometheus + хранилища логов и трассировок для одного сервиса и трёх разработчиков; 100 % семплирование трассировок в проде; дашборды без просмотров.
  • Как обнаружить. grep traces_sample_rate со значением 1.0 в боевых настройках; доля затрат на наблюдаемость в счёте за инфраструктуру гипотеза.
  • Недоинжиниринг. Ошибки на почту — Django сам советует систему мониторинга, потому что почта «не масштабируется» факт [S101]; логи без идентификатора запроса.

Б13. Авторизация на уровне объекта и арендатора

  • Суть. BOLA — первый риск OWASP API Top 10 2023 факт [S91]. Базовый QuerySet каждого представления ограничен текущим пользователем или компанией в get_queryset факт [S95]; доступ по ID через глобальный менеджер в API-коде запрещён; проверки прав живут в одном месте.
  • Метрики. Безопасность, стабильность.
  • Признаки оверинжиниринга. Внешний движок политик для трёх ролей; объектные права на каждую строку там, где хватает ролей.
  • Как обнаружить. AST/grep по модулям API: .objects.get( и .objects.filter(pk= вне scoped-менеджеров; параметризованный тест: для каждого detail-маршрута объект чужой компании даёт 404; навык Sentry django-access-review для ревью IDOR факт [S105].
  • Недоинжиниринг (встречается чаще). Фильтрация по компании есть в списке, но нет в detail, update и вложенных действиях.

Б14. Аутентификация

  • Суть. Сессии для браузера на своём домене, непрозрачные токены на устройство для мобильного клиента, JWT только по сигналу Р10 (см. раздел 4) факт [S9, S54]. Токены хранятся хешированными, как токены v2 в NetBox факт [S73].
  • Признаки оверинжиниринга. Собственный OAuth-сервер для своего мобильного приложения; JWT + ротация refresh + таблица отзыва в монолите — это сессии, написанные заново мнение [S54].
  • Как обнаружить. В проекте с одним сервисом есть таблица чёрного списка JWT.

Б15. Конфигурация и секреты

  • Суть. Один модуль настроек и переменные окружения; секреты из окружения или файла, ротация SECRET_KEY через SECRET_KEY_FALLBACKS; check --deploy против боевых настроек факт [S101]. Различия регионов и установок у клиентов — только в окружении и фича-флагах, образ один факт [S44].
  • Признаки оверинжиниринга. Больше трёх файлов настроек с цепочками наследования; удалённый сервис конфигурации для одного деплоя.
  • Как обнаружить. Подсчёт файлов в config/settings; grep -rn "environ.get(\"SECRET" с значением по умолчанию; manage.py check --deploy --fail-level WARNING в CI.

Б16. Тесты

  • Суть. pytest и pytest-django (45 % и 34 % респондентов эмпирика [S27]); эндпоинты тестируются через тестовый клиент, доменные функции — напрямую; реальная PostgreSQL с PostGIS; TestCase с откатом транзакции быстрее TransactionTestCase факт [S96]; --reuse-db и xdist факт [S106]. Внешние вызовы мокаются, база — нет мнение [S48]. Ориентир скорости — Zulip: весь бэкенд менее чем за 30 секунд параллельно факт [S46].
  • Метрики. Стабильность, скорость разработки.
  • Плюсы и минусы фабрик. factory_boy сокращает код мнение [S48]; функции-фабрики проще типизировать и читать мнение [S55].
  • Признаки оверинжиниринга. Моки ORM; гигантские JSON-фикстуры; пирамида из пяти видов тестов в проекте на 20 эндпоинтов.
  • Как обнаружить. Тренд длительности тестов в CI; grep -rn 'patch(".*objects'; доля нестабильных тестов.
  • Недоинжиниринг (встречается чаще). 19 % респондентов не имеют автотестов эмпирика [S27].

Б17. Типы, линтеры, форматирование

  • Суть. Ruff как форматер и линтер с наборами DJ, S, B и другими факт [S92]; аннотации у доменных функций и схем; mypy с плагином django-stubs (нужны настройки Django) или Pyright с базовой поддержкой факт [S22]. Kraken потратил 2,5 года на 5 млн строк факт [S45], поэтому в новом проекте строгость дешевле включить сразу гипотеза.
  • Признаки оверинжиниринга. Несколько пересекающихся линтеров; строгий mypy на весь унаследованный код как блокирующая проверка; собственные плагины проверки типов в малом проекте.
  • Как обнаружить. Тренд числа # type: ignore; время проверки типов в CI.
  • Недоинжиниринг. Нет форматера — шумные диффы, которые мешают ревью кода агентов.

Карточки «добавлять по сигналу»

ID Практика Сигнал и порог Главный риск без сигнала Как откатить
Р01 ASGI и async-представления SSE/WebSocket или 3+ независимых внешних вызова в запросе, ожидание которых даёт больше половины p95 (ориентир) Нет async-транзакций, переключения контекста, сложные тесты факт [S33, S34] Вернуть def-представления на WSGI
Р02 Пул Django или PgBouncer Соединения выше 70–80 % max_connections или заметная доля времени на установку TLS-соединений (ориентир) Лишний компонент; с PgBouncer ломаются server-side cursors факт [S13] Убрать pool, вернуть CONN_MAX_AGE
Р03 Реплики чтения CPU основной базы выше 60–70 % после оптимизации запросов, чтения преобладают, задержка реплики допустима (ориентир) Роутер Django не решает лаг репликации и read-your-writes факт [S107] Удалить роутер
Р04 Кэш данных в Redis p95 эндпоинта выше цели из-за повторяющихся одинаковых запросов, данные меняются редко, ключ инвалидации очевиден (ориентир) Устаревшие данные; cache_page не различает пользователей факт [S108] Удалить декоратор или вызов
Р05 Границы модулей: Import Linter, tach, фасады 15–20+ приложений, циклические импорты, 8–10+ разработчиков или агентов параллельно (ориентир) Церемонии без выигрыша в малом коде Удалить контракты из конфигурации
Р06 OpenTelemetry Больше одного сервиса в цепочке запроса или требование заказчика к вендор-нейтральности Коллектор и бэкенд трассировок на поддержке Оставить Sentry SDK
Р07 Prometheus-метрики Нужны алерты по SLO на частоты и задержки, Prometheus уже есть Ограничения multiprocess-режима: нет custom collectors, Info/Enum, нужна очистка каталога факт [S88] Удалить экспортёр
Р08 Celery вместо простой очереди Несколько очередей с приоритетами, маршрутизация, сотни тысяч задач в день, chord-сценарии (ориентир) Брокер и его отказы, visibility timeout факт [S102] Процедура переноса задач на другой бэкенд
Р09 Изоляция арендаторов сильнее общей базы Договорное или регуляторное требование Стоимость миграций на схемах эмпирика [S38] Дорогой; решать до продажи
Р10 JWT Несколько независимых сервисов проверяют токен Отзыв требует состояния мнение [S54] Перейти на непрозрачные токены с принудительным перелогином
Р11 Внешний поисковый движок PostgreSQL FTS с GIN-индексом не даёт нужной релевантности, опечаток или фасетов на объёме десятков миллионов документов (ориентир) Синхронизация индекса, второй источник правды Вернуть запросы к PostgreSQL
Р12 Партиционирование и архив больших таблиц Таблицы событий и истории в сотни миллионов строк или удаление по сроку хранения (ориентир) Сложные миграции; pghistory советует решать заранее факт [S109] Сложно; решать при проектировании
Р13 Версионирование API сверх v1 В поле есть версии мобильного приложения, которые нельзя заставить обновиться Двойная поддержка кода; DRF допускает и системы без версий факт [S110] Объявить срок жизни старой версии
Р14 orjson и оптимизация сериализации Профиль py-spy показывает JSON-кодирование в верхних строках (ориентир: больше 10–15 % времени запроса) Почти нет: замена рендерера вендор [S75] Вернуть стандартный рендерер
Р15 Нагрузочное тестирование в CI Ожидаемый RPS больше, чем вдвое превышающий проверенный в проде (ориентир), или SLO в договоре Время CI, стенд Запускать вручную перед релизами
Р16 Строгая типизация (mypy strict) Код больше 50 тыс. строк или много параллельных авторов, включая агентов (ориентир) Время на аннотации чужих библиотек Ослабить до базового режима по модулям

Пояснения к самым спорным расширениям:

  • Р01, ASGI. Документация Django связывает выгоду с сотнями соединений без потоков, долгими и стриминговыми ответами факт [S33]. Kraken применяет async для параллельных вызовов LLM-агентов и отмечает, что для большинства задач очереди проще мнение [S34]. Под ASGI постоянные соединения отключаются, транзакционный код оборачивается в sync_to_async факт [S13, S33]. Детекция оверинжиниринга: доля async def представлений, внутри которых только sync_to_async-вызовы ORM, — выигрыша нет, есть переключения гипотеза.
  • Р03, реплики. Роутер из документации Django отправляет чтение на случайную реплику и «не решает» лаг репликации факт [S107]. Минимальная защита — читать с основной базы в течение запроса, который писал, и в фоновых задачах, поставленных после записи гипотеза.
  • Р05, границы. Import Linter поддерживает контракты layers, independence, forbidden, protected и acyclic siblings факт [S111]; Kraken держит 40+ контрактов и ведёт счётчик игнорируемых импортов как метрику техдолга факт [S3]. Признак оверинжиниринга — контракты в проекте из пяти приложений, где нет ни одного нарушения за полгода гипотеза.
  • Р08, Celery. Kraken живёт на Celery с RabbitMQ при 9 млн строк факт [S67, S44]; Healthchecks.io обходится systemd-сервисами без очереди факт [S71]. Масштаб проекта, а не мода, определяет выбор.

Типовые задачи

1. Списки: фильтры, сортировка, пагинация

Вариант Плюсы Минусы Когда
Limit/offset или номер страницы + COUNT(*) Переход на любую страницу, общее число COUNT(*) на большой таблице доминирует во времени ответа: 781 мс из 786 мс в замере Бениты эмпирика [S37] Таблицы до сотен тысяч строк, админские экраны
Cursor (keyset) pagination Фиксированное время на любой глубине, нет дублей при вставках факт [S78] Нет перехода на произвольную страницу; поле сортировки уникальное, неизменное, с индексом факт [S78] Ленты, синхронизация, большие таблицы; в Ninja с 1.6 факт [S57]
Offset + count с таймаутом Сохраняет UX номеров страниц Число страниц приблизительное Унаследованные экраны, см. лайфхаки
  • Фильтры через django-filter (DjangoFilterBackend) или параметры схемы Ninja; сортировка только по ordering_fields факт [S95].
  • Тяжёлые списки отдают «краткое» представление, как ?brief=true в NetBox факт [S73].
  • Признаки оверинжиниринга: собственный язык запросов в query string, GraphQL ради фильтров у одного клиента.
  • Обнаружение: тест на максимальный размер страницы; EXPLAIN для каждого фильтра с индексом в тесте производительности гипотеза.

2. Права на объект и разделение данных по компаниям

Вариант Плюсы Минусы Когда
company_id + scoped-менеджер + get_queryset Просто, работает с ORM и админкой Ошибка в одном месте открывает данные По умолчанию
+ PostgreSQL RLS Гарантия на уровне базы, default-deny без политик факт [S89] Владелец таблицы обходит RLS без FORCE; контекст надо сбрасывать на пулах соединений факт [S89] Требование аудита
Схема на арендатора Изоляция по схеме migrate_schemas растёт с числом схем эмпирика [S38] Десятки крупных арендаторов
Экземпляр на регион или клиента Полная изоляция и резидентность Выкладка во многие окружения Регионы и on-prem; Kraken и Sentry факт [S44, S4]
  • Роли внутри компании — группы и права Django или поле роли на членстве; объектные права только там, где доступ различается внутри одной компании гипотеза.
  • Межрегиональные ссылки при экземплярах на регион — без внешних ключей, через outbox и tombstones, как в Sentry факт [S69].
  • Признаки оверинжиниринга: схемы на арендатора для сотен мелких клиентов; движок ABAC для трёх ролей.
  • Обнаружение: тест «чужой объект = 404» для каждого маршрута; запрос к базе на строки, где company_id объекта не совпадает с company_id родителя гипотеза.

3. Массовый импорт и экспорт

Вариант Плюсы Минусы Когда
Поштучный save() Срабатывают сигналы и save() 128,8 с на 32 500 строк в замере эмпирика [S36] До тысячи строк
bulk_create / bulk_update пачками Быстро, ON CONFLICT через update_conflicts факт [S98] Нет save() и сигналов факт [S98]; аудит на сигналах пропустит факт [S112] Тысячи — сотни тысяч строк
COPY во временную таблицу + INSERT … SELECT 0,46 с на 32 500 строк из итератора эмпирика [S36] Сырой SQL, проверки вне ORM Миллионы строк, регулярные загрузки
  • Импорт — фоновая задача: загрузка файла, задача по ID, отчёт об ошибках по строкам, идемпотентность через ключ импорта гипотеза.
  • Экспорт больших объёмов — iterator(chunk_size=…) и файл в объектное хранилище; prefetch_related в iterator() работает только с chunk_size факт [S98].
  • Признаки оверинжиниринга: конвейер на брокере сообщений для еженедельного CSV.

4. Файлы

Вариант Плюсы Минусы Когда
Загрузка через Django Просто, валидация в API Воркер занят на время загрузки Небольшие файлы
Presigned URL в S3-совместимое хранилище Файл идёт мимо Django, без учётных данных у клиента факт [S113] Ключ перезаписывается при совпадении факт [S113]; нужна проверка после загрузки Крупные файлы, мобильные клиенты
  • django-storages: подписанные URL по умолчанию живут 3600 с, file_overwrite по умолчанию True, endpoint_url подключает S3-совместимые хранилища, в том числе self-hosted факт [S114].
  • Для установок у клиентов — self-hosted S3-совместимое хранилище; Healthchecks.io ушёл с managed-хранилища на self-hosted из-за задержек операций факт [S115].
  • Признаки оверинжиниринга: собственный файловый сервис рядом с S3.

5. Фоновые и периодические задачи

Вариант Плюсы Минусы Когда
Management command в цикле или по таймеру systemd/cron Ноль инфраструктуры факт [S71] Ретраи и параллелизм — свои 1–3 постоянных процесса
django.tasks + django-tasks-db Стандартный API, только PostgreSQL, статус в админке факт [S52] Нет ретраев и расписания в ядре факт [S53] Малые объёмы
Procrastinate Periodic, ретраи, блокировки на PostgreSQL факт [S80] Меньше экосистемы Средние объёмы без брокера
Celery + beat Максимум возможностей факт [S12] Брокер, visibility timeout, ETA-ловушки факт [S102] Тяжёлая периодическая обработка, много очередей
  • Тяжёлая периодическая обработка: разбить на пачки по ID, каждая пачка — отдельная идемпотентная задача; блокировка от параллельного запуска одного и того же периодического задания (select_for_update(skip_locked=True) или блокировки очереди) гипотеза.
  • Признаки оверинжиниринга: Celery canvas для линейного процесса; отдельный кластер воркеров на каждую задачу.

6. Вебхуки: входящие и исходящие

  • Входящие. Проверить подпись по сырому телу, сохранить событие с уникальным внешним ID (уникальный индекс отсекает повтор), ответить 2xx, обработать в задаче гипотеза.
  • Исходящие. Событие пишется в таблицу outbox в той же транзакции, отдельный процесс доставляет; доставка «хотя бы один раз», получатель обязан быть идемпотентным факт [S116]. Подпись и заголовки по Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature, HMAC-SHA256, защита от replay и SSRF факт [S117].
  • Таймаут доставки ограничен: Saleor ждёт ответа не более 20 секунд и разделяет синхронные и асинхронные вебхуки факт [S25].
Вариант исходящих Плюсы Минусы Когда
Задача из on_commit Просто Задача теряется, если процесс упал между фиксацией и постановкой гипотеза Некритичные уведомления
Outbox-таблица + доставщик Гарантия «сообщение есть, если есть транзакция» факт [S116] Дубли, нужен доставщик факт [S116] Платёжные и договорные события
  • Признаки оверинжиниринга: собственная шина событий с подписками для пяти получателей.

7. Уведомления (почта, пуш, внутри приложения)

  • Запись уведомления в таблицу в той же транзакции, доставка задачей по каналам; повтор через идемпотентный ID доставки гипотеза.
  • Почтовые бэкенды с Django 6.1 настраиваются через MAILERS, что упрощает разделение транзакционной и маркетинговой почты факт [S2].
  • Признаки оверинжиниринга: собственный «сервис уведомлений» с шаблонизатором и правилами маршрутизации для двух типов писем.

8. Отчёты и агрегаты

Вариант Плюсы Минусы Когда
Агрегация ORM на лету (annotate, aggregate) Всегда актуально Нагрузка растёт с объёмом Небольшие объёмы, есть индексы
Материализованное представление + REFRESH … CONCURRENTLY Чтение не блокируется Нужен уникальный индекс, один refresh за раз факт [S118] Отчёты с допустимой задержкой
Таблица агрегатов, обновляемая задачей Полный контроль Код инкрементального пересчёта Тяжёлые периодические расчёты
  • Признаки оверинжиниринга: отдельное аналитическое хранилище для десятка отчётов; PostHog уводит в отдельный стек аналитику событий, а не бизнес-отчёты гипотеза.

9. Поиск

Вариант Плюсы Минусы Когда
icontains / триграммы pg_trgm Просто, нечёткие совпадения факт [S119] Медленно без индекса Поиск по имени и коду
PostgreSQL FTS: GeneratedField + SearchVectorField + GIN Ранжирование, словари; без индекса проблемы начинаются после «нескольких сотен записей» факт [S119] Ограниченная релевантность По умолчанию
Внешний движок Опечатки, фасеты Второй источник правды Только по сигналу Р11

10. Офлайн-синхронизация мобильного клиента

  • Протокол pull/push с меткой последней синхронизации, как в WatermelonDB: сервер ставит last_modified собственным временем и не доверяет клиентскому; удаления хранятся как tombstones; push отклоняется, если запись изменилась на сервере после lastPulledAt; push полностью транзакционен; pull делается консистентным снимком факт [S120].
  • Идентификаторы создаются на клиенте; UUID7() в Django 6.1 даёт сортируемые по времени UUID факт [S2].
  • Повторы push защищаются ключом идемпотентности (задача 14).
Вариант Плюсы Минусы Когда
updated_at + tombstones + отказ при конфликте Просто, понятные конфликты Клиент должен перетянуть и повторить По умолчанию
Журнал изменений (триггеры, pghistory) как источник pull Ловит и bulk-операции факт [S109] Растущие таблицы событий Много массовых изменений на сервере
CRDT и слияние полей Работа без конфликтов Сложность на обеих сторонах Совместное редактирование одних записей
  • Признаки оверинжиниринга: CRDT для данных, которые редактирует один пользователь.

11. Геоданные (GeoDjango и PostGIS)

  • PostGIS — рекомендованный бэкенд GeoDjango; Django 6.1 требует PostgreSQL 15+ факт [S63, S2].
  • Для запросов по расстоянию в WGS84 — geography=True, иначе пространственный индекс не используется и расстояние считается для каждой строки факт [S121].
  • Тесты с PostGIS в CI, а не на SQLite.
  • Признаки оверинжиниринга: отдельный гео-сервис для поиска «ближайших точек» в пределах одной базы.

12. WebSocket и SSE

Вариант Плюсы Минусы Когда
Поллинг с ETag/updated_since Работает на WSGI Задержка, лишние запросы Обновления раз в десятки секунд
SSE через StreamingHttpResponse с async-итератором под ASGI Без Channels факт [S122]; в Ninja стриминг SSE с 1.6 факт [S57] Под WSGI занимает воркер на всё время ответа факт [S122] Поток сервер → клиент
Django Channels Двусторонний WebSocket, группы через Redis Сопровождение best-effort факт [S64] Чат, совместная работа
Отдельный realtime-процесс Изоляция долгих соединений Второй рантайм Десятки тысяч соединений, как Tornado у Zulip факт [S6]

13. Аудит изменений

Вариант Плюсы Минусы Когда
django-simple-history (сигналы) Просто, история в Django-моделях Не пишет bulk_* и update() без специальных функций факт [S112] Правки идут через save()
django-pghistory (триггеры) Ловит любые изменения, без round trip факт [S109] Только PostgreSQL; контекст стоит лишней записи факт [S109] Есть bulk-операции, DB_CASCADE, SQL
Явный журнал событий в доменных функциях Бизнес-смысл события Нужно не забыть Юридически значимые действия
  • Конфликт: DB_CASCADE не вызывает сигналы pre_delete/post_delete факт [S2] — сигнальный аудит удалений теряется.

14. Идемпотентность и повторы

  • Заголовок Idempotency-Key (черновик IETF): ключ уникален, рекомендуется UUID; повтор с тем же ключом возвращает сохранённый результат; запрос с ключом, пока первый не завершён, — 409; тот же ключ с другим телом — 422 факт [S123].
  • Реализация: таблица ключей с уникальным индексом (key, client), отпечаток тела, статус и сохранённый ответ; запись ключа в той же транзакции, что и эффект; очистка по сроку гипотеза.
  • Черновик IETF истёк и архивирован, это не стандарт факт [S123].
  • Признаки оверинжиниринга: ключи идемпотентности на GET и на операциях, которые и так идемпотентны (PUT по ID).

15. Ограничение частоты

  • DRF throttling не является защитой от перебора и DoS, допускает гонки и нечёткость под конкуренцией факт [S79]; за прокси нужно правильно задать NUM_PROXIES факт [S79].
  • Защита от злоупотреблений — на прокси или балансировщике; в приложении — бизнес-квоты на Redis, как rate limiting в Zulip факт [S6]. Ninja с 1.7 добавляет Retry-After в ответы 429 факт [S57].
  • Признаки оверинжиниринга: собственный распределённый лимитер с точным счётом для внутреннего API.

16. Версии API

  • По умолчанию — один v1 в URL и только аддитивные изменения; новая версия — только по сигналу Р13 гипотеза. DRF поддерживает пять схем версионирования и отмечает, что системы без версий тоже бывают уместны факт [S110]. Ninja поддерживает несколько версий API в одном проекте факт [S10].
  • Признаки оверинжиниринга: версии на каждое изменение; дублирование всех сериализаторов «на будущее».
  • Обнаружение: diff OpenAPI в CI помечает удаление полей и изменение типов как ломающее.

17. Фича-флаги

Вариант Плюсы Минусы Когда
Переменные окружения Ноль кода Нужна перевыкладка Различия регионов и клиентов
Настройки в базе Мгновенное переключение Своя админка Kraken использует оба варианта факт [S44]
django-waffle: flags, switches, samples Проценты, пользователи, группы факт [S124] Ещё одна зависимость Постепенные раскатки
  • Признаки оверинжиниринга: SaaS-платформа флагов для пяти флагов; флаги, живущие дольше квартала.
  • Обнаружение: скрипт сверяет флаги в коде с флагами в базе и выводит неиспользуемые и старые.

Лайфхаки и удачные костыли

Приём Зачем Перестаёт работать, когда Источник
COUNT(*) пагинатора под statement_timeout 200 мс с подменой числа при таймауте Списки на больших таблицах без смены UX Клиенту нужен точный итог эмпирика [S37]
FETCH_PEERS в менеджере по умолчанию для старого кода Убрать большинство N+1 без ручной расстановки select_related Нужны точные only() и минимальный объём данных факт [S40]
Переименование поля только в Django через db_column Нет блокирующего ALTER TABLE … RENAME Имя колонки читают внешние системы факт [S66]
Фоновый процесс как management command под systemd Нет брокера и очереди Нужны ретраи, параллелизм, расписание многих задач факт [S71]
gc.collect() после каждой миграции на Python 3.14 Обойти OOM migrate После патча Python с откатом incremental GC факт [S59]
max_migration.txt из django-linear-migrations Конфликт веток миграций виден в git, а не в проде Миграции пишет один человек факт [S74]
Симуляция будущих границ (регион, модуль) в CI патчем ORM Проверить разделение до физического разделения После завершения разделения факт [S4]
Вынести один горячий эндпоинт в отдельный процесс на другом рантайме Снять основную нагрузку CPU Логика эндпоинта начинает расти и дублировать домен эмпирика [S43]
?brief=true для облегчённых списков Меньше полей и запросов Клиентов с разными наборами полей становится много факт [S73]

Сквозной сценарий

Пример, иллюстрация: B2B-сервис учёта полевых работ; команда из 4 человек, около половины кода пишут ИИ-агенты; три региональных экземпляра и две установки у клиентов; мобильное приложение с офлайн-режимом; ночной перерасчёт по геоданным.

Неделя Действие Артефакт Проверка
1 Скелет, настройки, CI с Ruff, mypy, makemigrations --check, Squawk, pytest Репозиторий из раздела 6, AGENTS.md Пустой PR проходит CI за 3–4 минуты (иллюстрация)
2 Модели Company, Membership, Site с PointField(geography=True), scoped-менеджеры Миграции 0001–0003 Тест «чужая компания = 404» на все маршруты
3 API списков с cursor pagination, фильтрами и белым списком сортировки openapi.yaml в репозитории assertNumQueries для 1 и 10 объектов
4 Синхронизация мобильного клиента: pull по updated_at, tombstones, push с Idempotency-Key Эндпоинты /sync/pull, /sync/push Тест конфликта: push после изменения на сервере даёт отказ
5 Фоновые задачи: Procrastinate или Celery, ночной перерасчёт пачками по 1 000 ID (пример) tasks.py, расписание captureOnCommitCallbacks, тест идемпотентности
6 Наблюдаемость: Sentry SDK в регионах, GlitchTip в установках клиентов, JSON-логи Настройки LOGGING, health-эндпоинты Искусственная ошибка видна в трекере за минуту
8+ Сигналы: при росте соединений до 80 % — пул Django; при 20 приложениях — Import Linter Записи в журнале решений Метрики из раздела 8

Типичные ошибки первого применения

  1. Задача ставится внутри транзакции без on_commit и не находит объект факт [S12].
  2. Список без пагинации и без проверки числа запросов.
  3. fields = "__all__" в сериализаторе открывает внутренние поля.
  4. Добавление NOT NULL-поля без значения по умолчанию в одной выкладке с кодом.
  5. Фильтрация по компании только в списке, но не в detail и вложенных действиях.
  6. ASGI «потому что быстрее», при этом весь код синхронный.
  7. Ошибки на почту и логи без request_id.
  8. JWT с долгим сроком жизни и без отзыва для собственного мобильного клиента.
  9. Аудит на сигналах в проекте, где импорт идёт через bulk_create факт [S112].
  10. cache_page на эндпоинте, ответ которого зависит от пользователя факт [S108].

Что происходит через месяцы

  • Счётчики техдолга, которые только уменьшаются, работают: у Kraken осталось 15 игнорируемых импортов факт [S3], PostHog запрещает рост пересечений моделей факт [S5].
  • Строгая типизация большого кода — проект на годы: 2,5 года у Kraken факт [S45].
  • Схемы на арендатора дорожают с ростом числа клиентов эмпирика [S38].
  • Таблицы аудита и контекста растут вместе с индексами факт [S109].
  • Горячий путь проявляется через полгода роста: у Healthchecks.io CPU пошёл вверх примерно через 6 месяцев после запуска эмпирика [S43].

Стоимость входа

Статья Оценка Основание
Деньги на софт 0: Django, DRF, Ninja, Celery, Procrastinate, GlitchTip — open source факт [S85, S80]
Self-hosted Sentry 4 CPU, 16 GB RAM + 16 GB swap факт [S84]
Self-hosted GlitchTip 256–512 MB RAM факт [S86]
Время на базовый набор 1–2 недели опытного разработчика на скелет и CI (ориентир) гипотеза
Компетенции PostgreSQL (блокировки, индексы, EXPLAIN), транзакции Django, основы очередей гипотеза

Что меняется для соло-проекта и для нагрузки на порядок выше

  • Соло. Убрать Р05 и Р07; фоновые процессы — management commands под systemd или django-tasks-db; ошибки — GlitchTip; одна база без реплик. Пример Healthchecks.io: обычные серверы, без контейнеров и автоскейлинга факт [S71].
  • Нагрузка ×10. Пул или PgBouncer (Р02), реплики (Р03), разделение очередей по приоритетам, партиционирование таблиц событий (Р12), нагрузочные тесты (Р15), границы модулей (Р05). Горячий эндпоинт — кандидат на вынос в отдельный процесс только после профилирования гипотеза.

Артефакты

Ниже — артефакты, которые порождает базовый набор. Конфигурации — стартовые примеры, а не стандарт: значения порогов и лимитов помечены как пример и подбираются под проект. Синтаксис опций Django, DRF, Ruff, django-stubs и pytest-django взят из их документации факт [S13, S78, S92, S22, S106].

6.1. Скелет проекта

  • Назначение. Одинаковое место для каждого вида кода, чтобы человек и агент находили его без поиска.
  • Жизненный цикл. Создаётся в первый день; новые приложения добавляются по бизнес-возможностям; структура пересматривается, когда приложений становится 15–20 (сигнал Р05).
project/
├── AGENTS.md                  # правила для ИИ-агентов (6.7)
├── README.md                  # запуск, бюджет соединений, сигналы Р01–Р16
├── pyproject.toml             # зависимости, ruff, mypy, pytest
├── uv.lock
├── openapi.yaml               # снимок контракта, генерируется, в git
├── config/
│   ├── settings.py            # один модуль, значения из окружения
│   ├── urls.py
│   ├── wsgi.py
│   └── asgi.py                # только при сигнале Р01
├── apps/
│   ├── core/                  # формат ошибок, пагинация, health, базовые модели
│   ├── companies/
│   │   ├── models.py          # модели и методы QuerySet
│   │   ├── services.py        # сценарии из нескольких моделей и внешних эффектов
│   │   ├── api/
│   │   │   ├── views.py       # тонкие: схема → один вызов домена → схема
│   │   │   ├── schemas.py     # сериализаторы DRF или Schema Ninja
│   │   │   └── urls.py
│   │   ├── tasks.py           # задачи вызывают services
│   │   ├── migrations/
│   │   │   └── max_migration.txt
│   │   └── tests/
│   │       ├── factories.py
│   │       ├── test_api.py
│   │       └── test_services.py
│   └── sync/                  # офлайн-синхронизация мобильного клиента
└── scripts/checks/            # самописные проверки CI (AST и grep)

6.2. Настройки Django

  • Назначение. Безопасные значения по умолчанию и явные точки для расширений по сигналу.
  • Жизненный цикл. Меняется при добавлении расширения; каждая закомментированная опция привязана к карточке Р.

Фрагмент config/settings.py; env() — обёртка над os.environ:

DATABASES = {
    "default": {
        "ENGINE": "django.contrib.gis.db.backends.postgis",
        "HOST": env("DB_HOST"),
        "NAME": env("DB_NAME"),
        "USER": env("DB_USER"),
        "PASSWORD": env("DB_PASSWORD"),
        "CONN_MAX_AGE": 300,            # пример; при пуле (Р02) должно быть 0
        "CONN_HEALTH_CHECKS": True,
        "OPTIONS": {
            # Р02: "pool": {"min_size": 2, "max_size": 8, "timeout": 10},
        },
        # Р02 с PgBouncer в transaction mode:
        # "DISABLE_SERVER_SIDE_CURSORS": True,
    }
}
DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

SECRET_KEY = env("SECRET_KEY")
SECRET_KEY_FALLBACKS = env.list("SECRET_KEY_FALLBACKS", default=[])
DEBUG = False
ALLOWED_HOSTS = env.list("ALLOWED_HOSTS")

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated"],
    "DEFAULT_PAGINATION_CLASS": "apps.core.api.pagination.DefaultCursorPagination",
    "PAGE_SIZE": 50,                                   # пример
    "DEFAULT_SCHEMA_CLASS": "drf_spectacular.openapi.AutoSchema",
    "EXCEPTION_HANDLER": "apps.core.api.errors.problem_details_handler",
    "DEFAULT_THROTTLE_RATES": {"login": "10/min"},     # пример, бизнес-квота
}

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": env("REDIS_URL"),
        "KEY_PREFIX": env("INSTANCE_NAME"),            # регион или клиент
    }
}

sentry_sdk.init(                      # тот же DSN-подход работает с GlitchTip
    dsn=env("SENTRY_DSN", default=""),
    environment=env("INSTANCE_NAME"),
    release=env("RELEASE"),
    traces_sample_rate=0.05,          # пример; 1.0 только локально
    send_default_pii=False,
)

6.3. Конфигурация линтеров, типов и тестов

  • Назначение. Автоматически ловить то, что иначе ловит ревью.
  • Жизненный цикл. Правила добавляются, когда ошибка повторилась дважды; отключения — только с комментарием-причиной.

Фрагмент pyproject.toml:

[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "W", "I", "B", "UP", "DJ", "S", "C4", "SIM", "DTZ", "T20", "C90", "PL", "RUF"]
ignore = ["PLR2004"]

[tool.ruff.lint.per-file-ignores]
"**/tests/**" = ["S101", "PLR2004"]

[tool.ruff.lint.mccabe]
max-complexity = 10                     # пример

[tool.mypy]
python_version = "3.12"
plugins = ["mypy_django_plugin.main"]
check_untyped_defs = true
warn_unused_ignores = true

[[tool.mypy.overrides]]
module = ["apps.*.services", "apps.*.api.*"]
disallow_untyped_defs = true            # новые слои типизируются полностью

[tool.django-stubs]
django_settings_module = "config.settings"

[tool.pytest.ini_options]
DJANGO_SETTINGS_MODULE = "config.settings"
addopts = "--reuse-db"
filterwarnings = ["error::DeprecationWarning"]  # исключения для сторонних пакетов — точечно

6.4. Проверки CI

  • Назначение. Ворота качества, одинаковые для кода людей и агентов.
  • Жизненный цикл. Каждый шаг привязан к карточке; шаг, который ни разу не падал за полгода и дорог по времени, переводится в ночной прогон гипотеза.
Шаг Команда (пример) Ловит Карточка
1 uv sync --locked Расхождение lock-файла Б01
2 ruff format --check . && ruff check . Стиль, баги, безопасность Б17
3 mypy . Типы Б17
4 python manage.py check --deploy --fail-level WARNING с боевыми настройками Небезопасная конфигурация Б15
5 python manage.py makemigrations --check --dry-run Забытые миграции Б09
6 sqlmigrate для новых миграций → файл → Squawk Блокирующий DDL Б09
7 python manage.py spectacular --file openapi.yaml --validate && git diff --exit-code openapi.yaml Незафиксированное изменение контракта Б04
8 pytest -n auto с django-zeal и тестами числа запросов Регрессии, N+1, предупреждения устаревания Б07, Б16
9 python scripts/checks/run_all.py __all__ в схемах, .objects.get( в API, traces_sample_rate=1.0, .delay( внутри atomic Б03, Б11, Б12, Б13
10 lint-imports Нарушение границ модулей Р05
11 Schemathesis против локального сервера (ночью) Ответы вне схемы, 5xx Б04

6.5. Чек-лист ревью PR (человек или агент-ревьюер)

  • Назначение. Проверить то, что не ловится автоматически.
  • Жизненный цикл. Пункт, который удалось автоматизировать, переносится в CI и удаляется из чек-листа.
  1. Новый эндпоинт ограничивает QuerySet компанией или пользователем; есть тест «чужой объект = 404».
  2. Схема ввода перечисляет поля явно; схема вывода не раскрывает внутренние поля.
  3. Список пагинирован, сортировка по белому списку, есть тест числа запросов.
  4. Сценарий из нескольких моделей — в одной доменной функции под transaction.atomic.
  5. Задачи ставятся после фиксации, получают ID, идемпотентны.
  6. Миграция совместима со старым кодом: nullable или db_default, без переименований и удалений в той же выкладке.
  7. Внешние вызовы с таймаутом и обработкой ошибок.
  8. Нет новых слоёв, абстракций и зависимостей без сигнала из карточек Р.
  9. Изменение OpenAPI ожидаемо и обратно совместимо.
  10. Логи несут контекст (request_id, ID объекта), без персональных данных.

6.6. Чек-лист аудита существующего проекта

  • Назначение. Найти недо- и оверинжиниринг в работающем проекте.
  • Жизненный цикл. Проходится раз в квартал и перед крупным обновлением Django.
Проверка Как выполнить автоматически Норма
Самые дорогие запросы SELECT query, calls, total_exec_time, mean_exec_time FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 20; факт [S97] Верх списка объясним и проиндексирован
Использование соединений SELECT count(*) FROM pg_stat_activity; против max_connections Ниже 70–80 % (ориентир)
Неиспользуемые индексы SELECT indexrelname FROM pg_stat_user_indexes WHERE idx_scan = 0; Пусто или объяснимо
N+1 django-zeal на полном прогоне тестов Ноль срабатываний вне allowlist
Сервисы-прокладки AST-скрипт по services.py Меньше 20–30 % функций из одного вызова ORM (ориентир)
Сигналы для бизнес-процессов Подсчёт @receiver и .connect( Только для развязки и аудита
Неиспользуемые фича-флаги Сверка флагов в коде и в базе Нет флагов старше квартала
Версия Django Сравнение с таблицей поддержки Поддерживаемая, предупреждений нет
BOLA Параметризованный тест по всем detail-маршрутам 404 на чужие объекты

6.7. AGENTS.md

  • Назначение. Короткий набор правил для ИИ-агентов; формат открыт, ближайший к файлу AGENTS.md имеет приоритет факт [S62]. Sentry требует AGENTS.md в каждом SDK-репозитории с обзором архитектуры, тестовыми соглашениями, сборкой, ожиданиями к вкладу и атрибуцией коммитов факт [S125]. Длина — ориентир «экран-два»: длинный файл агент читает хуже, чем ссылки на проверки CI гипотеза.
  • Жизненный цикл. Пополняется, когда агент дважды ошибся одинаково; правило, которое закрыто проверкой CI, сокращается до ссылки на проверку.
AGENTS.md (корень репозитория)

### Команды
- Тесты: `pytest -n auto`; один файл: `pytest apps/x/tests/test_api.py`
- Проверки: `ruff format . && ruff check --fix . && mypy . && python scripts/checks/run_all.py`

### Где писать код
- Правило одной модели → метод модели или QuerySet. Сценарий из нескольких моделей → `apps/<app>/services.py`.
- Представление: схема ввода → один вызов домена → схема вывода. Логики в сериализаторах, save() и сигналах нет.

### Обязательно
- Каждый QuerySet в API ограничен компанией (`.for_company(request.company)`); тест «чужой объект = 404».
- Список: пагинация, `ordering_fields`, тест `assertNumQueries` для 1 и 10 объектов.
- Задачи: `transaction.on_commit`, аргументы — ID, задача идемпотентна.
- Миграции: новое поле nullable или `db_default`; не переименовывать и не удалять колонки вместе с кодом.
- После изменения API: `python manage.py spectacular --file openapi.yaml --validate`.

### Запрещено без согласования
- Новые зависимости, слои, базовые классы «на будущее», async-представления, кэш данных.

6.8. Журнал решений по сигналам

  • Назначение. Фиксировать, какой сигнал пересёк порог и что добавлено, чтобы через год было ясно, можно ли откатить.
  • Поля. Дата; карточка Р; метрика и её значение; принятое решение; критерий отката.
  • Пример заполнения. «2027-03-02 · Р02 · соединений 86 из 100 при пике · включён пул Django max_size=8 · откат, если пик ниже 50 % в течение квартала» (иллюстрация).

С чем используется в связке

Что предшествует и что следует

  • Предшествует: PostgreSQL как основная база (индексы, EXPLAIN, блокировки), CI с обязательными проверками, контейнерная или systemd-сборка одного образа на все окружения.
  • Следует: SLO и алерты по ним, нагрузочное тестирование перед ростом (Р15), журнал решений по сигналам (6.8), регулярный аудит по чек-листу 6.6.

Усиливающие связки

Связка Эффект Источник
Снимок OpenAPI в git + генерация клиента мобильного приложения + Schemathesis Ломающее изменение видно в PR, клиент собирается из схемы, сервер проверяется по ней же факт [S81, S93]
on_commit + идемпотентные задачи + outbox для критичных событий Задача видит зафиксированные данные, повтор безопасен, событие не теряется факт [S12, S116]
Scoped-менеджер + тест «чужой объект = 404» + RLS по сигналу Три линии защиты от BOLA факт [S91, S89]
Тесты числа запросов + pg_stat_statements Регрессия ловится до прода, остаток — по статистике базы факт [S96, S97]
Фича-флаги + миграции expand/contract Релиз отделён от выкладки, выкладка не ломает старый код факт [S44]
AGENTS.md + те же проверки локально и в CI Агент сам исправляет нарушения до ревью гипотеза
Симуляция будущих границ в CI + outbox между регионами Разделение по регионам без переписывания монолита факт [S4, S69]

Известные конфликты

Сочетание Что ломается Причина Источник
PgBouncer transaction mode + QuerySet.iterator() Ошибка при чтении курсора Server-side cursor живёт в другом соединении факт [S13]
Встроенный пул + CONN_MAX_AGE > 0 Конфигурация недопустима Время жизни задаётся max_lifetime пула факт [S13]
ASGI + постоянные соединения Соединения переиспользуются между задачами event loop Документация требует их отключить факт [S13, S34]
Async-представления + transaction.atomic Транзакции в async не работают Нужна синхронная функция через sync_to_async факт [S33]
DB_CASCADE + сигналы удаления Аудит и очистка на сигналах пропускают удаления Каскад выполняет база, сигналы не отправляются факт [S2]
bulk_create/bulk_update/update() + логика в save() или сигналах Правила и история пропускаются save() не вызывается, сигналы не отправляются факт [S98, S112]
Celery acks_late + неидемпотентная задача Двойное выполнение после падения воркера Подтверждение после выполнения факт [S12]
Redis-брокер + ETA дольше visibility timeout Задача выполняется снова и снова Неподтверждённая задача переотдаётся факт [S102]
Prometheus multiprocess + Gunicorn Неверные метрики, рост числа файловых дескрипторов Каталог метрик нужно чистить между запусками, часть типов метрик не работает факт [S88]
cache_page + ответы, зависящие от пользователя Утечка чужих данных из кэша Кэш не различает auth и cookies факт [S108]
RLS + подключение под владельцем таблицы Политики не действуют Владелец обходит RLS без FORCE факт [S89]
JWT + требование мгновенного выхода Токен работает после logout Нужна проверка состояния мнение [S54]
StreamingHttpResponse + WSGI Воркер занят на всё время стрима WSGI рассчитан на короткие запросы факт [S122]
Gunicorn ASGI-воркер + некорректные запросы Нет ответа на часть запросов Не все исключения парсера обрабатываются факт [S58]
uWSGI + Sentry SDK SDK работает некорректно Нужны --enable-threads и --py-call-uwsgi-fork-hooks вендор [S83]
OpenTelemetry request_hook + атрибуты middleware Нет пользователя в спане Спан создаётся до middleware; использовать response_hook факт [S87]
Python 3.14 до отката incremental GC + migrate OOM на машинах с 512 MB GC не успевает за циклическими объектами ModelState.render() факт [S59]
drf-yasg + требование OpenAPI 3 Невозможно Генерируется только 2.0 факт [S82]

Метрики здоровья и антипаттерны

Нормы без источника — ориентиры автора и помечены словом «ориентир». Метрика полезна, только если у неё есть автоматический сбор и владелец, который реагирует на деградацию гипотеза.

Признак Здоровая норма Симптом деградации Источник
Время полного прогона тестов Ориентир по эталонам: весь бэкенд Zulip менее 30 с параллельно; 100 000+ тестов Kraken менее 30 мин Рост быстрее числа тестов, разработчики и агенты перестают запускать тесты локально [S46, S44]
Время от merge до прода Kraken: менее получаса без ручных шагов Выкладки пачками раз в неделю, ручные шаги [S44]
Число SQL-запросов на list-эндпоинт Не зависит от числа объектов Растёт линейно с размером страницы [S96, S46]
COUNT(*) пагинатора Ориентир: укладывается в 200 мс таймаута Доминирует во времени ответа [S37]
Доля занятых соединений PostgreSQL Ориентир: ниже 70–80 % на пике Ошибки «too many connections» при автоскейлинге [S13]
Миграции на выкладке Ни одна не ждёт блокировку дольше таймаута; индексы дольше 10 с — post-deploy Зависания записи во время выкладки [S66, S65]
Предупреждения об устаревании в тестах Ноль перед обновлением Django Обновление откладывается из-за накопленных предупреждений [S90]
Отставание версии Django Поддерживаемая версия; 43 % сообщества уже на 6.0 Версия вне поддержки [S28, S1]
Игнорируемые нарушения границ модулей Счётчик только уменьшается (у Kraken — 15) Растёт [S3, S5]
# type: ignore на 1000 строк Ориентир по Kraken: около 1 (5000 на 5 млн строк) Растёт с каждым PR [S45]
Семплирование трассировок в проде Меньше 1.0 1.0 в проде, счёт за наблюдаемость растёт [S83]
Возраст задач в очереди Ориентир: p95 ожидания меньше SLA задачи Очередь растёт ночью и не успевает к утру [S12]
Доля сервисов-прокладок Ориентир: меньше 20–30 % функций services.py Большинство функций — один вызов ORM ориентир автора, источника нет
Возраст фича-флагов Ориентир: не старше квартала Флаги, которые никто не помнит ориентир автора, источника нет
N+1 в тестах Ноль срабатываний django-zeal вне allowlist Allowlist растёт [S39]

Антипаттерны

Сервисный слой-прокладка

Как выглядит. В каждом приложении services.py и selectors.py, где функция user_create(**kwargs) вызывает ровно User.objects.create(**kwargs), а user_list() — User.objects.all(). Представление вызывает селектор, тот — менеджер, менеджер — QuerySet; при отладке путь проходит через четыре файла.

Почему возникает. Руководство HackSoft читают как обязательный шаблон, хотя авторы прямо пишут, что это «не единственный путь» мнение [S48]. Агенты и новички копируют структуру соседнего приложения, даже если в новом приложении нет сценариев гипотеза.

Как чинить. Удалить функции-прокладки и вызывать ORM-методы напрямую из представления; оставить в services.py только сценарии с несколькими моделями, внешними вызовами и задачами. Беннетт и Плант предлагают методы моделей и QuerySet как естественный «сервисный слой» Django мнение [S50, S51]. Обнаружение — AST-скрипт из 6.6.

Когда менять практику. Когда приложений больше 15–20 и появились циклические импорты, нужен не тонкий слой на всё, а фасады между доменами с машинной проверкой, как у Kraken и PostHog факт [S3, S5].

Логика в сериализаторах и сигналах

Как выглядит. create() сериализатора создаёт заказ, списывает лимит и шлёт письмо; post_save у Order создаёт счёт; импорт через bulk_create «теряет» счета, а задача, которой нужен тот же сценарий, дублирует код.

Почему возникает. CRUD-first старт с ModelViewSet и ModelSerializer быстрее всего даёт работающий эндпоинт; сигналы кажутся способом «не трогать» чужой код.

Как чинить. Сценарий переносится в доменную функцию, которую вызывают и API, и задачи. Сигналы остаются для развязки независимых частей мнение [S48]. Kraken запрещает вызывать save() вне методов-мутаторов модели факт [S49]. Обнаружение — подсчёт @receiver, переопределённых create()/update() в сериализаторах длиннее 10 строк (ориентир).

Когда менять практику. Если сигналы используются только для аудита, а bulk-операций и DB_CASCADE нет, их можно оставить; при появлении bulk-операций аудит переносится на триггеры факт [S112, S109].

Async ради моды

Как выглядит. Проект переведён на ASGI, представления объявлены async def, внутри — await sync_to_async(...) для каждого обращения к ORM и транзакций. Задержка не уменьшилась, тесты требуют transaction=True и особых фабрик.

Почему возникает. Async воспринимается как «быстрее»; 40 % респондентов планируют внедрять async эмпирика [S28].

Как чинить. Вернуть синхронные представления на WSGI; для SSE и параллельных внешних вызовов выделить отдельные async-эндпоинты или отдельный ASGI-деплой. Документация Django связывает выгоду async с долгими соединениями и множеством параллельных операций ввода-вывода факт [S33]; Kraken применил async для параллельных LLM-агентов и описал цену в тестах и транзакциях факт [S34].

Когда менять практику. При сигнале Р01: SSE или WebSocket либо p95, в котором ожидание внешних систем составляет больше половины.

Наблюдаемость как витрина

Как выглядит. Для одного монолита и трёх разработчиков развёрнуты коллектор OpenTelemetry, Prometheus, хранилища логов и трассировок, десятки дашбордов; при инциденте всё равно ищут ошибку в Sentry по request_id.

Почему возникает. Перенос практик больших организаций и вендорских гайдов без сигнала.

Как чинить. Оставить минимум Б12: трекер ошибок с выборочными трассировками, JSON-логи с request_id, health-эндпоинты, pg_stat_statements. Self-hosted Sentry требует 16 GB RAM, GlitchTip — 256–512 MB факт [S84, S86]. Обнаружение: дашборды без просмотров за 90 дней, traces_sample_rate = 1.0 в проде гипотеза.

Когда менять практику. При сигналах Р06 и Р07: несколько сервисов в цепочке запроса или алерты по SLO, которых нельзя построить в трекере ошибок.

Миграция-убийца (недоинжиниринг)

Как выглядит. PR добавляет NOT NULL-поле без значения по умолчанию и индекс на таблице в десятки миллионов строк; во время выкладки запись в таблицу стоит минуты, новые поды не проходят health-проверки.

Почему возникает. Миграции генерируются makemigrations и не читаются как SQL; на тестовой базе с сотней строк всё быстро.

Как чинить. Правила Sentry: nullable или db_default, индексы CONCURRENTLY в неатомарной миграции, post-deploy для операций дольше 10 секунд, двухфазное удаление факт [S66]. В CI — Squawk или RAISE_FOR_UNSAFE с LOCK_TIMEOUT факт [S100, S65].

Когда менять практику. Для таблиц до десятков тысяч строк и проектов с окном обслуживания строгие правила можно ослабить до таймаутов блокировок гипотеза.

Сводка признаков оверинжиниринга и их обнаружения

Область Признак Автоматическое обнаружение Обход
Структура Сервисы-прокладки, Repository над ORM AST-скрипт по services.py, grep "Repository" Встроить вызовы ORM
Структура Контракты импортов без нарушений в малом проекте История lint-imports без падений за полгода Снять контракты до сигнала Р05
API Версии на каждое изменение Число каталогов v*/ в URL Аддитивные изменения в v1
API Свой язык запросов в query string Ревью схемы фильтров django-filter
ORM Кэш поверх N+1 Тест числа запросов при выключенном кэше Исправить запросы
Конкурентность Redis-блокировки для того, что решает база grep "lock(" с клиентом Redis Ограничения, F(), select_for_update
Задачи Canvas и отдельная очередь на каждую задачу Очередей больше, чем пулов воркеров Одна-две очереди
Async async def с одними sync_to_async внутри AST-поиск Синхронное представление
Наблюдаемость 100 % трассировок, пустые дашборды Проверка настроек, статистика просмотров Минимум Б12
Аутентификация JWT с таблицей отзыва в монолите Наличие blacklist-приложения при одном сервисе Непрозрачные токены
Мультиарендность Схемы на сотни мелких арендаторов Время migrate_schemas на арендатора Общая база + company_id
Настройки Цепочки из 4+ файлов настроек Подсчёт файлов Один модуль + окружение
Тесты Моки ORM grep 'patch(".*objects' Тест с базой

Сводка признаков недоинжиниринга

Область Признак Автоматическое обнаружение
Безопасность Доступ по ID без scoped-менеджера AST-поиск .objects.get( в API, тест 404
API fields = "__all__", нет пагинации grep, тест обхода роутера
ORM N+1 django-zeal, assertNumQueries
Целостность Read-modify-write без блокировки, уникальность только в валидаторе AST-шаблон += + .save(), отсутствие UniqueConstraint
Миграции Блокирующий DDL Squawk, RAISE_FOR_UNSAFE
Задачи .delay() внутри транзакции, объекты в аргументах AST-поиск, grep
Наблюдаемость Ошибки на почту, логи без request_id Проверка LOGGING и наличия SDK
Обновления Версия вне поддержки, предупреждения устаревания Тесты с -W error, сравнение с таблицей поддержки

Инструменты и софт

Все перечисленные библиотеки — open source, если не указано иное; цены SaaS не проверялись и не приводятся. Вердикт «брать» означает базовый набор, «по сигналу» — карточку Р из раздела 5, «не брать» — есть лучшая замена или инструмент заброшен. Дата проверки состояния — 2026-10-01.

Категории и вердикты

Категория Инструмент Вердикт Основание
API-слой DRF 3.18 Брать (по умолчанию) Стабилен, Django 5.2+ факт [S18]
API-слой Django Ninja 1.7 Брать как альтернативу DRF в новом проекте Pydantic, встроенный OpenAPI, sync и async факт [S10, S19]
OpenAPI drf-spectacular Брать с DRF OpenAPI 3.0.3–3.2 факт [S81]
OpenAPI drf-yasg Не брать Только OpenAPI 2.0 факт [S82]
Фильтры django-filter Брать с DRF Интеграция DjangoFilterBackend факт [S95]
Аутентификация django-allauth (headless) Брать для регистрации, входа и MFA Session tokens и JWT-стратегии факт [S54]
Аутентификация django-rest-knox Брать для токенов DRF Токен на клиента, срок жизни факт [S9]
Аутентификация djangorestframework-simplejwt По сигналу Р10 Таблица отзыва факт [S9]
Аутентификация Django OAuth Toolkit По сигналу: сторонние интеграторы Рекомендован DRF для OAuth 2.0 факт [S9]
Задачи Celery 5.6 По сигналу Р08 или при тяжёлой обработке Ретраи, расписание, маршрутизация факт [S12]
Задачи Procrastinate Брать для средних объёмов без брокера PostgreSQL, periodic, транзакционная постановка факт [S80]
Задачи django-tasks-db Брать для малых объёмов db_worker, стандартный API факт [S52]
Миграции django-pg-zero-downtime-migrations Брать (бета, читать SQL) Безопасные DDL и таймауты факт [S65]
Миграции Squawk Брать как альтернативу или дополнение Линтер SQL миграций факт [S100]
Миграции django-linear-migrations Брать при 2+ авторах миграций Конфликты видны в git факт [S74]
Мультиарендность django-tenants По сигналу Р09 Стоимость миграций растёт с числом схем эмпирика [S38]
Аудит django-pghistory Брать при bulk-операциях и DB_CASCADE Триггеры факт [S109]
Аудит django-simple-history Брать, если все изменения идут через save() Сигналы факт [S112]
Ошибки и трассировки sentry-sdk Брать Автоспаны Django вендор [S83]
Ошибки и трассировки GlitchTip Брать для self-hosted и установок у клиентов 256–512 MB RAM факт [S86]
Ошибки и трассировки Sentry self-hosted По сигналу: есть эксплуатация под 16 GB RAM FSL, 4 CPU факт [S84]
Трассировки OpenTelemetry По сигналу Р06 факт [S87]
Метрики prometheus_client / django-prometheus По сигналу Р07 Ограничения multiprocess факт [S88]
Логи django-structlog Брать request_id, JSON, DRF и Ninja факт [S103]
Профилирование py-spy Брать как инструмент дежурного Без перезапуска процесса факт [S104]
N+1 django-zeal Брать в тестах 3–5 % накладных расходов вендор [S39]
N+1 nplusone Не брать По оценке автора zeal, заброшен мнение [S39]
Тесты pytest-django + pytest-xdist Брать --reuse-db, xdist факт [S106]
Тесты Schemathesis Брать в ночной прогон Тесты по OpenAPI факт [S93]
Нагрузка Locust По сигналу Р15 Python-сценарии, headless в CI факт [S126]
Качество Ruff Брать Форматер и линтер, правила DJ и S факт [S92]
Типы mypy + django-stubs (+ djangorestframework-stubs) Брать Плагин для Django факт [S22]
Типы Pyright Альтернатива при отказе от плагина Базовая поддержка stubs факт [S22]
Границы Import Linter, tach По сигналу Р05 факт [S111, S5]
Обновления django-upgrade Брать Автообновление кода под версию Django, есть хук pre-commit факт [S127]
Рантайм Gunicorn Брать WSGI и стабильный ASGI-воркер факт [S21]
Рантайм Uvicorn, Granian По сигналу Р01 Документированы Django факт [S8]
Realtime Django Channels По сигналу: двусторонний WebSocket Best-effort сопровождение факт [S64]
Сериализация django-orjson По сигналу Р14 вендор [S75]
Файлы django-storages Брать S3 и совместимые факт [S114]
Фича-флаги django-waffle По сигналу flags, switches, samples факт [S124]
Агенты django-mcpz По сигналу: агентам нужен доступ к данным приложения MCP в WSGI-представлении факт [S128]

django-upgrade приведён по описанию на сайте проекта; список целевых версий на странице опций не опубликован и не проверен.

Функциональный разбор ведущих продуктов

Django REST framework

  • Сущности. Представления (APIView, generic views, ViewSet), роутеры, сериализаторы, классы аутентификации, прав, ограничения частоты, пагинации, фильтров, версионирования.
  • Ключевые операции. Объявить сериализатор и представление, ограничить get_queryset, подключить пагинацию и фильтры, сгенерировать схему через drf-spectacular.
  • Интеграции. django-filter, drf-spectacular, Knox, simplejwt, Django OAuth Toolkit факт [S95, S9].
  • Ограничения. Новые функции не принимаются факт [S30]; встроенный throttling не защищает от перебора факт [S79]; TokenAuthentication без срока жизни факт [S9].
  • Цена входа (2026-10-01). Бесплатно; знание жизненного цикла generic views и сериализаторов.

Django Ninja

  • Сущности. NinjaAPI, роутеры, операции-функции, схемы на Pydantic, классы аутентификации и пагинации, throttling.
  • Ключевые операции. Объявить операцию с аннотациями, вернуть QuerySet или схему, получить OpenAPI автоматически; cursor pagination и стриминг SSE с 1.6 факт [S57].
  • Интеграции. Django ORM и auth через request факт [S10]; django-structlog факт [S103].
  • Ограничения. Меньше готовых пакетов, чем у DRF гипотеза; публично обсуждался bus factor факт [S32].
  • Цена входа. Бесплатно; знание Pydantic v2.

Celery

  • Сущности. Задачи, очереди, воркеры, брокер, backend результатов, расписание beat.
  • Ключевые операции. delay_on_commit, ретраи с retry_backoff, acks_late для идемпотентных задач, лимиты времени факт [S12].
  • Интеграции. Redis, RabbitMQ (quorum queues с 5.5) факт [S20].
  • Ограничения. Visibility timeout Redis и повтор ETA-задач; требование noeviction или allkeys-lru факт [S102]; официального бэкенда для django.tasks нет факт [S35].
  • Цена входа. Бесплатно; эксплуатация брокера и мониторинг очередей.

Sentry SDK с Sentry или GlitchTip

  • Сущности. События ошибок, транзакции и спаны, профили, релизы, окружения.
  • Ключевые операции. sentry_sdk.init с traces_sample_rate, автоспаны middleware, SQL, Redis и кэша вендор [S83].
  • Интеграции. GlitchTip принимает данные клиентских SDK Sentry вендор [S85].
  • Ограничения. Self-hosted Sentry — 4 CPU, 16 GB RAM + 16 GB swap, лицензия FSL факт [S84]; uWSGI требует флагов потоков вендор [S83].
  • Цена входа. SDK бесплатен; GlitchTip — 256–512 MB RAM факт [S86]; SaaS Sentry — платный, тариф не проверялся.

Что выбрать

Профиль API Задачи Наблюдаемость Качество
Соло DRF или Ninja Management commands или django-tasks-db GlitchTip или Sentry SaaS, JSON-логи Ruff, mypy базово, pytest
Небольшая команда с агентами (профиль справочника) DRF + drf-spectacular или Ninja Procrastinate или Celery при тяжёлой обработке Sentry SDK; GlitchTip в регионах и у клиентов Ruff, mypy + django-stubs, pytest-xdist, Squawk, Schemathesis ночью
Организация, 20+ разработчиков Как у команды + границы модулей Celery с RabbitMQ Sentry + OpenTelemetry + Prometheus + Import Linter или tach, строгий mypy по модулям

Адаптация под LLM и агентов

Состояние практики на дату среза

  • ИИ-инструменты в Django-разработке массовые. Только 10 % респондентов 2026 года не пользуются ими регулярно; Claude Code — 35 %, ChatGPT — 33 %, GitHub Copilot — 23 %; генерацию кода под надзором применяют 59 %, автономные многошаговые задачи — 27 % эмпирика [S27].
  • Появились открытые наборы правил для агентов под Django. Sentry публикует навыки django-perf-review и django-access-review (IDOR) факт [S105]; Vinta — django-expert, django-celery-expert, cdrf-expert, django-safe-migration, django-reviewer под MIT факт [S129].
  • Эффект не измерен. В статье Vinta о навыках количественных оценок нет факт [S130]; контролируемых сравнений качества кода агентов с правилами и без них для Django не найдено гипотеза.
  • Стандарт файла правил. AGENTS.md поддерживают основные агенты, файл ближе к коду имеет приоритет факт [S62]; Sentry делает его обязательным в SDK-репозиториях факт [S125].
  • Django как сервер инструментов для агентов. django-mcpz позволяет поднять MCP-сервер в обычном синхронном WSGI-представлении с отзываемыми bearer-токенами факт [S128].

Как устроить проект, чтобы агенты писали и ревьюили без лишней работы

Приём Почему работает Как проверить Источник
Один способ на типовую задачу и эталонное приложение для копирования Агент копирует соседний код; два стиля в репозитории дают третий гипотеза Ревью отклонений от эталона гипотеза
Короткий корневой AGENTS.md + вложенные AGENTS.md в приложениях с особыми правилами Ближайший файл имеет приоритет Агент цитирует правило в описании PR факт [S62]
Правила в виде проверок, а не текста Проверку нельзя «не заметить»; Kraken проверяет соответствие аннотаций представлений URL-шаблонам через django-consistency-enforcer Каждое правило AGENTS.md ссылается на шаг CI факт [S45, S111]
Те же команды проверки локально и в CI, быстрые тесты Агент итерирует сам до зелёного; эталон скорости — бэкенд Zulip менее 30 с Время pytest -n auto факт [S46]
Явные типы и схемы в сигнатурах Вход и выход эндпоинта видны без чтения реализации, как typed_endpoint в Zulip mypy и сверка OpenAPI факт [S24, S22]
Снимок OpenAPI в репозитории Контракт — контекст для агента и мобильного клиента git diff openapi.yaml в PR факт [S81]
Счётчики техдолга, которые могут только уменьшаться Агент не может незаметно добавить нарушение Baseline-файлы в CI, как в PostHog факт [S5]
Выборочный прогон тестов по изменённым контрактам Короче цикл обратной связи в большом монорепозитории Сравнение времени CI факт [S5]
Запрет новых слоёв, зависимостей и async без сигнала Агенты склонны добавлять абстракции «на будущее» гипотеза Пункт 8 чек-листа 6.5 гипотеза
Агент-ревьюер с профильными навыками до ревью человека Ловит N+1 и IDOR по шаблонам Доля замечаний, подтверждённых человеком факт [S105, S129]
Явные правила по новинкам Django в AGENTS.md Модели могут не знать FETCH_PEERS, DB_CASCADE, удаление coreapi в DRF 3.17 Ruff и тесты с -W error на устаревшее факт [S2, S18]

Что автоматизируется, а что остаётся человеку

Работа Агент Человек
Эндпоинт по эталону: схема, представление, тесты 404 и числа запросов Пишет целиком Ревью прав доступа
Миграции Пишет, прогоняет Squawk и makemigrations --check Утверждает миграции больших таблиц и удаления
Обновление Django и библиотек Запускает django-upgrade, чинит предупреждения Решает о переходе между LTS
Тесты и фабрики Пишет Проверяет, что тест проверяет поведение, а не реализацию
Ревью PR Первый проход по чек-листу 6.5 и навыкам Финальное решение
Решения по сигналам Р01–Р16, модель данных, границы арендаторов, модель аутентификации Готовит данные: метрики, запросы, профили Принимает и записывает в журнал 6.8

Риски

  • BOLA в сгенерированных эндпоинтах. Агент пишет Model.objects.get(pk=...) из типовых примеров; закрывается scoped-менеджерами и тестом 404 факт [S91].
  • Устаревшие API в обучающих данных. drf-yasg вместо drf-spectacular, select_related() без аргументов, coreapi факт [S82, S2, S18].
  • Небезопасные миграции. Генерация makemigrations без чтения SQL; Vinta выделяет отдельный навык безопасных миграций факт [S129].
  • Оверинжиниринг по образцу. Копирование services/selectors и слоёв в приложения, где нет сценариев гипотеза.
  • Утечки. Секреты и персональные данные в промптах и логах; send_default_pii=False в SDK как значение по умолчанию проекта вендор [S83].

Инструменты и репозитории (дата доступа 2026-10-01)

Инструмент Назначение Источник
AGENTS.md Формат правил для агентов [S62]
getsentry/skills Навыки ревью производительности и доступа в Django [S105]
vintasoftware/django-ai-plugins Навыки по Django, DRF, Celery, миграциям, ревью [S129]
django-mcpz MCP-сервер внутри Django [S128]
Import Linter Машинная проверка границ, понятная агенту по ошибке CI [S111]
django-consistency-enforcer (Kraken) Проверка согласованности представлений и URL [S45]

Происхождение, ключевые фигуры, что читать

Происхождение и этапы

Этап Какую боль решал Что актуально сейчас Источник
2003–2005: Django в газете Lawrence Journal-World (Адриан Головати, Саймон Уиллисон, Джейкоб Каплан-Мосс), публичный релиз в июле 2005 Быстрая разработка сайтов с базой данных Принцип «батарейки в комплекте» объясняет, почему auth, админка и миграции — не сторонние решения факт [S131]
2008: DSF и Django 1.0 со стабильным API Предсказуемость для бизнеса Политика совместимости и предупреждений об устаревании факт [S131]
С 2011: Django REST framework (Encode) Нет стандартного API-слоя 73 % пользователей API-фреймворков; с 2024 — feature-complete факт [S132, S28, S31]
2019–2020: ASGI в Django 3.0, async-представления в 3.1 Долгие соединения и I/O-конкурентность Async по-прежнему без транзакций факт [S131, S33]
2020: «Against service layers» Беннетта Реакция на перенос паттернов Data Mapper в Active Record Главный спор о месте логики мнение [S50]
Около 2020: Django Ninja (самые старые открытые issues датированы 2020 годом) Интеграция подхода FastAPI с Django ORM и auth 17 % пользователей API-фреймворков факт [S32, S10, S28]
2020: atomic(durable=True) после обсуждения в Kraken Вложенные atomic скрывали момент фиксации Внешняя транзакция бизнес-операции факт [S99]
2023–2024: db_default, пул соединений Безопасные миграции, задержка соединений Базовый набор Б09 и Р02 факт [S56, S14]
2024: DEP 14 (Джейк Говард), 2025: django.tasks в 6.0 Нет общего API фоновых задач Стандартный API без воркера в ядре факт [S133, S15]
2026: fetch modes в 6.1, DEP 20 о годовом цикле N+1 «по умолчанию», непредсказуемый цикл LTS Новый способ гасить N+1, обновление раз в год с 2028 факт [S2, S17]

Ключевые фигуры

  • Джеймс Беннетт — против сервисного слоя в Django мнение [S50].
  • Люк Плант — тонкие представления, цепочки QuerySet, фабрики-функции в тестах мнение [S51, S55].
  • HackSoft — services/selectors как систематический шаблон мнение [S48].
  • Адам Джонсон — инструменты автоматизации рутины Django: django-upgrade, django-linear-migrations, django-orjson, django-mcpz факт [S127, S74, S75, S128].
  • Хаки Бенита — работа с PostgreSQL через ORM с измерениями эмпирика [S36, S37].
  • Сопровождающие DRF — объявили проект завершённым по функциям факт [S31].
  • Карлтон Гибсон — сопровождение Django Channels в режиме best-effort факт [S64].
  • Виталий Кучерявый — автор Django Ninja факт [S10].
  • Дэвид Седдон, Дэвид Уинтерботтом (Kraken) — описали слои и контракты Import Linter в монолите Kraken и путь к durable=True факт [S3, S99].
  • Джейк Говард — автор DEP 14 и django.tasks факт [S133].

Что читать

  1. [S13] Databases — единственный точный источник правил соединений, пула и PgBouncer.
  2. [S33] Asynchronous support — когда async даёт выгоду и почему транзакции остаются синхронными.
  3. [S40] Fetch modes — новый способ гасить N+1 в Django 6.1.
  4. [S50] Against service layers — сильнейший аргумент против слоёв ради слоёв.
  5. [S48] Django Styleguide — противоположная позиция с конкретными шаблонами.
  6. [S51] Thin views — середина между двумя позициями.
  7. [S3] Kraken monolith — как держать 400 разработчиков в одном коде с Import Linter.
  8. [S49] Kraken conventions — проверенные масштабом запреты.
  9. [S5] PostHog architecture — фасады, контракты и счётчики «только вниз».
  10. [S66] Sentry migrations — правила миграций без простоя.
  11. [S4] Sentry multi-region — регионы внутри монолита и симуляция в CI.
  12. [S47] Zulip API docs — OpenAPI как проверяемый источник истины.
  13. [S76] Concurrency without locks — атомарные операции вместо блокировок.
  14. [S36] Fast load into PostgreSQL — измерения массовой загрузки.
  15. [S12] Celery tasks guide — идемпотентность, acks_late, транзакции.
  16. [S53] Tasks without a worker — трезвая критика django.tasks.
  17. [S54] JWT tokens in allauth — почему JWT не stateless.
  18. [S91] OWASP API Top 10 2023 — модель угроз API.
  19. [S71] Healthchecks.io hosting — как выглядит рациональный соло-проект.

Лучшие критические разборы среди прочитанного — Беннетт о сервисных слоях и Kevin Renskers о django.tasks; оба опираются на опыт авторов, а не на измерения мнение [S50, S53].

Открытые вопросы и границы уверенности

Что не удалось проверить

  • Независимый бенчмарк DRF против Django Ninja на эндпоинтах, где время уходит в базу, не найден; тезис о выигрыше Pydantic v2 остаётся гипотезой.
  • Эффект правил для ИИ-агентов (AGENTS.md, навыки Sentry и Vinta) на число дефектов не измерен ни в одном найденном источнике факт [S130].
  • Зрелость сторонних бэкендов django.tasks. Поисковые выдачи приводят списки бэкендов со статусами, но первоисточники, кроме django-tasks-db и открытого запроса к Celery, не прочитаны факт [S52, S35].
  • Внутренние практики Instagram (структура кода, тесты, типы) в доступных источниках не описаны; статья Instagram Engineering о производительности не открылась (отказ соединения), использованы статьи Meta Engineering факт [S42, S7].
  • Read the Docs. Страница архитектуры вернула 404 после переезда документации, проект в сравнение не включён.
  • История ухода с Django-монолита с числами не подтверждена: статья Botify о возврате сервиса в Django-монолит недоступна (403). Подтверждены только частичные выносы горячих путей (Healthchecks.io, Zulip) и разделение по регионам внутри монолита (Sentry) факт [S43, S6, S4].
  • «Two Scoops of Django» — книга закрыта, последнее издание под Django 3.x; её позиции не использованы факт [S77].
  • Влияние пула Django на задержку известно по одной статье без методики эмпирика [S41].
  • Список целевых версий django-upgrade на странице опций не опубликован факт [S127].

Противоречия между источниками

  • Место бизнес-логики: HackSoft против Беннетта и Планта; справочник выбирает гибрид, но это авторский вывод гипотеза.
  • Фабрики тестовых данных: factory_boy (HackSoft) против функций (Плант) мнение [S48, S55].
  • Версионирование: DRF называет версионирование через заголовок Accept «в целом лучшей практикой» мнение [S110], справочник рекомендует v1 в URL ради простоты кэширования и отладки мобильным клиентом гипотеза.
  • Даты релизов в вторичных источниках. Поисковая сводка давала Celery 5.6.0 дату 2026-07-27, changelog — 2025-11-30 факт [S20]; сводка страницы релизов Django Ninja давала 2024 год, PyPI — 2026 факт [S19]. В отчёте использованы первоисточники.

Что могло бы изменить выводы

  • Измерение DRF и Ninja на реальном проекте с одинаковыми запросами к базе.
  • Возникновение официального production-бэкенда django.tasks в ядре или у Celery: тогда рекомендация писать задачи против стандартного API станет сильнее.
  • Async-транзакции в Django: снимут главный аргумент против ASGI по умолчанию.
  • Исправление обработки исключений парсера в ASGI-воркере Gunicorn факт [S58].
  • Django 6.2 LTS (апрель 2027) — новая точка для политики версий установок у клиентов факт [S1].

Границы уверенности

  • Пороги сигналов (70–80 % соединений, 15–20 приложений, 60–70 % CPU и другие) — ориентиры автора без эмпирической калибровки.
  • Опросы DSF и JetBrains — самоотобранные выборки; доли не переносятся на все Django-проекты эмпирика [S28].
  • Кейсы Kraken, Sentry, PostHog описывают большие организации; перенос их механизмов на команду из нескольких человек сделан только по сигналам.
  • Доступ: прочитаны полные тексты официальной документации и блогов; книги и платные отчёты не использовались.
  • Инструмент чтения страниц возвращает сжатое изложение загруженной страницы, а не сырой текст; пометка «полный текст» в реестре означает, что страница загрузилась целиком. Цитаты взяты из этого изложения. Найденная ошибка инструмента (неверный год у релизов Django Ninja на GitHub) исправлена сверкой с PyPI, но аналогичные искажения в других местах полностью исключить нельзя.

Реестр источников

IDНазваниеАвтор или издательURLПубликацияДоступ (дата)Вид доступаЧто подтверждает
S1Download / Supported versionsDjango Software Foundationdjangoproject.com/download/без даты2026-10-01полный текстразделы 0, 1, 3, 5, 8, 12: сроки поддержки 5.2 LTS, 6.0, 6.1, 6.2 LTS, Django 2028
S2Django 6.1 release notesDjango Software Foundationdocs.djangoproject.com/en/6.1/releases/6.1/2026-08-052026-10-01полный текстразделы 0, 1, 2, 3, 5, 7, 10, 11: fetch modes, DB_CASCADE без сигналов, MAILERS, UUID7, PostgreSQL 15+, устаревание select_related() без аргументов
S3Kraken Technologies: How we organise our very large Python monolithDavid Seddon, EuroPython blogblog.europython.eu/kraken-technologies-how-we-organize-ou…2023-07-112026-10-01полный текстразделы 0, 1, 2, 3, 4, 5, 8, 11: 27 637 модулей, 400 разработчиков, 17 компаний, слои, 40+ контрактов Import Linter, 15 игнорируемых импортов
S4Removing risk from our multi-region design with simulationsSentryblog.sentry.io/removing-risk-from-our-multiregion-design-…2024-052026-10-01полный текстразделы 0, 3, 4, 5, 7, 11, 12: silo внутри монолита, симуляция границ в CI, 35 000 тестов в двух режимах
S5products/architecture.mdPostHoggithub.com/PostHog/posthog/blob/master/products/architect…без даты2026-10-01полный текстразделы 0, 1, 2, 4, 5, 8, 9, 10, 11: facade и frozen dataclasses, tach + import-linter, baseline «только вниз», DRF в presentation
S6Zulip architectural overviewZulip projectzulip.readthedocs.io/en/latest/overview/architecture-over…без даты2026-10-01полный текстразделы 0, 1, 3, 4, 5, 12: Django + Tornado для push, RabbitMQ-очереди, Redis для rate limit
S7How the Cinder JIT's function inliner helps us optimize InstagramMeta Engineeringengineering.fb.com/2022/05/02/open-source/cinder-jits-ins…2022-05-022026-10-01полный текстразделы 0, 2, 3, 4, 12: «one of the world's largest deployments of Django» (вендор)
S8How to deploy with ASGIDjango Software Foundationdocs.djangoproject.com/en/6.1/howto/deployment/asgi/без даты2026-10-01полный текстразделы 1, 9: Daphne, Granian, Hypercorn, Uvicorn
S9Authentication — DRF API guideEncode / DRFdjango-rest-framework.org/api-guide/authentication/без даты2026-10-01полный текстразделы 1, 4, 5, 9: сессии для SPA, TokenAuthentication без срока жизни, Knox, Django OAuth Toolkit
S10Motivation — Django NinjaVitaliy Kucheryaviydjango-ninja.dev/motivation/без даты2026-10-01полный текстразделы 1, 3, 4, 5, 9, 11: мотивация автора, интеграция с ORM и auth, несколько версий API, без бенчмарков
S11Django's Tasks framework (topic guide)Django Software Foundationdocs.djangoproject.com/en/6.1/topics/tasks/без даты2026-10-01полный текстразделы 1, 4, 5: ImmediateBackend/DummyBackend только для разработки, on_commit для постановки
S12Tasks — Celery user guideCelery projectdocs.celeryq.dev/en/stable/userguide/tasks.htmlбез даты2026-10-01полный текстразделы 1, 3, 4, 5, 7, 8, 9, 11: идемпотентность, acks_late, delay_on_commit, передача ID, ретраи
S13Databases (ref)Django Software Foundationdocs.djangoproject.com/en/6.1/ref/databases/без даты2026-10-01полный текстразделы 1, 4, 5, 6, 7, 8, 11: CONN_MAX_AGE, CONN_HEALTH_CHECKS, пул на процесс, ASGI без постоянных соединений, PgBouncer и server-side cursors
S14Django 5.1 release notesDjango Software Foundationdocs.djangoproject.com/en/6.1/releases/5.1/2024-08-072026-10-01полный текстразделы 1, 2, 3, 11: пул соединений PostgreSQL, LoginRequiredMiddleware
S15Django 6.0 release notesDjango Software Foundationdocs.djangoproject.com/en/6.0/releases/6.0/2025-12-032026-10-01полный текстразделы 1, 2, 3, 11: django.tasks без воркера, CSP, BigAutoField по умолчанию, AsyncPaginator, Python 3.12+
S16Django 5.2 release notesDjango Software Foundationdocs.djangoproject.com/en/6.1/releases/5.2/2025-04-022026-10-01полный текстразделы 1, 2: LTS, CompositePrimaryKey, async-методы auth
S17Django is moving to an annual release cycleDjango Software Foundationdjangoproject.com/weblog/2026/aug/10/annual-release-cycle/2026-08-102026-10-01полный текстразделы 1, 2, 3, 11: DEP 20, годовой цикл с 2028, три года поддержки каждой версии
S18Release Notes — Django REST frameworkEncode / DRFdjango-rest-framework.org/community/release-notes/без даты2026-10-01полный текстразделы 1, 2, 3, 4, 5, 9, 10: DRF 3.18.1 от 2026-09-07, 3.18 только Django 5.2+, coreapi удалён в 3.17
S19django-ninja (PyPI)Vitaliy Kucheryaviy, PyPIpypi.org/project/django-ninja/2026-09-192026-10-01полный текстразделы 1, 2, 4, 9, 12: история версий 1.4–1.7.1, десять релизов с ноября 2025
S20Change history — Celery 5.6.3Celery projectdocs.celeryq.dev/en/stable/changelog.html2026-03-262026-10-01полный текстразделы 1, 2, 9, 12: Celery 5.5–5.6, soft shutdown, quorum queues, лимит ETA-задач, даты релизов
S21Gunicorn 2026 newsGunicorngunicorn.org/2026-news/2026-09-062026-10-01полный текстразделы 1, 2, 4, 9: ASGI-воркер стабилен с 25.1.0, eventlet удалён в 26.0
S22django-stubs READMETypedDjangogithub.com/typeddjango/django-stubsбез даты2026-10-01полный текстразделы 1, 3, 5, 6, 9, 10: 6.1.1 для Django 6.1/6.0/5.2, плагин mypy на рантайме, Pyright базово
S23Bump djangorestframework from 3.18.0 to 3.18.1 (#25437)mozilla/addons-servergithub.com/mozilla/addons-server/pull/254372026-09-232026-10-01полный текстразделы 1, 4, 5: addons-server на DRF, обновления через Dependabot
S24Writing views in ZulipZulip projectzulip.readthedocs.io/en/latest/tutorials/writing-views.htmlбез даты2026-10-01полный текстразделы 1, 4, 10: typed_endpoint на Pydantic v2
S25Saleor webhooks overviewSaleordocs.saleor.io/developer/extending/webhooks/overviewбез даты2026-10-01полный текстразделы 1, 5: sync/async вебхуки, HMAC, таймаут 20 с, payload через GraphQL-подписки
S26GraphQL API — NetBoxNetBox Labsnetboxlabs.com/docs/netbox/en/stable/integrations/graphql…без даты2026-10-01полный текстразделы 1, 4: read-only GraphQL на Strawberry Django в дополнение к REST
S27The State of Django 2026: Boring is so backWill Vincent, JetBrainsblog.jetbrains.com/pycharm/2026/08/the-state-of-django-20…2026-082026-10-01полный текстразделы 2, 3, 5, 10: ~3500 ответов, API-only 53 %, PostgreSQL 76–79 %, Claude Code 35 %, Ruff 43 %, нет тестов 19 % (эмпирика)
S28Django Developers Survey 2026 ResultsJetBrains, DSFlp.jetbrains.com/django-developer-survey-2026/2026-082026-10-01полный текстразделы 2, 4, 5, 8, 11, 12: DRF 73 %, Ninja 17 %, Redis 53 %, async 33 %, версии Django (эмпирика)
S29The State of Django 2025Will Vincent, JetBrainsblog.jetbrains.com/pycharm/2025/10/the-state-of-django-2025/2025-102026-10-01полный текстраздел 2: более 4600 ответов, DRF 49 %, Celery 26 % (эмпирика)
S30Contributing to REST frameworkEncode / DRFdjango-rest-framework.org/community/contributing/без даты2026-10-01полный текстразделы 2, 3, 4, 9: DRF «feature-complete», новые функции не принимаются
S31Moving REST framework forward (#9270)encode/django-rest-frameworkgithub.com/encode/django-rest-framework/discussions/92702024-03-052026-10-01полный текстразделы 2, 4, 11: PR только для поддержки Django, безопасности, документации
S32Should I continue using Ninja? (#1197)vitalik/django-ninjagithub.com/vitalik/django-ninja/discussions/11972024-08-102026-10-01полный текстразделы 2, 3, 4, 9, 11: bus factor, обязательства поддержки по графику LTS, issues с 2020 года
S33Asynchronous supportDjango Software Foundationdocs.djangoproject.com/en/6.1/topics/async/без даты2026-10-01полный текстразделы 2, 3, 4, 5, 7, 8, 11: async ORM, транзакции не работают в async, цена переключений, выгода для долгих соединений
S34Working with async Django: lessons learnedFrederike Jaeger, Krakenengineering.kraken.tech/news/2026/01/12/using-django-asyn…2026-01-122026-10-01полный текстразделы 2, 3, 5, 7, 8: async для параллельных LLM-вызовов, сложности тестов и транзакций, CONN_MAX_AGE = 0
S35Add celery backend based on django 6 tasks (#10062)celery/celerygithub.com/celery/celery/issues/100622026-01-112026-10-01полный текстразделы 2, 9, 12: официального бэкенда Celery для django.tasks нет, запрос открыт
S36Fastest Way to Load Data Into PostgreSQL Using PythonHaki Benitahakibenita.com/fast-load-data-python-postgresql2019-07-092026-10-01полный текстразделы 2, 4, 5, 11: 32 500 строк — 128,8 с поштучно против 0,46 с COPY (эмпирика)
S37Optimizing the Django Admin PaginatorHaki Benitahakibenita.com/optimizing-the-django-admin-paginator2018-11-062026-10-01полный текстразделы 2, 4, 5, 8, 11: COUNT 781 мс из 786 мс, таймаут 200 мс на count (эмпирика)
S38migrate_schemas scans the whole catalog ~4× per tenant (#1269)django-tenants, GitHubgithub.com/django-tenants/django-tenants/issues/12692026-09-292026-10-01полный текстразделы 2, 4, 5, 9: ~1780 схем, 5–14 с CPU базы на арендатора при пустой миграции
S39django-zeal READMETao Bojléngithub.com/taobojlen/django-zealбез даты2026-10-01полный текстразделы 2, 5, 8, 9: детекция N+1 в тестах, накладные расходы 3–5 % (вендор), nplusone заброшен (мнение)
S40Fetch modesDjango Software Foundationdocs.djangoproject.com/en/6.1/topics/db/fetch-modes/без даты2026-10-01полный текстразделы 2, 3, 5, 11: FETCH_PEERS, FETCH_RAISE, менеджер по умолчанию
S41Cut Django Database Latency by 50-70ms With Native Connection PoolingSaurabh Kumarsaurabh-kumar.com/articles/2025/06/cut-django-database-la…2025-06-182026-10-01полный текстразделы 2, 12: единичный замер пула psycopg на managed PostgreSQL без методики
S42Introducing Immortal Objects for PythonEddie Elizondo, Meta Engineeringengineering.fb.com/2023/08/15/developer-tools/immortal-ob…2023-08-152026-10-01полный текстразделы 2, 3, 4, 12: Instagram на Django, pre-fork, copy-on-write, регрессия ~2 %
S43Healthchecks.io Blog, page 6 (2016–2017)Pēteris Cauneblog.healthchecks.io/page/6/без даты2026-10-01фрагментразделы 2, 3, 4, 5, 12: вынос ping handler в Go из-за CPU Python через ~6 месяцев после запуска
S44How we ship over 100 versions a day to over 25 environmentsJames S, Krakenengineering.kraken.tech/news/2025/02/07/how-we-ship.html2025-02-072026-10-01полный текстразделы 2, 3, 4, 5, 7, 8: ~9 млн строк, 100+ версий в день, 100 000+ тестов менее 30 мин, фича-флаги, совместимые миграции
S45Static typing Python at scale — Our journey with mypy and DjangoStephen Moore, Krakenengineering.kraken.tech/news/2026/02/16/static-typing-pyt…2026-02-162026-10-01полный текстразделы 2, 3, 4, 5, 8, 10: 5 млн строк под mypy, 2000+ моделей, 2,5 года, 5000 ignore, django-consistency-enforcer
S46Backend Django testsZulip projectzulip.readthedocs.io/en/latest/testing/testing-with-djang…без даты2026-10-01полный текстразделы 2, 3, 4, 5, 8, 10: менее 30 с параллельно, assert_database_query_count, 100 % покрытия нового кода
S47Documenting REST API endpointsZulip projectzulip.readthedocs.io/en/latest/documentation/api.htmlбез даты2026-10-01полный текстразделы 2, 4, 5, 11: каждый ответ в тестах сверяется с OpenAPI
S48Django StyleguideHackSoftgithub.com/HackSoftware/Django-Styleguideбез даты2026-10-01полный текстразделы 2, 4, 5, 8, 11, 12: services/selectors, Input/OutputSerializer, on_commit, factory_boy, «не единственный путь» (мнение)
S49octoenergy public-conventions: django.mdKraken Technologiesraw.githubusercontent.com/octoenergy/public-conventions/m…без даты2026-10-01полный текстразделы 2, 4, 5, 8, 11: один вызов домена из интерфейса, без implicit ordering, ограничения в базе, save() только в мутаторах
S50Against service layers in DjangoJames Bennettb-list.org/weblog/2020/mar/16/no-service/2020-03-162026-10-01полный текстразделы 2, 4, 5, 8, 11: логика в моделях, менеджерах и QuerySet; YAGNI (мнение)
S51Django Views — The Right Way: Thin viewsLuke Plantspookylukey.github.io/django-views-the-right-way/thin-vie…без даты2026-10-01полный текстразделы 2, 4, 5, 8, 11: логика в методах моделей и QuerySet, без отдельного service layer (мнение)
S52Using Django Tasks in productionTim Schilling, Better Simplebetter-simple.com/django/2026/05/06/using-django-tasks-in…2026-05-062026-10-01полный текстразделы 2, 4, 5, 9, 12: django-tasks-db + db_worker на малом VPS
S53Django 6.0 Tasks: a framework without a workerKevin Renskers, Loopwerkloopwerk.io/articles/2026/django-tasks-review/2026-01-192026-10-01полный текстразделы 2, 4, 5, 11: критика django.tasks — нет воркера, ретраев, расписания (мнение)
S54JWT Tokens — django-allauth headlessdjango-allauthdocs.allauth.org/en/dev/headless/token-strategies/jwt-tok…без даты2026-10-01полный текстразделы 2, 4, 5, 7, 9, 11: JWT не stateless при отзыве; польза для нескольких сервисов
S55Test factory functions in DjangoLuke Plantlukeplant.me.uk/blog/posts/test-factory-functions-in-django/2022-11-252026-10-01полный текстразделы 2, 4, 5, 11, 12: фабрики-функции вместо factory_boy (мнение)
S56Django 5.0 release notesDjango Software Foundationdocs.djangoproject.com/en/6.1/releases/5.0/2023-12-042026-10-01полный текстразделы 2, 3, 11: db_default, GeneratedField
S57Releases · vitalik/django-ninjaVitaliy Kucheryaviygithub.com/vitalik/django-ninja/releasesбез даты2026-10-01фрагментразделы 2, 4, 5, 9: состав релизов 1.6–1.7 — cursor pagination, Retry-After, стриминг JSONL и SSE
S58Should I use the newly stable asgi workers for a Django ASGI server? (#3524)benoitc/gunicorngithub.com/benoitc/gunicorn/discussions/35242026-02-202026-10-01полный текстразделы 2, 4, 7, 12: ASGI-воркер обрабатывает не все исключения парсера
S59Django: fixing a memory "leak" from Python 3.14's incremental garbage collectionAdam Johnsonadamj.eu/tech/2026/04/20/django-python-3.14-incremental-gc/2026-04-202026-10-01полный текстразделы 2, 4, 5, 7: OOM migrate на Python 3.14, gc.collect() после миграций, откат incremental GC в 3.14.5
S60opentelemetry-python-contrib READMEOpenTelemetrygithub.com/open-telemetry/opentelemetry-python-contribбез даты2026-10-01фрагментраздел 2: миграция HTTP-инструментаций на стабильные semantic conventions
S61Document OTEL_SEMCONV_STABILITY_OPT_IN (#4202)open-telemetry/opentelemetry-python-contribgithub.com/open-telemetry/opentelemetry-python-contrib/is…2026-02-132026-10-01полный текстраздел 2: значения http и http/dup, по умолчанию старые атрибуты
S62AGENTS.mdAgentic AI Foundationagents.md/без даты2026-10-01полный текстразделы 2, 6, 10: формат, ближайший файл приоритетен, поддержка основными агентами
S63GeoDjango InstallationDjango Software Foundationdocs.djangoproject.com/en/6.1/ref/contrib/gis/install/без даты2026-10-01полный текстразделы 3, 5: PostGIS рекомендован, PostgreSQL 15+
S64django/channels READMEDjango projectgithub.com/django/channelsбез даты2026-10-01полный текстразделы 3, 5, 9, 11: сопровождение best-effort под руководством Карлтона Гибсона, гарантированно только безопасность
S65django-pg-zero-downtime-migrationstbicr (Paveł Tyślacki)github.com/tbicr/django-pg-zero-downtime-migrationsбез даты2026-10-01полный текстразделы 3, 5, 8, 9: безопасные DDL, LOCK_TIMEOUT, RAISE_FOR_UNSAFE, PostgreSQL 14–18, статус бета
S66Database Migrations — Sentry Developer DocumentationSentrydevelop.sentry.dev/backend/application-domains/database-m…без даты2026-10-01полный текстразделы 3, 4, 5, 8, 11: post-deploy миграции для индексов дольше 10 с, двухфазное удаление, db_default, db_column
S67Kraken Engineering Blog (главная)Kraken Technologiesengineering.kraken.tech/без даты2026-10-01фрагментразделы 4, 5: Celery + RabbitMQ (обновление без поломки ETA-задач, 2026-01-09)
S68Django, Kubernetes Health Checks and Continuous DeliveryFederico Marani, Krakenengineering.kraken.tech/news/2026/02/11/django-kubernetes…2026-02-112026-10-01полный текстразделы 4, 5: один /health/ для трёх проб, миграции через pre-upgrade hook
S69Cross Region ReplicationSentrydevelop.sentry.dev/application-architecture/multi-region-…без даты2026-10-01полный текстразделы 4, 5, 7: outbox в той же транзакции, tombstones, HybridCloudForeignKey
S70About — Healthchecks.ioPēteris Caunehealthchecks.io/about/без даты2026-10-01полный текстраздел 4: один человек с июля 2015, BSD, доступность выше 99,9 % (вендор)
S71A Look at Healthchecks.io Hosting Setup, Summer 2019Pēteris Cauneblog.healthchecks.io/2019/08/a-look-at-healthchecks-io-ho…2019-082026-10-01полный текстразделы 4, 5, 11: без контейнеров и очередей, sendalerts/sendreports как systemd-сервисы, ~€274 в месяц
S72NetBox installationNetBox Labsnetboxlabs.com/docs/netbox/en/stable/installation/без даты2026-10-01полный текстраздел 4: Python 3.12+, PostgreSQL 15+, Redis, rqworker
S73REST API — NetBoxNetBox Labsnetboxlabs.com/docs/netbox/en/stable/integrations/rest-api/без даты2026-10-01полный текстразделы 4, 5: MAX_PAGE_SIZE 1000, brief-режим, токены v2 с хешем и pepper
S74django-linear-migrationsAdam Johnsongithub.com/adamchainz/django-linear-migrationsбез даты2026-10-01полный текстразделы 4, 5, 9, 11: max_migration.txt, rebase_migration
S75Django: introducing django-orjsonAdam Johnsonadamj.eu/tech/2026/07/15/introducing-django-orjson/2026-07-152026-10-01полный текстразделы 4, 5, 9, 11: замена JSON-компонентов Django и DRF на orjson (вендор)
S76Handling Concurrency Without LocksHaki Benitahakibenita.com/django-concurrency2022-06-092026-10-01полный текстразделы 4, 5, 11: EAFP, F-выражения, UPDATE … RETURNING, select_for_update (мнение)
S77Two Scoops of Django 3.xDaniel и Audrey Feldroyfeldroy.com/two-scoops-of-django2021-022026-10-01аннотацияразделы 4, 12: книга закрыта, издание под Django 3.x, не прочитана
S78Pagination — DRF API guideEncode / DRFdjango-rest-framework.org/api-guide/pagination/без даты2026-10-01полный текстразделы 4, 5, 6: CursorPagination — уникальное неизменное поле с индексом, фиксированное время
S79Throttling — DRF API guideEncode / DRFdjango-rest-framework.org/api-guide/throttling/без даты2026-10-01полный текстразделы 4, 5, 9: throttling не мера безопасности, гонки, NUM_PROXIES
S80Procrastinate documentationProcrastinateprocrastinate.readthedocs.io/en/stable/без даты2026-10-01полный текстразделы 4, 5, 9: очередь на PostgreSQL, транзакционная постановка, periodic, блокировки
S81drf-spectacular READMET. Franzeldrf-spectacular.readthedocs.io/en/latest/readme.htmlбез даты2026-10-01полный текстразделы 4, 5, 7, 9, 10: OpenAPI 3.0.3/3.1/3.2, --validate, версия ниже 1.0 сознательно
S82drf-yasg READMEaxnsan12github.com/axnsan12/drf-yasgбез даты2026-10-01полный текстразделы 4, 7, 9, 10: только OpenAPI 2.0, рекомендует drf-spectacular
S83Sentry Django integrationSentrydocs.sentry.io/platforms/python/integrations/django/без даты2026-10-01полный текстразделы 4, 5, 7, 8, 9, 10: автоспаны middleware, SQL, кэша; traces_sample_rate; флаги uWSGI (вендор)
S84Self-Hosted SentrySentrydevelop.sentry.dev/self-hosted/без даты2026-10-01полный текстразделы 4, 5, 8, 9: 4 CPU, 16 GB RAM + 16 GB swap, лицензия FSL
S85GlitchTip (главная)Burke Software and Consultingglitchtip.com/без даты2026-10-01полный текстразделы 4, 5, 9: совместимость с клиентскими SDK Sentry, uptime, логи (вендор)
S86GlitchTip installationBurke Software and Consultingglitchtip.com/documentation/installбез даты2026-10-01полный текстразделы 4, 5, 8, 9: 256–512 MB RAM, PostgreSQL 14+, Valkey опционально
S87OpenTelemetry Django InstrumentationOpenTelemetryopentelemetry-python-contrib.readthedocs.io/en/latest/ins…без даты2026-10-01полный текстразделы 4, 7, 9: DjangoInstrumentor, excluded URLs, sqlcommenter, response_hook
S88Multiprocess Mode — prometheus client_pythonPrometheusprometheus.github.io/client_python/multiprocess/без даты2026-10-01полный текстразделы 4, 5, 7, 9: ограничения multiprocess-режима, очистка каталога
S89Row Security PoliciesPostgreSQL Global Development Grouppostgresql.org/docs/current/ddl-rowsecurity.htmlбез даты2026-10-01полный текстразделы 4, 5, 7: владелец таблицы и BYPASSRLS обходят RLS, FORCE, default-deny
S90How to upgrade Django to a newer versionDjango Software Foundationdocs.djangoproject.com/en/6.1/howto/upgrade-version/без даты2026-10-01полный текстразделы 5, 8: по одной feature-версии, -Wa, сначала зависимости
S91OWASP API Security Top 10 — 2023OWASPapi-security.owasp.org/editions/2023/en/0x11-t1020232026-10-01полный текстразделы 5, 7, 10, 11: BOLA на первом месте, API3 Broken Object Property Level Authorization
S92Ruff rules: flake8-django (DJ)Astraldocs.astral.sh/ruff/rules/#flake8-django-djбез даты2026-10-01полный текстразделы 5, 6, 9: правила DJ001–DJ013, набор S (bandit)
S93Schemathesis documentationSchemathesisschemathesis.readthedocs.io/en/stable/без даты2026-10-01полный текстразделы 5, 7, 9: property-based тесты по OpenAPI
S94RFC 9457: Problem Details for HTTP APIsIETFrfc-editor.org/rfc/rfc9457.html2023-072026-10-01полный текстраздел 5: application/problem+json, поля type/title/status/detail/instance, без стек-трейсов
S95Filtering — DRF API guideEncode / DRFdjango-rest-framework.org/api-guide/filtering/без даты2026-10-01полный текстразделы 5, 9: DjangoFilterBackend, явный ordering_fields против утечки, фильтрация в get_queryset
S96Testing toolsDjango Software Foundationdocs.djangoproject.com/en/6.1/topics/testing/tools/без даты2026-10-01полный текстразделы 5, 7, 8: assertNumQueries, captureOnCommitCallbacks, TestCase быстрее TransactionTestCase
S97pg_stat_statementsPostgreSQL Global Development Grouppostgresql.org/docs/current/pgstatstatements.htmlбез даты2026-10-01полный текстразделы 5, 6, 7: статистика запросов, shared_preload_libraries
S98QuerySet API referenceDjango Software Foundationdocs.djangoproject.com/en/6.1/ref/models/querysets/без даты2026-10-01полный текстразделы 5, 7: bulk_create/bulk_update/update без save() и сигналов, select_for_update в транзакции, iterator с chunk_size
S99Durable database transactions in DjangoDavid Winterbottom, Krakenengineering.kraken.tech/news/2020/11/30/durable-transacti…2020-11-302026-10-01полный текстразделы 5, 11: atomic(durable=True) в Django 3.2
S100Squawk docsSquawksquawkhq.com/docs/без даты2026-10-01полный текстразделы 5, 8, 9: правила линтера миграций PostgreSQL, GitHub Action
S101Deployment checklistDjango Software Foundationdocs.djangoproject.com/en/6.1/howto/deployment/checklist/без даты2026-10-01полный текстраздел 5: check --deploy, SECRET_KEY_FALLBACKS, постоянные соединения, мониторинг ошибок вместо почты
S102Using Redis — CeleryCelery projectdocs.celeryq.dev/en/stable/getting-started/backends-and-b…без даты2026-10-01полный текстразделы 5, 7, 9: visibility timeout 1 ч, повторы ETA-задач, noeviction
S103django-structlog documentationdjango-structlogdjango-structlog.readthedocs.io/en/latest/без даты2026-10-01полный текстразделы 5, 9: request_id и user_id в каждой строке, JSON, DRF и Ninja
S104py-spy READMEBen Fredericksongithub.com/benfred/py-spyбез даты2026-10-01полный текстразделы 5, 9: сэмплирующий профайлер без перезапуска, CPython до 3.14
S105getsentry/skillsSentrygithub.com/getsentry/skillsбез даты2026-10-01полный текстразделы 5, 10: навыки django-perf-review, django-access-review, agents-md
S106pytest-django: Database accesspytest-djangopytest-django.readthedocs.io/en/latest/database.htmlбез даты2026-10-01полный текстразделы 5, 6, 9: --reuse-db, --nomigrations, суффиксы для xdist
S107Multiple databasesDjango Software Foundationdocs.djangoproject.com/en/6.1/topics/db/multi-db/без даты2026-10-01полный текстраздел 5: роутер primary/replica не решает лаг репликации
S108Django's cache frameworkDjango Software Foundationdocs.djangoproject.com/en/6.1/topics/cache/без даты2026-10-01полный текстразделы 5, 7: RedisCache, cache_page не различает auth, LocMem на процесс
S109Performance and Scaling — django-pghistory 2.5.0AmbitionEngdjango-pghistory.readthedocs.io/en/2.5.0/performance.htmlбез даты2026-10-01полный текстразделы 5, 8, 9: триггеры без round trip, цена контекста, рост таблиц и партиционирование
S110Versioning — DRF API guideEncode / DRFdjango-rest-framework.org/api-guide/versioning/без даты2026-10-01полный текстразделы 5, 12: схемы версионирования, Accept-заголовок как «лучшая практика», допустимость систем без версий
S111Import Linter documentationImport Linter projectimport-linter.readthedocs.io/en/stable/без даты2026-10-01полный текстразделы 5, 9, 10: контракты layers, independence, forbidden, protected, acyclic siblings
S112Common Issues — django-simple-historydjango-simple-historydjango-simple-history.readthedocs.io/en/latest/common_iss…без даты2026-10-01полный текстразделы 5, 7, 8, 9: bulk-операции и update() не пишут историю
S113Uploading objects with presigned URLsAmazon Web Servicesdocs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUr…без даты2026-10-01полный текстраздел 5: загрузка без учётных данных, срок до 7 дней, перезапись ключа
S114django-storages: Amazon S3django-storagesdjango-storages.readthedocs.io/en/latest/backends/amazon-…без даты2026-10-01полный текстразделы 5, 9: подписанные URL 3600 с, file_overwrite=True по умолчанию, endpoint_url
S115Healthchecks.io Blog (главная)Pēteris Cauneblog.healthchecks.io/без даты2026-10-01фрагментраздел 5: переход с managed-хранилища на self-hosted S3, bare metal
S116Pattern: Transactional outboxChris Richardson, microservices.iomicroservices.io/patterns/data/transactional-outbox.htmlбез даты2026-10-01полный текстразделы 5, 7: запись сообщения в той же транзакции, дубли, идемпотентный потребитель
S117Standard WebhooksStandard Webhooks TSCstandardwebhooks.com/без даты2026-10-01полный текстраздел 5: webhook-id/timestamp/signature, HMAC-SHA256, защита от replay и SSRF
S118REFRESH MATERIALIZED VIEWPostgreSQL Global Development Grouppostgresql.org/docs/current/sql-refreshmaterializedview.htmlбез даты2026-10-01полный текстраздел 5: CONCURRENTLY требует уникальный индекс, один refresh за раз
S119Full text search (contrib.postgres)Django Software Foundationdocs.djangoproject.com/en/6.1/ref/contrib/postgres/search/без даты2026-10-01полный текстраздел 5: проблемы после «нескольких сотен записей» без индекса, GeneratedField + GIN, триграммы
S120Sync: BackendWatermelonDB (Nozbe)watermelondb.dev/docs/Sync/Backendбез даты2026-10-01полный текстраздел 5: серверное время, tombstones, отказ push при конфликте, транзакционность
S121GeoDjango Database APIDjango Software Foundationdocs.djangoproject.com/en/6.1/ref/contrib/gis/db-api/без даты2026-10-01полный текстраздел 5: geography=True для дистанций в WGS84 с индексом
S122Request and response objectsDjango Software Foundationdocs.djangoproject.com/en/6.1/ref/request-response/без даты2026-10-01полный текстразделы 5, 7: StreamingHttpResponse занимает воркер под WSGI, async-итератор под ASGI
S123The Idempotency-Key HTTP Header Field, draft-07IETF httpapi WGietf.org/archive/id/draft-ietf-httpapi-idempotency-key-he…2025-10-152026-10-01полный текстраздел 5: 409 при параллельном повторе, 422 при другом теле, UUID, черновик истёк
S124django-waffle documentationdjango-wafflewaffle.readthedocs.io/en/stable/без даты2026-10-01фрагментразделы 5, 9: flags, switches, samples; версия 5.0.0
S125Repository and Documentation (SDK standards)Sentrydevelop.sentry.dev/sdk/getting-started/standards/reposito…без даты2026-10-01полный текстразделы 6, 10: обязательный AGENTS.md и его разделы
S126What is Locust?Locustdocs.locust.io/en/stable/what-is-locust.htmlбез даты2026-10-01полный текстраздел 9: сценарии на Python, headless-режим для CI, MIT
S127adamchainz/django-upgradeAdam Johnsongithub.com/adamchainz/django-upgradeбез даты2026-10-01фрагментразделы 9, 11, 12: «Automatically upgrade your Django projects»; в репозитории есть .pre-commit-hooks.yaml
S128Django: introducing django-mcpz, for making MCP serversAdam Johnsonadamj.eu/tech/2026/09/15/introducing-django-mcpz/2026-09-152026-10-01полный текстразделы 9, 10, 11: MCP-сервер в синхронном WSGI-представлении, отзываемые bearer-токены
S129vintasoftware/django-ai-pluginsVinta Softwaregithub.com/vintasoftware/django-ai-pluginsбез даты2026-10-01полный текстраздел 10: навыки django-expert, django-celery-expert, cdrf-expert, django-safe-migration, django-reviewer; MIT
S130Teaching AI agents to write Django like senior developersRaí Siqueira, Vinta Softwarevintasoftware.com/blog/teaching-ai-agents-to-write-django…2026-02-192026-10-01полный текстразделы 10, 12: навыки для агентов, без количественной оценки
S131Django (web framework)Wikipediaen.wikipedia.org/wiki/Django_(web_framework)без даты2026-10-01полный текстраздел 11: 2003 Lawrence Journal-World, релиз 2005, DSF 2008, ASGI в 3.0, async-представления в 3.1
S132Django REST framework (главная)Encode OSS Ltddjango-rest-framework.org/без даты2026-10-01полный текстраздел 11: copyright с 2011, Python 3.10–3.15, Django 5.2–6.1
S133Django Enhancement Proposal 14: Background WorkersDjango Software Foundationdjangoproject.com/weblog/2024/may/29/django-enhancement-p…2024-05-292026-10-01полный текстраздел 11: DEP 14 принят, автор Jake Howard, референс django-tasks

Словарь терминов

acks_late позднее подтверждение
режим Celery, при котором воркер подтверждает задачу после выполнения; безопасен только для идемпотентных задач.
Active Record / Data Mapper активная запись / преобразователь данных
два стиля ORM; в Django модель сама сохраняет себя, поэтому слои в стиле Data Mapper ложатся на неё плохо.
AGENTS.md файл правил для агентов
открытый формат Markdown-инструкций для ИИ-агентов в корне репозитория и вложенных каталогах.
ASGI / WSGI асинхронный и синхронный интерфейс сервера
протоколы между сервером приложений и Django; ASGI нужен для долгих соединений.
BOLA / IDOR нарушение авторизации на уровне объекта / небезопасная прямая ссылка на объект
доступ к чужому объекту подстановкой ID; первый риск OWASP API Top 10 2023.
Bus factor фактор автобуса
число людей, без которых проект останавливается.
CONN_MAX_AGE время жизни соединения
настройка Django, сколько секунд держать соединение с базой между запросами.
CONCURRENTLY параллельно
режим создания и удаления индекса PostgreSQL без блокировки записи; не работает внутри транзакции.
Connection pool пул соединений
набор открытых соединений, которые переиспользуются; в Django 5.1+ — на процесс через psycopg 3.
Cursor (keyset) pagination курсорная пагинация
постраничный вывод по значению упорядоченного уникального поля вместо смещения.
DB_CASCADE каскад в базе
опция on_delete Django 6.1, при которой удаление выполняет PostgreSQL через ON DELETE CASCADE, без сигналов.
db_default значение по умолчанию в базе
значение поля, вычисляемое базой; безопасно при выкладке миграций.
DEP Django Enhancement Proposal, предложение по улучшению Django
формальный документ изменения процесса или функциональности Django.
django.tasks фреймворк задач Django
API для объявления и постановки фоновых задач с Django 6.0, без воркера в ядре.
EAFP проще попросить прощения, чем разрешения
подход «попробовать вставку и обработать IntegrityError» вместо предварительной проверки.
Expand/contract расширить/сжать
схема изменения базы в несколько выкладок: добавить новое, перевести код, удалить старое.
Fetch modes: FETCH_ONE, FETCH_PEERS, FETCH_RAISE режимы догрузки полей
настройки Django 6.1 для поведения при обращении к незагруженному полю: по одному объекту, пачкой для всех объектов выборки или исключение.
Feature flag фича-флаг
переключатель функциональности без перевыкладки.
FSL Functional Source License
лицензия Sentry, ограничивающая конкурирующее коммерческое использование и переходящая в Apache 2.0 через два года.
GeneratedField вычисляемое поле
колонка, значение которой вычисляет база по выражению.
GeoDjango / PostGIS геоподсистема Django / георасширение PostgreSQL
поля и запросы по геометрии; geography=True включает индексируемые расстояния в WGS84.
GIN обобщённый инвертированный индекс
тип индекса PostgreSQL для полнотекстового поиска и массивов.
GlitchTip трекер ошибок
self-hosted система, принимающая данные клиентских SDK Sentry.
Health check: liveness / readiness проверка живости / готовности
эндпоинты для перезапуска процесса и для снятия его с балансировки.
Idempotency-Key ключ идемпотентности
заголовок запроса, по которому сервер распознаёт повтор и возвращает сохранённый результат.
Import Linter / tach линтеры импортов
инструменты проверки архитектурных контрактов между модулями Python в CI.
JWT JSON Web Token
подписанный токен, проверяемый без обращения к базе; отзыв требует дополнительного состояния.
Materialized view материализованное представление
сохранённый результат запроса PostgreSQL, обновляемый REFRESH.
MCP Model Context Protocol, протокол контекста модели
протокол, через который ИИ-ассистенты вызывают инструменты приложения.
Modular monolith модульный монолит
один деплой с машинно проверяемыми границами между доменными модулями.
Multi-tenancy мультиарендность
обслуживание нескольких компаний одной системой с разделением данных.
N+1 проблема N+1 запросов
один запрос за списком и по одному запросу на каждый элемент при обращении к связанным данным.
OpenAPI спецификация HTTP API
машиночитаемое описание эндпоинтов, схем и ошибок.
Outbox исходящий ящик
таблица событий, записываемых в той же транзакции, что и данные, и доставляемых отдельным процессом.
pg_stat_statements статистика запросов
расширение PostgreSQL с агрегированной статистикой выполнения запросов.
PgBouncer transaction mode режим пула по транзакциям
внешний пулер, отдающий соединение на время транзакции; несовместим с server-side cursors между транзакциями.
Pre-fork предварительное ветвление
модель сервера, где мастер-процесс порождает рабочие процессы, разделяющие память через copy-on-write.
Problem Details (RFC 9457) детали проблемы
стандартный JSON-формат ошибок HTTP API application/problem+json.
Property-based testing тестирование свойствами
генерация множества входных данных по схеме для поиска ошибок; так работает Schemathesis.
QuerySet / Manager набор запроса / менеджер
ленивое описание SQL-запроса и точка входа к нему в модели Django; место для методов выборки.
Read replica реплика чтения
копия базы для чтения; отстаёт от основной на время репликации.
RLS Row Level Security, построчная безопасность
политики PostgreSQL, ограничивающие видимые строки; владелец таблицы обходит их без FORCE.
Schema-per-tenant схема на арендатора
отдельная схема PostgreSQL для каждой компании.
Semantic conventions семантические соглашения
стандартные имена атрибутов OpenTelemetry для HTTP, баз данных и других областей.
Serializer / Schema сериализатор / схема
объект DRF или Pydantic, проверяющий вход и формирующий выход API.
Server-side cursor серверный курсор
курсор PostgreSQL для потокового чтения, используемый QuerySet.iterator().
Service layer / selectors сервисный слой / селекторы
функции записи и чтения вне моделей и представлений по руководству HackSoft.
Silo изолированный сегмент
у Sentry — режим монолита, где контрольные данные и данные регионов разделены и общаются через RPC и outbox.
SSE Server-Sent Events, события от сервера
однонаправленный поток событий по HTTP от сервера к клиенту.
Throttling / rate limiting ограничение частоты
ограничение числа запросов клиента за интервал.
Tombstone надгробие
запись об удалении, по которой клиенты или другие регионы узнают, что объект удалён.
Visibility timeout тайм-аут видимости
время, после которого неподтверждённая задача в Redis-брокере выдаётся другому воркеру.
YAGNI вам это не понадобится
принцип не строить абстракции до появления потребности.
Оверинжиниринг / недоинжиниринг избыточное / недостаточное проектирование
практика, не двигающая метрики проекта при ненулевой цене, либо отсутствие практики, без которой метрики деградируют.