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 |
Механизм: путь запроса
- Сервер приложений принимает соединение и передаёт его Django через WSGI или ASGI. Django документирует ASGI-серверы Daphne, Granian, Hypercorn и Uvicorn факт [S8].
- Запрос проходит цепочку middleware, затем URL-резолвер выбирает представление.
- API-слой выполняет аутентификацию, проверку прав, ограничение частоты и разбор тела. В DRF это классы authentication, permission и throttle, в Django Ninja — параметры операции и схемы Pydantic факт [S9, S10].
- Доменный код читает и меняет данные через ORM внутри транзакции.
- Ответ сериализуется в JSON.
- После фиксации транзакции срабатывают хуки
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] | Удобство против прозрачности |
Главные споры
- Где живёт бизнес-логика и сколько слоёв нужно.
- DRF или Django Ninja для нового проекта.
- Нужен ли ASGI и async-код API-серверу без долгих соединений.
- Celery, более простая очередь или
django.tasksс бэкендом. - Сессии, непрозрачные токены или JWT.
- Мультиарендность общей базой, схемами или отдельными базами.
- Насколько строгая типизация окупается в 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].
- Минусы: своя библиотека, которую поддерживает команда.
Философии знаковых проектов и людей
| Кто | Подтверждение | Логика и слои | Тесты | Типы | Фоновые задачи | Наблюдаемость и эксплуатация | Обновления | Сознательно избегают |
|---|---|---|---|---|---|---|---|---|
| «Один из крупнейших деплоев 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), которые добавляются только после пересечения порога. Пороги без ссылки на источник — ориентиры автора, их стоит калибровать на своих метриках гипотеза.
Порядок внедрения
- Зафиксировать версии: Python 3.12+, Django 5.2 LTS или 6.1, lock-файл зависимостей (Б01).
- Создать скелет проекта и настройки из раздела 6, прогнать
manage.py check --deployс боевыми настройками (Б02, Б15). - До первой фичи включить проверки CI: форматер и линтер, проверку типов в мягком режиме,
makemigrations --check, линтер миграций, тесты с подсчётом запросов, сверку OpenAPI (Б04, Б07, Б09, Б16, Б17). - Описать модели с ограничениями в базе и scoped-менеджерами арендатора (Б08, Б13).
- Написать API с явными схемами, общей пагинацией и единым форматом ошибок (Б03, Б05, Б06).
- Подключить минимум наблюдаемости: ошибки, JSON-логи с
request_id, health-эндпоинты (Б12). - Добавить фоновые задачи с постановкой после фиксации транзакции (Б11).
- Выкладывать миграции по схеме expand/contract (Б09).
- Всё остальное — только по сигналам из карточек Р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; RuffDJ007ловит__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; навык Sentrydjango-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 |
Типичные ошибки первого применения
- Задача ставится внутри транзакции без
on_commitи не находит объект факт [S12]. - Список без пагинации и без проверки числа запросов.
fields = "__all__"в сериализаторе открывает внутренние поля.- Добавление
NOT NULL-поля без значения по умолчанию в одной выкладке с кодом. - Фильтрация по компании только в списке, но не в detail и вложенных действиях.
- ASGI «потому что быстрее», при этом весь код синхронный.
- Ошибки на почту и логи без
request_id. - JWT с долгим сроком жизни и без отзыва для собственного мобильного клиента.
- Аудит на сигналах в проекте, где импорт идёт через
bulk_createфакт [S112]. 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 и удаляется из чек-листа.
- Новый эндпоинт ограничивает
QuerySetкомпанией или пользователем; есть тест «чужой объект = 404». - Схема ввода перечисляет поля явно; схема вывода не раскрывает внутренние поля.
- Список пагинирован, сортировка по белому списку, есть тест числа запросов.
- Сценарий из нескольких моделей — в одной доменной функции под
transaction.atomic. - Задачи ставятся после фиксации, получают ID, идемпотентны.
- Миграция совместима со старым кодом: nullable или
db_default, без переименований и удалений в той же выкладке. - Внешние вызовы с таймаутом и обработкой ошибок.
- Нет новых слоёв, абстракций и зависимостей без сигнала из карточек Р.
- Изменение OpenAPI ожидаемо и обратно совместимо.
- Логи несут контекст (
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].
Что читать
- [S13] Databases — единственный точный источник правил соединений, пула и PgBouncer.
- [S33] Asynchronous support — когда async даёт выгоду и почему транзакции остаются синхронными.
- [S40] Fetch modes — новый способ гасить N+1 в Django 6.1.
- [S50] Against service layers — сильнейший аргумент против слоёв ради слоёв.
- [S48] Django Styleguide — противоположная позиция с конкретными шаблонами.
- [S51] Thin views — середина между двумя позициями.
- [S3] Kraken monolith — как держать 400 разработчиков в одном коде с Import Linter.
- [S49] Kraken conventions — проверенные масштабом запреты.
- [S5] PostHog architecture — фасады, контракты и счётчики «только вниз».
- [S66] Sentry migrations — правила миграций без простоя.
- [S4] Sentry multi-region — регионы внутри монолита и симуляция в CI.
- [S47] Zulip API docs — OpenAPI как проверяемый источник истины.
- [S76] Concurrency without locks — атомарные операции вместо блокировок.
- [S36] Fast load into PostgreSQL — измерения массовой загрузки.
- [S12] Celery tasks guide — идемпотентность,
acks_late, транзакции. - [S53] Tasks without a worker — трезвая критика
django.tasks. - [S54] JWT tokens in allauth — почему JWT не stateless.
- [S91] OWASP API Top 10 2023 — модель угроз API.
- [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 | Публикация | Доступ (дата) | Вид доступа | Что подтверждает |
|---|---|---|---|---|---|---|---|
| S1 | Download / Supported versions | Django Software Foundation | djangoproject.com/download/ | без даты | 2026-10-01 | полный текст | разделы 0, 1, 3, 5, 8, 12: сроки поддержки 5.2 LTS, 6.0, 6.1, 6.2 LTS, Django 2028 |
| S2 | Django 6.1 release notes | Django Software Foundation | docs.djangoproject.com/en/6.1/releases/6.1/ | 2026-08-05 | 2026-10-01 | полный текст | разделы 0, 1, 2, 3, 5, 7, 10, 11: fetch modes, DB_CASCADE без сигналов, MAILERS, UUID7, PostgreSQL 15+, устаревание select_related() без аргументов |
| S3 | Kraken Technologies: How we organise our very large Python monolith | David Seddon, EuroPython blog | blog.europython.eu/kraken-technologies-how-we-organize-ou… | 2023-07-11 | 2026-10-01 | полный текст | разделы 0, 1, 2, 3, 4, 5, 8, 11: 27 637 модулей, 400 разработчиков, 17 компаний, слои, 40+ контрактов Import Linter, 15 игнорируемых импортов |
| S4 | Removing risk from our multi-region design with simulations | Sentry | blog.sentry.io/removing-risk-from-our-multiregion-design-… | 2024-05 | 2026-10-01 | полный текст | разделы 0, 3, 4, 5, 7, 11, 12: silo внутри монолита, симуляция границ в CI, 35 000 тестов в двух режимах |
| S5 | products/architecture.md | PostHog | github.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 |
| S6 | Zulip architectural overview | Zulip project | zulip.readthedocs.io/en/latest/overview/architecture-over… | без даты | 2026-10-01 | полный текст | разделы 0, 1, 3, 4, 5, 12: Django + Tornado для push, RabbitMQ-очереди, Redis для rate limit |
| S7 | How the Cinder JIT's function inliner helps us optimize Instagram | Meta Engineering | engineering.fb.com/2022/05/02/open-source/cinder-jits-ins… | 2022-05-02 | 2026-10-01 | полный текст | разделы 0, 2, 3, 4, 12: «one of the world's largest deployments of Django» (вендор) |
| S8 | How to deploy with ASGI | Django Software Foundation | docs.djangoproject.com/en/6.1/howto/deployment/asgi/ | без даты | 2026-10-01 | полный текст | разделы 1, 9: Daphne, Granian, Hypercorn, Uvicorn |
| S9 | Authentication — DRF API guide | Encode / DRF | django-rest-framework.org/api-guide/authentication/ | без даты | 2026-10-01 | полный текст | разделы 1, 4, 5, 9: сессии для SPA, TokenAuthentication без срока жизни, Knox, Django OAuth Toolkit |
| S10 | Motivation — Django Ninja | Vitaliy Kucheryaviy | django-ninja.dev/motivation/ | без даты | 2026-10-01 | полный текст | разделы 1, 3, 4, 5, 9, 11: мотивация автора, интеграция с ORM и auth, несколько версий API, без бенчмарков |
| S11 | Django's Tasks framework (topic guide) | Django Software Foundation | docs.djangoproject.com/en/6.1/topics/tasks/ | без даты | 2026-10-01 | полный текст | разделы 1, 4, 5: ImmediateBackend/DummyBackend только для разработки, on_commit для постановки |
| S12 | Tasks — Celery user guide | Celery project | docs.celeryq.dev/en/stable/userguide/tasks.html | без даты | 2026-10-01 | полный текст | разделы 1, 3, 4, 5, 7, 8, 9, 11: идемпотентность, acks_late, delay_on_commit, передача ID, ретраи |
| S13 | Databases (ref) | Django Software Foundation | docs.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 |
| S14 | Django 5.1 release notes | Django Software Foundation | docs.djangoproject.com/en/6.1/releases/5.1/ | 2024-08-07 | 2026-10-01 | полный текст | разделы 1, 2, 3, 11: пул соединений PostgreSQL, LoginRequiredMiddleware |
| S15 | Django 6.0 release notes | Django Software Foundation | docs.djangoproject.com/en/6.0/releases/6.0/ | 2025-12-03 | 2026-10-01 | полный текст | разделы 1, 2, 3, 11: django.tasks без воркера, CSP, BigAutoField по умолчанию, AsyncPaginator, Python 3.12+ |
| S16 | Django 5.2 release notes | Django Software Foundation | docs.djangoproject.com/en/6.1/releases/5.2/ | 2025-04-02 | 2026-10-01 | полный текст | разделы 1, 2: LTS, CompositePrimaryKey, async-методы auth |
| S17 | Django is moving to an annual release cycle | Django Software Foundation | djangoproject.com/weblog/2026/aug/10/annual-release-cycle/ | 2026-08-10 | 2026-10-01 | полный текст | разделы 1, 2, 3, 11: DEP 20, годовой цикл с 2028, три года поддержки каждой версии |
| S18 | Release Notes — Django REST framework | Encode / DRF | django-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 |
| S19 | django-ninja (PyPI) | Vitaliy Kucheryaviy, PyPI | pypi.org/project/django-ninja/ | 2026-09-19 | 2026-10-01 | полный текст | разделы 1, 2, 4, 9, 12: история версий 1.4–1.7.1, десять релизов с ноября 2025 |
| S20 | Change history — Celery 5.6.3 | Celery project | docs.celeryq.dev/en/stable/changelog.html | 2026-03-26 | 2026-10-01 | полный текст | разделы 1, 2, 9, 12: Celery 5.5–5.6, soft shutdown, quorum queues, лимит ETA-задач, даты релизов |
| S21 | Gunicorn 2026 news | Gunicorn | gunicorn.org/2026-news/ | 2026-09-06 | 2026-10-01 | полный текст | разделы 1, 2, 4, 9: ASGI-воркер стабилен с 25.1.0, eventlet удалён в 26.0 |
| S22 | django-stubs README | TypedDjango | github.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 базово |
| S23 | Bump djangorestframework from 3.18.0 to 3.18.1 (#25437) | mozilla/addons-server | github.com/mozilla/addons-server/pull/25437 | 2026-09-23 | 2026-10-01 | полный текст | разделы 1, 4, 5: addons-server на DRF, обновления через Dependabot |
| S24 | Writing views in Zulip | Zulip project | zulip.readthedocs.io/en/latest/tutorials/writing-views.html | без даты | 2026-10-01 | полный текст | разделы 1, 4, 10: typed_endpoint на Pydantic v2 |
| S25 | Saleor webhooks overview | Saleor | docs.saleor.io/developer/extending/webhooks/overview | без даты | 2026-10-01 | полный текст | разделы 1, 5: sync/async вебхуки, HMAC, таймаут 20 с, payload через GraphQL-подписки |
| S26 | GraphQL API — NetBox | NetBox Labs | netboxlabs.com/docs/netbox/en/stable/integrations/graphql… | без даты | 2026-10-01 | полный текст | разделы 1, 4: read-only GraphQL на Strawberry Django в дополнение к REST |
| S27 | The State of Django 2026: Boring is so back | Will Vincent, JetBrains | blog.jetbrains.com/pycharm/2026/08/the-state-of-django-20… | 2026-08 | 2026-10-01 | полный текст | разделы 2, 3, 5, 10: ~3500 ответов, API-only 53 %, PostgreSQL 76–79 %, Claude Code 35 %, Ruff 43 %, нет тестов 19 % (эмпирика) |
| S28 | Django Developers Survey 2026 Results | JetBrains, DSF | lp.jetbrains.com/django-developer-survey-2026/ | 2026-08 | 2026-10-01 | полный текст | разделы 2, 4, 5, 8, 11, 12: DRF 73 %, Ninja 17 %, Redis 53 %, async 33 %, версии Django (эмпирика) |
| S29 | The State of Django 2025 | Will Vincent, JetBrains | blog.jetbrains.com/pycharm/2025/10/the-state-of-django-2025/ | 2025-10 | 2026-10-01 | полный текст | раздел 2: более 4600 ответов, DRF 49 %, Celery 26 % (эмпирика) |
| S30 | Contributing to REST framework | Encode / DRF | django-rest-framework.org/community/contributing/ | без даты | 2026-10-01 | полный текст | разделы 2, 3, 4, 9: DRF «feature-complete», новые функции не принимаются |
| S31 | Moving REST framework forward (#9270) | encode/django-rest-framework | github.com/encode/django-rest-framework/discussions/9270 | 2024-03-05 | 2026-10-01 | полный текст | разделы 2, 4, 11: PR только для поддержки Django, безопасности, документации |
| S32 | Should I continue using Ninja? (#1197) | vitalik/django-ninja | github.com/vitalik/django-ninja/discussions/1197 | 2024-08-10 | 2026-10-01 | полный текст | разделы 2, 3, 4, 9, 11: bus factor, обязательства поддержки по графику LTS, issues с 2020 года |
| S33 | Asynchronous support | Django Software Foundation | docs.djangoproject.com/en/6.1/topics/async/ | без даты | 2026-10-01 | полный текст | разделы 2, 3, 4, 5, 7, 8, 11: async ORM, транзакции не работают в async, цена переключений, выгода для долгих соединений |
| S34 | Working with async Django: lessons learned | Frederike Jaeger, Kraken | engineering.kraken.tech/news/2026/01/12/using-django-asyn… | 2026-01-12 | 2026-10-01 | полный текст | разделы 2, 3, 5, 7, 8: async для параллельных LLM-вызовов, сложности тестов и транзакций, CONN_MAX_AGE = 0 |
| S35 | Add celery backend based on django 6 tasks (#10062) | celery/celery | github.com/celery/celery/issues/10062 | 2026-01-11 | 2026-10-01 | полный текст | разделы 2, 9, 12: официального бэкенда Celery для django.tasks нет, запрос открыт |
| S36 | Fastest Way to Load Data Into PostgreSQL Using Python | Haki Benita | hakibenita.com/fast-load-data-python-postgresql | 2019-07-09 | 2026-10-01 | полный текст | разделы 2, 4, 5, 11: 32 500 строк — 128,8 с поштучно против 0,46 с COPY (эмпирика) |
| S37 | Optimizing the Django Admin Paginator | Haki Benita | hakibenita.com/optimizing-the-django-admin-paginator | 2018-11-06 | 2026-10-01 | полный текст | разделы 2, 4, 5, 8, 11: COUNT 781 мс из 786 мс, таймаут 200 мс на count (эмпирика) |
| S38 | migrate_schemas scans the whole catalog ~4× per tenant (#1269) | django-tenants, GitHub | github.com/django-tenants/django-tenants/issues/1269 | 2026-09-29 | 2026-10-01 | полный текст | разделы 2, 4, 5, 9: ~1780 схем, 5–14 с CPU базы на арендатора при пустой миграции |
| S39 | django-zeal README | Tao Bojlén | github.com/taobojlen/django-zeal | без даты | 2026-10-01 | полный текст | разделы 2, 5, 8, 9: детекция N+1 в тестах, накладные расходы 3–5 % (вендор), nplusone заброшен (мнение) |
| S40 | Fetch modes | Django Software Foundation | docs.djangoproject.com/en/6.1/topics/db/fetch-modes/ | без даты | 2026-10-01 | полный текст | разделы 2, 3, 5, 11: FETCH_PEERS, FETCH_RAISE, менеджер по умолчанию |
| S41 | Cut Django Database Latency by 50-70ms With Native Connection Pooling | Saurabh Kumar | saurabh-kumar.com/articles/2025/06/cut-django-database-la… | 2025-06-18 | 2026-10-01 | полный текст | разделы 2, 12: единичный замер пула psycopg на managed PostgreSQL без методики |
| S42 | Introducing Immortal Objects for Python | Eddie Elizondo, Meta Engineering | engineering.fb.com/2023/08/15/developer-tools/immortal-ob… | 2023-08-15 | 2026-10-01 | полный текст | разделы 2, 3, 4, 12: Instagram на Django, pre-fork, copy-on-write, регрессия ~2 % |
| S43 | Healthchecks.io Blog, page 6 (2016–2017) | Pēteris Caune | blog.healthchecks.io/page/6/ | без даты | 2026-10-01 | фрагмент | разделы 2, 3, 4, 5, 12: вынос ping handler в Go из-за CPU Python через ~6 месяцев после запуска |
| S44 | How we ship over 100 versions a day to over 25 environments | James S, Kraken | engineering.kraken.tech/news/2025/02/07/how-we-ship.html | 2025-02-07 | 2026-10-01 | полный текст | разделы 2, 3, 4, 5, 7, 8: ~9 млн строк, 100+ версий в день, 100 000+ тестов менее 30 мин, фича-флаги, совместимые миграции |
| S45 | Static typing Python at scale — Our journey with mypy and Django | Stephen Moore, Kraken | engineering.kraken.tech/news/2026/02/16/static-typing-pyt… | 2026-02-16 | 2026-10-01 | полный текст | разделы 2, 3, 4, 5, 8, 10: 5 млн строк под mypy, 2000+ моделей, 2,5 года, 5000 ignore, django-consistency-enforcer |
| S46 | Backend Django tests | Zulip project | zulip.readthedocs.io/en/latest/testing/testing-with-djang… | без даты | 2026-10-01 | полный текст | разделы 2, 3, 4, 5, 8, 10: менее 30 с параллельно, assert_database_query_count, 100 % покрытия нового кода |
| S47 | Documenting REST API endpoints | Zulip project | zulip.readthedocs.io/en/latest/documentation/api.html | без даты | 2026-10-01 | полный текст | разделы 2, 4, 5, 11: каждый ответ в тестах сверяется с OpenAPI |
| S48 | Django Styleguide | HackSoft | github.com/HackSoftware/Django-Styleguide | без даты | 2026-10-01 | полный текст | разделы 2, 4, 5, 8, 11, 12: services/selectors, Input/OutputSerializer, on_commit, factory_boy, «не единственный путь» (мнение) |
| S49 | octoenergy public-conventions: django.md | Kraken Technologies | raw.githubusercontent.com/octoenergy/public-conventions/m… | без даты | 2026-10-01 | полный текст | разделы 2, 4, 5, 8, 11: один вызов домена из интерфейса, без implicit ordering, ограничения в базе, save() только в мутаторах |
| S50 | Against service layers in Django | James Bennett | b-list.org/weblog/2020/mar/16/no-service/ | 2020-03-16 | 2026-10-01 | полный текст | разделы 2, 4, 5, 8, 11: логика в моделях, менеджерах и QuerySet; YAGNI (мнение) |
| S51 | Django Views — The Right Way: Thin views | Luke Plant | spookylukey.github.io/django-views-the-right-way/thin-vie… | без даты | 2026-10-01 | полный текст | разделы 2, 4, 5, 8, 11: логика в методах моделей и QuerySet, без отдельного service layer (мнение) |
| S52 | Using Django Tasks in production | Tim Schilling, Better Simple | better-simple.com/django/2026/05/06/using-django-tasks-in… | 2026-05-06 | 2026-10-01 | полный текст | разделы 2, 4, 5, 9, 12: django-tasks-db + db_worker на малом VPS |
| S53 | Django 6.0 Tasks: a framework without a worker | Kevin Renskers, Loopwerk | loopwerk.io/articles/2026/django-tasks-review/ | 2026-01-19 | 2026-10-01 | полный текст | разделы 2, 4, 5, 11: критика django.tasks — нет воркера, ретраев, расписания (мнение) |
| S54 | JWT Tokens — django-allauth headless | django-allauth | docs.allauth.org/en/dev/headless/token-strategies/jwt-tok… | без даты | 2026-10-01 | полный текст | разделы 2, 4, 5, 7, 9, 11: JWT не stateless при отзыве; польза для нескольких сервисов |
| S55 | Test factory functions in Django | Luke Plant | lukeplant.me.uk/blog/posts/test-factory-functions-in-django/ | 2022-11-25 | 2026-10-01 | полный текст | разделы 2, 4, 5, 11, 12: фабрики-функции вместо factory_boy (мнение) |
| S56 | Django 5.0 release notes | Django Software Foundation | docs.djangoproject.com/en/6.1/releases/5.0/ | 2023-12-04 | 2026-10-01 | полный текст | разделы 2, 3, 11: db_default, GeneratedField |
| S57 | Releases · vitalik/django-ninja | Vitaliy Kucheryaviy | github.com/vitalik/django-ninja/releases | без даты | 2026-10-01 | фрагмент | разделы 2, 4, 5, 9: состав релизов 1.6–1.7 — cursor pagination, Retry-After, стриминг JSONL и SSE |
| S58 | Should I use the newly stable asgi workers for a Django ASGI server? (#3524) | benoitc/gunicorn | github.com/benoitc/gunicorn/discussions/3524 | 2026-02-20 | 2026-10-01 | полный текст | разделы 2, 4, 7, 12: ASGI-воркер обрабатывает не все исключения парсера |
| S59 | Django: fixing a memory "leak" from Python 3.14's incremental garbage collection | Adam Johnson | adamj.eu/tech/2026/04/20/django-python-3.14-incremental-gc/ | 2026-04-20 | 2026-10-01 | полный текст | разделы 2, 4, 5, 7: OOM migrate на Python 3.14, gc.collect() после миграций, откат incremental GC в 3.14.5 |
| S60 | opentelemetry-python-contrib README | OpenTelemetry | github.com/open-telemetry/opentelemetry-python-contrib | без даты | 2026-10-01 | фрагмент | раздел 2: миграция HTTP-инструментаций на стабильные semantic conventions |
| S61 | Document OTEL_SEMCONV_STABILITY_OPT_IN (#4202) | open-telemetry/opentelemetry-python-contrib | github.com/open-telemetry/opentelemetry-python-contrib/is… | 2026-02-13 | 2026-10-01 | полный текст | раздел 2: значения http и http/dup, по умолчанию старые атрибуты |
| S62 | AGENTS.md | Agentic AI Foundation | agents.md/ | без даты | 2026-10-01 | полный текст | разделы 2, 6, 10: формат, ближайший файл приоритетен, поддержка основными агентами |
| S63 | GeoDjango Installation | Django Software Foundation | docs.djangoproject.com/en/6.1/ref/contrib/gis/install/ | без даты | 2026-10-01 | полный текст | разделы 3, 5: PostGIS рекомендован, PostgreSQL 15+ |
| S64 | django/channels README | Django project | github.com/django/channels | без даты | 2026-10-01 | полный текст | разделы 3, 5, 9, 11: сопровождение best-effort под руководством Карлтона Гибсона, гарантированно только безопасность |
| S65 | django-pg-zero-downtime-migrations | tbicr (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, статус бета |
| S66 | Database Migrations — Sentry Developer Documentation | Sentry | develop.sentry.dev/backend/application-domains/database-m… | без даты | 2026-10-01 | полный текст | разделы 3, 4, 5, 8, 11: post-deploy миграции для индексов дольше 10 с, двухфазное удаление, db_default, db_column |
| S67 | Kraken Engineering Blog (главная) | Kraken Technologies | engineering.kraken.tech/ | без даты | 2026-10-01 | фрагмент | разделы 4, 5: Celery + RabbitMQ (обновление без поломки ETA-задач, 2026-01-09) |
| S68 | Django, Kubernetes Health Checks and Continuous Delivery | Federico Marani, Kraken | engineering.kraken.tech/news/2026/02/11/django-kubernetes… | 2026-02-11 | 2026-10-01 | полный текст | разделы 4, 5: один /health/ для трёх проб, миграции через pre-upgrade hook |
| S69 | Cross Region Replication | Sentry | develop.sentry.dev/application-architecture/multi-region-… | без даты | 2026-10-01 | полный текст | разделы 4, 5, 7: outbox в той же транзакции, tombstones, HybridCloudForeignKey |
| S70 | About — Healthchecks.io | Pēteris Caune | healthchecks.io/about/ | без даты | 2026-10-01 | полный текст | раздел 4: один человек с июля 2015, BSD, доступность выше 99,9 % (вендор) |
| S71 | A Look at Healthchecks.io Hosting Setup, Summer 2019 | Pēteris Caune | blog.healthchecks.io/2019/08/a-look-at-healthchecks-io-ho… | 2019-08 | 2026-10-01 | полный текст | разделы 4, 5, 11: без контейнеров и очередей, sendalerts/sendreports как systemd-сервисы, ~€274 в месяц |
| S72 | NetBox installation | NetBox Labs | netboxlabs.com/docs/netbox/en/stable/installation/ | без даты | 2026-10-01 | полный текст | раздел 4: Python 3.12+, PostgreSQL 15+, Redis, rqworker |
| S73 | REST API — NetBox | NetBox Labs | netboxlabs.com/docs/netbox/en/stable/integrations/rest-api/ | без даты | 2026-10-01 | полный текст | разделы 4, 5: MAX_PAGE_SIZE 1000, brief-режим, токены v2 с хешем и pepper |
| S74 | django-linear-migrations | Adam Johnson | github.com/adamchainz/django-linear-migrations | без даты | 2026-10-01 | полный текст | разделы 4, 5, 9, 11: max_migration.txt, rebase_migration |
| S75 | Django: introducing django-orjson | Adam Johnson | adamj.eu/tech/2026/07/15/introducing-django-orjson/ | 2026-07-15 | 2026-10-01 | полный текст | разделы 4, 5, 9, 11: замена JSON-компонентов Django и DRF на orjson (вендор) |
| S76 | Handling Concurrency Without Locks | Haki Benita | hakibenita.com/django-concurrency | 2022-06-09 | 2026-10-01 | полный текст | разделы 4, 5, 11: EAFP, F-выражения, UPDATE … RETURNING, select_for_update (мнение) |
| S77 | Two Scoops of Django 3.x | Daniel и Audrey Feldroy | feldroy.com/two-scoops-of-django | 2021-02 | 2026-10-01 | аннотация | разделы 4, 12: книга закрыта, издание под Django 3.x, не прочитана |
| S78 | Pagination — DRF API guide | Encode / DRF | django-rest-framework.org/api-guide/pagination/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 6: CursorPagination — уникальное неизменное поле с индексом, фиксированное время |
| S79 | Throttling — DRF API guide | Encode / DRF | django-rest-framework.org/api-guide/throttling/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 9: throttling не мера безопасности, гонки, NUM_PROXIES |
| S80 | Procrastinate documentation | Procrastinate | procrastinate.readthedocs.io/en/stable/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 9: очередь на PostgreSQL, транзакционная постановка, periodic, блокировки |
| S81 | drf-spectacular README | T. Franzel | drf-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 сознательно |
| S82 | drf-yasg README | axnsan12 | github.com/axnsan12/drf-yasg | без даты | 2026-10-01 | полный текст | разделы 4, 7, 9, 10: только OpenAPI 2.0, рекомендует drf-spectacular |
| S83 | Sentry Django integration | Sentry | docs.sentry.io/platforms/python/integrations/django/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 7, 8, 9, 10: автоспаны middleware, SQL, кэша; traces_sample_rate; флаги uWSGI (вендор) |
| S84 | Self-Hosted Sentry | Sentry | develop.sentry.dev/self-hosted/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 8, 9: 4 CPU, 16 GB RAM + 16 GB swap, лицензия FSL |
| S85 | GlitchTip (главная) | Burke Software and Consulting | glitchtip.com/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 9: совместимость с клиентскими SDK Sentry, uptime, логи (вендор) |
| S86 | GlitchTip installation | Burke Software and Consulting | glitchtip.com/documentation/install | без даты | 2026-10-01 | полный текст | разделы 4, 5, 8, 9: 256–512 MB RAM, PostgreSQL 14+, Valkey опционально |
| S87 | OpenTelemetry Django Instrumentation | OpenTelemetry | opentelemetry-python-contrib.readthedocs.io/en/latest/ins… | без даты | 2026-10-01 | полный текст | разделы 4, 7, 9: DjangoInstrumentor, excluded URLs, sqlcommenter, response_hook |
| S88 | Multiprocess Mode — prometheus client_python | Prometheus | prometheus.github.io/client_python/multiprocess/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 7, 9: ограничения multiprocess-режима, очистка каталога |
| S89 | Row Security Policies | PostgreSQL Global Development Group | postgresql.org/docs/current/ddl-rowsecurity.html | без даты | 2026-10-01 | полный текст | разделы 4, 5, 7: владелец таблицы и BYPASSRLS обходят RLS, FORCE, default-deny |
| S90 | How to upgrade Django to a newer version | Django Software Foundation | docs.djangoproject.com/en/6.1/howto/upgrade-version/ | без даты | 2026-10-01 | полный текст | разделы 5, 8: по одной feature-версии, -Wa, сначала зависимости |
| S91 | OWASP API Security Top 10 — 2023 | OWASP | api-security.owasp.org/editions/2023/en/0x11-t10 | 2023 | 2026-10-01 | полный текст | разделы 5, 7, 10, 11: BOLA на первом месте, API3 Broken Object Property Level Authorization |
| S92 | Ruff rules: flake8-django (DJ) | Astral | docs.astral.sh/ruff/rules/#flake8-django-dj | без даты | 2026-10-01 | полный текст | разделы 5, 6, 9: правила DJ001–DJ013, набор S (bandit) |
| S93 | Schemathesis documentation | Schemathesis | schemathesis.readthedocs.io/en/stable/ | без даты | 2026-10-01 | полный текст | разделы 5, 7, 9: property-based тесты по OpenAPI |
| S94 | RFC 9457: Problem Details for HTTP APIs | IETF | rfc-editor.org/rfc/rfc9457.html | 2023-07 | 2026-10-01 | полный текст | раздел 5: application/problem+json, поля type/title/status/detail/instance, без стек-трейсов |
| S95 | Filtering — DRF API guide | Encode / DRF | django-rest-framework.org/api-guide/filtering/ | без даты | 2026-10-01 | полный текст | разделы 5, 9: DjangoFilterBackend, явный ordering_fields против утечки, фильтрация в get_queryset |
| S96 | Testing tools | Django Software Foundation | docs.djangoproject.com/en/6.1/topics/testing/tools/ | без даты | 2026-10-01 | полный текст | разделы 5, 7, 8: assertNumQueries, captureOnCommitCallbacks, TestCase быстрее TransactionTestCase |
| S97 | pg_stat_statements | PostgreSQL Global Development Group | postgresql.org/docs/current/pgstatstatements.html | без даты | 2026-10-01 | полный текст | разделы 5, 6, 7: статистика запросов, shared_preload_libraries |
| S98 | QuerySet API reference | Django Software Foundation | docs.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 |
| S99 | Durable database transactions in Django | David Winterbottom, Kraken | engineering.kraken.tech/news/2020/11/30/durable-transacti… | 2020-11-30 | 2026-10-01 | полный текст | разделы 5, 11: atomic(durable=True) в Django 3.2 |
| S100 | Squawk docs | Squawk | squawkhq.com/docs/ | без даты | 2026-10-01 | полный текст | разделы 5, 8, 9: правила линтера миграций PostgreSQL, GitHub Action |
| S101 | Deployment checklist | Django Software Foundation | docs.djangoproject.com/en/6.1/howto/deployment/checklist/ | без даты | 2026-10-01 | полный текст | раздел 5: check --deploy, SECRET_KEY_FALLBACKS, постоянные соединения, мониторинг ошибок вместо почты |
| S102 | Using Redis — Celery | Celery project | docs.celeryq.dev/en/stable/getting-started/backends-and-b… | без даты | 2026-10-01 | полный текст | разделы 5, 7, 9: visibility timeout 1 ч, повторы ETA-задач, noeviction |
| S103 | django-structlog documentation | django-structlog | django-structlog.readthedocs.io/en/latest/ | без даты | 2026-10-01 | полный текст | разделы 5, 9: request_id и user_id в каждой строке, JSON, DRF и Ninja |
| S104 | py-spy README | Ben Frederickson | github.com/benfred/py-spy | без даты | 2026-10-01 | полный текст | разделы 5, 9: сэмплирующий профайлер без перезапуска, CPython до 3.14 |
| S105 | getsentry/skills | Sentry | github.com/getsentry/skills | без даты | 2026-10-01 | полный текст | разделы 5, 10: навыки django-perf-review, django-access-review, agents-md |
| S106 | pytest-django: Database access | pytest-django | pytest-django.readthedocs.io/en/latest/database.html | без даты | 2026-10-01 | полный текст | разделы 5, 6, 9: --reuse-db, --nomigrations, суффиксы для xdist |
| S107 | Multiple databases | Django Software Foundation | docs.djangoproject.com/en/6.1/topics/db/multi-db/ | без даты | 2026-10-01 | полный текст | раздел 5: роутер primary/replica не решает лаг репликации |
| S108 | Django's cache framework | Django Software Foundation | docs.djangoproject.com/en/6.1/topics/cache/ | без даты | 2026-10-01 | полный текст | разделы 5, 7: RedisCache, cache_page не различает auth, LocMem на процесс |
| S109 | Performance and Scaling — django-pghistory 2.5.0 | AmbitionEng | django-pghistory.readthedocs.io/en/2.5.0/performance.html | без даты | 2026-10-01 | полный текст | разделы 5, 8, 9: триггеры без round trip, цена контекста, рост таблиц и партиционирование |
| S110 | Versioning — DRF API guide | Encode / DRF | django-rest-framework.org/api-guide/versioning/ | без даты | 2026-10-01 | полный текст | разделы 5, 12: схемы версионирования, Accept-заголовок как «лучшая практика», допустимость систем без версий |
| S111 | Import Linter documentation | Import Linter project | import-linter.readthedocs.io/en/stable/ | без даты | 2026-10-01 | полный текст | разделы 5, 9, 10: контракты layers, independence, forbidden, protected, acyclic siblings |
| S112 | Common Issues — django-simple-history | django-simple-history | django-simple-history.readthedocs.io/en/latest/common_iss… | без даты | 2026-10-01 | полный текст | разделы 5, 7, 8, 9: bulk-операции и update() не пишут историю |
| S113 | Uploading objects with presigned URLs | Amazon Web Services | docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUr… | без даты | 2026-10-01 | полный текст | раздел 5: загрузка без учётных данных, срок до 7 дней, перезапись ключа |
| S114 | django-storages: Amazon S3 | django-storages | django-storages.readthedocs.io/en/latest/backends/amazon-… | без даты | 2026-10-01 | полный текст | разделы 5, 9: подписанные URL 3600 с, file_overwrite=True по умолчанию, endpoint_url |
| S115 | Healthchecks.io Blog (главная) | Pēteris Caune | blog.healthchecks.io/ | без даты | 2026-10-01 | фрагмент | раздел 5: переход с managed-хранилища на self-hosted S3, bare metal |
| S116 | Pattern: Transactional outbox | Chris Richardson, microservices.io | microservices.io/patterns/data/transactional-outbox.html | без даты | 2026-10-01 | полный текст | разделы 5, 7: запись сообщения в той же транзакции, дубли, идемпотентный потребитель |
| S117 | Standard Webhooks | Standard Webhooks TSC | standardwebhooks.com/ | без даты | 2026-10-01 | полный текст | раздел 5: webhook-id/timestamp/signature, HMAC-SHA256, защита от replay и SSRF |
| S118 | REFRESH MATERIALIZED VIEW | PostgreSQL Global Development Group | postgresql.org/docs/current/sql-refreshmaterializedview.html | без даты | 2026-10-01 | полный текст | раздел 5: CONCURRENTLY требует уникальный индекс, один refresh за раз |
| S119 | Full text search (contrib.postgres) | Django Software Foundation | docs.djangoproject.com/en/6.1/ref/contrib/postgres/search/ | без даты | 2026-10-01 | полный текст | раздел 5: проблемы после «нескольких сотен записей» без индекса, GeneratedField + GIN, триграммы |
| S120 | Sync: Backend | WatermelonDB (Nozbe) | watermelondb.dev/docs/Sync/Backend | без даты | 2026-10-01 | полный текст | раздел 5: серверное время, tombstones, отказ push при конфликте, транзакционность |
| S121 | GeoDjango Database API | Django Software Foundation | docs.djangoproject.com/en/6.1/ref/contrib/gis/db-api/ | без даты | 2026-10-01 | полный текст | раздел 5: geography=True для дистанций в WGS84 с индексом |
| S122 | Request and response objects | Django Software Foundation | docs.djangoproject.com/en/6.1/ref/request-response/ | без даты | 2026-10-01 | полный текст | разделы 5, 7: StreamingHttpResponse занимает воркер под WSGI, async-итератор под ASGI |
| S123 | The Idempotency-Key HTTP Header Field, draft-07 | IETF httpapi WG | ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-he… | 2025-10-15 | 2026-10-01 | полный текст | раздел 5: 409 при параллельном повторе, 422 при другом теле, UUID, черновик истёк |
| S124 | django-waffle documentation | django-waffle | waffle.readthedocs.io/en/stable/ | без даты | 2026-10-01 | фрагмент | разделы 5, 9: flags, switches, samples; версия 5.0.0 |
| S125 | Repository and Documentation (SDK standards) | Sentry | develop.sentry.dev/sdk/getting-started/standards/reposito… | без даты | 2026-10-01 | полный текст | разделы 6, 10: обязательный AGENTS.md и его разделы |
| S126 | What is Locust? | Locust | docs.locust.io/en/stable/what-is-locust.html | без даты | 2026-10-01 | полный текст | раздел 9: сценарии на Python, headless-режим для CI, MIT |
| S127 | adamchainz/django-upgrade | Adam Johnson | github.com/adamchainz/django-upgrade | без даты | 2026-10-01 | фрагмент | разделы 9, 11, 12: «Automatically upgrade your Django projects»; в репозитории есть .pre-commit-hooks.yaml |
| S128 | Django: introducing django-mcpz, for making MCP servers | Adam Johnson | adamj.eu/tech/2026/09/15/introducing-django-mcpz/ | 2026-09-15 | 2026-10-01 | полный текст | разделы 9, 10, 11: MCP-сервер в синхронном WSGI-представлении, отзываемые bearer-токены |
| S129 | vintasoftware/django-ai-plugins | Vinta Software | github.com/vintasoftware/django-ai-plugins | без даты | 2026-10-01 | полный текст | раздел 10: навыки django-expert, django-celery-expert, cdrf-expert, django-safe-migration, django-reviewer; MIT |
| S130 | Teaching AI agents to write Django like senior developers | Raí Siqueira, Vinta Software | vintasoftware.com/blog/teaching-ai-agents-to-write-django… | 2026-02-19 | 2026-10-01 | полный текст | разделы 10, 12: навыки для агентов, без количественной оценки |
| S131 | Django (web framework) | Wikipedia | en.wikipedia.org/wiki/Django_(web_framework) | без даты | 2026-10-01 | полный текст | раздел 11: 2003 Lawrence Journal-World, релиз 2005, DSF 2008, ASGI в 3.0, async-представления в 3.1 |
| S132 | Django REST framework (главная) | Encode OSS Ltd | django-rest-framework.org/ | без даты | 2026-10-01 | полный текст | раздел 11: copyright с 2011, Python 3.10–3.15, Django 5.2–6.1 |
| S133 | Django Enhancement Proposal 14: Background Workers | Django Software Foundation | djangoproject.com/weblog/2024/may/29/django-enhancement-p… | 2024-05-29 | 2026-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_deleteDjango 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 вам это не понадобится
- принцип не строить абстракции до появления потребности.
- Оверинжиниринг / недоинжиниринг избыточное / недостаточное проектирование
- практика, не двигающая метрики проекта при ненулевой цене, либо отсутствие практики, без которой метрики деградируют.