---
title: "Django для API-серверов: производительность, гибкость, наблюдаемость и поддерживаемость без оверинжиниринга"
slug: "django-api-practices"
participant: opus
model: "claude-opus-5-5"
effort: "xhigh"
date: 2026-10-01
cutoff: 2026-10-01
language: ru
sources_read: 133
status: complete
summary: "Справочник рациональных практик Django API-серверов на 2026-10-01: 17 практик базового набора с автоматическими проверками CI, 16 расширений по сигналу с порогами, 17 типовых задач с вариантами, сравнение философий Kraken, Sentry, PostHog, Zulip, Instagram, HackSoft, Беннетта и Планта. Главный вывод: качество определяют машинно проверяемые правила, а не число слоёв; монолит на Django 5.2 LTS или 6.1 с DRF или Ninja подтверждён масштабом. Ограничение: доказательная база — документация, опросы и кейсы, пороги сигналов — ориентиры автора."
---

# Django для API-серверов: производительность, гибкость, наблюдаемость и поддерживаемость без оверинжиниринга

## 0. Вердикт {#verdict}

Справочник описывает рациональный способ строить 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 (первоисточники), средняя для архитектурных рекомендаций (мнения и кейсы больших организаций), низкая для численных порогов.

## 1. Что это и как работает {#basics}

### Определение

**Django API-сервер — это Django-проект, который отвечает клиентам машиночитаемыми данными (обычно JSON по HTTP) и не рендерит HTML-страницы.** Предмет справочника — не сам Django, а набор решений вокруг него: как устроены API-слой, доменный код, работа с PostgreSQL, фоновые задачи, наблюдаемость, тесты, типы и рантайм. Практика в справочнике считается полезной, только если она двигает хотя бы одну метрику проекта: стабильность, скорость разработки, гибкость, производительность, наблюдаемость, поддерживаемость или функциональность.

Составные части типичного проекта:

| Часть | Назначение | Выбор по умолчанию на 2026-10 | Добавлять по сигналу |
|---|---|---|---|
| Сервер приложений | Принимает HTTP, держит процессы и потоки | Gunicorn (WSGI, sync/gthread) | ASGI-сервер (Uvicorn, Granian и др.) при долгих соединениях |
| Django core | Middleware, URL, ORM, миграции, auth, cache, settings | Django 5.2 LTS или 6.1 | — |
| API-слой | Разбор и проверка входа, права, сериализация, OpenAPI | DRF или Django Ninja | Собственный тонкий слой, GraphQL |
| Доменный код | Бизнес-правила и операции | Методы моделей и QuerySet, функции для сценариев | Фасады и контракты между доменами |
| PostgreSQL | Данные, ограничения, транзакции, поиск, PostGIS | Одна основная база | Реплики чтения, пул на стороне сервера |
| Redis | Кэш, брокер, rate limit | Один экземпляр | Отдельные экземпляры под кэш и брокер |
| Фоновые задачи | Работа вне цикла запрос-ответ | Одна очередь с воркером | Расширенная маршрутизация, отдельные пулы |
| Наблюдаемость | Ошибки, логи, метрики, трассировки | Sentry SDK или совместимый self-hosted, JSON-логи | OpenTelemetry, Prometheus |

### Механизм: путь запроса

1. Сервер приложений принимает соединение и передаёт его Django через WSGI или ASGI. Django документирует ASGI-серверы Daphne, Granian, Hypercorn и Uvicorn {факт} [S8].
2. Запрос проходит цепочку middleware, затем URL-резолвер выбирает представление.
3. API-слой выполняет аутентификацию, проверку прав, ограничение частоты и разбор тела. В DRF это классы authentication, permission и throttle, в Django Ninja — параметры операции и схемы Pydantic {факт} [S9, S10].
4. Доменный код читает и меняет данные через ORM внутри транзакции.
5. Ответ сериализуется в JSON.
6. После фиксации транзакции срабатывают хуки `transaction.on_commit`, которые ставят фоновые задачи. Документация Django прямо предупреждает, что воркер может начать задачу раньше фиксации и не увидеть объект, если ставить её внутри транзакции {факт} [S11, S12].

### Модель процессов и соединений

Производительность и стабильность Django API-сервера в первую очередь определяет не код представлений, а **арифметика процессов, потоков и соединений с базой** {гипотеза}. Правила Django:

- Без пула соединение открывается при первом запросе к базе и живёт до `CONN_MAX_AGE` секунд; значение `0` закрывает его в конце каждого запроса, `None` держит без ограничения {факт} [S13].
- `CONN_HEALTH_CHECKS = True` проверяет переиспользуемое соединение один раз за запрос, что спасает после перезапуска PostgreSQL {факт} [S13].
- Встроенный пул (только psycopg 3, с Django 5.1) создаётся отдельно для каждого алиаса базы в каждом процессе; при включённом пуле `CONN_MAX_AGE` обязан быть `0` {факт} [S13, S14].
- Под ASGI постоянные соединения нужно отключать и использовать пул {факт} [S13].
- В режиме transaction pooling PgBouncer нужно отключить server-side cursors (`DISABLE_SERVER_SIDE_CURSORS = True`), иначе `iterator()` ломается на чужом соединении {факт} [S13].

Отсюда следует оценка верхней границы соединений, которую стоит держать в README проекта {гипотеза}:

```text
соединения ≈ Σ по типам процессов (экземпляры × процессы × потоки_или_размер_пула)
условие:    соединения ≤ 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] |

## 2. Актуальность и доказательная база на дату среза {#evidence}

### Распространённость и тренд

Главный количественный источник — ежегодный опрос DSF и JetBrains. **Django для API — основной, а не нишевый сценарий: 53 % респондентов 2026 года делают API-only приложения** {эмпирика} [S27].

| Показатель | Значение | Год опроса | Источник |
|---|---|---|---|
| Респондентов | около 3 500 из 40+ стран | 2026 | [S27] |
| API-only приложения | 53 % | 2026 | [S27] |
| DRF среди пользователей API-фреймворков | 73 % | 2026 | [S28] |
| Django Ninja среди пользователей API-фреймворков | 17 % | 2026 | [S28] |
| Собственный API-слой / GraphQL | 13 % / 9 % | 2026 | [S28] |
| Используют async-возможности Django / планируют | 33 % / 40 % | 2026 | [S28] |
| PostgreSQL | 76–79 %, пять лет подряд | 2026 | [S27] |
| Redis как кэш | 53 % | 2026 | [S28] |
| На Django 6.0 / 5.x / 4.x / старше | 43 % / 44 % / 6 % / 3 % | 2026 | [S28] |
| Монолит / self-hosted или VPS | 54 % / 44 % | 2026 | [S28] |
| Используют аннотации типов / mypy / Pyright / ty | 57 % / 32 % / 22 % / 12 % | 2026 | [S27] |
| Ruff / pytest / pytest-django / нет автотестов | 43 % / 45 % / 34 % / 19 % | 2026 | [S27] |
| Claude Code / ChatGPT / Copilot; без ИИ-инструментов | 35 % / 33 % / 23 %; 10 % | 2026 | [S27] |
| Celery (django-celery) | 26 % | 2025 | [S29] |

Ограничения опроса: выборка самоотобранная через каналы DSF и JetBrains, JetBrains — заинтересованная сторона в теме инструментов, формулировки вопросов меняются между годами, поэтому DRF «49 %» в 2025 году {эмпирика} [S29] и «73 %» в 2026 году считаются от разных знаменателей и не образуют тренд.

Тренды с основаниями:

- **DRF — стабилен и заморожен по функциям.** Проект объявлен «feature-complete», принимаются только изменения для новых версий Django и Python, безопасность и документация {факт} [S30, S31]. Релизы при этом выходят регулярно: 3.17.0 в марте 2026, 3.18.0 в августе 2026 с поддержкой Django 6.1 {факт} [S18].
- **Django Ninja — растёт.** Десять релизов с ноября 2025 по сентябрь 2026 {факт} [S19]; в 2024 году пользователи поднимали вопрос о единственном сопровождающем, автор ответил, что проект финансируется и обязан поддерживаться по графику LTS Django {факт} [S32].
- **Async — интерес выше практики.** 33 % используют, 40 % планируют {эмпирика} [S28]; документированные случаи пользы — долгие соединения и параллельные внешние вызовы {факт} [S33, S34].
- **Фоновые задачи — переходный период.** `django.tasks` задаёт общий API с Django 6.0, но без воркера и production-бэкенда в ядре {факт} [S15]; официального бэкенда Celery для него нет, запрос открыт с января 2026 {факт} [S35].
- **Цикл релизов Django меняется.** С 2028 года — одна версия в год, каждая с тремя годами поддержки; 5.2 LTS и 6.2 LTS сохраняют прежние обязательства {факт} [S17].

### Научная и эмпирическая база

Контролируемых исследований или рецензируемых сравнений архитектурных практик Django не найдено; вывод о «лучшей» структуре проекта на экспериментах не опирается {гипотеза}. Имеющаяся эмпирика — это измерения отдельных механизмов и кейсы проектов с числами:

| Наблюдение | Дизайн и ограничения | Источник |
|---|---|---|
| Загрузка 32 500 строк: 128,8 с поштучно, 1,47 с `execute_values`, 0,46 с `COPY` из итератора | один набор данных, один стенд, 2019 год, psycopg2 | {эмпирика} [S36] |
| `COUNT(*)` занимал 781 мс из 786 мс загрузки страницы списка | одна большая таблица, админка Django, 2018 год | {эмпирика} [S37] |
| `migrate_schemas` при ~1780 схемах: 5–14 с CPU базы на арендатора даже без изменений | один отчёт пользователя django-tenants, сентябрь 2026 | {эмпирика} [S38] |
| Детектор N+1 django-zeal даёт 3–5 % накладных расходов | бенчмарк автора библиотеки | {вендор} [S39] |
| `FETCH_PEERS` сводит цикл с N+1 к двум запросам | пример из документации, не нагрузочный тест | {факт} [S40] |
| Пул psycopg снижает задержку на 50–70 мс | одна статья без описания методики, managed PostgreSQL | {эмпирика} [S41] |
| Immortal Objects в Instagram: регрессия около 2 % при росте разделяемой памяти | внутреннее измерение Meta | {эмпирика} [S42] |
| Healthchecks.io: CPU уходил на Python-код приёма пингов, после переноса обработчика на Go основная нагрузка — TLS | наблюдение автора соло-проекта, 2016–2017 | {эмпирика} [S43] |

Кейсы с подтверждённым масштабом:

- **Kraken (Octopus Energy):** 27 637 модулей и около 400 разработчиков в 2023 году {факт} [S3]; около 9 млн строк Python, более 100 выкладок в день в 25+ окружений, более 100 000 тестов за время до получаса {факт} [S44]; 5 млн строк под mypy, 2000+ моделей, 2,5 года до нуля неаннотированного кода {факт} [S45].
- **Instagram:** «один из крупнейших в мире деплоев Django» {вендор} [S7]; pre-fork-процессы с разделяемой памятью {факт} [S42].
- **Zulip:** тесты бэкенда параллельно укладываются менее чем в 30 секунд, новый код требует 100 % покрытия, каждый ответ API в тестах сверяется с OpenAPI {факт} [S46, S47].

### Мнение отрасли

| Спорная позиция | Сторонники | Критики | Суть спора |
|---|---|---|---|
| Отдельный сервисный слой (services/selectors) | HackSoft {мнение} [S48]; Kraken: интерфейс делает один вызов в домен {факт} [S49] | Джеймс Беннетт, Люк Плант {мнение} [S50, S51] | Слой даёт явные точки входа, но в Active Record ORM превращается в «собственный приватный ORM» |
| Принудительные границы модулей | PostHog (tach + import-linter, baseline только вниз) {факт} [S5]; Kraken (40+ контрактов Import Linter) {факт} [S3] | — | Цена — инверсия зависимостей и локальная сложность, признают сами авторы {мнение} [S3] |
| Async Django | документация Django для долгих соединений {факт} [S33] | Kraken: для большинства задач очереди проще {мнение} [S34] | Выигрыш только при параллельном вводе-выводе |
| `django.tasks` как основной инструмент | Тим Шиллинг для малых проектов {мнение} [S52] | Kevin Renskers: нет воркера, ретраев, расписания {мнение} [S53] | Стандарт API против зрелости экосистемы |
| JWT для своего клиента | — | django-allauth: JWT ошибочно называют stateless, отзыв требует состояния {мнение} [S54] | Сложность без выигрыша в монолите |
| Библиотеки фабрик тестовых данных | HackSoft рекомендует factory_boy {мнение} [S48] | Люк Плант: простые функции понятнее и лучше типизируются {мнение} [S55] | Удобство против прозрачности |

### Главные споры

1. Где живёт бизнес-логика и сколько слоёв нужно.
2. DRF или Django Ninja для нового проекта.
3. Нужен ли ASGI и async-код API-серверу без долгих соединений.
4. Celery, более простая очередь или `django.tasks` с бэкендом.
5. Сессии, непрозрачные токены или JWT.
6. Мультиарендность общей базой, схемами или отдельными базами.
7. Насколько строгая типизация окупается в Django.

### Что изменилось за последние 2–3 года

| Изменение | Версия и дата | Влияние на практики | Источник |
|---|---|---|---|
| `db_default`, `GeneratedField` | Django 5.0, 2023-12-04 | Значения по умолчанию на стороне базы, безопасные для выкладки миграций; вычисляемые поля для поиска | [S56] |
| Встроенный пул соединений PostgreSQL | Django 5.1, 2024-08-07 | PgBouncer перестаёт быть обязательным для малого числа хостов | [S14] |
| `CompositePrimaryKey`, async-методы auth | Django 5.2 LTS, 2025-04-02 | Таблицы связей и унаследованные схемы без суррогатного ключа | [S16] |
| API задач, CSP, `BigAutoField` по умолчанию, `AsyncPaginator`, Python 3.12+ | Django 6.0, 2025-12-03 | Код задач можно писать против стандартного API; новые модели сразу с 64-битным ключом | [S15] |
| Fetch modes, `DB_CASCADE`, `MAILERS`, `UUID7()`, PostgreSQL 15+ | Django 6.1, 2026-08-05 | N+1 гасится режимом `FETCH_PEERS`, а `FETCH_RAISE` ловит лишние запросы; каскад в базе быстрее, но без сигналов | [S2] |
| Годовой цикл и календарные версии | DEP 20, 2026-08-10 | Обновление раз в год вместо прыжков между LTS | [S17] |
| DRF объявлен feature-complete, coreapi удалён | 2024–2026 | Новых функций в DRF ждать не стоит, расширения — сторонние пакеты | [S31, S18] |
| Ninja: cursor pagination, стриминг JSONL и SSE, `Retry-After` | 1.6–1.7, 2026 | Закрывает типовые задачи без самописного кода | [S57] |
| Gunicorn: ASGI-воркер стабилен, eventlet удалён | 25.1.0 и 26.0.0, 2026 | Один сервер для WSGI и ASGI, но с оговорками по обработке ошибок парсера | [S21, S58] |
| Celery: soft shutdown, quorum queues, лимит ETA-задач | 5.5–5.6, 2025 | Меньше потерь задач при выкладке | [S20] |
| Регресс памяти incremental GC в Python 3.14, откат в 3.14.5 | 2026 | Обновлять Python до патч-версии с откатом | [S59] |
| Стабилизация HTTP semantic conventions OpenTelemetry | 2025–2026 | По умолчанию инструментации Python всё ещё пишут старые экспериментальные атрибуты; переход включается `OTEL_SEMCONV_STABILITY_OPT_IN=http` или `http/dup` | [S60, S61] |
| AGENTS.md под Agentic AI Foundation | 2025–2026 | Единый файл правил для ИИ-агентов вместо разрозненных конфигураций | [S62] |

## 3. Где применимо и где нет, плюсы и минусы {#fit}

Предмет раздела — 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].

## 4. Альтернативы и дерево решений {#alternatives}

### Альтернативные подходы к устройству кода

Предмет сравнения — подход, рекомендуемый этим справочником: **идиоматичный Django с явными схемами API и доменными функциями, которые появляются только для сценариев, затрагивающих несколько моделей или внешние эффекты**. Это синтез позиций Беннетта и Планта, HackSoft и конвенций Kraken; как целое он нигде не измерен {гипотеза}.

| Подход | Где живёт логика | Слоёв | Скорость старта | Защита от связности | Удобство для ИИ-агентов | Цена отката | Подтверждение |
|---|---|---|---|---|---|---|---|
| **Предмет: идиоматичный Django + явные схемы + доменные функции по сигналу** | Методы модели и `QuerySet` для одной сущности; функции `services.py` для сценариев с несколькими моделями, задачами и внешними вызовами | 2–3 | Высокая | Средняя; import-linter добавляется по сигналу | Высокое: одна точка входа на сценарий, схемы явные | Низкая | Синтез источников ниже {гипотеза} |
| «Толстые модели» (Беннетт, Плант) | Модели, менеджеры, `QuerySet` | 2 | Максимальная | Низкая | Среднее: сценарии из нескольких моделей не имеют своего места | Низкая | Мнение авторов {мнение} [S50, S51] |
| Services/selectors (HackSoft) | `services` для записи, `selectors` для чтения; не в views, serializers, `save()`, сигналах | 3 | Средняя | Средняя | Высокое, но много однотипных файлов | Средняя | Руководство компании-разработчика, масштаб не опубликован {мнение} [S48] |
| Модульный монолит с контрактами (Kraken, PostHog) | Доменные пакеты с фасадами и DTO; линтер импортов в CI | 3–4 | Низкая | Высокая, автоматическая | Высокое в большой команде | Высокая | 400 разработчиков Kraken {факт} [S3]; PostHog {факт} [S5] |
| CRUD-first DRF | `ModelSerializer`, `perform_create`, сигналы | 1–2 | Максимальная на старте | Низкая | Низкое при росте: логика спрятана в хуках | Средняя | Распространённая практика без опубликованных кейсов {гипотеза} |
| Собственный тонкий слой (Zulip) | Функции + декоратор `typed_endpoint` на Pydantic v2 | 2 | Средняя | Средняя | Высокое: типы в сигнатуре | Высокая: свой мини-фреймворк | Zulip {факт} [S24] |

Когда альтернатива целесообразнее предмета:

- **«Толстые модели»** — соло-проект или домен из 5–10 моделей без сложных сценариев.
  - Плюсы: меньше файлов, полное использование ORM и DRF без прослоек.
  - Минусы: сценарий «создать заказ, списать лимит, отправить вебхук» не принадлежит ни одной модели и оседает в представлении.
- **Services/selectors** — команда со смешанным опытом, которой нужен один шаблон на всё.
  - Плюсы: предсказуемость; задачи Celery вызывают сервисы, а не наоборот {мнение} [S48].
  - Минусы: тонкие сервисы-прокладки над `Model.objects.create`; сами авторы называют подход «не единственным» {мнение} [S48]; Беннетт называет это написанием «собственного приватного ORM» {мнение} [S50].
- **Модульный монолит с контрактами** — от 20–30 разработчиков или от 15–20 доменных приложений с циклическими импортами (порог — ориентир {гипотеза}).
  - Плюсы: границы проверяются машиной; PostHog запрещает рост счётчика пересечений моделей в CI {факт} [S5].
  - Минусы: инверсия зависимостей и локальная сложность, которые признаёт сам Kraken {мнение} [S3].
- **CRUD-first DRF** — прототип, внутренняя админ-API, срок жизни меньше года.
  - Плюсы: минимум кода.
  - Минусы: бизнес-правила в `perform_create` и сигналах не видны из точки вызова и не переиспользуются задачами.
- **Собственный слой** — только при масштабе и сроке жизни уровня Zulip.
  - Плюсы: полный контроль, OpenAPI как источник истины с проверкой каждого ответа в тестах {факт} [S47].
  - Минусы: своя библиотека, которую поддерживает команда.

### Философии знаковых проектов и людей

| Кто | Подтверждение | Логика и слои | Тесты | Типы | Фоновые задачи | Наблюдаемость и эксплуатация | Обновления | Сознательно избегают |
|---|---|---|---|---|---|---|---|---|
| Instagram | «Один из крупнейших деплоев Django» {вендор} [S7] | Не опубликовано в прочитанных источниках | Не опубликовано | Не опубликовано | Не опубликовано | Pre-fork-процессы с разделяемой памятью; доработки рантайма (Cinder, Immortal Objects) {факт} [S42] | Не опубликовано | Смены фреймворка: вкладываются в рантайм Python {гипотеза} |
| Kraken | ~9 млн строк, 100+ выкладок в день, 25+ окружений {факт} [S44] | Слои `clients` → `territories` → `core`, 40+ контрактов Import Linter {факт} [S3]; интерфейс делает один вызов в домен {факт} [S49] | 100 000+ тестов менее чем за 30 минут {факт} [S44] | mypy на 5 млн строк, свой плагин {факт} [S45] | Celery на RabbitMQ {факт} [S67] | Один `/health/` для трёх проб; миграции до выкладки {факт} [S68] | Непрерывная выкладка, фича-флаги, обратно совместимые миграции {факт} [S44] | Неявного `ordering` в `Meta`, `ModelForm`, валидаторов полей, запросов в `@property` {факт} [S49] |
| Sentry | 35 000 тестов, прогон в двух режимах {факт} [S4] | Монолит с silo: control и регионы, RPC и outbox {факт} [S4, S69] | Симуляция границ silo в CI через ORM {факт} [S4] | Не проверено | Outbox и tombstones для межрегиональных изменений {факт} [S69] | Свой продукт | Двухфазное удаление колонок, post-deploy миграции {факт} [S66] | Переименований колонок, межрегиональных внешних ключей {факт} [S66, S69] |
| PostHog | Открытый монорепозиторий | Вертикальные продукты: `facade` + frozen dataclasses, DRF в `presentation` {факт} [S5] | Выборочный прогон по изменённым контрактам {факт} [S5] | Контракты без импортов Django {факт} [S5] | Celery в `tasks/` {факт} [S5] | Не проверено | Не проверено | Выдачи моделей через фасады, роста пересечений {факт} [S5] |
| Zulip | Открытый проект с долгой историей | Django + отдельный Tornado для push {факт} [S6] | < 30 с параллельно, 100 % покрытия нового кода, проверка числа запросов {факт} [S46] | `typed_endpoint` на Pydantic v2 {факт} [S24] | RabbitMQ-очереди {факт} [S6] | OpenAPI сверяется с каждым ответом {факт} [S47] | Не проверено | Блокирующих вызовов в Tornado {факт} [S6] |
| Healthchecks.io | Один человек с июля 2015 года, доступность выше 99,9 % {вендор} [S70]; ~€274 в месяц на железо в 2019 {факт} [S71] | Обычный Django | Не проверено | Не проверено | Нет очереди: `sendalerts`, `sendreports` как systemd-сервисы {факт} [S71] | Внешние пинги, агрегатор логов {факт} [S71] | Не проверено | Контейнеров, автоскейлинга, serverless {факт} [S71]; горячий путь вынесен в Go {факт} [S43] |
| addons-server (Mozilla) | Бэкенд addons.mozilla.org | DRF {факт} [S23] | Не проверено | Не проверено | Не проверено | Не проверено | DRF 3.18.1 влит через 16 дней после выхода, Dependabot {факт} [S23, S18] | Не проверено |
| NetBox | Широко используемый open source | REST плюс read-only GraphQL на Strawberry {факт} [S26] | Не проверено | Не проверено | RQ-воркер {факт} [S72] | Лимит страницы 1000, хешированные токены v2 {факт} [S73] | PostgreSQL 15+, Python 3.12+ {факт} [S72] | Не проверено |
| HackSoft | Руководство без метрик масштаба | services/selectors, Input/OutputSerializer внутри API {мнение} [S48] | Фабрики, тесты бьют в базу, мокаются внешние вызовы {мнение} [S48] | Аннотации у сервисов {мнение} [S48] | Задача вызывает сервис, постановка через `on_commit` {мнение} [S48] | Не входит в руководство | Не входит | Логики в сериализаторах, `save()`, сигналах {мнение} [S48] |
| Джеймс Беннетт | Многолетний участник Django | Модели и `QuerySet`, без service layer {мнение} [S50] | — | — | — | — | — | Слоёв «на всякий случай» (YAGNI) {мнение} [S50] |
| Люк Плант | Автор «Django Views — The Right Way» | Тонкие представления, цепочки `QuerySet` {мнение} [S51] | Фабрики-функции вместо factory_boy {мнение} [S55] | Типы через обычные функции {мнение} [S55] | — | — | — | `filter()` прямо в представлении {мнение} [S51] |
| Адам Джонсон | Участник Django, автор инструментов | Автоматизация рутины: линейные миграции, быстрый JSON {мнение} [S74, S75] | — | — | — | — | Обходит регрессию рантайма до патча Python: `gc.collect()` после миграций {факт} [S59] | Ручных merge-миграций {мнение} [S74] |
| Хаки Бенита | Автор разборов ORM и PostgreSQL | Работу переносить в базу: F-выражения, `UPDATE … RETURNING`, `COPY` {мнение} [S76, S36] | — | — | — | Измерять запрос, а не гадать {эмпирика} [S37] | — | Блокировок, где хватает атомарных операций {мнение} [S76] |
| Сопровождающие DRF | Самый массовый API-слой Django | Узкий объём ядра, расширения снаружи {факт} [S31] | — | — | — | — | Только поддержка новых Django и безопасность {факт} [S30] | Новых функций в ядре {факт} [S30] |
| Автор Django Ninja | Используется в критичных проектах автора {мнение} [S32] | Схемы Pydantic, auth через `request` {факт} [S10] | — | Аннотации — основа API {факт} [S10] | — | — | Поддержка по графику LTS Django {мнение} [S32] | Многословного dependency injection {мнение} [S10] |

Что объединяет подтверждённые масштабом проекты: монолит сохраняется, а при росте добавляются **машинно проверяемые границы** (Kraken, PostHog, Sentry), а не новые слои абстракций. Горячие пути выносят точечно (Healthchecks, Zulip), рантайм улучшают вместо смены фреймворка (Instagram) {гипотеза}.

Книга «Two Scoops of Django» в последнем издании 3.x закрыта и не прочитана; её позиция в сравнение не включена {факт} [S77].

### Сравнение инструментов по вариантам

#### API-слой

| Критерий | DRF | Django Ninja | Собственный слой |
|---|---|---|---|
| Статус | Feature-complete, релизы под новые Django {факт} [S30, S18] | Активное развитие, 1.7.1 от 2026-09-19 {факт} [S19] | Поддерживает команда |
| Доля среди пользователей API-фреймворков | 73 % {эмпирика} [S28] | 17 % {эмпирика} [S28] | 13 % {эмпирика} [S28] |
| OpenAPI | Через drf-spectacular | Встроен | Вручную или как у Zulip |
| Валидация | Сериализаторы DRF | Pydantic | Pydantic или своя |
| Async | Синхронный в ядре; async только через сторонние пакеты {гипотеза} | sync и async {факт} [S10] | Как напишете |
| Пагинация и ограничение частоты | Встроены {факт} [S78, S79] | Встроены, cursor pagination и `Retry-After` с 1.6–1.7 {факт} [S57] | Своё |
| Когда выбирать | Нужна экосистема (фильтры, права на объект, viewsets) или код уже на DRF | Новый проект, типы и схема важнее экосистемы, есть async-эндпоинты | Масштаб и срок жизни уровня Zulip |

Надёжного независимого бенчмарка DRF против Ninja не найдено; аргумент о скорости Pydantic v2 остаётся непроверенным для реальных эндпоинтов, где доминирует время базы {гипотеза}.

#### WSGI или ASGI

| Вариант | Когда | Плюсы | Минусы |
|---|---|---|---|
| WSGI: Gunicorn sync/gthread или uWSGI | По умолчанию | Простая модель, транзакции и ORM без оговорок | Долгие соединения занимают поток |
| ASGI: Uvicorn, Granian, Daphne, Hypercorn | SSE, WebSocket, параллельные внешние вызовы | Сотни соединений без потоков {факт} [S33] | Нет async-транзакций, постоянные соединения отключаются {факт} [S33, S13] |
| Gunicorn с ASGI-воркером | Один сервер для обоих режимов | Стабилен с 25.1.0 {факт} [S21] | Обрабатывает не все исключения парсера {факт} [S58] |
| Два деплоя: WSGI для API и ASGI для стриминга | Нужен realtime, но основная часть синхронная | Изоляция рисков | Два конфига выкладки {гипотеза} |

#### Фоновые задачи

| Вариант | Инфраструктура | Ретраи и расписание | Транзакционная постановка | Когда |
|---|---|---|---|---|
| Celery | Брокер Redis или RabbitMQ | Есть: `autoretry_for`, `retry_backoff`, beat {факт} [S12] | `delay_on_commit` {факт} [S12] | Много очередей, маршрутизация, большие объёмы |
| `django.tasks` + django-tasks-db | Только PostgreSQL и `db_worker` {факт} [S52] | В ядре нет {факт} [S53] | `on_commit` {факт} [S11] | Малый объём, разовые задачи |
| Procrastinate | Только PostgreSQL | Ретраи, periodic, блокировки {факт} [S80] | Да, в той же транзакции {факт} [S80] | Нужны надёжность и periodic без отдельного брокера |
| RQ | Redis | Не проверялось | Нет данных | Пример: NetBox {факт} [S72] |
| Management command в цикле под systemd | Ничего | Своё | — | 1–3 постоянных фоновых цикла, соло-проект {факт} [S71] |

#### Генерация OpenAPI

| Вариант | Версия OpenAPI | Статус | Вердикт |
|---|---|---|---|
| drf-spectacular | 3.0.3, 3.1, 3.2 {факт} [S81] | Активен, сознательно ниже 1.0 {факт} [S81] | Брать для DRF |
| drf-yasg | Только 2.0 {факт} [S82] | Сам рекомендует drf-spectacular для новых проектов {факт} [S82] | Не брать в новые проекты |
| Django Ninja | Встроен {факт} [S10] | — | Брать вместе с Ninja |

#### Аутентификация

| Вариант | Когда | Плюсы | Минусы |
|---|---|---|---|
| Сессии + CSRF | SPA на том же домене {факт} [S9] | Мгновенный отзыв, нет хранения токена в JS | Не подходит мобильному клиенту без cookie |
| DRF `TokenAuthentication` | Внутренние интеграции | Просто | Один токен на пользователя, без срока жизни {факт} [S9] |
| Knox или session token allauth headless | Мобильное приложение, несколько устройств | Токен на клиента, отзыв {факт} [S9, S54] | Запрос к базе на каждый вызов |
| JWT (simplejwt, allauth JWT) | Несколько сервисов проверяют токен без центра {факт} [S54] | Проверка без запроса к базе | Отзыв требует состояния, «stateless» — заблуждение {мнение} [S54] |
| OAuth 2.0 (Django OAuth Toolkit) | Сторонние интеграторы | Стандарт {факт} [S9] | Сложность сервера авторизации |

#### Наблюдаемость

| Вариант | Что даёт | Цена входа | Вердикт |
|---|---|---|---|
| Sentry SDK + Sentry SaaS | Ошибки, трассировки, профили; автоспаны middleware, SQL, кэша {вендор} [S83] | Платный SaaS с бесплатным уровнем (тарифы не проверялись) | Брать, если SaaS допустим |
| Sentry self-hosted | То же | 4 CPU, 16 GB RAM + 16 GB swap; лицензия FSL {факт} [S84] | По сигналу: большая команда эксплуатации |
| GlitchTip (self-hosted, принимает данные от SDK Sentry {вендор} [S85]) | Ошибки, базовая производительность, uptime {вендор} [S85] | 256–512 MB RAM, PostgreSQL {факт} [S86] | Брать для установок у клиентов и регионов |
| OpenTelemetry | Вендор-нейтральные трассировки, sqlcommenter {факт} [S87] | Коллектор и бэкенд трассировок | По сигналу: несколько сервисов или требование нейтральности |
| Prometheus | Метрики и алерты | Multiprocess-режим с ограничениями {факт} [S88] | По сигналу: SLO-алерты, уже есть Prometheus |

#### Мультиарендность

| Вариант | Изоляция | Цена | Когда |
|---|---|---|---|
| Общая база + `company_id` + scoped QuerySet | Логическая, в коде | Минимальная | По умолчанию |
| Общая база + PostgreSQL RLS | В базе; владелец таблицы обходит RLS без `FORCE` {факт} [S89] | Политики в миграциях, сброс контекста на пуле | Требование аудиторов или высокий риск утечки |
| Схема на арендатора (django-tenants) | Сильная | Миграции растут с числом схем: 5–14 с CPU на схему при ~1780 схемах {эмпирика} [S38] | Десятки арендаторов с требованием физического разделения |
| Отдельная база или экземпляр на клиента | Полная | Отдельный деплой | Регионы, установки у клиентов; так работают Kraken и Sentry {факт} [S3, S4] |

#### Соединения с базой

| Вариант | Когда | Ограничения |
|---|---|---|
| `CONN_MAX_AGE` + `CONN_HEALTH_CHECKS` | WSGI, соединений с запасом | Соединение держит каждый поток {факт} [S13] |
| Пул Django (psycopg 3) | Соединения дорогие (TLS, managed PostgreSQL) или ASGI | Пул на процесс; `CONN_MAX_AGE = 0` {факт} [S13] |
| PgBouncer в transaction mode | Сумма соединений превышает лимит базы | Отключить server-side cursors {факт} [S13] |

### Дерево решений

- Если нужно решить, где писать бизнес-логику → применить правила ниже
  - Если правило касается одного объекта или одного набора строк → метод модели или метод `QuerySet`
  - Если сценарий меняет несколько моделей, ставит задачи или зовёт внешний API → функция в `<app>/services.py` с `transaction.atomic`
  - Если приложений больше 15–20 или есть циклические импорты → добавить Import Linter с контрактами слоёв и независимости
  - Иначе → не вводить отдельный слой селекторов; чтение через методы `QuerySet`
- Если выбирается API-слой → применить правила ниже
  - Если в проекте уже есть DRF-код → DRF, без второго фреймворка
  - Если нужны готовые пакеты фильтров, прав на объект и viewsets → DRF + drf-spectacular
  - Если проект новый и важнее сквозные типы и встроенный OpenAPI → Django Ninja
  - Иначе → DRF + drf-spectacular
- Если выбирается сервер приложений → применить правила ниже
  - Если нет SSE, WebSocket и долгих запросов → Gunicorn WSGI с потоками
  - Если долгие соединения нужны только части эндпоинтов → отдельный ASGI-деплой (Uvicorn) для них, остальное на WSGI
  - Иначе → ASGI-сервер с пулом соединений Django
- Если нужны фоновые задачи → применить правила ниже
  - Если задач мало и нужен один-два постоянных цикла → management command под systemd или контейнер-воркер
  - Если нужны ретраи, расписание и не хочется брокера → Procrastinate
  - Если нужны несколько очередей, маршрутизация, высокие объёмы → Celery с Redis, а при требованиях к надёжности доставки → Celery с RabbitMQ
  - Иначе → Celery с Redis
- Если выбирается аутентификация → применить правила ниже
  - Если клиент — браузерный SPA на том же домене → сессии + CSRF
  - Если клиент — мобильное приложение → непрозрачные токены на устройство (Knox или allauth headless session token)
  - Если токен проверяют несколько независимых сервисов → JWT с коротким сроком жизни и проверкой отзыва
  - Иначе → сессии
- Если данные разделяются по компаниям → применить правила ниже
  - Если требуется физическое разделение или размещение в стране клиента → отдельный экземпляр с отдельной базой
  - Если аудит требует гарантии на уровне базы → общая база + RLS c `FORCE ROW LEVEL SECURITY`
  - Иначе → общая база с `company_id` и обязательным scoped-менеджером
- Если суммарных соединений больше 70–80 % `max_connections` (ориентир) → применить правила ниже
  - Если хостов приложения немного и соединения дорогие → пул Django
  - Иначе → PgBouncer в transaction mode с `DISABLE_SERVER_SIDE_CURSORS = True`
- Если выбирается наблюдаемость → применить правила ниже
  - Если данные можно отправлять во внешний SaaS → Sentry SDK + Sentry SaaS
  - Если нужна установка у клиента или в регионе с ограничениями → Sentry SDK + GlitchTip
  - Если сервисов несколько или требуется вендор-нейтральность → OpenTelemetry + коллектор
  - Иначе → Sentry SDK + JSON-логи с `request_id`

## 5. Практическое применение {#practice}

Раздел — главный каталог справочника. **Практики делятся на базовый набор (Б01–Б17), который окупается в любом проекте, и расширения по сигналу (Р01–Р16), которые добавляются только после пересечения порога.** Пороги без ссылки на источник — ориентиры автора, их стоит калибровать на своих метриках {гипотеза}.

### Порядок внедрения

1. Зафиксировать версии: Python 3.12+, Django 5.2 LTS или 6.1, lock-файл зависимостей (Б01).
2. Создать скелет проекта и настройки из раздела 6, прогнать `manage.py check --deploy` с боевыми настройками (Б02, Б15).
3. До первой фичи включить проверки CI: форматер и линтер, проверку типов в мягком режиме, `makemigrations --check`, линтер миграций, тесты с подсчётом запросов, сверку OpenAPI (Б04, Б07, Б09, Б16, Б17).
4. Описать модели с ограничениями в базе и scoped-менеджерами арендатора (Б08, Б13).
5. Написать API с явными схемами, общей пагинацией и единым форматом ошибок (Б03, Б05, Б06).
6. Подключить минимум наблюдаемости: ошибки, JSON-логи с `request_id`, health-эндпоинты (Б12).
7. Добавить фоновые задачи с постановкой после фиксации транзакции (Б11).
8. Выкладывать миграции по схеме expand/contract (Б09).
9. Всё остальное — только по сигналам из карточек Р01–Р16.

### Карточки базового набора

#### Б01. Версии, зависимости и обновления
- **Суть.** Django 5.2 LTS (поддержка до апреля 2028) или актуальная 6.x; обновление по одной feature-версии, сначала зависимости, перед прыжком — ноль предупреждений об устаревании (`python -Wa manage.py test`) {факт} [S90, S1]. Зависимости в lock-файле; uv используют 43 % респондентов {эмпирика} [S27]. Бот обновлений открывает PR, CI решает: addons-server влил DRF 3.18.1 через 16 дней после выхода {факт} [S23, S18].
- **Метрики.** Стабильность, поддерживаемость, безопасность.
- **Когда.** Всегда. Для установок у клиентов, которые обновляются редко, выгоднее LTS с трёхлетним окном {гипотеза}.
- **Плюсы.** Маленькие шаги обновления; патчи безопасности приходят без авралов.
- **Минусы.** Регулярные затраты времени; Python 3.14 до патча с откатом incremental GC давал OOM при `migrate` {факт} [S59].
- **Цена внедрения и отката.** Часы на настройку бота; откат — вернуть пин версии.
- **Признаки оверинжиниринга.** Собственный форк Django или DRF; вендоринг библиотек; ручное ведение транзитивных пинов без lock-инструмента.
- **Недоинжиниринг (встречается чаще).** Неподдерживаемая версия: 3 % респондентов сидят на версиях старше 4.x {эмпирика} [S28].
- **Как обнаружить.** Тесты с `-W error::DeprecationWarning` в CI; django-upgrade с целевой версией в pre-commit; скрипт, который падает, если до конца поддержки установленной версии Django меньше 90 дней {гипотеза}.
- **Как упростить.** Одна политика: «последний патч текущей LTS или текущей feature-версии», без исключений.

#### Б02. Структура проекта и место бизнес-логики
- **Суть.** Один Django-проект; `config/` для настроек, URL и точек входа; 5–15 приложений по бизнес-возможностям. Правило одной сущности — метод модели или `QuerySet` {мнение} [S50, S51]; сценарий из нескольких моделей, задач и внешних вызовов — функция в `services.py` с явными аргументами. Интерфейсы (представление, задача, команда) делают один вызов в домен {факт} [S49]. Логика не живёт в сериализаторах, `save()` и сигналах {мнение} [S48, S49].
- **Метрики.** Скорость разработки, поддерживаемость, гибкость.
- **Когда нет.** Прототип со сроком жизни меньше квартала — допустим CRUD-first.
- **Плюсы.** Одна точка входа на сценарий удобна людям и агентам; задачи и команды переиспользуют те же функции.
- **Минусы.** Требует ревью дисциплины: границу «одна сущность или сценарий» каждый понимает по-своему.
- **Цена.** Внедрение — соглашение в AGENTS.md и ревью; откат — встроить функции обратно, дёшево.
- **Признаки оверинжиниринга.** Сервис-прокладка, вызывающий ровно один `Model.objects.create`; селектор на каждый `filter()`; Repository поверх ORM; абстрактные классы с единственной реализацией; DTO между функциями одного приложения.
- **Как обнаружить.** AST-скрипт: доля функций в `services.py`, чьё тело — один вызов ORM; число ABC-классов с одним наследником; `grep -rn "class .*Repository"`.
- **Недоинжиниринг.** Представления по 100+ строк, `create()` сериализатора с бизнес-правилами, `post_save` для бизнес-процессов. Обнаружение: правила сложности Ruff (`C901`, `PLR0915`) на модулях API, подсчёт `post_save.connect` и `@receiver`.
- **Как упростить.** Встроить сервисы-прокладки в вызывающий код; правила одной сущности перенести в методы модели.

#### Б03. Явные схемы ввода и вывода, тонкие представления
- **Суть.** У каждого эндпоинта явная схема входа и выхода; при различии — две схемы (`InputSerializer`/`OutputSerializer` у HackSoft {мнение} [S48], `Schema` в Ninja). Запрещены `fields = "__all__"` и `exclude`: перечень полей защищает от API3 OWASP «Broken Object Property Level Authorization» {факт} [S91].
- **Метрики.** Стабильность контракта, безопасность, скорость ревью.
- **Плюсы.** Изменение модели не меняет API незаметно; агенту видно, что принимает эндпоинт.
- **Минусы.** Больше кода, чем с `ModelSerializer` на всё.
- **Цена.** Низкая на старте, высокая при переделке готового API.
- **Признаки оверинжиниринга.** Отдельные DTO, мапперы и сериализаторы на один и тот же набор полей; метапрограммирование «фабрик сериализаторов».
- **Как обнаружить.** `grep -rn '__all__\|exclude =' */api*/` в CI; Ruff `DJ007` ловит `__all__` только в `ModelForm` {факт} [S92], поэтому для сериализаторов нужна своя проверка.
- **Как упростить.** Одна схема, если вход и выход совпадают.

#### Б04. Контракт OpenAPI в CI
- **Суть.** Схема генерируется из кода (drf-spectacular или Ninja), снимок `openapi.yaml` лежит в репозитории, CI перегенерирует, валидирует (`spectacular --validate`) и показывает diff {факт} [S81]. Ответы в тестах сверяются со схемой, как в Zulip {факт} [S47], либо Schemathesis генерирует запросы по схеме {факт} [S93].
- **Метрики.** Стабильность для мобильного клиента, скорость разработки клиентов.
- **Плюсы.** Ломающее изменение видно в PR; генерация клиента для мобильного приложения.
- **Минусы.** Нужно поддерживать аннотации там, где генератор ошибается.
- **Цена.** День на настройку; откат — удалить шаг CI.
- **Признаки оверинжиниринга.** Рукописная схема отдельно от кода при одном потребителе; контрактные тесты со стороны потребителя (consumer-driven) для одного внутреннего клиента {гипотеза}.
- **Как обнаружить.** Число переопределений `@extend_schema` растёт быстрее числа эндпоинтов — генератор не понимает код {гипотеза}.
- **Недоинжиниринг.** Схемы нет, мобильное приложение узнаёт об изменениях из падений в проде.

#### Б05. Единый формат ошибок
- **Суть.** Все ошибки в одном формате, лучше RFC 9457 `application/problem+json` с полями `type`, `title`, `status`, `detail`, `instance` и расширением для ошибок полей {факт} [S94]; альтернатива — `{"message", "extra"}` HackSoft {мнение} [S48]. Стек-трейсы наружу не отдаются {факт} [S94].
- **Метрики.** Скорость разработки клиентов, наблюдаемость.
- **Признаки оверинжиниринга.** Иерархия из десятков классов исключений с кодами, которые клиент не различает; перевод машинных сообщений.
- **Как обнаружить.** Тест обходит эндпоинты с заведомо неверным вводом и проверяет `Content-Type: application/problem+json`; `grep -rn 'Response({"error"'`.
- **Недоинжиниринг.** Смесь `{"detail": ...}` DRF и самописных словарей.

#### Б06. Пагинация, фильтры и сортировка по умолчанию
- **Суть.** Каждый список пагинирован, у размера страницы есть максимум (в NetBox `MAX_PAGE_SIZE = 1000` по умолчанию {факт} [S73]); сортировка только по белому списку полей, иначе возможна утечка через сортировку по чувствительному полю {факт} [S95]. Подробности — в типовой задаче 1.
- **Как обнаружить.** Тест-обход роутера: каждый list-эндпоинт без `?limit` возвращает не больше страницы; `ordering_fields` задан явно.

#### Б07. Контроль числа запросов
- **Суть.** Тест каждого списка проверяет, что число запросов не растёт с числом объектов: `assertNumQueries` {факт} [S96], как `assert_database_query_count` в Zulip {факт} [S46]. В тестах включён django-zeal, падающий на N+1 {факт} [S39]. На Django 6.1 в критичном коде включается `FETCH_RAISE`, а для унаследованного кода — `FETCH_PEERS` через менеджер по умолчанию {факт} [S40].
- **Метрики.** Производительность, стабильность под нагрузкой.
- **Плюсы.** Самая частая причина медленных Django API ловится до прода.
- **Минусы.** zeal даёт 3–5 % накладных расходов {вендор} [S39], поэтому только в тестах.
- **Признаки оверинжиниринга.** Кэш поверх N+1 вместо исправления запроса; денормализация «на всякий случай».
- **Как обнаружить.** Тест с 1 и 10 объектами сравнивает число запросов; `pg_stat_statements` по `calls` показывает запросы с аномальным числом вызовов {факт} [S97].
- **Замечание.** В 6.1 вызов `select_related()` без аргументов объявлен устаревшим {факт} [S2].

#### Б08. Целостность и конкурентные изменения в базе
- **Суть.** Инварианты — ограничениями базы (`UniqueConstraint`, `CheckConstraint`), а не проверками в Python {факт} [S49]. Счётчики и балансы — `F()`-выражениями и условными `UPDATE`; уникальность — попыткой вставки с перехватом `IntegrityError` {мнение} [S76]. Чтение-изменение-запись — `select_for_update()` внутри транзакции, иначе Django бросает `TransactionManagementError` {факт} [S98]. Внешняя бизнес-транзакция — `atomic(durable=True)` {факт} [S99].
- **Метрики.** Стабильность, корректность данных.
- **Признаки оверинжиниринга.** Распределённые блокировки в Redis для того, что решает база; поле версии для оптимистичной блокировки на каждой модели; `SERIALIZABLE` глобально без обработки ошибок сериализации {факт} [S13].
- **Как обнаружить.** `grep -rn "lock(" ` по коду с клиентом Redis; поиск `isolation_level` в настройках.
- **Недоинжиниринг (встречается чаще).** `obj.balance += x; obj.save()` без блокировки; уникальность только в валидаторе сериализатора. Обнаружение: AST-проверка «атрибут модели изменён `+=`, затем `.save()`» {гипотеза}.

#### Б09. Миграции без простоя
- **Суть.** Изменения схемы и кода выкладываются раздельно и совместимы в обе стороны {факт} [S44]. Правила Sentry: новая колонка nullable или с `db_default`; переименование только в Django через `db_column`/`db_table`; удаление в две фазы; индексы `CONCURRENTLY` вне транзакции, а дольше 10 секунд — post-deploy миграцией; данные — пачками {факт} [S66]. Таймауты блокировок и запрет опасных операций даёт django-pg-zero-downtime-migrations {факт} [S65]. Миграции идут до раскатки кода, у Kraken — Helm pre-upgrade hook {факт} [S68].
- **Метрики.** Стабильность выкладок, частота выкладок.
- **Признаки оверинжиниринга.** Blue/green-клоны базы на каждую выкладку; собственный фреймворк миграций.
- **Как обнаружить.** CI: `makemigrations --check --dry-run`; для новых миграций `sqlmigrate` → Squawk с правилами `adding-not-nullable-field`, `require-concurrent-index-creation`, `require-lock-timeout` {факт} [S100]; `ZERO_DOWNTIME_MIGRATIONS_RAISE_FOR_UNSAFE = True` {факт} [S65]; django-linear-migrations против конфликтов веток {факт} [S74].
- **Недоинжиниринг (встречается чаще).** `AddField` с `NOT NULL` без значения по умолчанию на большой таблице; удаление поля в той же выкладке, что и кода.

#### Б10. Рантайм и соединения
- **Суть.** Gunicorn в режиме WSGI с потоками; число процессов, потоков и экземпляров считается по формуле соединений из раздела 1. Для WSGI — `CONN_MAX_AGE` с `CONN_HEALTH_CHECKS = True` {факт} [S13]; постоянные соединения ускоряют ответ, когда соединение с базой дорогое {факт} [S101].
- **Метрики.** Производительность, стабильность.
- **Признаки оверинжиниринга.** Тонкая настройка автоскейлинга до первого пользователя; несколько видов серверов приложений в одном проекте.
- **Как обнаружить.** Сравнить `SELECT count(*) FROM pg_stat_activity` с `max_connections` и формулой из README {гипотеза}.
- **Недоинжиниринг.** `CONN_MAX_AGE = 0` при managed PostgreSQL с TLS; таймауты запросов не заданы.

#### Б11. Фоновые задачи: надёжный минимум
- **Суть.** Один инструмент очереди; постановка после фиксации (`delay_on_commit` или `on_commit`); в задачу передаются ID, а не объекты; задачи идемпотентны, `acks_late` включается только для идемпотентных; ретраи с `retry_backoff` только для временных ошибок; таймауты на внешних вызовах {факт} [S12, S11]. Задача вызывает доменную функцию {мнение} [S48]. Для Redis-брокера visibility timeout больше самой длинной ETA, иначе задача повторяется по кругу {факт} [S102].
- **Метрики.** Стабильность, производительность ответа.
- **Признаки оверинжиниринга.** Canvas-цепочки и chord для линейной работы; отдельная очередь на каждый тип задачи; Kafka для внутренних задач одного монолита.
- **Как обнаружить.** Число очередей больше числа пулов воркеров; AST-поиск `.delay(` внутри `with transaction.atomic()` без `on_commit`; `grep -rn "delay(self\|delay(obj"` — передача объектов.
- **Тест.** `captureOnCommitCallbacks(execute=True)` проверяет, что задача ставится после фиксации {факт} [S96].
- **Недоинжиниринг.** Отправка почты, пушей и HTTP-вебхуков внутри запроса.

#### Б12. Наблюдаемость: минимальный набор
- **Суть.**
  1. Ошибки и выборочные трассировки — Sentry SDK: автоспаны middleware, SQL, Redis и кэша {вендор} [S83]; для установок без SaaS — GlitchTip на 256–512 MB RAM {факт} [S86].
  2. JSON-логи с `request_id` и `user_id` в каждой строке (django-structlog, поддерживает DRF и Ninja) {факт} [S103].
  3. Health-эндпоинты: живость без зависимостей, готовность с проверкой базы; Kraken использует один `/health/` с полной проверкой подсистем на старте {факт} [S68].
  4. `pg_stat_statements` на базе {факт} [S97].
  5. py-spy для разового профилирования живого процесса без перезапуска {факт} [S104].
- **Метрики.** Наблюдаемость, стабильность (время обнаружения и восстановления).
- **Признаки оверинжиниринга.** Полный стек OpenTelemetry + Prometheus + хранилища логов и трассировок для одного сервиса и трёх разработчиков; 100 % семплирование трассировок в проде; дашборды без просмотров.
- **Как обнаружить.** `grep traces_sample_rate` со значением `1.0` в боевых настройках; доля затрат на наблюдаемость в счёте за инфраструктуру {гипотеза}.
- **Недоинжиниринг.** Ошибки на почту — Django сам советует систему мониторинга, потому что почта «не масштабируется» {факт} [S101]; логи без идентификатора запроса.

#### Б13. Авторизация на уровне объекта и арендатора
- **Суть.** BOLA — первый риск OWASP API Top 10 2023 {факт} [S91]. Базовый `QuerySet` каждого представления ограничен текущим пользователем или компанией в `get_queryset` {факт} [S95]; доступ по ID через глобальный менеджер в API-коде запрещён; проверки прав живут в одном месте.
- **Метрики.** Безопасность, стабильность.
- **Признаки оверинжиниринга.** Внешний движок политик для трёх ролей; объектные права на каждую строку там, где хватает ролей.
- **Как обнаружить.** AST/grep по модулям API: `.objects.get(` и `.objects.filter(pk=` вне scoped-менеджеров; параметризованный тест: для каждого detail-маршрута объект чужой компании даёт 404; навык Sentry `django-access-review` для ревью IDOR {факт} [S105].
- **Недоинжиниринг (встречается чаще).** Фильтрация по компании есть в списке, но нет в detail, update и вложенных действиях.

#### Б14. Аутентификация
- **Суть.** Сессии для браузера на своём домене, непрозрачные токены на устройство для мобильного клиента, JWT только по сигналу Р10 (см. раздел 4) {факт} [S9, S54]. Токены хранятся хешированными, как токены v2 в NetBox {факт} [S73].
- **Признаки оверинжиниринга.** Собственный OAuth-сервер для своего мобильного приложения; JWT + ротация refresh + таблица отзыва в монолите — это сессии, написанные заново {мнение} [S54].
- **Как обнаружить.** В проекте с одним сервисом есть таблица чёрного списка JWT.

#### Б15. Конфигурация и секреты
- **Суть.** Один модуль настроек и переменные окружения; секреты из окружения или файла, ротация `SECRET_KEY` через `SECRET_KEY_FALLBACKS`; `check --deploy` против боевых настроек {факт} [S101]. Различия регионов и установок у клиентов — только в окружении и фича-флагах, образ один {факт} [S44].
- **Признаки оверинжиниринга.** Больше трёх файлов настроек с цепочками наследования; удалённый сервис конфигурации для одного деплоя.
- **Как обнаружить.** Подсчёт файлов в `config/settings`; `grep -rn "environ.get(\"SECRET"` с значением по умолчанию; `manage.py check --deploy --fail-level WARNING` в CI.

#### Б16. Тесты
- **Суть.** pytest и pytest-django (45 % и 34 % респондентов {эмпирика} [S27]); эндпоинты тестируются через тестовый клиент, доменные функции — напрямую; реальная PostgreSQL с PostGIS; `TestCase` с откатом транзакции быстрее `TransactionTestCase` {факт} [S96]; `--reuse-db` и xdist {факт} [S106]. Внешние вызовы мокаются, база — нет {мнение} [S48]. Ориентир скорости — Zulip: весь бэкенд менее чем за 30 секунд параллельно {факт} [S46].
- **Метрики.** Стабильность, скорость разработки.
- **Плюсы и минусы фабрик.** factory_boy сокращает код {мнение} [S48]; функции-фабрики проще типизировать и читать {мнение} [S55].
- **Признаки оверинжиниринга.** Моки ORM; гигантские JSON-фикстуры; пирамида из пяти видов тестов в проекте на 20 эндпоинтов.
- **Как обнаружить.** Тренд длительности тестов в CI; `grep -rn 'patch(".*objects'`; доля нестабильных тестов.
- **Недоинжиниринг (встречается чаще).** 19 % респондентов не имеют автотестов {эмпирика} [S27].

#### Б17. Типы, линтеры, форматирование
- **Суть.** Ruff как форматер и линтер с наборами `DJ`, `S`, `B` и другими {факт} [S92]; аннотации у доменных функций и схем; mypy с плагином django-stubs (нужны настройки Django) или Pyright с базовой поддержкой {факт} [S22]. Kraken потратил 2,5 года на 5 млн строк {факт} [S45], поэтому в новом проекте строгость дешевле включить сразу {гипотеза}.
- **Признаки оверинжиниринга.** Несколько пересекающихся линтеров; строгий mypy на весь унаследованный код как блокирующая проверка; собственные плагины проверки типов в малом проекте.
- **Как обнаружить.** Тренд числа `# type: ignore`; время проверки типов в CI.
- **Недоинжиниринг.** Нет форматера — шумные диффы, которые мешают ревью кода агентов.

### Карточки «добавлять по сигналу»

| ID | Практика | Сигнал и порог | Главный риск без сигнала | Как откатить |
|---|---|---|---|---|
| Р01 | ASGI и async-представления | SSE/WebSocket или 3+ независимых внешних вызова в запросе, ожидание которых даёт больше половины p95 (ориентир) | Нет async-транзакций, переключения контекста, сложные тесты {факт} [S33, S34] | Вернуть `def`-представления на WSGI |
| Р02 | Пул Django или PgBouncer | Соединения выше 70–80 % `max_connections` или заметная доля времени на установку TLS-соединений (ориентир) | Лишний компонент; с PgBouncer ломаются server-side cursors {факт} [S13] | Убрать `pool`, вернуть `CONN_MAX_AGE` |
| Р03 | Реплики чтения | CPU основной базы выше 60–70 % после оптимизации запросов, чтения преобладают, задержка реплики допустима (ориентир) | Роутер Django не решает лаг репликации и read-your-writes {факт} [S107] | Удалить роутер |
| Р04 | Кэш данных в Redis | p95 эндпоинта выше цели из-за повторяющихся одинаковых запросов, данные меняются редко, ключ инвалидации очевиден (ориентир) | Устаревшие данные; `cache_page` не различает пользователей {факт} [S108] | Удалить декоратор или вызов |
| Р05 | Границы модулей: Import Linter, tach, фасады | 15–20+ приложений, циклические импорты, 8–10+ разработчиков или агентов параллельно (ориентир) | Церемонии без выигрыша в малом коде | Удалить контракты из конфигурации |
| Р06 | OpenTelemetry | Больше одного сервиса в цепочке запроса или требование заказчика к вендор-нейтральности | Коллектор и бэкенд трассировок на поддержке | Оставить Sentry SDK |
| Р07 | Prometheus-метрики | Нужны алерты по SLO на частоты и задержки, Prometheus уже есть | Ограничения multiprocess-режима: нет custom collectors, Info/Enum, нужна очистка каталога {факт} [S88] | Удалить экспортёр |
| Р08 | Celery вместо простой очереди | Несколько очередей с приоритетами, маршрутизация, сотни тысяч задач в день, chord-сценарии (ориентир) | Брокер и его отказы, visibility timeout {факт} [S102] | Процедура переноса задач на другой бэкенд |
| Р09 | Изоляция арендаторов сильнее общей базы | Договорное или регуляторное требование | Стоимость миграций на схемах {эмпирика} [S38] | Дорогой; решать до продажи |
| Р10 | JWT | Несколько независимых сервисов проверяют токен | Отзыв требует состояния {мнение} [S54] | Перейти на непрозрачные токены с принудительным перелогином |
| Р11 | Внешний поисковый движок | PostgreSQL FTS с GIN-индексом не даёт нужной релевантности, опечаток или фасетов на объёме десятков миллионов документов (ориентир) | Синхронизация индекса, второй источник правды | Вернуть запросы к PostgreSQL |
| Р12 | Партиционирование и архив больших таблиц | Таблицы событий и истории в сотни миллионов строк или удаление по сроку хранения (ориентир) | Сложные миграции; pghistory советует решать заранее {факт} [S109] | Сложно; решать при проектировании |
| Р13 | Версионирование API сверх `v1` | В поле есть версии мобильного приложения, которые нельзя заставить обновиться | Двойная поддержка кода; DRF допускает и системы без версий {факт} [S110] | Объявить срок жизни старой версии |
| Р14 | orjson и оптимизация сериализации | Профиль py-spy показывает JSON-кодирование в верхних строках (ориентир: больше 10–15 % времени запроса) | Почти нет: замена рендерера {вендор} [S75] | Вернуть стандартный рендерер |
| Р15 | Нагрузочное тестирование в CI | Ожидаемый RPS больше, чем вдвое превышающий проверенный в проде (ориентир), или SLO в договоре | Время CI, стенд | Запускать вручную перед релизами |
| Р16 | Строгая типизация (mypy strict) | Код больше 50 тыс. строк или много параллельных авторов, включая агентов (ориентир) | Время на аннотации чужих библиотек | Ослабить до базового режима по модулям |

Пояснения к самым спорным расширениям:

- **Р01, ASGI.** Документация Django связывает выгоду с сотнями соединений без потоков, долгими и стриминговыми ответами {факт} [S33]. Kraken применяет async для параллельных вызовов LLM-агентов и отмечает, что для большинства задач очереди проще {мнение} [S34]. Под ASGI постоянные соединения отключаются, транзакционный код оборачивается в `sync_to_async` {факт} [S13, S33]. Детекция оверинжиниринга: доля `async def` представлений, внутри которых только `sync_to_async`-вызовы ORM, — выигрыша нет, есть переключения {гипотеза}.
- **Р03, реплики.** Роутер из документации Django отправляет чтение на случайную реплику и «не решает» лаг репликации {факт} [S107]. Минимальная защита — читать с основной базы в течение запроса, который писал, и в фоновых задачах, поставленных после записи {гипотеза}.
- **Р05, границы.** Import Linter поддерживает контракты layers, independence, forbidden, protected и acyclic siblings {факт} [S111]; Kraken держит 40+ контрактов и ведёт счётчик игнорируемых импортов как метрику техдолга {факт} [S3]. Признак оверинжиниринга — контракты в проекте из пяти приложений, где нет ни одного нарушения за полгода {гипотеза}.
- **Р08, Celery.** Kraken живёт на Celery с RabbitMQ при 9 млн строк {факт} [S67, S44]; Healthchecks.io обходится systemd-сервисами без очереди {факт} [S71]. Масштаб проекта, а не мода, определяет выбор.

### Типовые задачи

#### 1. Списки: фильтры, сортировка, пагинация

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| Limit/offset или номер страницы + `COUNT(*)` | Переход на любую страницу, общее число | `COUNT(*)` на большой таблице доминирует во времени ответа: 781 мс из 786 мс в замере Бениты {эмпирика} [S37] | Таблицы до сотен тысяч строк, админские экраны |
| Cursor (keyset) pagination | Фиксированное время на любой глубине, нет дублей при вставках {факт} [S78] | Нет перехода на произвольную страницу; поле сортировки уникальное, неизменное, с индексом {факт} [S78] | Ленты, синхронизация, большие таблицы; в Ninja с 1.6 {факт} [S57] |
| Offset + count с таймаутом | Сохраняет UX номеров страниц | Число страниц приблизительное | Унаследованные экраны, см. лайфхаки |

- Фильтры через django-filter (`DjangoFilterBackend`) или параметры схемы Ninja; сортировка только по `ordering_fields` {факт} [S95].
- Тяжёлые списки отдают «краткое» представление, как `?brief=true` в NetBox {факт} [S73].
- Признаки оверинжиниринга: собственный язык запросов в query string, GraphQL ради фильтров у одного клиента.
- Обнаружение: тест на максимальный размер страницы; `EXPLAIN` для каждого фильтра с индексом в тесте производительности {гипотеза}.

#### 2. Права на объект и разделение данных по компаниям

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| `company_id` + scoped-менеджер + `get_queryset` | Просто, работает с ORM и админкой | Ошибка в одном месте открывает данные | По умолчанию |
| + PostgreSQL RLS | Гарантия на уровне базы, default-deny без политик {факт} [S89] | Владелец таблицы обходит RLS без `FORCE`; контекст надо сбрасывать на пулах соединений {факт} [S89] | Требование аудита |
| Схема на арендатора | Изоляция по схеме | `migrate_schemas` растёт с числом схем {эмпирика} [S38] | Десятки крупных арендаторов |
| Экземпляр на регион или клиента | Полная изоляция и резидентность | Выкладка во многие окружения | Регионы и on-prem; Kraken и Sentry {факт} [S44, S4] |

- Роли внутри компании — группы и права Django или поле роли на членстве; объектные права только там, где доступ различается внутри одной компании {гипотеза}.
- Межрегиональные ссылки при экземплярах на регион — без внешних ключей, через outbox и tombstones, как в Sentry {факт} [S69].
- Признаки оверинжиниринга: схемы на арендатора для сотен мелких клиентов; движок ABAC для трёх ролей.
- Обнаружение: тест «чужой объект = 404» для каждого маршрута; запрос к базе на строки, где `company_id` объекта не совпадает с `company_id` родителя {гипотеза}.

#### 3. Массовый импорт и экспорт

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| Поштучный `save()` | Срабатывают сигналы и `save()` | 128,8 с на 32 500 строк в замере {эмпирика} [S36] | До тысячи строк |
| `bulk_create` / `bulk_update` пачками | Быстро, `ON CONFLICT` через `update_conflicts` {факт} [S98] | Нет `save()` и сигналов {факт} [S98]; аудит на сигналах пропустит {факт} [S112] | Тысячи — сотни тысяч строк |
| `COPY` во временную таблицу + `INSERT … SELECT` | 0,46 с на 32 500 строк из итератора {эмпирика} [S36] | Сырой SQL, проверки вне ORM | Миллионы строк, регулярные загрузки |

- Импорт — фоновая задача: загрузка файла, задача по ID, отчёт об ошибках по строкам, идемпотентность через ключ импорта {гипотеза}.
- Экспорт больших объёмов — `iterator(chunk_size=…)` и файл в объектное хранилище; `prefetch_related` в `iterator()` работает только с `chunk_size` {факт} [S98].
- Признаки оверинжиниринга: конвейер на брокере сообщений для еженедельного CSV.

#### 4. Файлы

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| Загрузка через Django | Просто, валидация в API | Воркер занят на время загрузки | Небольшие файлы |
| Presigned URL в S3-совместимое хранилище | Файл идёт мимо Django, без учётных данных у клиента {факт} [S113] | Ключ перезаписывается при совпадении {факт} [S113]; нужна проверка после загрузки | Крупные файлы, мобильные клиенты |

- django-storages: подписанные URL по умолчанию живут 3600 с, `file_overwrite` по умолчанию `True`, `endpoint_url` подключает S3-совместимые хранилища, в том числе self-hosted {факт} [S114].
- Для установок у клиентов — self-hosted S3-совместимое хранилище; Healthchecks.io ушёл с managed-хранилища на self-hosted из-за задержек операций {факт} [S115].
- Признаки оверинжиниринга: собственный файловый сервис рядом с S3.

#### 5. Фоновые и периодические задачи

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| Management command в цикле или по таймеру systemd/cron | Ноль инфраструктуры {факт} [S71] | Ретраи и параллелизм — свои | 1–3 постоянных процесса |
| `django.tasks` + django-tasks-db | Стандартный API, только PostgreSQL, статус в админке {факт} [S52] | Нет ретраев и расписания в ядре {факт} [S53] | Малые объёмы |
| Procrastinate | Periodic, ретраи, блокировки на PostgreSQL {факт} [S80] | Меньше экосистемы | Средние объёмы без брокера |
| Celery + beat | Максимум возможностей {факт} [S12] | Брокер, visibility timeout, ETA-ловушки {факт} [S102] | Тяжёлая периодическая обработка, много очередей |

- Тяжёлая периодическая обработка: разбить на пачки по ID, каждая пачка — отдельная идемпотентная задача; блокировка от параллельного запуска одного и того же периодического задания (`select_for_update(skip_locked=True)` или блокировки очереди) {гипотеза}.
- Признаки оверинжиниринга: Celery canvas для линейного процесса; отдельный кластер воркеров на каждую задачу.

#### 6. Вебхуки: входящие и исходящие

- **Входящие.** Проверить подпись по сырому телу, сохранить событие с уникальным внешним ID (уникальный индекс отсекает повтор), ответить 2xx, обработать в задаче {гипотеза}.
- **Исходящие.** Событие пишется в таблицу outbox в той же транзакции, отдельный процесс доставляет; доставка «хотя бы один раз», получатель обязан быть идемпотентным {факт} [S116]. Подпись и заголовки по Standard Webhooks: `webhook-id`, `webhook-timestamp`, `webhook-signature`, HMAC-SHA256, защита от replay и SSRF {факт} [S117].
- Таймаут доставки ограничен: Saleor ждёт ответа не более 20 секунд и разделяет синхронные и асинхронные вебхуки {факт} [S25].

| Вариант исходящих | Плюсы | Минусы | Когда |
|---|---|---|---|
| Задача из `on_commit` | Просто | Задача теряется, если процесс упал между фиксацией и постановкой {гипотеза} | Некритичные уведомления |
| Outbox-таблица + доставщик | Гарантия «сообщение есть, если есть транзакция» {факт} [S116] | Дубли, нужен доставщик {факт} [S116] | Платёжные и договорные события |

- Признаки оверинжиниринга: собственная шина событий с подписками для пяти получателей.

#### 7. Уведомления (почта, пуш, внутри приложения)

- Запись уведомления в таблицу в той же транзакции, доставка задачей по каналам; повтор через идемпотентный ID доставки {гипотеза}.
- Почтовые бэкенды с Django 6.1 настраиваются через `MAILERS`, что упрощает разделение транзакционной и маркетинговой почты {факт} [S2].
- Признаки оверинжиниринга: собственный «сервис уведомлений» с шаблонизатором и правилами маршрутизации для двух типов писем.

#### 8. Отчёты и агрегаты

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| Агрегация ORM на лету (`annotate`, `aggregate`) | Всегда актуально | Нагрузка растёт с объёмом | Небольшие объёмы, есть индексы |
| Материализованное представление + `REFRESH … CONCURRENTLY` | Чтение не блокируется | Нужен уникальный индекс, один refresh за раз {факт} [S118] | Отчёты с допустимой задержкой |
| Таблица агрегатов, обновляемая задачей | Полный контроль | Код инкрементального пересчёта | Тяжёлые периодические расчёты |

- Признаки оверинжиниринга: отдельное аналитическое хранилище для десятка отчётов; PostHog уводит в отдельный стек аналитику событий, а не бизнес-отчёты {гипотеза}.

#### 9. Поиск

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| `icontains` / триграммы `pg_trgm` | Просто, нечёткие совпадения {факт} [S119] | Медленно без индекса | Поиск по имени и коду |
| PostgreSQL FTS: `GeneratedField` + `SearchVectorField` + GIN | Ранжирование, словари; без индекса проблемы начинаются после «нескольких сотен записей» {факт} [S119] | Ограниченная релевантность | По умолчанию |
| Внешний движок | Опечатки, фасеты | Второй источник правды | Только по сигналу Р11 |

#### 10. Офлайн-синхронизация мобильного клиента

- Протокол pull/push с меткой последней синхронизации, как в WatermelonDB: сервер ставит `last_modified` собственным временем и не доверяет клиентскому; удаления хранятся как tombstones; push отклоняется, если запись изменилась на сервере после `lastPulledAt`; push полностью транзакционен; pull делается консистентным снимком {факт} [S120].
- Идентификаторы создаются на клиенте; `UUID7()` в Django 6.1 даёт сортируемые по времени UUID {факт} [S2].
- Повторы push защищаются ключом идемпотентности (задача 14).

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| `updated_at` + tombstones + отказ при конфликте | Просто, понятные конфликты | Клиент должен перетянуть и повторить | По умолчанию |
| Журнал изменений (триггеры, pghistory) как источник pull | Ловит и bulk-операции {факт} [S109] | Растущие таблицы событий | Много массовых изменений на сервере |
| CRDT и слияние полей | Работа без конфликтов | Сложность на обеих сторонах | Совместное редактирование одних записей |

- Признаки оверинжиниринга: CRDT для данных, которые редактирует один пользователь.

#### 11. Геоданные (GeoDjango и PostGIS)

- PostGIS — рекомендованный бэкенд GeoDjango; Django 6.1 требует PostgreSQL 15+ {факт} [S63, S2].
- Для запросов по расстоянию в WGS84 — `geography=True`, иначе пространственный индекс не используется и расстояние считается для каждой строки {факт} [S121].
- Тесты с PostGIS в CI, а не на SQLite.
- Признаки оверинжиниринга: отдельный гео-сервис для поиска «ближайших точек» в пределах одной базы.

#### 12. WebSocket и SSE

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| Поллинг с ETag/`updated_since` | Работает на WSGI | Задержка, лишние запросы | Обновления раз в десятки секунд |
| SSE через `StreamingHttpResponse` с async-итератором под ASGI | Без Channels {факт} [S122]; в Ninja стриминг SSE с 1.6 {факт} [S57] | Под WSGI занимает воркер на всё время ответа {факт} [S122] | Поток сервер → клиент |
| Django Channels | Двусторонний WebSocket, группы через Redis | Сопровождение best-effort {факт} [S64] | Чат, совместная работа |
| Отдельный realtime-процесс | Изоляция долгих соединений | Второй рантайм | Десятки тысяч соединений, как Tornado у Zulip {факт} [S6] |

#### 13. Аудит изменений

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| django-simple-history (сигналы) | Просто, история в Django-моделях | Не пишет `bulk_*` и `update()` без специальных функций {факт} [S112] | Правки идут через `save()` |
| django-pghistory (триггеры) | Ловит любые изменения, без round trip {факт} [S109] | Только PostgreSQL; контекст стоит лишней записи {факт} [S109] | Есть bulk-операции, `DB_CASCADE`, SQL |
| Явный журнал событий в доменных функциях | Бизнес-смысл события | Нужно не забыть | Юридически значимые действия |

- Конфликт: `DB_CASCADE` не вызывает сигналы `pre_delete`/`post_delete` {факт} [S2] — сигнальный аудит удалений теряется.

#### 14. Идемпотентность и повторы

- Заголовок `Idempotency-Key` (черновик IETF): ключ уникален, рекомендуется UUID; повтор с тем же ключом возвращает сохранённый результат; запрос с ключом, пока первый не завершён, — `409`; тот же ключ с другим телом — `422` {факт} [S123].
- Реализация: таблица ключей с уникальным индексом `(key, client)`, отпечаток тела, статус и сохранённый ответ; запись ключа в той же транзакции, что и эффект; очистка по сроку {гипотеза}.
- Черновик IETF истёк и архивирован, это не стандарт {факт} [S123].
- Признаки оверинжиниринга: ключи идемпотентности на GET и на операциях, которые и так идемпотентны (PUT по ID).

#### 15. Ограничение частоты

- DRF throttling не является защитой от перебора и DoS, допускает гонки и нечёткость под конкуренцией {факт} [S79]; за прокси нужно правильно задать `NUM_PROXIES` {факт} [S79].
- Защита от злоупотреблений — на прокси или балансировщике; в приложении — бизнес-квоты на Redis, как rate limiting в Zulip {факт} [S6]. Ninja с 1.7 добавляет `Retry-After` в ответы 429 {факт} [S57].
- Признаки оверинжиниринга: собственный распределённый лимитер с точным счётом для внутреннего API.

#### 16. Версии API

- По умолчанию — один `v1` в URL и только аддитивные изменения; новая версия — только по сигналу Р13 {гипотеза}. DRF поддерживает пять схем версионирования и отмечает, что системы без версий тоже бывают уместны {факт} [S110]. Ninja поддерживает несколько версий API в одном проекте {факт} [S10].
- Признаки оверинжиниринга: версии на каждое изменение; дублирование всех сериализаторов «на будущее».
- Обнаружение: diff OpenAPI в CI помечает удаление полей и изменение типов как ломающее.

#### 17. Фича-флаги

| Вариант | Плюсы | Минусы | Когда |
|---|---|---|---|
| Переменные окружения | Ноль кода | Нужна перевыкладка | Различия регионов и клиентов |
| Настройки в базе | Мгновенное переключение | Своя админка | Kraken использует оба варианта {факт} [S44] |
| django-waffle: flags, switches, samples | Проценты, пользователи, группы {факт} [S124] | Ещё одна зависимость | Постепенные раскатки |

- Признаки оверинжиниринга: SaaS-платформа флагов для пяти флагов; флаги, живущие дольше квартала.
- Обнаружение: скрипт сверяет флаги в коде с флагами в базе и выводит неиспользуемые и старые.

### Лайфхаки и удачные костыли

| Приём | Зачем | Перестаёт работать, когда | Источник |
|---|---|---|---|
| `COUNT(*)` пагинатора под `statement_timeout` 200 мс с подменой числа при таймауте | Списки на больших таблицах без смены UX | Клиенту нужен точный итог | {эмпирика} [S37] |
| `FETCH_PEERS` в менеджере по умолчанию для старого кода | Убрать большинство N+1 без ручной расстановки `select_related` | Нужны точные `only()` и минимальный объём данных | {факт} [S40] |
| Переименование поля только в Django через `db_column` | Нет блокирующего `ALTER TABLE … RENAME` | Имя колонки читают внешние системы | {факт} [S66] |
| Фоновый процесс как management command под systemd | Нет брокера и очереди | Нужны ретраи, параллелизм, расписание многих задач | {факт} [S71] |
| `gc.collect()` после каждой миграции на Python 3.14 | Обойти OOM `migrate` | После патча Python с откатом incremental GC | {факт} [S59] |
| `max_migration.txt` из django-linear-migrations | Конфликт веток миграций виден в git, а не в проде | Миграции пишет один человек | {факт} [S74] |
| Симуляция будущих границ (регион, модуль) в CI патчем ORM | Проверить разделение до физического разделения | После завершения разделения | {факт} [S4] |
| Вынести один горячий эндпоинт в отдельный процесс на другом рантайме | Снять основную нагрузку CPU | Логика эндпоинта начинает расти и дублировать домен | {эмпирика} [S43] |
| `?brief=true` для облегчённых списков | Меньше полей и запросов | Клиентов с разными наборами полей становится много | {факт} [S73] |

### Сквозной сценарий

Пример, иллюстрация: B2B-сервис учёта полевых работ; команда из 4 человек, около половины кода пишут ИИ-агенты; три региональных экземпляра и две установки у клиентов; мобильное приложение с офлайн-режимом; ночной перерасчёт по геоданным.

| Неделя | Действие | Артефакт | Проверка |
|---|---|---|---|
| 1 | Скелет, настройки, CI с Ruff, mypy, `makemigrations --check`, Squawk, pytest | Репозиторий из раздела 6, AGENTS.md | Пустой PR проходит CI за 3–4 минуты (иллюстрация) |
| 2 | Модели `Company`, `Membership`, `Site` с `PointField(geography=True)`, scoped-менеджеры | Миграции 0001–0003 | Тест «чужая компания = 404» на все маршруты |
| 3 | API списков с cursor pagination, фильтрами и белым списком сортировки | `openapi.yaml` в репозитории | `assertNumQueries` для 1 и 10 объектов |
| 4 | Синхронизация мобильного клиента: pull по `updated_at`, tombstones, push с `Idempotency-Key` | Эндпоинты `/sync/pull`, `/sync/push` | Тест конфликта: push после изменения на сервере даёт отказ |
| 5 | Фоновые задачи: Procrastinate или Celery, ночной перерасчёт пачками по 1 000 ID (пример) | `tasks.py`, расписание | `captureOnCommitCallbacks`, тест идемпотентности |
| 6 | Наблюдаемость: Sentry SDK в регионах, GlitchTip в установках клиентов, JSON-логи | Настройки `LOGGING`, health-эндпоинты | Искусственная ошибка видна в трекере за минуту |
| 8+ | Сигналы: при росте соединений до 80 % — пул Django; при 20 приложениях — Import Linter | Записи в журнале решений | Метрики из раздела 8 |

### Типичные ошибки первого применения

1. Задача ставится внутри транзакции без `on_commit` и не находит объект {факт} [S12].
2. Список без пагинации и без проверки числа запросов.
3. `fields = "__all__"` в сериализаторе открывает внутренние поля.
4. Добавление `NOT NULL`-поля без значения по умолчанию в одной выкладке с кодом.
5. Фильтрация по компании только в списке, но не в detail и вложенных действиях.
6. ASGI «потому что быстрее», при этом весь код синхронный.
7. Ошибки на почту и логи без `request_id`.
8. JWT с долгим сроком жизни и без отзыва для собственного мобильного клиента.
9. Аудит на сигналах в проекте, где импорт идёт через `bulk_create` {факт} [S112].
10. `cache_page` на эндпоинте, ответ которого зависит от пользователя {факт} [S108].

### Что происходит через месяцы

- Счётчики техдолга, которые только уменьшаются, работают: у Kraken осталось 15 игнорируемых импортов {факт} [S3], PostHog запрещает рост пересечений моделей {факт} [S5].
- Строгая типизация большого кода — проект на годы: 2,5 года у Kraken {факт} [S45].
- Схемы на арендатора дорожают с ростом числа клиентов {эмпирика} [S38].
- Таблицы аудита и контекста растут вместе с индексами {факт} [S109].
- Горячий путь проявляется через полгода роста: у Healthchecks.io CPU пошёл вверх примерно через 6 месяцев после запуска {эмпирика} [S43].

### Стоимость входа

| Статья | Оценка | Основание |
|---|---|---|
| Деньги на софт | 0: Django, DRF, Ninja, Celery, Procrastinate, GlitchTip — open source | {факт} [S85, S80] |
| Self-hosted Sentry | 4 CPU, 16 GB RAM + 16 GB swap | {факт} [S84] |
| Self-hosted GlitchTip | 256–512 MB RAM | {факт} [S86] |
| Время на базовый набор | 1–2 недели опытного разработчика на скелет и CI (ориентир) | {гипотеза} |
| Компетенции | PostgreSQL (блокировки, индексы, `EXPLAIN`), транзакции Django, основы очередей | {гипотеза} |

### Что меняется для соло-проекта и для нагрузки на порядок выше

- **Соло.** Убрать Р05 и Р07; фоновые процессы — management commands под systemd или django-tasks-db; ошибки — GlitchTip; одна база без реплик. Пример Healthchecks.io: обычные серверы, без контейнеров и автоскейлинга {факт} [S71].
- **Нагрузка ×10.** Пул или PgBouncer (Р02), реплики (Р03), разделение очередей по приоритетам, партиционирование таблиц событий (Р12), нагрузочные тесты (Р15), границы модулей (Р05). Горячий эндпоинт — кандидат на вынос в отдельный процесс только после профилирования {гипотеза}.

## 6. Артефакты {#artifacts}

Ниже — артефакты, которые порождает базовый набор. **Конфигурации — стартовые примеры, а не стандарт: значения порогов и лимитов помечены как пример и подбираются под проект.** Синтаксис опций Django, DRF, Ruff, django-stubs и pytest-django взят из их документации {факт} [S13, S78, S92, S22, S106].

### 6.1. Скелет проекта

- **Назначение.** Одинаковое место для каждого вида кода, чтобы человек и агент находили его без поиска.
- **Жизненный цикл.** Создаётся в первый день; новые приложения добавляются по бизнес-возможностям; структура пересматривается, когда приложений становится 15–20 (сигнал Р05).

```text
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`:

```python
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`:

```toml
[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "W", "I", "B", "UP", "DJ", "S", "C4", "SIM", "DTZ", "T20", "C90", "PL", "RUF"]
ignore = ["PLR2004"]

[tool.ruff.lint.per-file-ignores]
"**/tests/**" = ["S101", "PLR2004"]

[tool.ruff.lint.mccabe]
max-complexity = 10                     # пример

[tool.mypy]
python_version = "3.12"
plugins = ["mypy_django_plugin.main"]
check_untyped_defs = true
warn_unused_ignores = true

[[tool.mypy.overrides]]
module = ["apps.*.services", "apps.*.api.*"]
disallow_untyped_defs = true            # новые слои типизируются полностью

[tool.django-stubs]
django_settings_module = "config.settings"

[tool.pytest.ini_options]
DJANGO_SETTINGS_MODULE = "config.settings"
addopts = "--reuse-db"
filterwarnings = ["error::DeprecationWarning"]  # исключения для сторонних пакетов — точечно
```

### 6.4. Проверки CI

- **Назначение.** Ворота качества, одинаковые для кода людей и агентов.
- **Жизненный цикл.** Каждый шаг привязан к карточке; шаг, который ни разу не падал за полгода и дорог по времени, переводится в ночной прогон {гипотеза}.

| Шаг | Команда (пример) | Ловит | Карточка |
|---|---|---|---|
| 1 | `uv sync --locked` | Расхождение lock-файла | Б01 |
| 2 | `ruff format --check . && ruff check .` | Стиль, баги, безопасность | Б17 |
| 3 | `mypy .` | Типы | Б17 |
| 4 | `python manage.py check --deploy --fail-level WARNING` с боевыми настройками | Небезопасная конфигурация | Б15 |
| 5 | `python manage.py makemigrations --check --dry-run` | Забытые миграции | Б09 |
| 6 | `sqlmigrate` для новых миграций → файл → Squawk | Блокирующий DDL | Б09 |
| 7 | `python manage.py spectacular --file openapi.yaml --validate && git diff --exit-code openapi.yaml` | Незафиксированное изменение контракта | Б04 |
| 8 | `pytest -n auto` с django-zeal и тестами числа запросов | Регрессии, N+1, предупреждения устаревания | Б07, Б16 |
| 9 | `python scripts/checks/run_all.py` | `__all__` в схемах, `.objects.get(` в API, `traces_sample_rate=1.0`, `.delay(` внутри `atomic` | Б03, Б11, Б12, Б13 |
| 10 | `lint-imports` | Нарушение границ модулей | Р05 |
| 11 | Schemathesis против локального сервера (ночью) | Ответы вне схемы, 5xx | Б04 |

### 6.5. Чек-лист ревью PR (человек или агент-ревьюер)

- **Назначение.** Проверить то, что не ловится автоматически.
- **Жизненный цикл.** Пункт, который удалось автоматизировать, переносится в CI и удаляется из чек-листа.

1. Новый эндпоинт ограничивает `QuerySet` компанией или пользователем; есть тест «чужой объект = 404».
2. Схема ввода перечисляет поля явно; схема вывода не раскрывает внутренние поля.
3. Список пагинирован, сортировка по белому списку, есть тест числа запросов.
4. Сценарий из нескольких моделей — в одной доменной функции под `transaction.atomic`.
5. Задачи ставятся после фиксации, получают ID, идемпотентны.
6. Миграция совместима со старым кодом: nullable или `db_default`, без переименований и удалений в той же выкладке.
7. Внешние вызовы с таймаутом и обработкой ошибок.
8. Нет новых слоёв, абстракций и зависимостей без сигнала из карточек Р.
9. Изменение OpenAPI ожидаемо и обратно совместимо.
10. Логи несут контекст (`request_id`, ID объекта), без персональных данных.

### 6.6. Чек-лист аудита существующего проекта

- **Назначение.** Найти недо- и оверинжиниринг в работающем проекте.
- **Жизненный цикл.** Проходится раз в квартал и перед крупным обновлением Django.

| Проверка | Как выполнить автоматически | Норма |
|---|---|---|
| Самые дорогие запросы | `SELECT query, calls, total_exec_time, mean_exec_time FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 20;` {факт} [S97] | Верх списка объясним и проиндексирован |
| Использование соединений | `SELECT count(*) FROM pg_stat_activity;` против `max_connections` | Ниже 70–80 % (ориентир) |
| Неиспользуемые индексы | `SELECT indexrelname FROM pg_stat_user_indexes WHERE idx_scan = 0;` | Пусто или объяснимо |
| N+1 | django-zeal на полном прогоне тестов | Ноль срабатываний вне allowlist |
| Сервисы-прокладки | AST-скрипт по `services.py` | Меньше 20–30 % функций из одного вызова ORM (ориентир) |
| Сигналы для бизнес-процессов | Подсчёт `@receiver` и `.connect(` | Только для развязки и аудита |
| Неиспользуемые фича-флаги | Сверка флагов в коде и в базе | Нет флагов старше квартала |
| Версия Django | Сравнение с таблицей поддержки | Поддерживаемая, предупреждений нет |
| BOLA | Параметризованный тест по всем detail-маршрутам | 404 на чужие объекты |

### 6.7. AGENTS.md

- **Назначение.** Короткий набор правил для ИИ-агентов; формат открыт, ближайший к файлу AGENTS.md имеет приоритет {факт} [S62]. Sentry требует AGENTS.md в каждом SDK-репозитории с обзором архитектуры, тестовыми соглашениями, сборкой, ожиданиями к вкладу и атрибуцией коммитов {факт} [S125]. Длина — ориентир «экран-два»: длинный файл агент читает хуже, чем ссылки на проверки CI {гипотеза}.
- **Жизненный цикл.** Пополняется, когда агент дважды ошибся одинаково; правило, которое закрыто проверкой CI, сокращается до ссылки на проверку.

```text
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 % в течение квартала» (иллюстрация).

## 7. С чем используется в связке {#combo}

### Что предшествует и что следует

- **Предшествует:** 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] |

## 8. Метрики здоровья и антипаттерны {#health}

Нормы без источника — ориентиры автора и помечены словом «ориентир». **Метрика полезна, только если у неё есть автоматический сбор и владелец, который реагирует на деградацию** {гипотеза}.

| Признак | Здоровая норма | Симптом деградации | Источник |
|---|---|---|---|
| Время полного прогона тестов | Ориентир по эталонам: весь бэкенд 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`, сравнение с таблицей поддержки |

## 9. Инструменты и софт {#tools}

Все перечисленные библиотеки — 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 по модулям |

## 10. Адаптация под LLM и агентов {#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] |

## 11. Происхождение, ключевые фигуры, что читать {#origins}

### Происхождение и этапы

| Этап | Какую боль решал | Что актуально сейчас | Источник |
|---|---|---|---|
| 2003–2005: Django в газете Lawrence Journal-World (Адриан Головати, Саймон Уиллисон, Джейкоб Каплан-Мосс), публичный релиз в июле 2005 | Быстрая разработка сайтов с базой данных | Принцип «батарейки в комплекте» объясняет, почему auth, админка и миграции — не сторонние решения | {факт} [S131] |
| 2008: DSF и Django 1.0 со стабильным API | Предсказуемость для бизнеса | Политика совместимости и предупреждений об устаревании | {факт} [S131] |
| С 2011: Django REST framework (Encode) | Нет стандартного API-слоя | 73 % пользователей API-фреймворков; с 2024 — feature-complete | {факт} [S132, S28, S31] |
| 2019–2020: ASGI в Django 3.0, async-представления в 3.1 | Долгие соединения и I/O-конкурентность | Async по-прежнему без транзакций | {факт} [S131, S33] |
| 2020: «Against service layers» Беннетта | Реакция на перенос паттернов Data Mapper в Active Record | Главный спор о месте логики | {мнение} [S50] |
| Около 2020: Django Ninja (самые старые открытые issues датированы 2020 годом) | Интеграция подхода FastAPI с Django ORM и auth | 17 % пользователей API-фреймворков | {факт} [S32, S10, S28] |
| 2020: `atomic(durable=True)` после обсуждения в Kraken | Вложенные `atomic` скрывали момент фиксации | Внешняя транзакция бизнес-операции | {факт} [S99] |
| 2023–2024: `db_default`, пул соединений | Безопасные миграции, задержка соединений | Базовый набор Б09 и Р02 | {факт} [S56, S14] |
| 2024: DEP 14 (Джейк Говард), 2025: `django.tasks` в 6.0 | Нет общего API фоновых задач | Стандартный API без воркера в ядре | {факт} [S133, S15] |
| 2026: fetch modes в 6.1, DEP 20 о годовом цикле | N+1 «по умолчанию», непредсказуемый цикл LTS | Новый способ гасить N+1, обновление раз в год с 2028 | {факт} [S2, S17] |

### Ключевые фигуры

- **Джеймс Беннетт** — против сервисного слоя в Django {мнение} [S50].
- **Люк Плант** — тонкие представления, цепочки `QuerySet`, фабрики-функции в тестах {мнение} [S51, S55].
- **HackSoft** — services/selectors как систематический шаблон {мнение} [S48].
- **Адам Джонсон** — инструменты автоматизации рутины Django: django-upgrade, django-linear-migrations, django-orjson, django-mcpz {факт} [S127, S74, S75, S128].
- **Хаки Бенита** — работа с PostgreSQL через ORM с измерениями {эмпирика} [S36, S37].
- **Сопровождающие DRF** — объявили проект завершённым по функциям {факт} [S31].
- **Карлтон Гибсон** — сопровождение Django Channels в режиме best-effort {факт} [S64].
- **Виталий Кучерявый** — автор Django Ninja {факт} [S10].
- **Дэвид Седдон, Дэвид Уинтерботтом (Kraken)** — описали слои и контракты Import Linter в монолите Kraken и путь к `durable=True` {факт} [S3, S99].
- **Джейк Говард** — автор DEP 14 и `django.tasks` {факт} [S133].

### Что читать

1. [S13] Databases — единственный точный источник правил соединений, пула и PgBouncer.
2. [S33] Asynchronous support — когда async даёт выгоду и почему транзакции остаются синхронными.
3. [S40] Fetch modes — новый способ гасить N+1 в Django 6.1.
4. [S50] Against service layers — сильнейший аргумент против слоёв ради слоёв.
5. [S48] Django Styleguide — противоположная позиция с конкретными шаблонами.
6. [S51] Thin views — середина между двумя позициями.
7. [S3] Kraken monolith — как держать 400 разработчиков в одном коде с Import Linter.
8. [S49] Kraken conventions — проверенные масштабом запреты.
9. [S5] PostHog architecture — фасады, контракты и счётчики «только вниз».
10. [S66] Sentry migrations — правила миграций без простоя.
11. [S4] Sentry multi-region — регионы внутри монолита и симуляция в CI.
12. [S47] Zulip API docs — OpenAPI как проверяемый источник истины.
13. [S76] Concurrency without locks — атомарные операции вместо блокировок.
14. [S36] Fast load into PostgreSQL — измерения массовой загрузки.
15. [S12] Celery tasks guide — идемпотентность, `acks_late`, транзакции.
16. [S53] Tasks without a worker — трезвая критика `django.tasks`.
17. [S54] JWT tokens in allauth — почему JWT не stateless.
18. [S91] OWASP API Top 10 2023 — модель угроз API.
19. [S71] Healthchecks.io hosting — как выглядит рациональный соло-проект.

Лучшие критические разборы среди прочитанного — Беннетт о сервисных слоях и Kevin Renskers о `django.tasks`; оба опираются на опыт авторов, а не на измерения {мнение} [S50, S53].

## 12. Открытые вопросы и границы уверенности {#open-questions}

### Что не удалось проверить

- **Независимый бенчмарк 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, но аналогичные искажения в других местах полностью исключить нельзя.

## 13. Реестр источников {#sources}

| ID | Название | Автор или издатель | URL | Дата публикации | Дата доступа | Доступ | Что подтверждает |
|---|---|---|---|---|---|---|---|
| S1 | Download / Supported versions | Django Software Foundation | https://www.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 | https://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 | https://blog.europython.eu/kraken-technologies-how-we-organize-our-very-large-pythonmonolith/ | 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 | https://blog.sentry.io/removing-risk-from-our-multiregion-design-with-simulations/ | 2024-05 | 2026-10-01 | полный текст | разделы 0, 3, 4, 5, 7, 11, 12: silo внутри монолита, симуляция границ в CI, 35 000 тестов в двух режимах |
| S5 | products/architecture.md | PostHog | https://github.com/PostHog/posthog/blob/master/products/architecture.md | без даты | 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 | https://zulip.readthedocs.io/en/latest/overview/architecture-overview.html | без даты | 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 | https://engineering.fb.com/2022/05/02/open-source/cinder-jits-instagram/ | 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 | https://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 | https://www.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 | https://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 | https://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 | https://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 | https://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 | https://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 | https://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 | https://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 | https://www.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 | https://www.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 | https://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 | https://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 | https://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 | https://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 | https://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 | https://zulip.readthedocs.io/en/latest/tutorials/writing-views.html | без даты | 2026-10-01 | полный текст | разделы 1, 4, 10: typed_endpoint на Pydantic v2 |
| S25 | Saleor webhooks overview | Saleor | https://docs.saleor.io/developer/extending/webhooks/overview | без даты | 2026-10-01 | полный текст | разделы 1, 5: sync/async вебхуки, HMAC, таймаут 20 с, payload через GraphQL-подписки |
| S26 | GraphQL API — NetBox | NetBox Labs | https://netboxlabs.com/docs/netbox/en/stable/integrations/graphql-api/ | без даты | 2026-10-01 | полный текст | разделы 1, 4: read-only GraphQL на Strawberry Django в дополнение к REST |
| S27 | The State of Django 2026: Boring is so back | Will Vincent, JetBrains | https://blog.jetbrains.com/pycharm/2026/08/the-state-of-django-2026-boring-is-so-back/ | 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 | https://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 | https://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 | https://www.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 | https://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 | https://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 | https://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 | https://engineering.kraken.tech/news/2026/01/12/using-django-async.html | 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 | https://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 | https://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 | https://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 | https://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 | https://github.com/taobojlen/django-zeal | без даты | 2026-10-01 | полный текст | разделы 2, 5, 8, 9: детекция N+1 в тестах, накладные расходы 3–5 % (вендор), nplusone заброшен (мнение) |
| S40 | Fetch modes | Django Software Foundation | https://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 | https://saurabh-kumar.com/articles/2025/06/cut-django-database-latency-by-50-70ms-with-native-connection-pooling/ | 2025-06-18 | 2026-10-01 | полный текст | разделы 2, 12: единичный замер пула psycopg на managed PostgreSQL без методики |
| S42 | Introducing Immortal Objects for Python | Eddie Elizondo, Meta Engineering | https://engineering.fb.com/2023/08/15/developer-tools/immortal-objects-for-python-instagram-meta/ | 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 | https://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 | https://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 | https://engineering.kraken.tech/news/2026/02/16/static-typing-python-at-scale.html | 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 | https://zulip.readthedocs.io/en/latest/testing/testing-with-django.html | без даты | 2026-10-01 | полный текст | разделы 2, 3, 4, 5, 8, 10: менее 30 с параллельно, assert_database_query_count, 100 % покрытия нового кода |
| S47 | Documenting REST API endpoints | Zulip project | https://zulip.readthedocs.io/en/latest/documentation/api.html | без даты | 2026-10-01 | полный текст | разделы 2, 4, 5, 11: каждый ответ в тестах сверяется с OpenAPI |
| S48 | Django Styleguide | HackSoft | https://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 | https://raw.githubusercontent.com/octoenergy/public-conventions/main/conventions/django.md | без даты | 2026-10-01 | полный текст | разделы 2, 4, 5, 8, 11: один вызов домена из интерфейса, без implicit ordering, ограничения в базе, save() только в мутаторах |
| S50 | Against service layers in Django | James Bennett | https://www.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 | https://spookylukey.github.io/django-views-the-right-way/thin-views.html | без даты | 2026-10-01 | полный текст | разделы 2, 4, 5, 8, 11: логика в методах моделей и QuerySet, без отдельного service layer (мнение) |
| S52 | Using Django Tasks in production | Tim Schilling, Better Simple | https://www.better-simple.com/django/2026/05/06/using-django-tasks-in-production/ | 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 | https://www.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 | https://docs.allauth.org/en/dev/headless/token-strategies/jwt-tokens.html | без даты | 2026-10-01 | полный текст | разделы 2, 4, 5, 7, 9, 11: JWT не stateless при отзыве; польза для нескольких сервисов |
| S55 | Test factory functions in Django | Luke Plant | https://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 | https://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 | https://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 | https://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 | https://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 | https://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 | https://github.com/open-telemetry/opentelemetry-python-contrib/issues/4202 | 2026-02-13 | 2026-10-01 | полный текст | раздел 2: значения http и http/dup, по умолчанию старые атрибуты |
| S62 | AGENTS.md | Agentic AI Foundation | https://agents.md/ | без даты | 2026-10-01 | полный текст | разделы 2, 6, 10: формат, ближайший файл приоритетен, поддержка основными агентами |
| S63 | GeoDjango Installation | Django Software Foundation | https://docs.djangoproject.com/en/6.1/ref/contrib/gis/install/ | без даты | 2026-10-01 | полный текст | разделы 3, 5: PostGIS рекомендован, PostgreSQL 15+ |
| S64 | django/channels README | Django project | https://github.com/django/channels | без даты | 2026-10-01 | полный текст | разделы 3, 5, 9, 11: сопровождение best-effort под руководством Карлтона Гибсона, гарантированно только безопасность |
| S65 | django-pg-zero-downtime-migrations | tbicr (Paveł Tyślacki) | https://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 | https://develop.sentry.dev/backend/application-domains/database-migrations/ | без даты | 2026-10-01 | полный текст | разделы 3, 4, 5, 8, 11: post-deploy миграции для индексов дольше 10 с, двухфазное удаление, db_default, db_column |
| S67 | Kraken Engineering Blog (главная) | Kraken Technologies | https://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 | https://engineering.kraken.tech/news/2026/02/11/django-kubernetes-health-checks-continuous-delivery.html | 2026-02-11 | 2026-10-01 | полный текст | разделы 4, 5: один /health/ для трёх проб, миграции через pre-upgrade hook |
| S69 | Cross Region Replication | Sentry | https://develop.sentry.dev/application-architecture/multi-region-deployment/cross-region-replication/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 7: outbox в той же транзакции, tombstones, HybridCloudForeignKey |
| S70 | About — Healthchecks.io | Pēteris Caune | https://healthchecks.io/about/ | без даты | 2026-10-01 | полный текст | раздел 4: один человек с июля 2015, BSD, доступность выше 99,9 % (вендор) |
| S71 | A Look at Healthchecks.io Hosting Setup, Summer 2019 | Pēteris Caune | https://blog.healthchecks.io/2019/08/a-look-at-healthchecks-io-hosting-setup-summer-2019/ | 2019-08 | 2026-10-01 | полный текст | разделы 4, 5, 11: без контейнеров и очередей, sendalerts/sendreports как systemd-сервисы, ~€274 в месяц |
| S72 | NetBox installation | NetBox Labs | https://netboxlabs.com/docs/netbox/en/stable/installation/ | без даты | 2026-10-01 | полный текст | раздел 4: Python 3.12+, PostgreSQL 15+, Redis, rqworker |
| S73 | REST API — NetBox | NetBox Labs | https://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 | https://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 | https://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 | https://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 | https://feldroy.com/two-scoops-of-django | 2021-02 | 2026-10-01 | аннотация | разделы 4, 12: книга закрыта, издание под Django 3.x, не прочитана |
| S78 | Pagination — DRF API guide | Encode / DRF | https://www.django-rest-framework.org/api-guide/pagination/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 6: CursorPagination — уникальное неизменное поле с индексом, фиксированное время |
| S79 | Throttling — DRF API guide | Encode / DRF | https://www.django-rest-framework.org/api-guide/throttling/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 9: throttling не мера безопасности, гонки, NUM_PROXIES |
| S80 | Procrastinate documentation | Procrastinate | https://procrastinate.readthedocs.io/en/stable/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 9: очередь на PostgreSQL, транзакционная постановка, periodic, блокировки |
| S81 | drf-spectacular README | T. Franzel | https://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 | https://github.com/axnsan12/drf-yasg | без даты | 2026-10-01 | полный текст | разделы 4, 7, 9, 10: только OpenAPI 2.0, рекомендует drf-spectacular |
| S83 | Sentry Django integration | Sentry | https://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 | https://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 | https://glitchtip.com/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 9: совместимость с клиентскими SDK Sentry, uptime, логи (вендор) |
| S86 | GlitchTip installation | Burke Software and Consulting | https://glitchtip.com/documentation/install | без даты | 2026-10-01 | полный текст | разделы 4, 5, 8, 9: 256–512 MB RAM, PostgreSQL 14+, Valkey опционально |
| S87 | OpenTelemetry Django Instrumentation | OpenTelemetry | https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/django/django.html | без даты | 2026-10-01 | полный текст | разделы 4, 7, 9: DjangoInstrumentor, excluded URLs, sqlcommenter, response_hook |
| S88 | Multiprocess Mode — prometheus client_python | Prometheus | https://prometheus.github.io/client_python/multiprocess/ | без даты | 2026-10-01 | полный текст | разделы 4, 5, 7, 9: ограничения multiprocess-режима, очистка каталога |
| S89 | Row Security Policies | PostgreSQL Global Development Group | https://www.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 | https://docs.djangoproject.com/en/6.1/howto/upgrade-version/ | без даты | 2026-10-01 | полный текст | разделы 5, 8: по одной feature-версии, -Wa, сначала зависимости |
| S91 | OWASP API Security Top 10 — 2023 | OWASP | https://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 | https://docs.astral.sh/ruff/rules/#flake8-django-dj | без даты | 2026-10-01 | полный текст | разделы 5, 6, 9: правила DJ001–DJ013, набор S (bandit) |
| S93 | Schemathesis documentation | Schemathesis | https://schemathesis.readthedocs.io/en/stable/ | без даты | 2026-10-01 | полный текст | разделы 5, 7, 9: property-based тесты по OpenAPI |
| S94 | RFC 9457: Problem Details for HTTP APIs | IETF | https://www.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 | https://www.django-rest-framework.org/api-guide/filtering/ | без даты | 2026-10-01 | полный текст | разделы 5, 9: DjangoFilterBackend, явный ordering_fields против утечки, фильтрация в get_queryset |
| S96 | Testing tools | Django Software Foundation | https://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 | https://www.postgresql.org/docs/current/pgstatstatements.html | без даты | 2026-10-01 | полный текст | разделы 5, 6, 7: статистика запросов, shared_preload_libraries |
| S98 | QuerySet API reference | Django Software Foundation | https://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 | https://engineering.kraken.tech/news/2020/11/30/durable-transactions.html | 2020-11-30 | 2026-10-01 | полный текст | разделы 5, 11: atomic(durable=True) в Django 3.2 |
| S100 | Squawk docs | Squawk | https://squawkhq.com/docs/ | без даты | 2026-10-01 | полный текст | разделы 5, 8, 9: правила линтера миграций PostgreSQL, GitHub Action |
| S101 | Deployment checklist | Django Software Foundation | https://docs.djangoproject.com/en/6.1/howto/deployment/checklist/ | без даты | 2026-10-01 | полный текст | раздел 5: check --deploy, SECRET_KEY_FALLBACKS, постоянные соединения, мониторинг ошибок вместо почты |
| S102 | Using Redis — Celery | Celery project | https://docs.celeryq.dev/en/stable/getting-started/backends-and-brokers/redis.html | без даты | 2026-10-01 | полный текст | разделы 5, 7, 9: visibility timeout 1 ч, повторы ETA-задач, noeviction |
| S103 | django-structlog documentation | django-structlog | https://django-structlog.readthedocs.io/en/latest/ | без даты | 2026-10-01 | полный текст | разделы 5, 9: request_id и user_id в каждой строке, JSON, DRF и Ninja |
| S104 | py-spy README | Ben Frederickson | https://github.com/benfred/py-spy | без даты | 2026-10-01 | полный текст | разделы 5, 9: сэмплирующий профайлер без перезапуска, CPython до 3.14 |
| S105 | getsentry/skills | Sentry | https://github.com/getsentry/skills | без даты | 2026-10-01 | полный текст | разделы 5, 10: навыки django-perf-review, django-access-review, agents-md |
| S106 | pytest-django: Database access | pytest-django | https://pytest-django.readthedocs.io/en/latest/database.html | без даты | 2026-10-01 | полный текст | разделы 5, 6, 9: --reuse-db, --nomigrations, суффиксы для xdist |
| S107 | Multiple databases | Django Software Foundation | https://docs.djangoproject.com/en/6.1/topics/db/multi-db/ | без даты | 2026-10-01 | полный текст | раздел 5: роутер primary/replica не решает лаг репликации |
| S108 | Django's cache framework | Django Software Foundation | https://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 | https://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 | https://www.django-rest-framework.org/api-guide/versioning/ | без даты | 2026-10-01 | полный текст | разделы 5, 12: схемы версионирования, Accept-заголовок как «лучшая практика», допустимость систем без версий |
| S111 | Import Linter documentation | Import Linter project | https://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 | https://django-simple-history.readthedocs.io/en/latest/common_issues.html | без даты | 2026-10-01 | полный текст | разделы 5, 7, 8, 9: bulk-операции и update() не пишут историю |
| S113 | Uploading objects with presigned URLs | Amazon Web Services | https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html | без даты | 2026-10-01 | полный текст | раздел 5: загрузка без учётных данных, срок до 7 дней, перезапись ключа |
| S114 | django-storages: Amazon S3 | django-storages | https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html | без даты | 2026-10-01 | полный текст | разделы 5, 9: подписанные URL 3600 с, file_overwrite=True по умолчанию, endpoint_url |
| S115 | Healthchecks.io Blog (главная) | Pēteris Caune | https://blog.healthchecks.io/ | без даты | 2026-10-01 | фрагмент | раздел 5: переход с managed-хранилища на self-hosted S3, bare metal |
| S116 | Pattern: Transactional outbox | Chris Richardson, microservices.io | https://microservices.io/patterns/data/transactional-outbox.html | без даты | 2026-10-01 | полный текст | разделы 5, 7: запись сообщения в той же транзакции, дубли, идемпотентный потребитель |
| S117 | Standard Webhooks | Standard Webhooks TSC | https://www.standardwebhooks.com/ | без даты | 2026-10-01 | полный текст | раздел 5: webhook-id/timestamp/signature, HMAC-SHA256, защита от replay и SSRF |
| S118 | REFRESH MATERIALIZED VIEW | PostgreSQL Global Development Group | https://www.postgresql.org/docs/current/sql-refreshmaterializedview.html | без даты | 2026-10-01 | полный текст | раздел 5: CONCURRENTLY требует уникальный индекс, один refresh за раз |
| S119 | Full text search (contrib.postgres) | Django Software Foundation | https://docs.djangoproject.com/en/6.1/ref/contrib/postgres/search/ | без даты | 2026-10-01 | полный текст | раздел 5: проблемы после «нескольких сотен записей» без индекса, GeneratedField + GIN, триграммы |
| S120 | Sync: Backend | WatermelonDB (Nozbe) | https://watermelondb.dev/docs/Sync/Backend | без даты | 2026-10-01 | полный текст | раздел 5: серверное время, tombstones, отказ push при конфликте, транзакционность |
| S121 | GeoDjango Database API | Django Software Foundation | https://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 | https://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 | https://www.ietf.org/archive/id/draft-ietf-httpapi-idempotency-key-header-07.html | 2025-10-15 | 2026-10-01 | полный текст | раздел 5: 409 при параллельном повторе, 422 при другом теле, UUID, черновик истёк |
| S124 | django-waffle documentation | django-waffle | https://waffle.readthedocs.io/en/stable/ | без даты | 2026-10-01 | фрагмент | разделы 5, 9: flags, switches, samples; версия 5.0.0 |
| S125 | Repository and Documentation (SDK standards) | Sentry | https://develop.sentry.dev/sdk/getting-started/standards/repository-docs/ | без даты | 2026-10-01 | полный текст | разделы 6, 10: обязательный AGENTS.md и его разделы |
| S126 | What is Locust? | Locust | https://docs.locust.io/en/stable/what-is-locust.html | без даты | 2026-10-01 | полный текст | раздел 9: сценарии на Python, headless-режим для CI, MIT |
| S127 | adamchainz/django-upgrade | Adam Johnson | https://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 | https://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 | https://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 | https://www.vintasoftware.com/blog/teaching-ai-agents-to-write-django-like-senior-developers | 2026-02-19 | 2026-10-01 | полный текст | разделы 10, 12: навыки для агентов, без количественной оценки |
| S131 | Django (web framework) | Wikipedia | https://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 | https://www.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 | https://www.djangoproject.com/weblog/2024/may/29/django-enhancement-proposal-14-background-workers/ | 2024-05-29 | 2026-10-01 | полный текст | раздел 11: DEP 14 принят, автор Jake Howard, референс django-tasks |

## 14. Словарь терминов {#glossary}

- **acks_late** (позднее подтверждение): режим Celery, при котором воркер подтверждает задачу после выполнения; безопасен только для идемпотентных задач.
- **Active Record / Data Mapper** (активная запись / преобразователь данных): два стиля ORM; в Django модель сама сохраняет себя, поэтому слои в стиле Data Mapper ложатся на неё плохо.
- **AGENTS.md** (файл правил для агентов): открытый формат Markdown-инструкций для ИИ-агентов в корне репозитория и вложенных каталогах.
- **ASGI / WSGI** (асинхронный и синхронный интерфейс сервера): протоколы между сервером приложений и Django; ASGI нужен для долгих соединений.
- **BOLA / IDOR** (нарушение авторизации на уровне объекта / небезопасная прямая ссылка на объект): доступ к чужому объекту подстановкой ID; первый риск OWASP API Top 10 2023.
- **Bus factor** (фактор автобуса): число людей, без которых проект останавливается.
- **CONN_MAX_AGE** (время жизни соединения): настройка Django, сколько секунд держать соединение с базой между запросами.
- **CONCURRENTLY** (параллельно): режим создания и удаления индекса PostgreSQL без блокировки записи; не работает внутри транзакции.
- **Connection pool** (пул соединений): набор открытых соединений, которые переиспользуются; в Django 5.1+ — на процесс через psycopg 3.
- **Cursor (keyset) pagination** (курсорная пагинация): постраничный вывод по значению упорядоченного уникального поля вместо смещения.
- **DB_CASCADE** (каскад в базе): опция `on_delete` Django 6.1, при которой удаление выполняет PostgreSQL через `ON DELETE CASCADE`, без сигналов.
- **db_default** (значение по умолчанию в базе): значение поля, вычисляемое базой; безопасно при выкладке миграций.
- **DEP** (Django Enhancement Proposal, предложение по улучшению Django): формальный документ изменения процесса или функциональности Django.
- **django.tasks** (фреймворк задач Django): API для объявления и постановки фоновых задач с Django 6.0, без воркера в ядре.
- **EAFP** (проще попросить прощения, чем разрешения): подход «попробовать вставку и обработать `IntegrityError`» вместо предварительной проверки.
- **Expand/contract** (расширить/сжать): схема изменения базы в несколько выкладок: добавить новое, перевести код, удалить старое.
- **Fetch modes: FETCH_ONE, FETCH_PEERS, FETCH_RAISE** (режимы догрузки полей): настройки Django 6.1 для поведения при обращении к незагруженному полю: по одному объекту, пачкой для всех объектов выборки или исключение.
- **Feature flag** (фича-флаг): переключатель функциональности без перевыкладки.
- **FSL** (Functional Source License): лицензия Sentry, ограничивающая конкурирующее коммерческое использование и переходящая в Apache 2.0 через два года.
- **GeneratedField** (вычисляемое поле): колонка, значение которой вычисляет база по выражению.
- **GeoDjango / PostGIS** (геоподсистема Django / георасширение PostgreSQL): поля и запросы по геометрии; `geography=True` включает индексируемые расстояния в WGS84.
- **GIN** (обобщённый инвертированный индекс): тип индекса PostgreSQL для полнотекстового поиска и массивов.
- **GlitchTip** (трекер ошибок): self-hosted система, принимающая данные клиентских SDK Sentry.
- **Health check: liveness / readiness** (проверка живости / готовности): эндпоинты для перезапуска процесса и для снятия его с балансировки.
- **Idempotency-Key** (ключ идемпотентности): заголовок запроса, по которому сервер распознаёт повтор и возвращает сохранённый результат.
- **Import Linter / tach** (линтеры импортов): инструменты проверки архитектурных контрактов между модулями Python в CI.
- **JWT** (JSON Web Token): подписанный токен, проверяемый без обращения к базе; отзыв требует дополнительного состояния.
- **Materialized view** (материализованное представление): сохранённый результат запроса PostgreSQL, обновляемый `REFRESH`.
- **MCP** (Model Context Protocol, протокол контекста модели): протокол, через который ИИ-ассистенты вызывают инструменты приложения.
- **Modular monolith** (модульный монолит): один деплой с машинно проверяемыми границами между доменными модулями.
- **Multi-tenancy** (мультиарендность): обслуживание нескольких компаний одной системой с разделением данных.
- **N+1** (проблема N+1 запросов): один запрос за списком и по одному запросу на каждый элемент при обращении к связанным данным.
- **OpenAPI** (спецификация HTTP API): машиночитаемое описание эндпоинтов, схем и ошибок.
- **Outbox** (исходящий ящик): таблица событий, записываемых в той же транзакции, что и данные, и доставляемых отдельным процессом.
- **pg_stat_statements** (статистика запросов): расширение PostgreSQL с агрегированной статистикой выполнения запросов.
- **PgBouncer transaction mode** (режим пула по транзакциям): внешний пулер, отдающий соединение на время транзакции; несовместим с server-side cursors между транзакциями.
- **Pre-fork** (предварительное ветвление): модель сервера, где мастер-процесс порождает рабочие процессы, разделяющие память через copy-on-write.
- **Problem Details (RFC 9457)** (детали проблемы): стандартный JSON-формат ошибок HTTP API `application/problem+json`.
- **Property-based testing** (тестирование свойствами): генерация множества входных данных по схеме для поиска ошибок; так работает Schemathesis.
- **QuerySet / Manager** (набор запроса / менеджер): ленивое описание SQL-запроса и точка входа к нему в модели Django; место для методов выборки.
- **Read replica** (реплика чтения): копия базы для чтения; отстаёт от основной на время репликации.
- **RLS** (Row Level Security, построчная безопасность): политики PostgreSQL, ограничивающие видимые строки; владелец таблицы обходит их без `FORCE`.
- **Schema-per-tenant** (схема на арендатора): отдельная схема PostgreSQL для каждой компании.
- **Semantic conventions** (семантические соглашения): стандартные имена атрибутов OpenTelemetry для HTTP, баз данных и других областей.
- **Serializer / Schema** (сериализатор / схема): объект DRF или Pydantic, проверяющий вход и формирующий выход API.
- **Server-side cursor** (серверный курсор): курсор PostgreSQL для потокового чтения, используемый `QuerySet.iterator()`.
- **Service layer / selectors** (сервисный слой / селекторы): функции записи и чтения вне моделей и представлений по руководству HackSoft.
- **Silo** (изолированный сегмент): у Sentry — режим монолита, где контрольные данные и данные регионов разделены и общаются через RPC и outbox.
- **SSE** (Server-Sent Events, события от сервера): однонаправленный поток событий по HTTP от сервера к клиенту.
- **Throttling / rate limiting** (ограничение частоты): ограничение числа запросов клиента за интервал.
- **Tombstone** (надгробие): запись об удалении, по которой клиенты или другие регионы узнают, что объект удалён.
- **Visibility timeout** (тайм-аут видимости): время, после которого неподтверждённая задача в Redis-брокере выдаётся другому воркеру.
- **YAGNI** (вам это не понадобится): принцип не строить абстракции до появления потребности.
- **Оверинжиниринг / недоинжиниринг** (избыточное / недостаточное проектирование): практика, не двигающая метрики проекта при ненулевой цене, либо отсутствие практики, без которой метрики деградируют.
