bulgakov

Backend: деньги, контракты и повторные операции

После урока

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

Начните с инвариантов

Backend часто скрывает ошибки за успешным HTTP-ответом. Код компилируется, тестовый запрос возвращает 200, но скидка применяется дважды или пользователь читает чужой заказ. Поэтому до реализации сформулируйте свойства, которые должны оставаться истинными при любом допустимом входе.

Для учебного расчёта цены: суммы — целые копейки; сумма неотрицательна; процент задан в базисных пунктах; итог не ниже нуля; скидка применяется начиная с 10 000 копеек включительно; округление суммы скидки — half-up; скидка одна. Один базисный пункт равен 0,01 процентного пункта, поэтому 10% — 1 000 bps. Тип bool в Python является подклассом int, но для суммы True неприемлем; это проверяется отдельно.

Спецификация должна определить именно округление скидки, а не итога: эти варианты могут различаться на половине минимальной единицы. Нельзя позволять агенту выбрать один из них незаметно. Для реального продукта правила денег и налогов согласуются с владельцем предметной области.

Разобранный расчёт

Пусть сумма 10 005 копеек и скидка 10%. Неокруглённая скидка 1 000,5 копейки. По нашему учебному правилу округляем вверх до 1 001; итог 9 004. Для неотрицательных целых можно считать:

Python
discount = (subtotal * discount_bps + 5000) // 10000
total = subtotal - discount

Эта формула относится к указанному контракту и не должна бездумно применяться к отрицательным возвратам. Возвраты лучше считать отдельной операцией с явно заданной связью с первоначальным расчётом. Использование float для копеек создаёт ненужную проблему представления дробей; для более сложной денежной арифметики нужен согласованный decimal-контекст.

Вход, коп. Причина Ожидаемый итог, коп.
0 Ниже порога 0
9 999 На единицу ниже порога 9 999
10 000 Порог включён 9 000
10 001 Сразу выше порога 9 001
10 005 Проверка половины копейки 9 004

В labs/pricing.py находится решение, а labs/test_pricing.py проверяет условия. Тесты опираются на контракт, а не копируют формулу внутри функции. Если заменить >= на >, проверка точного порога должна упасть. Если изменить half-up на округление вниз, должен упасть пример 10 005. Такие намеренные изменения называются проверкой чувствительности тестов; в главе 09 мы расширим идею.

Идемпотентность

Пользователь нажал кнопку дважды, сеть оборвалась после записи, клиент повторил запрос. Это нормальные сценарии распределённой системы. Идемпотентность означает, что повтор одной и той же логической операции не создаёт дополнительного эффекта. Она не появляется от фразы «будь осторожен с дублями» в промпте.

Учебная операция получает request_key, идентификатор пользователя и сумму. База хранит уникальную пару пользователя и ключа, отпечаток запроса и созданный результат. При повторе с тем же содержимым возвращается прежний результат. Тот же ключ с другим содержимым вызывает конфликт. Проверка существования и вставка защищены транзакцией и ограничением уникальности.

В labs/idempotency.py показан небольшой пример на SQLite. Он создаёт учебную запись заказа, а не проводит банковский платёж. Конкурентный повтор проверяется отдельным тестом. В реальной системе понадобится решить срок хранения ключей, область уникальности, обработку частично выполненных внешних действий и наблюдаемость.

Почему «проверили, потом записали» недостаточно

Два процесса могут одновременно не найти запись, затем оба попытаться создать её. Логическая проверка в Python без ограничения базы не защищает от гонки. Точно так же повтор внешнего вызова после тайм-аута опасен: неизвестно, выполнил ли удалённый сервис действие до обрыва. Нужны идентификатор операции и сверка состояния, а не слепой retry.

Если операция меняет базу и должна отправить событие, простой порядок «записать, затем отправить» имеет окно сбоя. Практический вариант — transactional outbox: запись бизнес-изменения и события в одной транзакции, отдельная доставка с дедупликацией. Это архитектурный шаблон, а не гарантия exactly-once во всей системе. Транспорт может доставить повтор, поэтому получатель тоже должен корректно его обработать.

Контракт API и права доступа

Определите обязательные поля, типы, допустимые диапазоны, коды ошибок и версионирование. Структурированная схема помогает проверить форму, но не бизнес-смысл. Число заказа может быть корректным integer и всё равно принадлежать другому пользователю.

Авторизацию проверяет сервер, опираясь на аутентифицированного пользователя, а не на свободный текст модели. Агент не должен сам назначать себе tenant или роль из аргумента инструмента. Даже если UI не показывает чужие заказы, API обязан отклонять прямое обращение. В тестовой матрице должны быть владелец, другой пользователь, сотрудник с ограниченной ролью и отсутствующая сессия.

Внешние данные валидируются до применения. Ответ модели «refund_amount: 5000» — предложение, которое должен проверить обычный код: доступный остаток, валюта, состояние заказа и предел полномочий. Нельзя превращать LLM в единственный источник финансового правила.

Производительность и диагностика

Не просите «оптимизировать всё» без измерения. Сначала найдите медленный путь: трасса запроса, число SQL-вызовов, p95 задержки, объём результата. N+1 определяется поведением последовательности запросов, а не одним взглядом на схему таблиц. Индекс полезен при определённой селективности и распределении данных; на маленькой таблице эффект может быть незаметен.

EXPLAIN и EXPLAIN ANALYZE различаются принципиально: второй действительно выполняет запрос. Для изменяющих запросов и тяжёлой нагрузки это существенно. Учитесь на копии данных с подходящими ограничениями, сначала изучая обычный план. S35

Практика и приёмка

Запустите python3 -m unittest discover -s labs -p 'test_*.py'. Найдите тесты цены и идемпотентности. Затем в отдельной копии внесите три дефекта: исключите точный порог, отключите проверку конфликта ключа и ослабьте ограничение типа. Убедитесь, что соответствующие тесты их обнаруживают. Верните рабочую версию.

Критерий: вы можете объяснить, почему каждый тест нужен, и назвать то, что локальная проверка не подтверждает: реальную платёжную интеграцию, отказоустойчивость кластера и условия production-нагрузки. Такое ограничение — часть технической точности, а не недостаток учебного упражнения.

Разбор сбоя по временной линии

Рассмотрим три точки остановки операции. До записи заказа повтор создаёт запись впервые. После записи, но до получения ответа клиентом повтор должен найти прежний результат. После выполнения внешнего действия, но до сохранения локального подтверждения состояние неопределённо: сначала нужна сверка с внешней системой по тому же ключу.

Эти случаи нельзя объединить одним except: retry(). Попросите агента написать таблицу «точка сбоя → известное состояние → разрешённое восстановление». Если он предлагает повторять внешнюю операцию без идентификатора и сверки, решение ещё не готово. Для учебного SQLite-примера внешнего действия нет, поэтому его гарантия уже и понятнее: одна запись заказа на согласованную пару пользователя и ключа.


Скачать практикумы и рабочие шаблоны.