Асинхронный Python-сервис: собрать и эксплуатировать

До кода реши, чем этот сервис является, а чем — нет. Асинхронный сервис оправдывает свою сложность только когда работа I/O-bound и конкурентна — фан-аут к другим сервисам, запросы к БД, записи в очередь, — а не CPU-bound вычисления, которые просто заблокируют loop. Набросай поток запроса (приём → валидация → стадии пайплайна → ответ), оцени конкурентность (целевой RPS, фан-аут на запрос, ожидаемое число задач в полёте) и выпиши SLO (например, p99 приёма < 100 мс, durability принятого payload) плюс явные non-goals, чтобы не тянуться к async там, где место потокам или process pool.

Подними приложение FastAPI и сделай границу приёма строгой. Каждый payload проходит один валидационный шлюз: Pydantic-модель, которая приводит, ограничивает и отвергает, — так что некорректный вход падает на краю с 422, а не глубже в пайплайне. Держи обработчик запроса асинхронным и неблокирующим; единственный синхронный парсинг или хеширование большого тела тихо сериализует весь loop. Опиши модели запроса и ответа, чтобы контракт был явным, а форма ошибки — единообразной.

Преврати провалидированный запрос в пайплайн конкурентных асинхронных стадий — обогащение, фан-аут к зависимостям, агрегация. Используй структурную конкурентность (task group / nursery), чтобы дочерние задачи принадлежали области: если одна падает, её соседи отменяются и ошибка пробрасывается, а не протекает осиротевшей задачей, которая досчитывается в темноте. Это этап, где разница между fire-and-forget и владеемой конкурентностью становится разницей между отлаживаемым сервисом и сервисом с привидениями.

Ограничь каждое внешнее ожидание и обрабатывай отмену честно. Оберни вызовы зависимостей потаймстейджными таймаутами, чтобы один медленный upstream не пришпиливал запрос — и задачу — навсегда. Главное: относись к CancelledError как к управлению потоком, а не ошибке: лови его только для очистки, затем перебрасывай, никогда не проглатывай. Там, где шаг обязан завершиться атомарно (закоммиченная запись, отпущенный lock), защити shielding ровно эту критическую секцию и ничего больше — избыточный shielding делает сервис, игнорирующий собственные дедлайны.

Сделай сервис устанавливаемым и воспроизводимым, а не папкой скриптов. Опиши проект в pyproject.toml с зафиксированными рантайм-зависимостями и entry point, запускающим сервер, затем разреши и закоммить lock-файл, чтобы каждая установка — твоя, CI, контейнера — получала ровно один и тот же граф зависимостей. Держи импортную поверхность чистой: ясная раскладка пакета означает отсутствие sys.path-хаков и сюрпризов от случайного модуля верхнего уровня, затеняющего зависимость.

Помести сервис в контейнер, который завершается gracefully. Ловушка — PID 1: процесс Python, запущенный как PID 1, не получает дефолтных обработчиков сигналов ядра, так что наивный контейнер игнорирует SIGTERM, и оркестратор жёстко убивает его после grace-периода, теряя запросы в полёте на каждом деплое. Почини настоящим init (tini / exec-форма) или явной обработкой сигналов, затем заставь сервер дренироваться — перестать принимать, дать пайплайнам в полёте завершиться или упереться в дедлайн — до выхода. Собери лёгкий multi-stage образ от lock-файла, чтобы рантайм-слой нёс только то, что исполняет.

Заставь работающий сервис сообщать тебе, что он делает. Снимай структурные (JSON) логи с request id, протянутым через каждую стадию, чтобы один медленный или упавший запрос был одним запросом, а не grep по перемешанным строкам от конкурентных задач. Вынеси конфигурацию — уровень логов, таймауты, URL зависимостей, число воркеров — через окружение, а не константы, чтобы один образ работал в dev и prod сменой входов, а не кода. Логируй события, важные для предстоящего инцидента: задача порождена, стадия истекла по таймауту, отмена замечена, дренаж начат.

Под нагрузкой p99 латентности приёма растёт и не восстанавливается, хотя CPU выглядит простаивающим. Корневая причина — утечка отмены: одна стадия пайплайна ловит CancelledError и проглатывает его вместо переброса, так что задачи с истёкшим таймаутом на самом деле не умирают — они накапливаются, каждая держит соединение и слот, пока event loop не настолько забит задачами-зомби, что готовые корутины ждут своей очереди и всё голодает. Воспроизведи это нагрузочным тестом, форсирующим таймауты, посмотри, как число задач в полёте растёт без предела в твоих логах, затем почини перебросом CancelledError и подтверди, что число задач возвращается к базовой линии. Напиши пост-мортем: он обязан назвать механизм проглоченной отмены, а не просто «высокая латентность». Профилируй, если нужно доказать, куда ушло время loop.