Все публикации подряд на Хабре [expanded by feedex.net]

Электрохимический транзистор: что с патентами?

Oksana_Nedvigina (Online patent) — Tue, 23 Jun 2026 08:15:31 +0000

Обзор

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

В электрохимическом транзисторе есть канал (полупроводниковый или проводящий слой), электроды истока и стока, а также электрод затвора, который находится в ионном контакте с каналом через электролит. Электролит может быть жидким, гелеобразным или твёрдым. Проводимость канала регулируется за счёт окислительно-восстановительных реакций и миграции ионов между каналом и электролитом. При подаче напряжения на электрод затвора происходит взаимодействие ионов из электролита с материалом канала, что изменяет плотность электронного заряда и, соответственно, ток стока. В зависимости от полярности напряжения и характера реакций канал может переходить из проводящего состояния в изолирующее и наоборот. Например, при положительном напряжении на затворе катионы из электролита вводятся в канал, что может привести к электрохимическому восстановлению материала (например, PEDOT:PSS) и снижению его проводимости. При снятии напряжения ионы возвращаются в электролит, и ток стока возвращается к первоначальному значению. Некоторые материалы канала могут удерживать мигрировавшие ионы даже после снятия напряжения на затворе, что позволяет использовать такие транзисторы в качестве запоминающих устройств.

О них сегодня мы и поговорим.

Особенности

Низкое рабочее напряжение (обычно менее 1 В), что делает электрохимические транзисторы перспективными для применения в биологических системах, биосенсорах и биоэлектронике.

Возможность интеграции с биологическими системами. Это открывает пути для применения в нейроморфных вычислениях, нейронных интерфейсах, а также для мониторинга состояния здоровья, биомаркеров и других задач.

Разнообразие материалов. В качестве электролита могут использоваться полимеры, ионные жидкости, ионные гели, водные жидкие электролиты. Для каналов часто применяют органические полупроводники, например, PEDOT:PSS, полипиррол, политиофен.

Примеры применения:

электрохимические биосенсоры;
нейронные интерфейсы;
нейроморфные устройства;
мониторинг развития растений;
носимые устройства для биомедицинского зондирования (измерение уровня натрия, калия в крови, частоты сердечных сокращений и т. д.).

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

Какие патенты на изобретения по этой теме существуют?

На портале Google.Patents поиск по запросу electrochemical transistor показывал более 100 000 документов на июнь 2026 г. В рамках МПК рейтинг тематик следующий:

полупроводниковые приборы, предназначенные для преобразования энергии или информации H10D – 21,4%;
исследование или анализ материалов путем определения их химических или физических свойств G01N – 19,7%;
органические электрические твердотельные устройства H10K – 18,8%;
оптические устройства G02F – 15,7%;
сокращение выбросов парниковых газов Y02E – 15,6%;
схемы или устройства управления индикаторными приборами с использованием статических средств для представления переменных величин G09G – 15,5%;
способы и устройства, например батареи, для непосредственного преобразования химической энергии в электрическую H01M – 9,2%;
и т.д.

Динамика мирового патентования представлена на рис. 1.

Источник: интерпретация автора данных Google.Patents

Видно, что в 1992-2007 активность патентования резко выросла, последние 20 лет была платообразной с небольшим пиком в 2010-2013 гг.

Рейтинг патентовладельцев следующий:

Seiko Epson Corporation – 7%;
Semiconductor Energy Laboratory Co., Ltd. – 3,1%;
Samsung Display Co., Ltd. – 1%;
The Regents Of The University Of California – 1%;
The Board Of Trustees Of The University Of Illinois – 1%;
Ethicon Llc – 0,9%;
Acreo Ab – 0,8%;
Monolithic 3D Inc. – 0,8%;
Sony Corporation – 0,7%;
Northwestern University – 0,7%;

В ТОП-10 патентодержателей входят в основном японские, южнокорейские и американские компании и организации. При этом США в рейтинге представлены в основном вузами, а не техногигантами, что очень странно. Обычно в подобных рейтингах всегда присутствуют корпорации, вроде Intel или IBM. Вероятно, последним проще лицензировать или купить разработки у того же Калифорнийского университета.

Что примечательно, на втором месте Semiconductor Energy Laboratory Co., Ltd. О ее главе, патентом короле Японии Ямадзаки Сюмпэе, мы уже писали отдельный материал на Хабре.

Примеры патентов:

US10424751B2 Organic electrochemical transistors with tunable threshold voltage. Genesee Valley Innovations LLC. В одном варианте осуществления предлагается электронное устройство, которое может включать в себя, по меньшей мере, два органических электрохимических транзистора (ОЭХТ). Соответствующий ОЭХТ включает в себя проводящий канал, затвор, электрически связанный с проводящим каналом через первый электролит, и электроды истока и стока, отделенные друг от друга проводящим каналом.
CN113607795B Double gate organic electrochemical transistor. Hong Kong Polytechnic University HKPU. Настоящее изобретение обеспечивает транзистор и способ обнаружения и/или определения концентрации анализируемого вещества в образце с использованием транзистора.
US12364089B2 Pressure sensor device with organic electrochemical transistors with microstructured hydrogel gating medium. University of California San Diego UCSD. Раскрыт ионтронный датчик давления с низким энергопотреблением, основанный на OECT, в котором ионный гидрогель используется в качестве твердой стробирующей среды для сформированных на нем чувствительных к давлению транзисторных элементов.

Схема из патента US10424751B2

Что в России?

В базе ФИПС патентов РФ на изобретения по рефератам на электрохимический транзистор поисковая машина выдаёт 32 ед. периода 1994-2026 гг., но большинство патентов составляет шум, например «электрохимическое осаждение плёнкой для полевых транзисторов», «защита от электрохимической коррозии устройствами с транзисторами». При ручной выборке обнаружено, увы, только два патента:

№2796202 (2023) Способ изготовления биосенсорной структуры. Саратовский национальный исследовательский государственный университет имени Н.Г. Чернышевского. Изобретение относится к технологии изготовления сенсорных структур на основе твердотельного полупроводника и функционального органического покрытия и может быть использовано при создании ферментных биосенсоров на основе полевых транзисторов или структур «электролит-диэлектрик-полупроводник».

Схема из патента №2796202

№2859283 (2026) Способ получения композитных пленок на основе гудрона. Национальный исследовательский Томский политехнический университет. Изобретение относится к получению композиций на основе органических высокомолекулярных соединений, а именно к получению композитных пленок на основе гудрона на подложке из полиэтилентерефталата, и может быть использовано при изготовлении электрохимических транзисторов и неметаллических антенн.

Патентов РФ на полезные модели по теме нет. Зарегистрированных баз данных, топологий интегральных схем и программ для ЭВМ по нашей теме в России нет.

НИОКР

По теме электрохимический транзистор в базе ГИС «Наука» 68 документов на июнь 2026 года, в основном отчёты НИОКР.

Так, в 2025 г. Институт синтетических полимерных материалов им. Н.С. Ениколопова РАН за грант 38,2 млн руб. от Минобрнаука выполнил НИР «Разработка функциональных органических, полимерных и гибридных материалов с заданными полупроводниковыми, оптическими, электрохимическими, сенсорными и другими свойствами, необходимыми для обеспечения создания элементной базы электроники, фотоники и оптоэлектроники нового поколения на основе нанотехнологий». Ранее было сотрудничество с Курчатовским Комплексом Синхротронных и Нейтронных Исследований НИЦ Курчатовский Институт, 2022-2025 гг.

НИР «Молекулярное конструирование полимерных металлокомплексов с редокс-активными лигандами и разработка подходов к управлению их электронно-ионной проводимостью для электрохимических транзисторов нового поколения» в 2023-2025 гг. за 3 млн руб. выполнил Физико-технический институт им. А.Ф. Иоффе РАН. Целью являлось создание новых функциональных материалов для каналов электрохимических транзисторов на основе проводящих полимерных комплексов никеля (II) с саленовыми лигандами и комплексное исследование влияния природы мономера, условий электрополимеризации и осуществления окислительно-восстановительных превращений на параметры электронного и ионного транспорта в данных материалах.

Заключение

Уровень патентования в мире достаточно высокий последние 20 лет. В России он почти нулевой, хотя ведутся впечатляющие по умственной наполненности НИОКР, которые потенциально способны привести к изобретениям и соответствующим патентам.

Сделать точный прогноз рынка электрохимических транзисторов сложно из-за:

отсутствия массовых коммерческих продуктов;
неопределённости в сроках преодоления технологических барьеров;
конкуренции с более зрелыми технологиями (например, кремниевыми транзисторами).

Если технология получит широкое распространение, рост рынка может быть экспоненциальным, особенно в нишевых сегментах. Однако это произойдёт только при успешном решении проблем с надёжностью и производительностью.

Пока что мы видим множество патентов у японских, южнокорейских и американских компаний и организаций.

О сервисе Онлайн Патент:

Онлайн Патент — цифровая система №1 в рейтинге Роспатента. С 2013 года мы создаем уникальные LegalTech‑решения для защиты и управления интеллектуальной собственностью. Зарегистрируйтесь в сервисе Онлайн Патент и получите доступ к следующим услугам:

Онлайн‑регистрация программ, патентов на изобретение, товарных знаков, промышленного дизайна;
Подача заявки на внесение в реестр отечественного ПО;
Поиск по программам;
Регистрация программы в Роспатенте;
Регистрация товарных знаков;
Опции ускоренного оформления услуг;
Бесплатный поиск по базам патентов, программ, товарных знаков;
Мониторинги новых заявок по критериям;
Онлайн‑поддержку специалистов.

Skills исправляют привычки MCP исправляет память

DarkenAmber — Tue, 23 Jun 2026 08:13:14 +0000

DarkenAmber2 минуты назад

2 мин

Кейс

Я долго пытался решить одну проблему Claude Code в разных сессиях ведет себя поразному и это иногда просто ломает логику работы

сначала думал что дело в промптах потом начал думать что проблема в контексте но в итоге стало понятно что все немного глубже

Что именно ломалось

больше всего бесило то что модель сама начинала “улучшать” код даже когда ее об этом вообще не просили

она могла убирать тесты потому что так якобы чище или менять архитектуру которая уже нормально работала и это выглядело странно

вторая проблема это память между сессиями мы вроде договорились как должен выглядеть проект но через день это уже просто забывается

третье это MCP инструменты которые постепенно превращаются в кашу и потом уже непонятно где логика а где данные

Я разделил систему на две части

сначала я пытался просто улучшать промпты но это довольно быстро перестало работать

тогда я разделил систему на Skills которые отвечают за поведение и MCP которые отвечают за память и инструменты

Skills и первая ошибка

Skill это просто SKILL.md файл и на первый взгляд это звучит очень просто

я сначала написал правило типа ship fast dont overthink и выглядело это нормально

но потом оказалось что модель начинает следовать этому слишком буквально

она начинала убирать тесты и упрощать код даже там где этого делать нельзя

Пришлось добавлять ограничения

после этого стало понятно что без явных ограничений это просто не работает нормально

я добавил правило Do NOT use when payments auth irreversible operations и только после этого стало хоть как то контролируемо

Баги которые меня реально удивили

один из первых багов был с asyncio и web сервером когда я просто соединил два подхода к event loop и все просто упало и сначала вообще непонятно было почему

потом была история с env переменными где ADMIN_IDS выглядели как обычная строка через запятую но pydantic ожидал json и все ломалось

самый неприятный баг был во Flutter когда длина строки считалась в символах а Google Drive ожидал байты и в итоге кириллица просто тихо обрезалась без ошибок

MCP и что там пошло не так

memory kit это просто SQLite с FTS5 чтобы можно было хранить и искать память локально идея простая но на удивление рабочая

skills server внезапно начал ловить проблему с параллельными запросами когда один skill дергается много раз одновременно и GitHub просто не выдерживает

пришлось добавить asyncio Lock чтобы это не разлеталось

github MCP сначала вообще не имел нормальной валидации и потом стало понятно что repo строку можно сломать через странный input

telegram MCP я сначала хотел делать с передачей токена как параметра но потом понял что это плохая идея и теперь токен живет только в env и вообще не попадает в модель

Проект пока сырой

я не пытаюсь делать вид что это какой то готовый фреймворк это скорее набор экспериментов который еще постоянно меняется

skills будут допиливаться MCP тоже будет меняться и возможно часть решений вообще окажется неправильной

Что дальше

планируется добавить - docs writer skill, test writer skill, новые MCP сервера и возможно mcpm как визуальный менеджер для всего этого

Итог

главное что я понял это то что проблема не в том что модель плохая а в том что у нее нет нормальных стабильных границ поведения и памяти

skills и MCP это просто попытка эти границы хоть как то зафиксировать

GitHub https://github.com/DarkenAmber/claude-kit

Хабр Курсы для всех

Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!

Регулирование криптовалют в России: убить то, что так и не смогли понять за прошедшие 17 лет

Hau515 — Tue, 23 Jun 2026 08:09:14 +0000

Hau5156 минут назад

8 мин

Мнение

Из песочницы

Сразу обозначу: это моё личное мнение, и оно злое. Потому что то, что сейчас собираются принять под видом «регулирования криптовалют», — это не регулирование. Это управляемое уничтожение целой отрасли, замаскированное под оное «регулирование» и очередную «защиту наших граждан и их денег от них самих». И самое мерзкое — что делают это люди, которые либо не понимают, как работает крипта, либо прекрасно понимают и делают это сознательно, и тогда все еще хуже, чем кажется на первый взгляд.

Ура! Наконец‑то ЦБ легализует криптовалюты!

Рано радуетесь. ЦБ не запрещает криптовалюту прямо, и даже вроде бы как разрешает, а на самом деле — неявно её запрещает. Как? Очень просто: разрешает крупняку — Мосбирже, банкам и прочим «избранным», — а для всех остальных строит заградительные механики (о них — далее). И даже дело не в уставном капитале, это самое лайтовое из всего, что нас ждёт.

Торгуют все!

Начнём с «разрешённого» — 300 тысяч рублей в год на человека, такой торговый объём будет разрешён простым смертным. Ну праздник же.

Это целых 25 тысяч рублей в месяц. Цена одного похода в ресторан среднего уровня на двоих. Это меньше, чем билеты в театр на семью на не самые паршивые места (и, заметьте — даже без бутербродов в буфете). И вот это называют «инвестициями».

Это не инвестиции — это издевательство над людьми. Цирк, фарс и плевок в лицо людям, которые даже более‑менее понимают что такое криптовалюта. Это 1/195 биткоина. ОДНА СТОДЕВЯНОСТОПЯТАЯ. Тут даже пробелы ставить не хочется.

Инвестируйте на здоровье, это ведь гораздо более рискованно, чем Самолёт или ВТБ, или вообще весь наш рынок в целом (нет).

Криптодепозитарии

«Ладно, обычных смертных мы проехали и переехали, едем дальше — кого теперь мы переедем? А давайте переедем бизнес! Устроим монополию, ведь нам так скучно живётся, мы любим всё консолидировать, монополизировать и убивать МСП!» — мне кажется, примерно такие разговоры царят в курилках где‑то там, где пишутся грядущие законы, или что‑то в этом роде.

Познакомьтесь: прекрасная сущность под названием «криптодепозитарий». Что это такое и зачем? А это придумано ровно для того, чтобы обменники, биржи и кошельки не могли больше легально существовать. А если бы могли — то хранили бы криптовалюту ТОЛЬКО в этих самых депозитариях. Не у себя, не в своей инфраструктуре, которую они писали годы, интегрировали блокчейны, заботились о безопасности и собирали шишки, набирали опыт и вкладывали силы, время своей жизни и деньги. Всё это — на помойку, если хочешь работать в России. И пользуйся депозитариями, написанными кем? А тем, кто никогда до этого с криптовалютами в принципе не работал.

Иными словами: собираем всю ликвидность через обменники, кошельки и агентов, которые работают с физами, в один котёл, и там храним. «А чо, удобно же».

Кто это лоббирует, все знают, называть не будем эту одну большую биржу, которая очень хорошо «дружит» с ЦБ и методично пропихивает нужные ей положения в законе. Кто знает, тот знает, как говорится. А кто не знает, догадывается и понимает.

Только вот, эта одна большая биржа в силу своей жадности не понимает одной простой вещи: всё это приведёт к такой консолидации криптовалюты в одних руках (или в двух‑трех), что весь рынок и весь ВЭД ляжет и уже не встанет. Почему?

Да потому, что USDT там будут заморожены славной американской компанией Tether — это вопрос не «если», а «когда». А всё, что не USDT, будет промаркировано и не будет приниматься нигде, кроме России и даркнета. Крупная биржа что, всерьёз планирует обелять промаркированную криптовалюту через миксеры? Или сбывать и покупать оружие и наркотики в даркнете? На что надежда — на Казахстан, Беларусь? Кто будет забирать санкционные BTC и ETH?? Про USDT даже речи не идёт, забирать в принципе нечего будет.

Чем они мотивируются — понятно: всосать в себя максимум ликвидности и зарабатывать на стейкинге. Большие деньги, между прочим, если взять всю криптовалюту, которая есть в РФ.

А вот вопрос: а смогут ли они стейкать замороженные USDT? (спойлер: нет, не смогут.) Смогут ли стейкать маркированные BTC и ETH? С большим трудом, а скорее всего, тоже вообще не смогут.

А где после этого оборонка будет брать криптовалютную ликвидность для закупки стратегически важного для того же СВО? Да, там не всё через криптовалюту идет, но по тем же данным тех же ФОИВов, 40–50% ВЭД идет именно так. Так что, где ликвидность будут брать, которая не маркированная? Правильно — нигде. Останутся с рублём, который заперт ровно так же, как будет заперта и крипта.

А вот теперь особенно обидно: Минфин, который вроде бы за свободу криптовалюты в России ратовал, и сам теперь туда же. Вместо того, чтобы хоть раз сесть и разобраться, как вообще работает криптовалюта, в чём сила децентрализации и что реально произойдёт после принятия этого замечательного закона о цифровых валютах, придумали подарок всем нам ещё и от себя. О нём — далее.

Запрет холодных кошельков

Я даже не знаю, как к этому относиться. У меня, кажется, дежавю. Однажды запретили слово «жопа», но слово почему‑то осталось. Как и жопа, в которую мы все дружно погружаемся. Я конечно не сравниваю кошельки с этим запрещённым словом, но аналогия примерно такая же.

Мне вот искренне интересно: хоть кто‑нибудь из этих авторов задумывается, КАК физически/технически можно запретить холодный кошелёк? Они понимают, что холодный кошелёк — это, по сути, набор слов в голове или на бумажке? Что они запретят? Память? Бумагу? Математику? Интернет? Не назапрещались ещё?

Ну а раз запретить никак, надо что? Надо уголовку! Ура! Ещё статей! Больше! Жить станет лучше с каждым днём! Пока не знают, каких статей, но наверняка придумают. Это даже не 451 градус по Фаренгейту, а уже где‑то за 700. В общем, ждём и предвкушаем, друзья.

И тут внезапный вопрос: а ПОЧЕМУ они хотят запретить холодные кошельки? Ради безопасности? Контроля? Налогов? Чтобы знали, кто что куда зачем когда? Мне кажется, нет.

Я думаю, что дело в той же ликвидности, чтобы с большой и крупной биржи криптовалюту не выводили. Завёл — и хватит, сиди там. Получи расписку и пусть лежит, где положено. Стейкинг ведь должен капать, и не тебе, холопу, а достойной организации. И будет капать, пока благополучно не сдохнет в заморозке, вместе с настейканным. Очевидно, опыт заморозки ЗВР не научил ничему. Опыт Garantex и Grinex — тоже. Грабли — наше всё, это круче хождения по гвоздям в сто раз, ещё и звездочки увидеть можно.

Ладно, резюмируем: завёл крипту в «лицензированную историю» — нет у тебя крипты. Тока. Fin.

И кстати, не слушайте рассказов «ведь можно будет выводить на какие‑то иностранные биржи». Удачи выводить маркированную, красную, санкционную, замороженную криптовалюту на иностранные и даже не иностранные биржи. Можно, конечно, попробовать использовать какие‑то близлежащие биржи, типа Токенспота, Whityebird, как прокси: наша скрепная большая биржа → СНГшная → холодный кошелёк. Только на одной этой схеме вы разгрузитесь минимум на $10 на одних комиссиях блокчейна + комиссиях самих бирж за вывод (в среднем $3 на биржу + $3 с биржи на вторую + $3 со второй на холодный). И даже если всё это получится — поздравляю, у вас на холодном кошельке прекрасная маркированная криптовалюта! Winning!

Подарок от Минфина

Вы думаете, это всё? А вот и нет.

Биржам и обменникам планируется вменить обязательную торговую комиссию в 2–3% на каждую операцию. Да, это не опечатка. Не 0,2–0,3% — ДВА‑ТРИ процента! Представляете, какими «конкурентоспособными» они станут? Против 0,075–0,1% на Binance или Bybit? Консолидируем и заставим торговать с комиссиями в 40–50 раз выше, чем на нескрепных биржах.

Так вот, если всех отправят в это стойло и заставят жевать кактус, то к вашим $9 за перемещение собственных монет САМОМУ СЕБЕ вы ещё разгрузитесь на пару процентов сверху, если надо будет что‑то конвертнуть. Это ли не искренняя, нежная любовь к инвесторам и трейдерам?

Откуда это всё взялось

Напоминаю — личное мнение тут высказываю, можно соглашаться, можно нет. Мне кажется — тут дело в банальной аффилированности. От желания срубить денег здесь и сейчас, а «после нас хоть потоп», и гори оно всё (наша экономика) синим пламенем. Получалось торговать с заграницей через криптовалюту? Удобно было обходить санкции? А вот больше не надо, зато правильные люди денег заработают, а то голодают, небось.

Да, нам рассказывают красивые слова: «ВЭД это не коснётся, ВЭД будут торговать, как и раньше». Ещё как коснётся, бестолочи! Ликвидности в стране просто не будет! Откуда у ВЭД‑платформ и агентов криптовалюта? Оттуда, что её собирают по крошкам тут и там, в серой зоне, часто на честном слове. А после этого чудо‑юдо‑закона собирать будет негде и не у кого, либо уже не в серую, а в очень-очень чёрную. Вы были криптотрейдером или инвестором? Поздравляю, либо в стойло, либо вы будете на уровне торговцев наркотой, оружием и прочим запрещенным.

Са‑бо‑таж

Мне четко понятно и видно: то, что происходит, — это не действия в интересах страны, народа или государственной безопасности. Это запланированное разрушение целой индустрии, в которой мы итак находимся примерно в том самом запрещённом слове. Это настоящий саботаж даже не криптоиндустрии, а вообще всей экономики. Стартапы в крипте? Что? Какие такие стартапы? Блокчейн кошельки, DeFI? Что? Какая такая децентрализация, не знаем. Зато у нас — в квартире газ. А у вас?

Тут недавно услышал смешное: «за границей же есть депозитарии, и они работают, и у нас будут!». Да, там они работают. Только там есть две маленькие детали: 1) там нет санкций, и никто не «окрашивает» хранящуюся там крипту в красный и не будет ее замораживать; 2) их использование — сугубо по желанию, а не из‑под палки, не под угрозой уголовки. Как говорится, так‑то оно так, но есть нюансы.

Я вообще не уверен, что Эльвира Сахипзадовна в курсе, что творят её подчинённые. Мне кажется, что нет, — не может такого быть, она ведь очень умная женщина. Подозреваю, что ей рассказывают, как всё будет прекрасно и почему именно так надо сделать, как все заживут счастливо и весело, а о негативных последствиях либо сами не в курсе, либо умалчивают. И я очень сильно подозреваю, что как раз второе.

Напоследок, поделюсь наблюдением: Все, абсолютно ВСЕ, кто в России ещё остался и не уехал (наверное, мы дебилы — зачем мы тут сидим и пытаемся что‑то улучшить, построить, легализовать), об этих рисках говорили, писали, отправляли правки в законопроект. Толку — ноль. Ровно ноль. Никого из нас не услышали, потому что нас изначально и не собирались слушать.

Живи ярко, сгори красиво — лучше один раз полыхнуть, чем медленно тлеть.

Аминь.

P. S. А мы ещё лидеров ЕС ругаем и думаем, смеемся. Задорнов наверное бы, увидев то что происходит сейчас, переквалифицировался бы.

P.P. S. Я добавил хаб киберпанк, потому что это уже не фантастика, это реальность к которой мы все ближе и ближе.

Хабр Курсы для всех

Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!

[Перевод] Что делать, если HTTP‑запрос прошёл, а транзакция в БД откатилась?

ZheleznyChel (Timeweb Cloud) — Tue, 23 Jun 2026 08:05:12 +0000

ZheleznyChel10 минут назад

Средний

34 мин

Туториал

Перевод

❯ Введение

Суть проблемы предельно проста: если внешний сетевой запрос завершится успешно, а фиксация изменений в БД сорвется, ваша система зависнет в несогласованном состоянии, которое невозможно откатить. В этой статье мы подробно, шаг за шагом, разберем реально работающую реализацию связки паттернов Transactional Outbox (исходящие транзакции) + Result Table (таблица результатов) + Saga Compensation (компенсирующие транзакции) на языке Scala с использованием Play Framework, Slick и Pekko.

Если ваше приложение одновременно сохраняет данные в базу и отправляет запросы к внешним веб-сервисам, у вас гарантированно возникнет проблема несогласованности данных (проблема двойной записи). Паттерны Transactional Outbox и Saga – это классические, описанные во всех учебниках решения. Однако большинство статей на эту тему ограничиваются голой теорией. Мы же пойдем дальше.

Мы создадим полноценное рабочее приложение, которое вы сможете склонировать, запустить у себя и адаптировать под свои задачи. Проект объединяет три паттерна, которые идеально дополняют друг друга. Transactional Outbox (исходящий почтовый ящик) дает железную гарантию того, что каждое событие будет обработано, даже если само приложение внезапно упадет посреди отправки запроса. Result Table (таблица результатов) фиксирует детали каждого вызова API, ответы сторонних систем и полученные идентификаторы, которые понадобятся, если операцию придется отменить. Saga Compensation (компенсирующие транзакции) – если, к примеру, четвертый шаг цепочки завершится сбоем, этот механизм автоматически и в правильном порядке откатит предыдущие три шага.

В нашем примере используются Play Framework, Scala 3, PostgreSQL, Slick и акторы Pekko. Тем не менее вся архитектура абсолютно не зависит от языка программирования или фреймворка. Вы можете заменить эти библиотеки на любые аналоги – сами концепции останутся неизменными.

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

git clone https://github.com/hanishi/never-call-apis-inside-database-transactions
cd never-call-apis-inside-database-transactions

Чтобы запустить его локально:

docker-compose up -d postgres
sbt run
# Открыть http://localhost:9000

В проект встроен интерактивный симулятор внешних служб (склад, биллинг, доставка, проверка на мошенничество) с настраиваемой вероятностью сбоев, удобный веб-интерфейс для оформления заказов и провоцирования ошибок, а также подробный журнал аудита для каждого вызова API. О том, как запустить конкретные сценарии, мы поговорим в разделе «Время экспериментов» в конце статьи.

Итак, поехали.

❯ Зачем всё это нужно?

Если ваша система выполняет хотя бы одно из следующих действий, вы неизбежно сталкиваетесь с проблемой двойной записи (dual-write problem):

Сохраняет данные в локальную базу, а затем вызывает внешнее API, меняющее состояние сторонней системы (списание денег через платежный шлюз, резервирование товара на складе, планирование логистики на стороне курьерской службы или публикация события в Kafka). Обратите внимание: запросы только на чтение (например, загрузка кредитного рейтинга) подобных проблем не создают, поскольку на той стороне просто нечего откатывать при аварии.
Координирует работу нескольких сервисов в рамках одной сквозной бизнес-операции (например: заблокировать товар → проверить на фрод → запланировать доставку → провести оплату).
Должна уметь откатить частично выполненную работу, если один из этапов длинной цепочки завершился неудачей.

Без этих паттернов ваша система рано или поздно окажется в ситуации, когда деньги с клиента успешно списаны, а самого заказа в базе нет; товары на складе заблокированы под заказы-невидимки, или курьеры спешат везти посылку, которая была давно отменена. Паттерн Outbox устраняет подобные нестыковки непосредственно на уровне архитектурного дизайна.

Прежде чем начать:
В примерах мы используем Scala 3 и три ключевые библиотеки. Вот краткий экскурс для быстрого погружения:
Slick: функционально-реляционная библиотека для Scala, обеспечивающая типобезопасность запросов к СУБД. В коде вам будет регулярно встречаться тип DBIO[T]. Это декларативное описание операции с базой данных, возвращающее результат типа T. Оно похоже на то, как Future[T] описывает асинхронную операцию. Сам по себе DBIO не запускается, пока вы явно не передадите его методу db.run(...). Вы можете объединять несколько цепочек DBIO с помощью for-comprehension и оборачивать их в .transactionally, чтобы СУБД выполнила их как единую атомарную транзакцию.
Apache Pekko: фреймворк для параллельного программирования на базе модели акторов (открытый преемник Акка). Акторы – это ультралегкие изолированные сущности, обрабатывающие сообщения строго поочередно, что делает их идеальными кандидатами для построения надежных фоновых обработчиков.
Play Framework: веб-фреймворк для Scala, использующий формат HOCON (application.conf) для удобной конфигурации приложения.

❯ В чем корень проблемы?

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

Сохранить заказ в базу данных
Зарезервировать товары на складе
Запланировать доставку
Списать деньги с карты

Библиотека Slick предлагает удобную лазейку: метод DBIO.from() преобразует любой Future в DBIO. Это позволяет выстраивать асинхронную работу и запросы к БД в единую цепочку с помощью for-comprehension. Штука удобная, но в ней скрыта опасная ловушка. В Scala запросы к внешним API обычно возвращают Future[T] (неважно, используете ли вы WSClient из состава Play, библиотеку sttp или любой другой HTTP-клиент). А поскольку DBIO.from() проглатывает вообще любой Future, у разработчика возникает соблазн упаковать туда сетевые вызовы и засунуть всё это внутрь блока .transactionally. Код компилируется без единой ошибки, типы идеально сходятся, и всё выглядит так, будто весь процесс застрахован единой транзакцией:

db.run {
  (for {
    orderId <- orders += order                              // Запись в БД
    _       <- DBIO.from(inventoryApi.reserve(orderId))     // HTTP-вызов, обернутый в DBIO
    _       <- DBIO.from(shippingApi.schedule(orderId))     // HTTP-вызов, обернутый в DBIO
    _       <- DBIO.from(billingApi.charge(orderId))        // HTTP-вызов, обернутый в DBIO
    _       <- shipments += Shipment(orderId, shippingRes)  // Запись в БД
  } yield orderId).transactionally
}

Но здесь кроется подвох: транзакция СУБД контролирует исключительно процессы внутри самой базы данных. С точки зрения транзакции, HTTP-запросы внутри DBIO.from() – это операции по принципу «выстрелил и забыл». Они выполняются, их побочные эффекты материализуются мгновенно, а у базы просто нет механизмов, чтобы откатить изменения на сторонних серверах. Представьте, что произойдет, если последняя запись в БД сорвется:

Создание заказа в БД → успешно
Вызов API склада → 200 OK (товар зарезервирован)
Вызов API службы доставки → 200 OK (доставка запланирована)
Вызов API платежной системы → 200 OK (деньги списаны)
Запись информации о доставке в БД → сбой (дедлок, сетевой таймаут – неважно)
База данных откатывает транзакцию

Итог: у клиента списали деньги, доставка вовсю готовится, на складе товар заблокирован… а в вашей базе данных нет и следа самого заказа! Внешние сервисы понятия не имеют, что транзакция в вашей локальной БД развалилась. Они свою работу сделали и спят спокойно.

Простая попытка разделить эти операции тоже не спасет:

// Шаг 1: Сохраняем в БД
val orderId = db.run(orders += order).transactionally  // Успешно
// Шаг 2: Вызываем внешние сервисы
inventoryApi.reserve(orderId)   // Успешно
shippingApi.schedule(orderId)   // Здесь приложение падает; доставка не вызвана
billingApi.charge(orderId)      // Этот вызов даже не начинался

Если приложение потерпит крах в зазоре между шагом 1 и шагом 2, заказ останется лежать в БД мертвым грузом – больше ничего не произойдет. Никакой повторный запуск не сработает, потому что идентификатор orderId бесследно стерся из оперативной памяти.

Распределенных транзакций, способных бесшовно связать разнородные системы, в реальном мире не существует. СУБД гарантирует атомарность только для собственных таблиц, но она бессильна перед сторонними HTTP API, брокерами Kafka или чужими платежными шлюзами. Каждая система фиксирует изменения независимо, падает независимо и абсолютно не подозревает о том, что происходит у соседей.

❯ Решение: паттерн Transactional Outbox

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

То есть вместо прямой отправки запросов на склад, доставку и оплату мы добавляем специальную запись в таблицу outbox_events – и делаем это в рамках той же транзакции базы данных, в которой создается сам заказ:

BEGIN;
  INSERT INTO orders (customer_id, total_amount, ...) VALUES ('C-123', 99.99, ...);
  INSERT INTO outbox_events (event_type, payloads, status) VALUES ('OrderCreated', '{...}', 'PENDING');
COMMIT;

По ходу транзакции не происходит никаких сетевых вызовов – только быстрые и надежные локальные записи в таблицы.

Специальный фоновый обработчик (в нашей реализации – актор Pekko под названием OutboxProcessor) непрерывно сканирует эту таблицу. Обнаружив событие в статусе PENDING (ожидает обработки), он резервирует его под себя, отправляет реальные HTTP-запросы и меняет статус записи на PROCESSED (обработано). Если приложение упадет до того, как воркер доберется до записи, событие никуда не денется из БД. Воркер просто подхватит его сразу после перезапуска.

Это полностью решает проблему «API сработал, а БД откатилась», поскольку к внешним вызовам мы переходим только после успешной фиксации локальной транзакции.

❯ А что делать при частичных сбоях?

Паттерн Outbox гарантирует доставку и обработку каждого события. Но представьте: воркер поочередно совершил два успешных вызова, а на третьем споткнулся:

1. Зарезервировать товар  → успешно (reservationId: "RES-456")
2. Запланировать доставку → успешно (shipmentId: "SHIP-789")
3. Списать оплату         → сбой после 3 попыток отправки

Товар на складе заблокирован, курьеры уже пакуют посылку, но оплата так и не прошла. Очевидно, нужно откатить шаги 1 и 2. Причем делать это нужно строго в обратном порядке (LIFO – последним вошёл, первым вышел), ведь оформление доставки логически зависит от резерва на складе.

Перед нами классический паттерн Saga Compensation (компенсирующая транзакция): при сбое на промежуточном этапе мы последовательно отменяем все успешные предыдущие шаги в обратном порядке. Сначала отменяем доставку, затем снимаем резерв со склада.

Но чтобы выполнить откаты, система должна точно знать, какие шаги завершились успехом и какие данные они нам вернули. Например, для вызова отмены доставки сервису нужен конкретный shipmentId, сгенерированный сторонней службой. Вот почему нам жизненно необходим паттерн Result Table (таблица результатов) – подробнейший аудит-лог, куда записывается каждый сетевой запрос, его результат и полный текст ответа API.

Эти три паттерна безупречно работают в связке:

Паттерн	Какую проблему решает	Как именно
Transactional Outbox	Двойная запись (dual-write)	Атомарно записывает заказ и событие в БД
Result Table	«Что именно мне откатывать?»	Регистрирует каждый вызов API и ответ от него
Saga compensation	Частичные сбои в цепочке	Отменяет успешные вызовы в обратном порядке (LIFO)

Разберем создание всех трех компонентов шаг за шагом.

❯ Схема базы данных

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

❯ orders – бизнес-данные

Эту таблицу вы бы спроектировали в любом случае. Никакой специфики Outbox здесь нет:

CREATE TABLE orders (
    id            BIGSERIAL PRIMARY KEY,
    customer_id   VARCHAR(255)   NOT NULL,
    total_amount  DECIMAL(10, 2) NOT NULL,
    shipping_type VARCHAR(20)    NOT NULL DEFAULT 'domestic',
    order_status  VARCHAR(50)    NOT NULL DEFAULT 'PENDING',
    created_at    TIMESTAMP      NOT NULL DEFAULT NOW(),
    updated_at    TIMESTAMP      NOT NULL DEFAULT NOW(),
    deleted       BOOLEAN        NOT NULL DEFAULT FALSE
);

❯ outbox_events – план работ

Каждая строка в этой таблице представляет собой конкретное бизнес-событие, информацию о котором нужно передать внешним API. Чтением и записью здесь заправляет вспомогательный класс OutboxHelper (его мы разберем далее):

CREATE TABLE outbox_events (
    id                BIGSERIAL PRIMARY KEY,
    aggregate_id      VARCHAR(255)  NOT NULL,   -- к какому заказу (или сущности) относится событие
    event_type        VARCHAR(255)  NOT NULL,   -- например, "OrderCreated", "OrderStatusUpdated"
    payloads          JSONB         NOT NULL,   -- специфические данные для каждого адресата (один ключ на API)
    status            VARCHAR(20)   NOT NULL DEFAULT 'PENDING',  -- PENDING → PROCESSING → PROCESSED
    retry_count       INT           NOT NULL DEFAULT 0,
    idempotency_key   VARCHAR(512)  NOT NULL,   -- защищает от дублирования событий
    next_retry_at     TIMESTAMP WITH TIME ZONE, -- когда повторить попытку в случае сбоя
    -- ... плюс временные метки, трекинг ошибок и т.д.
);
-- Только одно активное событие на связку агрегат + тип (защита от дубликатов)
CREATE UNIQUE INDEX idx_outbox_idempotency
    ON outbox_events (idempotency_key)
    WHERE status != 'PROCESSED';

СУБД-колонка payloads с типом JSONB хранит карту (map), где ключи – это названия систем-получателей (например, "inventory", "billing"), а значения – передаваемые им данные. Совсем скоро мы увидим, как строятся эти структуры при объявлении доменных событий.

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

❯ Атомарная запись событий

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

❯ Доменные события

Каждая бизнес-операция генерирует определенное доменное событие. Например, событие OrderCreatedEvent точно знает, в какие сервисы нужно отправить данные и какие структуры им для этого нужны:

sealed trait DomainEvent {
  def aggregateId: String                        // к какой сущности относится (например, ID заказа)
  def eventType: String                          // например, "OrderCreated"
  def toPayloads: Map[String, DestinationConfig] // специфические данные для каждого адресата
}
case class OrderCreatedEvent(
    orderId: Long, customerId: String,
    totalAmount: BigDecimal, shippingType: String,
    timestamp: Instant = Instant.now()
) extends DomainEvent {
  override def aggregateId = orderId.toString
  override def eventType   = "OrderCreated"
  override def toPayloads = Map(
    "inventory" -> DestinationConfig(payload = Some(Json.obj(
      "orderId" -> orderId, "totalAmount" -> totalAmount, "shippingType" -> shippingType
    ))),
    "fraudCheck" -> DestinationConfig(payload = Some(Json.obj(
      "orderId" -> orderId, "customerId" -> customerId, "totalAmount" -> totalAmount
    ))),
    "shipping" -> DestinationConfig(payload = Some(Json.obj(
      "customerId" -> customerId, "shippingType" -> shippingType, "totalAmount" -> totalAmount
    ))),
    "billing" -> DestinationConfig(payload = Some(Json.obj(
      "amount" -> totalAmount, "currency" -> "USD"
    )))
  )
}

Каждая служба-адресат получает только те данные, которые ей действительно необходимы. Сервису проверки на мошенничество (fraudCheck) уходят идентификатор клиента и сумма покупки для скоринга рисков. Сервису оплаты (billing) – только сумма и валюта платежа.

❯ Трейт OutboxHelper

Трейт OutboxHelper берет на себя гарантию атомарности. Он оборачивает выполнение вашей бизнес-логики и сохранение события в системный метод .transactionally. В итоге они либо запишутся в базу вместе, либо обе операции будут откачены:

trait OutboxHelper {
  protected val outbox = TableQuery[OutboxTable]
  protected def withEvent[T](event: DomainEvent)(action: DBIO[T])
      (using ec: ExecutionContext): DBIO[T] =
    (for {
      result <- action              // Ваша запись бизнес-данных (например, INSERT INTO orders)
      _      <- saveEvent(event)    // INSERT INTO outbox_events
    } yield result).transactionally // ← обе операции в рамках одной транзакции
  protected def withEventFactory[T](action: DBIO[T])(eventFactory: T => DomainEvent)
      (using ec: ExecutionContext): DBIO[T] =
    (for {
      result <- action
      _      <- saveEvent(eventFactory(result))  // событие зависит от результата выполнения действия (например, автоинкрементный ID)
    } yield result).transactionally
}

Здесь предусмотрено два удобных сценария использования:

withEvent принимает уже созданное событие и саму процедуру изменения БД. Он идеален для ситуаций, когда все реквизиты события у вас на руках еще до обращения к базе (например, при отмене заказа, когда его ID давно известен).
withEventFactory принимает СУБД-действие и фабричный метод T => DomainEvent. Сначала выполняется запись бизнес-данных, результат этой записи передается в фабрику, а та генерирует событие. Без этого не обойтись, если параметры события зависят от значений, генерируемых самой СУБД (например, от автоинкрементного первичного ключа заказа). Вы просто не сможете заранее создать OrderCreatedEvent без orderId, а сам orderId станет известен только после выполнения инструкции INSERT. Метод withEventFactory решает эту дилемму: он откладывает сборку события ровно до того момента, когда у нас появится сгенерированный базой ID, при этом по-прежнему гарантируя безупречную атомарность в рамках единой транзакции.

Этот блок написан под Slick: сущности DBIO, TableQuery и метод .transactionally – чисто его специфика. Но сам архитектурный паттерн абсолютно универсален. Ваша задача – связать воедино сохранение бизнес-сущности и запись события в одной транзакции СУБД. В Hibernate/JPA для этого используют аннотацию @Transactional, в jOOQ – вызов dsl.transaction(...), а на голом JDBC – инструкцию connection.setAutoCommit(false).

❯ Собираем всё вместе в репозитории

Репозиторий OrderRepository просто примешивает трейт OutboxHelper. Теперь создание нового заказа превращается в элегантную однострочную конструкцию:

@Singleton
class OrderRepository @Inject() ()(using ec: ExecutionContext) extends OutboxHelper {
  private val orders = TableQuery[OrderTable]
  def createWithEvent(order: Order): DBIO[Long] =
    withEventFactory((orders returning orders.map(_.id)) += order) { orderId =>
      OrderCreatedEvent(orderId, order.customerId, order.totalAmount, order.shippingType)
    }
}

Во время вызова метода createWithEvent на стороне СУБД выполняется следующий SQL-сценарий:

BEGIN;
  INSERT INTO orders (customer_id, total_amount, shipping_type, order_status)
    VALUES ('C-123', 99.99, 'domestic', 'PENDING')
    RETURNING id;  -- Возвращает 123
  INSERT INTO outbox_events (aggregate_id, event_type, payloads, idempotency_key, status)
    VALUES ('123', 'OrderCreated',
      '{"inventory": {...}, "fraudCheck": {...}, "shipping": {...}, "billing": {...}}',
      '123:OrderCreated', 'PENDING');
COMMIT;

В результате либо сохранятся обе записи, либо ни одна из них. Сервисному уровню остается лишь выполнить привычный метод db.run(...). В терминах Slick эта функция принимает DBIO (описание плана СУБД-операций), запускает его физическое выполнение и возвращает привычный Future с полученным значением:

class OrderService @Inject() (orderRepo: OrderRepository, ...)
    (using ec: ExecutionContext, db: Database) {
  def createOrder(order: Order): Future[Long] =
    db.run(orderRepo.createWithEvent(order))
    // createWithEvent возвращает DBIO[Long] (описание плана СУБД-транзакции)
    // db.run(...) запускает транзакцию на выполнение и возвращает Future[Long] (сгенерированный ID заказа)
}

Отлично. Теперь заказ благополучно сохранен в базу, а в таблице событий дожидается своего часа запись со статусом PENDING. Никаких лишних HTTP-запросов во время транзакции выполнено не было. Теперь перейдем к обработке накопившейся очереди.

❯ Обработка событий: OutboxProcessor

В нашей таблице появилось событие в состоянии PENDING. Логично, что теперь нужен фоновый обработчик, который прочитает эту запись и дернет внешние API. За это и отвечает OutboxProcessor – фоновый типизированный актор Pekko.

❯ Безопасный захват событий в конкурентной среде

В высоконагруженных продакшен-системах события обрабатывают сразу несколько параллельных воркеров. Но как гарантировать, что два независимых процесса не схватят одновременно одну и ту же запись? Эту проблему решает встроенная конструкция PostgreSQL FOR UPDATE SKIP LOCKED всего за один атомарный запрос:

def findAndClaimUnprocessed(limit: Int = 100): DBIO[Seq[OutboxEvent]] = {
  sql"""
    WITH claimed AS (
      SELECT id FROM outbox_events
      WHERE status = 'PENDING'
        AND (next_retry_at IS NULL OR next_retry_at <= NOW())
      ORDER BY created_at
      LIMIT $limit
      FOR UPDATE SKIP LOCKED
    )
    UPDATE outbox_events e
    SET status = 'PROCESSING', status_changed_at = NOW()
    FROM claimed
    WHERE e.id = claimed.id
    RETURNING e.*
  """.as[OutboxEvent]
}

С помощью обобщенного табличного выражения (CTE) этот запрос выполняет три важнейших действия за одно обращение к диску (атомарно):

Поиск (Select). Временная таблица WITH claimed находит строки в статусе 'PENDING', время повторной отправки которых подошло (или поле next_retry_at вовсе пусто). Сортировка по created_at гарантирует обработку строго по хронологии, а параметр LIMIT ограничивает размер порции.
Блокировка (Lock). Ключевым элементом здесь выступает инструкция FOR UPDATE SKIP LOCKED. Она накладывает монопольную блокировку на выбранные строки, но при этом воркеры не зависают в ожидании освобождения занятых записей, а просто пропускают заблокированные (SKIP LOCKED). Если запустить три параллельных воркера одновременно, каждый из них получит чисто свой уникальный пакет событий – без пересечений, конфликтов или повторной обработки.
Обновление и возврат данных (Update & Return). Внешний оператор UPDATE переводит выбранные записи из статуса 'PENDING' в 'PROCESSING' и мгновенно возвращает их содержимое в приложение. За один единственный сетевой цикл мы находим, блокируем, резервируем и забираем нужные события!

❯ Вызов внешних API

Захватив событие, процессор переходит к публикации – то есть поочередно дергает внешние HTTP-эндпоинты. Дальнейшие действия зависят от ответа серверов:

private def publishEvent(event: OutboxEvent): Future[Boolean] =
  publisher.publish(event).flatMap {
    case PublishResult.Success =>
      db.run(outboxRepo.markProcessed(event.id)).map(_ => true)
    case PublishResult.Retryable(error, retryAfter) =>
      handleRetryableFailure(event, error, retryAfter)
    case PublishResult.NonRetryable(error) =>
      handleNonRetryableFailure(event, error)
  }

Успех (Success). Помечаем запись в базе как PROCESSED. Задача решена.
Повторяемый сбой (Retryable failure) (например, при ошибке 503 Service Unavailable). Планируем повтор с экспоненциальной задержкой (выжидаем 2, 4, затем 8 секунд). Если сервер вернул заголовок Retry-After, ориентируемся строго на него.
Неповторяемый сбой (Non-retryable failure) (например, критический статус ответа 400 Bad Request). Отправляем событие напрямую в очередь недоставленных сообщений (DLQ – Dead Letter Queue).

Если лимит повторных попыток исчерпан (по умолчанию разрешено 3 попытки), событие отправляется в очередь недоставленных сообщений для запуска процедуры автоматического отката (о ней мы подробно поговорим в разделе «Автоматическая компенсация»).

❯ Мгновенный запуск процессов через механизмы LISTEN и NOTIFY

Вместо того чтобы мучить базу данных постоянными опросами каждые несколько секунд и плодить лишние задержки, мы настроим триггер PostgreSQL. Он будет мгновенно будить наш обработчик при добавлении новой записи:

CREATE OR REPLACE FUNCTION notify_new_outbox_event() RETURNS trigger AS $$
BEGIN
    IF NEW.status = 'PENDING' THEN
        PERFORM pg_notify('outbox_events_channel', NEW.id::text);
    END IF;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;
CREATE TRIGGER outbox_event_inserted
    AFTER INSERT OR UPDATE OF status ON outbox_events
    FOR EACH ROW EXECUTE FUNCTION notify_new_outbox_event();

Разумеется, подобные конструкции специфичны для PostgreSQL. Однако именно благодаря богатейшему встроенному функционалу (LISTEN/NOTIFY, FOR UPDATE SKIP LOCKED, поддержка типа JSONB, частичные индексы) Postgres выглядит идеальным выбором под паттерн Outbox. В проекте из репозитория весь этот потенциал выжат по полной программе.

Мостом, связывающим уведомления из Postgres с нашим OutboxProcessor, служит источник Pekko Streams (PostgresListenNotifyStream). Он постоянно держит соединение в канале уведомлений, буферизирует поступающие ID событий и отправляет актору команду ProcessUnhandledEvent. Использование реактивного стрима из коробки дает нам управление нагрузкой (backpressure), автоматическое восстановление соединения с растущим таймаутом и безопасное выключение фонового процесса. Как только транзакция с заказом и событием успешно фиксируется (о чем говорилось в разделе «Атомарная запись событий»), СУБД активирует триггер, стрим мгновенно перехватывает сигнал, и процессор приступает к работе буквально через миллисекунды. А если по каким-то причинам механизмы LISTEN/NOTIFY недоступны, система автоматически переключается в классический режим периодического опроса таблиц.

❯ Веерная рассылка (fan-out) и условная маршрутизация

До сих пор мы рассматривали обработку одиночных вызовов. Но наше событие OrderCreated должно поочередно облететь целый ряд систем, причем в строгом порядке. В нашей реализации правила маршрутизации вынесены целиком в файл конфигурации application.conf – никакой жесткой привязки к адресам в программном коде. Это дает потрясающую гибкость: подключать внешние системы, менять URL или изменять порядок рассылки можно прямо «на лету», без перекомпиляции приложения:

outbox.http.fanout {
  OrderCreated       = ["inventory", "fraudCheck", "shipping", "billing"]
  OrderStatusUpdated = ["notifications"]
}

Термин «веерная рассылка» (fan-out) в данном случае означает, что на одно доменное событие завязана целая пачка вызовов. Эти запросы выполняются последовательно, а не параллельно. Это сделано намеренно: последующие сервисы могут изменять свое поведение в зависимости от результатов предыдущих (например, биллинг сопоставляет риск-скоринг от фрода для выбора платежного шлюза). Тело каждого HTTP-запроса извлекается из той самой карты toPayloads, которую мы подготовили внутри структуры нашего доменного события, где ключи в точности соответствуют именам систем-получателей. Каждому такому получателю сопоставляется конкретный эндпоинт в конфигурации:

outbox.http.routes {
  inventory {
    url = "http://localhost:9000/api/inventory/reserve"
    method = "POST"
    timeout = 5 seconds
  }
  fraudCheck {
    url = "http://localhost:9000/api/fraud/check"
    method = "POST"
    timeout = 5 seconds
  }
}

После каждого успешного запроса результат немедленно сохраняется в третью таблицу – aggregate_results. Это наш журнал аудита. Таблица фиксирует отправленные данные, полные ответы от API и признак успешности вызова:

CREATE TABLE aggregate_results (
    id               BIGSERIAL PRIMARY KEY,
    aggregate_id     VARCHAR(255)  NOT NULL,   -- к какому заказу относится
    destination      VARCHAR(255)  NOT NULL,   -- получатель (например, "inventory", "shipping")
    request_payload  JSONB,                    -- что именно мы отправили в API
    response_payload JSONB,                    -- что API вернул нам в ответ
    success          BOOLEAN       NOT NULL,   -- прошел ли вызов успешно?
    fanout_order     INT           NOT NULL DEFAULT 0,  -- порядковый номер шага в рассылке (0, 1, 2...)
    -- ... плюс целевой URL, HTTP-метод, статус-код, время выполнения и т.д.
);

Зачем тащить в СУБД весь JSON-ответ целиком? Дело в том, что если на этапе оплаты произойдет сбой, системе придется отменять ранее созданную доставку. А для этого нам позарез нужен идентификатор shipmentId, сгенерированный сторонним сервисом во время прямого запроса. Это уникальное значение лежит как раз внутри сохраненного response_payload. Колонка fanout_order фиксирует порядковый номер шага (0, 1, 2…). Во время проведения компенсирующей транзакции мы пойдем по этим номерам в обратном направлении (LIFO), тем самым раскручивая клубок зависимостей без риска нарушить порядок этапов отмены.

❯ Условная маршрутизация

Пока всё выглядит просто – одному получателю соответствует строго один URL. Но что делать, если адрес назначения колеблется в зависимости от контекста заказа? Например, если для параметра "shippingType" указано значение "domestic" (внутри страны), доставка должна уходить на внутреннее API курьерской службы, а если "international" – на шлюз глобального почтового оператора.

Для этого мы можем задекларировать динамический список маршрутов в конфигурационном блоке routes в виде пар «URL + условие». При публикации обработчик последовательно проверяет эти правила сверху вниз и выбирает первый совпавший вариант:

shipping {
  method = "POST"
  routes = [{
    url = "http://localhost:9000/api/domestic-shipping"
    condition {
      jsonPath = "$.shippingType"   # извлекаем это поле из входящих данных
      operator = "eq"               # проверяем на равенство
      value = "domestic"            # ожидаемое значение
    }
  }, {
    url = "http://localhost:9000/api/international-shipping"
    condition {
      jsonPath = "$.shippingType"
      operator = "eq"
      value = "international"
    }
  }]
}

Добежав до этапа доставки (shipping), модуль публикации открывает тело исходящего запроса (например, {"shippingType": "domestic", ...}) и вычисляет выражение $.shippingType == "domestic". Условие соблюдено, а значит, система выполнит вызов POST /api/domestic-shipping. Если бы в параметре доставки стояла международная почта, первая проверка благополучно провалилась бы и система переключилась бы на второй URL.

Реализации условного блока поддерживает широкий набор стандартных операторов сравнения: eq (равно), ne (не равно), gt (больше), gte (больше или равно), lt (меньше), lte (меньше или равно), contains (содержит) и exists (существует/присутствует).

❯ Цепочка принятия решений: роутинг по ответам смежных сервисов

По-настоящему условная маршрутизация раскрывается тогда, когда логика маршрута строится вокруг данных, которых не было в изначальном запросе, – то есть параметров, возвращенных одной из соседних систем на ранних этапах.

Рассмотрим процесс оплаты. В клиентском запросе нет и не может быть оценки репутационных рисков – эту информацию генерирует наш собственный сервис фрод-скоринга (fraudCheck). При этом бизнес-логика требует: транзакции с низким риском проводить через рядовой платежный шлюз, а рискованные платежи отправлять специализированной системе контроля высокорисковых операций. Поскольку проверка на фрод выполняется до инициации платежа (в списке веерной рассылки она расположена раньше), к моменту запуска биллинга в системе уже сохранен исчерпывающий ответ от скоринг-сервиса.

Чтобы связать их воедино, мы используем специальное поле previousDestination. Оно дает инструкции обработчику: «проверяй указанное условие не во входящем payload, а в сохраненном ответе от указанного смежного сервиса»:

billing {
  method = "POST"
  routes = [{
    url = "http://localhost:9000/api/billing"
    condition {
      jsonPath = "$.riskScore"
      operator = "lt"
      value = "50"
      previousDestination = "fraudCheck"  # ← смотрим на ответ fraudCheck, а не на исходный запрос
    }
  }, {
    url = "http://localhost:9000/api/high-value-processing"
    condition {
      jsonPath = "$.riskScore"
      operator = "gte"
      value = "50"
      previousDestination = "fraudCheck"
    }
  }]
}

Каким образом публикатор получает доступ к ответам пройденных систем? Всё благодаря сущности RoutingContext. Это хранилище данных, которое аккумулирует возвращаемые JSON-ответы на протяжении всего жизненного цикла цепочки:

case class RoutingContext(destinationResponses: Map[String, JsValue] = Map.empty) {
  def withResponse(destination: String, response: JsValue): RoutingContext =
    copy(destinationResponses = destinationResponses + (destination -> response))
}

Вот как весь этот путь выглядит для события OrderCreated по шагам:

1. Обращаемся к складу (inventory)
   → 200 OK, ответ: {"reservationId": "RES-456"}
   → Результат записывается в aggregate_results
   → В контекст добавляется: {inventory: {"reservationId": "RES-456"}}
2. Проверяем операцию на защищенность (fraudCheck)
   → 200 OK, ответ: {"riskScore": 25, ...}
   → Результат записывается in aggregate_results
   → В контекст добавляется: {inventory: {...}, fraudCheck: {"riskScore": 25}}
3. Рассчитываем маршрут доставки (shipping)
   → Проверяем исходное тело запроса: $.shippingType == "domestic"? Да.
   → Выполняем вызов: POST /api/domestic-shipping
   → Сохраняем результат, обновляем контекст
4. Рассчитываем маршрут биллинга (billing)
   → Видим параметр previousDestination = "fraudCheck" и заглядываем в context["fraudCheck"]
   → Проверяем: $.riskScore < 50? В скоринге записано 25 → Да!
   → Выполняем вызов: POST /api/billing (стандартная оплата, без повышенного контроля)
   → Сохраняем результат в бэкенд и закрываем цепочку

Если бы скоринг-система вернула более тревожное значение вроде {"riskScore": 75}, на четвертом шаге сработал бы альтернативный маршрут до /api/high-value-processing. Самое приятное, что логика принятия решений диктуется исключительно гибкими конфигурациями и реальными данными – код приложения при этом остается железобетонным и защищенным от лишних изменений.

❯ Описание логики отмены через конфигурацию

В идеальном сценарии все четыре сервиса успешно завершают работу и событие помечается статусом PROCESSED. Но что если на каком-то этапе произойдет критическая ошибка? Прежде чем углубляться в архитектуру механизма откатов, ответим на фундаментальный вопрос: как нашей системе понять, каким образом отменить конкретный HTTP-вызов?

Вспомним, как шел прямой процесс. Веб-сервер отправил запрос службе доставки:

POST /api/domestic-shipping
Body: {"customerId": "C-123", "shippingType": "domestic", ...}

И в ответ прилетел документ:

{"shipmentId": "SHIP-789", "orderId": "123", "carrier": "FedEx"}

И исходящий запрос, и ответ сервиса благополучно лежат в нашей таблице aggregate_results (как мы разбирали в разделе «Веерная рассылка (Fan-Out) и условная маршрутизация»). Чтобы отменить эту доставку, нам нужно прийти на эндпоинт:

POST /api/domestic-shipping/SHIP-789/cancel

Разумеется, на этапе проектирования или компиляции мы не могли знать значение SHIP-789 – идентификатор сгенерировала сторонняя служба доставки в реальном времени. Единственное место, откуда мы можем его выудить, – это поле сохраненного JSON-ответа.

❯ Обучаем систему искусству отката

Любой шаг веерной рассылки имеет право содержать в конфигурации специальный блок revert. Начнем с самого простого примера отмены – из каталога склада (inventory):

inventory {
  url = "http://localhost:9000/api/inventory/reserve"
  method = "POST"
  revert {
    url = "http://localhost:9000/api/inventory/{reservationId}/release"
    method = "DELETE"
    extract {
      reservationId = "response:$.reservationId"
    }
  }
}

Разберем архитектуру этого блока:

extract (извлечение): дает указание системе выдернуть значение reservationId из тела JSON-ответа прямого вызова с помощью выражения JSONPath $.reservationId. Приставка response: явно указывает, что копать нужно в сохраненном ответе (в то время как приставка request: заставила бы искать во входящем payload исходного запроса).
url: использует заполнитель {reservationId} в качестве шаблона. Парсер автоматически подставит туда извлеченную строку.
method: задает метод DELETE. Передавать тело запроса в данном случае не требуется.

Таким образом, если при успешной попытке нам вернулось {"reservationId": "RES-456", ...}, компенсирующий вызов преобразуется в:

DELETE /api/inventory/RES-456/release

Те системы доставки данных, у которых блок revert отсутствует (например, сканирование fraudCheck), процессор отмены просто проигнорирует. Это исключительно читающие операции, которые логически не требуют обратного действия.

❯ Сложный пример: отмена запланированной доставки

Процесс отмены доставки устроен немного сложнее: здесь получателю требуется полноценное тело POST-запроса, собранное из данных как исходного запроса, так и прилетевшего ранее ответа:

shipping {
  routes = [{
    url = "http://localhost:9000/api/domestic-shipping"
    condition { jsonPath = "$.shippingType", operator = "eq", value = "domestic" }
    revert {
      url = "http://localhost:9000/api/domestic-shipping/{shipmentId}/cancel"
      method = "POST"
      extract {
        shipmentId = "response:$.shipmentId"    # Из ответа API службы доставки
        orderId    = "response:$.orderId"       # Тоже из ответа
        customerId = "request:$.customerId"     # Из исходного тела запроса, который мы слали
      }
      payload = """{"reason": "payment_failed", "shipmentId": "{shipmentId}",
                    "orderId": "{orderId}", "customerId": "{customerId}"}"""
    }
  }]
}

В данном случае блок extract берет на себя извлечение трех параметров: двух из ответа и одного из запроса. Затем все найденные фигурные скобки и в строке URL, и в строке payload заполняются полученными данными:

URL:     /api/domestic-shipping/{shipmentId}/cancel
       → /api/domestic-shipping/SHIP-789/cancel
Payload: {"reason": "payment_failed", "shipmentId": "{shipmentId}", ...}
       → {"reason": "payment_failed", "shipmentId": "SHIP-789",
          "orderId": "123", "customerId": "C-123"}

Фабричный объект RevertEndpointBuilder связывает воедино эти настройки с сохраненными в БД телами запросов/ответов и выдает полностью сконфигурированный объект для отправки в сеть:

object RevertEndpointBuilder {
  def buildRevertEndpoint(
      revertConfig: RevertConfig,
      requestPayload: Option[JsValue],
      responsePayload: Option[JsValue],
      baseDestination: String,
      headers: Map[String, String],
      timeout: FiniteDuration
  ): Try[(HttpEndpointConfig, Option[JsValue])] =
    for {
      placeholderValues <- extractPlaceholderValues(revertConfig, requestPayload, responsePayload)
      revertUrl         <- buildRevertUrl(revertConfig.url, placeholderValues)
    } yield (
      HttpEndpointConfig(
        destinationName = baseDestination,
        url             = Some(revertUrl),
        method          = revertConfig.method,
        headers         = headers,
        timeout         = timeout
      ),
      buildRevertPayload(revertConfig, placeholderValues)
    )
}

При любых конфигурационных изменениях на стороне сторонних сервисов (сменились пути, обновился формат параметров) вы просто правите файлы настроек. Сам RevertEndpointBuilder не привязан к предметной области: он ничего не знает ни о балансе склада, ни о перевозчиках. Это абстрактный парсер, который беспрекословно следует заданным правилам извлечения и подстановки.

❯ Автоматическая компенсация (обработчик DLQ)

Мы разобрались с тем, как формируются запросы отмены, теперь перейдем к механизму, который их дергает. Как отмечалось в процессе разбора фоновых процессов, при сетевых таймаутах OutboxProcessor предпринимает повторные попытки с нарастающей паузой (2, 4, 8 секунд). Но если все попытки достучаться провалились, наступает фаза компенсации: нам нужно планомерно стереть следы всех действий, которые к этому моменту успели успешно выполниться на сторонних серверах.

Допустим, оплата после 3 честных попыток выбросила белый флаг. В базе данных таблица aggregate_results будет выглядеть следующим образом:

destination    success  fanout_order  response_payload
--------------+---------+--------------+-----------------------------------------
inventory      true     0             {"reservationId": "RES-456", ...}
fraudCheck     true     1             {"riskScore": 25, ...}
shipping       true     2             {"shipmentId": "SHIP-789", ...}
billing        false    3             null

Три шага завершились успехом, последний – критической ошибкой. На складе забронировано, курьеры грузят коробки, но транзакция по карте не прошла. Придется разматывать цепочку 0-2 в обратную сторону. Именно на этом этапе в игру вступает паттерн Saga Compensation.

Чтобы не усложнять и не устраивать попытки отмены прямо внутри рабочего потока (ведь откат тоже может сорваться из-за сетевого сбоя, заведя систему в еще более дремучие дебри), разработчик использует изящный шаг. OutboxProcessor немедленно убирает проблемное событие с радаров основной таблицы и отгружает его в специальную накопительную таблицу dead_letter_events. Тут будут регистрироваться все инциденты, требующие принудительного отката:

CREATE TABLE dead_letter_events (
    id                 BIGSERIAL PRIMARY KEY,
    original_event_id  BIGINT        NOT NULL,   -- ссылка на исходную запись в outbox_events
    aggregate_id       VARCHAR(255)  NOT NULL,
    event_type         VARCHAR(255)  NOT NULL,
    payloads           JSONB         NOT NULL,    -- резервная копия исходных данных
    status             VARCHAR(20)   NOT NULL DEFAULT 'PENDING',
    reason             VARCHAR(1024) NOT NULL,    -- причина сбоя, напр. "MAX_RETRIES_EXCEEDED"
    -- ... параметры отслеживания попыток отката
);

Обработкой этой таблицы занимается автономный воркер DLQProcessor. Подобно нашему основному процессору, это типизированный Pekko-актор, однако он запущен не сам по себе, а как дочерний элемент по отношению к OutboxProcessor. В терминологии Pekko/Akka это означает постоянный супервизор-контроль над его жизненным циклом: если в коде дочернего процессора возникнет фатальная ошибка, родительский актор мгновенно перезапустит его без потери состояния. Каждый рабочий экземпляр OutboxProcessor инициализирует собственного ребенка-обработчика DLQProcessor. Соответственно, если на благо базы трудятся 3 параллельных воркера outbox, система автоматически выделит им 3 дублирующих DLQ-процессора.

❯ Алгоритм работы DLQ-процессора

Шаги проведения компенсирующих действий выглядят так:

Выборка результатов (Query). Выгружаем из aggregate_results список всех успешных прямых вызовов, отсортированный по убыванию номера шага fanout_order DESC (это и есть LIFO / порядок от последнего к первому).
Анализ конфигураций (Check). Для каждой записи смотрим, описан ли для нее компенсирующий блок revert в файле настроек. Шаги без него (как условный фрод-скоринг) просто отбрасываем.
Формирование и отправка (Send). Собираем сетевой запрос с помощью RevertEndpointBuilder и шлем его по сети, предварительно убедившись, что откат для этого конкретного шага не выполнялся ранее.
Завершение. Меняем статус события в таблице DLQ на PROCESSED.

Если наложить этот сценарий на наш пример, шаги компенсации пройдут так:

shipping (fanout_order=2):   Есть revert-блок → POST /api/domestic-shipping/SHIP-789/cancel
fraudCheck (fanout_order=1): Нет revert-блока → Пропускаем (только чтение, отмена не нужна)
inventory (fanout_order=0):  Есть revert-блок → DELETE /api/inventory/RES-456/release

Главной точкой входа в процедуру отката является метод revertDLQEvent. Первым делом он запрашивает из СУБД всё успешное наследие прямого пути (по ID заказа). Если во время выстраивания цепочки первый же вызов API потерпел неудачу, то и откатывать нам нечего – база просто моментально отметит DLQ-событие как успешно закрытое. Если же успешные шаги были, трансляция передается методу publishRevertEvent, который поочередно раскрутит все шаги и отправит нужные HTTP-запросы в обратном порядке:

private def revertDLQEvent(dlqEvent: DeadLetterEvent): Future[Boolean] = {
  db.run(
    resultRepo.findByAggregateId(dlqEvent.aggregateId, Result.Success, includeReverts = false)
  ).flatMap { successful =>
    if (successful.isEmpty) {
      db.run(dlqRepo.markProcessed(dlqEvent.id)).map(_ => true)
    } else {
      publishRevertEvent(dlqEvent, successful)  // собираем и вызываем эндпоинты отмены в порядке LIFO
    }
  }
}

❯ Защита от повторной компенсации (идемпотентность)

Перед отправкой компенсирующего запроса наш фоновый воркер обязательно убеждается, что данная операция не была отменена ранее. Все вызовы без исключений сохраняются в логах aggregate_results. Чтобы на уровне БД легко разделять их на прямые и компенсирующие, к имени целевого сервиса при записи отката прибавляется суффикс .revert: прямой вызов сохранится как "shipping", а компенсирующий – как "shipping.revert". Отсюда предельно прозрачная проверка на повторы: ищем в таблице результатов успешную запись с ключом "shipping.revert". Нашли? Значит, шаг отмены уже позади и его можно спокойно пропустить.

Описанный ниже метод разом проверяет все целевые точки. Он опрашивает базу по каждому получателю параллельно и возвращает список названий сервисов, которые уже благополучно пережили отмену:

private def checkAlreadyCompensated(
    aggregateId: String, successfulResults: Seq[AggregateResult]
): Future[Set[String]] =
  Future.sequence(
    successfulResults.map { result =>
      db.run(resultRepo.findSuccessfulRevert(aggregateId, result.destination))
        .map(alreadyCompensated => (result.destination, alreadyCompensated.isDefined))
    }
  ).map(_.filter(_._2).map(_._1).toSet)

Подобный барьер идемпотентности жизненно необходим, так как DLQ-процесс в силу внешних причин (аварийная перезагрузка серверов, деплой новой версии сервиса) может прерваться посреди выполнения. Без такой глубокой проверки повторный запуск недовыполненных задач мог бы привести к крайне неприятным последствиям: например, дважды перевести деньги обратно покупателю или отправить избыточный запрос отмены в доставку, которая давно закрыта.

❯ Ручная отмена: повторное использование движка компенсаций

Пока мы говорили об автоматическом запуске процедур отката при аварийном падении API. Но как быть в классической ситуации, когда сам пользователь нажимает кнопку «Отменить заказ»? Прелесть архитектуры в том, что мы можем переиспользовать уже написанный движок отмены. Секрет кроется в простом соглашении об именовании событий: добавление восклицательного знака ! перед типом доменного события служит сигналом для OutboxProcessor о том, что перед ним не обычный прямой процесс, а директива на проведение компенсации.

Класс события OrderCancelledEvent как раз и реализует этот элегантный подход:

case class OrderCancelledEvent(
    orderId: Long,
    reason: String,
    timestamp: Instant = Instant.now()
) extends DomainEvent {
  override def aggregateId: String = orderId.toString
  override def eventType: String   = "!OrderCreated"  // ← Префикс ! дает сигнал на проведение компенсации
  // ...
}

Наш репозиторий оформляет запрос на отмену и запись события о компенсации в общую СУБД-транзакцию – точно так же, как мы делали при первичном создании корзины. Метод cancelWithEvent сначала проверяет факт существования заказа в базе, после чего обновляет его статус на CANCELLED и атомарно дописывает событие !OrderCreated в очередь:

def cancelWithEvent(orderId: Long, reason: String): DBIO[Int] =
  for {
    orderOpt <- findById(orderId)
    _        <- orderOpt match {
      case Some(_) => DBIO.successful(())
      case None    => DBIO.failed(new NoSuchElementException(s"Order $orderId not found"))
    }
    updated  <- withEvent(OrderCancelledEvent(orderId = orderId, reason = reason)) {
      orders.filter(_.id === orderId)
        .map(o => (o.orderStatus, o.updatedAt))
        .update(("CANCELLED", Instant.now()))
    }
  } yield updated

Обнаружив при парсинге свежего события символ !, OutboxProcessor автоматически перестраивает рабочий режим с прямого выполнения веерной отправки на процедуру отката. Вот как выглядит этот пошаговый алгоритм:

Очистка имени. Срезаем системный префикс со служебной строки: !OrderCreated превращается обратно в исходный OrderCreated.
Поиск конфигурации. Считываем из файлов настроек схему связей для нужного события: OrderCreated → ["inventory", "fraudCheck", "shipping", "billing"].
Инверсия шагов (LIFO). Переворачиваем полученный список задом наперед: ["billing", "shipping", "fraudCheck", "inventory"].
Получение логов. Для каждого шага ищем в таблице результатов aggregate_results лог успешного прямого выполнения.
Построение запроса и выполнение. С помощью RevertEndpointBuilder воссоздаем эндпоинты отмены и отправляем запросы в сеть (пропуская сервисы без revert-конфигураций).
Фиксация результата. Помечаем исходное событие в базе как полностью обработанное.

Обратите внимание: OutboxProcessor использует абсолютно те же программные классы RevertEndpointBuilder и методы проверки дубликатов, что и фоновый DLQProcessor. Вся система обладает врожденным свойством идемпотентности: перед инициацией отработки отката она всегда запрашивает базу на предмет наличия признака .revert у каждого адресата. Если нетерпеливый пользователь кликнет по кнопке «Отменить заказ» несколько раз подряд, повторная задача моментально обнаружит, что все шаги цепи отката уже проведены, и завершится как мгновенная пустая операция.

❯ События отмены защищены от попадания в DLQ

В случае если само компенсирующее событие (!OrderCreated) терпит крах после исчерпания всех лимитов повтора, система ни в коем случае не пытается запустить для него процедуру отката. Идея «компенсировать отмену компенсации» увела бы систему в бесконечный цикл вызовов. Вместо этого строка помечается критическим флагом отказа и отправляется ожидать ручного разбора нашей дежурной сменой инженеров:

if (isRevertEvent) {
  log.error(
    s"Revert event ${event.id} (${event.eventType}) exceeded retries - " +
      s"marking as FAILED, requires manual intervention"
  )
  db.run(outboxRepo.markProcessed(event.id)).map(_ => false)
}

Компонент	Ручная отмена (`!OrderCreated`)	Автоматическая (через DLQ)
Триггер инициации	Действие пользователя (клик по кнопке отмены)	Сбой прямого запроса API после лимита попыток
Таблица хранения	`outbox_events`	`dead_letter_events`
Скорость выполнения	Сразу при обработке входящей очереди	После исчерпания попыток основного прохода
Крах отката	Требует внимания службы поддержки	Аналогично требует ручного разбора в БД

❯ Инициализация: EventProcessingService

Мы детально проанализировали все независимые шестеренки движка: от записи событий в БД до веерных рассылок, динамической маршрутизации отмены и механизмов DLQ. Пришло время собрать этот пазл воедино. В архитектуре Play Framework синглтоны с нетерпеливой инициализацией (eager singletons) автоматически запускаются прямо на старте системы. Именно таким звеном выступает EventProcessingService. При поднятии приложения он разворачивает пул акторов, отправляет стартовое сообщение активации работы фонового воркера и аккуратно регистрирует слушателя завершения сессии для корректного выхода из процессов:

@Singleton
class EventProcessingService @Inject() (
    lifecycle: ApplicationLifecycle,
    publisher: EventPublisher,
    outboxRepo: OutboxRepository,
    dlqRepo: DeadLetterRepository,
    resultRepo: DestinationResultRepository,
    eventRouter: EventRouter,
    config: Configuration
)(using system: ActorSystem[Nothing], ec: ExecutionContext, db: Database)
    extends Logging {
  val outboxActor: ActorRef[OutboxProcessor.Command] =
    if (poolSize > 1) {
      system.systemActorOf(
        OutboxProcessorRouter(publisher, outboxRepo, dlqRepo, resultRepo, eventRouter,
          pollInterval, batchSize, poolSize, maxRetries, useListenNotify,
          staleCleanupEnabled, staleTimeoutMinutes, cleanupInterval),
        "outbox-processor-pool"
      )
    } else {
      system.systemActorOf(
        OutboxProcessor(publisher, outboxRepo, dlqRepo, resultRepo, eventRouter,
          pollInterval, batchSize, maxRetries, useListenNotify,
          staleCleanupEnabled, staleTimeoutMinutes, cleanupInterval),
        "outbox-processor"
      )
    }
  // Запуск процесса
  outboxActor ! OutboxProcessor.ProcessUnhandledEvent
  // Корректное завершение работы
  lifecycle.addStopHook { () =>
    outboxActor.ask(To => OutboxProcessor.Stop(To))
      .map(_ => logger.info("Процессор Outbox успешно остановлен"))
  }
}

Конфигурационный файл содержит следующие параметры:

outbox {
  pollInterval = 2 seconds
  batchSize    = 100
  poolSize     = 3              # 3 параллельных воркера
  maxRetries   = 3
  useListenNotify = true        # Мгновенная реакция через LISTEN/NOTIFY
  enableStaleEventCleanup = true
  staleEventTimeoutMinutes = 5  # Сброс зависших событий через 5 минут
  cleanupInterval = 1 minute
  dlq {
    maxRetries   = 3
    pollInterval = 2 seconds
  }
}

Настроив параметр poolSize = 3, мы параллельно запускаем трех акторов OutboxProcessor под управлением балансировщика, причем за каждым из них закреплен персональный дочерний подпроцесс DLQProcessor. А неизменная конструкция FOR UPDATE SKIP LOCKED на уровне СУБД железобетонно страхует систему от ситуации, когда два разных потока параллельно захватят одну и ту же строчку.

❯ Наглядный пример: как это работает

Давайте проследим за кулисами реального сбоя: от создания корзины до экстренной отмены операций из-за отказа платежного шлюза.

Шаг 1: Пользователь создает заказ

POST /api/orders
Body: {"customerId": "C-123", "totalAmount": 99.99, "shippingType": "domestic"}

Шаг 2: Атомарная транзакция в базу

BEGIN;
  INSERT INTO orders (...) RETURNING id;  -- Возвращает 123
  INSERT INTO outbox_events (aggregate_id='123', event_type='OrderCreated',
    payloads='{"inventory": {...}, "fraudCheck": {...}, "shipping": {...}, "billing": {...}}',
    status='PENDING');
COMMIT;
-- Триггер PostgreSQL посылает сигнал pg_notify('outbox_events_channel', '123')

Шаг 3: Воркер забирает событие и начинает веерную отправку

SELECT ... FROM outbox_events WHERE status='PENDING' ... FOR UPDATE SKIP LOCKED;
UPDATE outbox_events SET status='PROCESSING' WHERE id=456;
POST /api/inventory/reserve       → 200 OK (reservationId: RES-456)   → UPSERT aggregate_results
POST /api/fraud/check             → 200 OK (riskScore: 25)            → UPSERT aggregate_results
POST /api/domestic-shipping       → 200 OK (shipmentId: SHIP-789)     → UPSERT aggregate_results
POST /api/billing                 → 503 Service Unavailable           → UPSERT aggregate_results

Шаг 4: Повторные попытки при таймаутах биллинга

Попытка 1: ожидание 2с  → 503
Попытка 2: ожидание 4с  → 503
Попытка 3: ожидание 8с  → 503

Шаг 5: Перемещение в очередь недоставленных сообщений (DLQ)

INSERT INTO dead_letter_events (original_event_id=456, aggregate_id='123',
  event_type='OrderCreated', status='PENDING', reason='MAX_RETRIES_EXCEEDED');
UPDATE outbox_events SET status='PROCESSED', moved_to_dlq=true WHERE id=456;

Шаг 6: DLQProcessor последовательно выполняет откат в порядке LIFO

Query: SELECT * FROM aggregate_results WHERE aggregate_id='123' AND success=true
       ORDER BY fanout_order DESC
       → [shipping(2), fraudCheck(1), inventory(0)]
POST /api/domestic-shipping/SHIP-789/cancel  → 200 OK  → UPSERT (shipping.revert)
Пропускаем fraudCheck (нет revert-конфигурации)
DELETE /api/inventory/RES-456/release        → 200 OK  → UPSERT (inventory.revert)
UPDATE dead_letter_events SET status='PROCESSED' WHERE id=...;

Шаг 7: целостность данных спасена!

Заказ корректно записан в нашей базе данных и имеет статус сбоя оплаты, но все сопутствующие внешние резервы на серверах партнеров были чисто компенсированы в автоматическом режиме. При этом таблица aggregate_results теперь содержит исчерпывающую историю каждого сетевого чиха – со всеми входящими и исходящими телами прямых и компенсирующих вызовов.

❯ О чем важно помнить

Безусловно, связка паттернов Transactional Outbox, Result Table и Saga Compensation – это не какая-то серебряная пуля. Вам по-прежнему будут нужны качественный мониторинг для отслеживания зависших процессов, триггеры алертов на переполнение очередей DLQ и резервные регламенты работы для тех редких инфраструктурных инцидентов, когда автоматическая компенсация тоже падает, требуя человеческого вмешательства.

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

Заменив хаос на эти паттерны, вы переведете потенциальные аварии (зависшую в попытках строку DLQ, таймаут эндпоинта отмены или устаревшую запись, ожидающую повторной обработки) в категорию наблюдаемых, легко прослеживаемых и полностью контролируемых событий. Благодаря таблице aggregate_results у вас перед глазами будет доскональная история каждого вызова, а таблица событий dead_letter_events всегда любезно укажет пальцем, какой шаг дал сбои и почему это произошло.

❯ Подведем итоги

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

В рамках этой статьи мы во всеоружии подошли к решению фундаментальной проблемы двойной записи, подстерегающей любые архитектуры при попытке атомарно связать воедино базу данных с внешним сетевым миром. Эти три паттерна превращают непредсказуемый хаос рассинхронизации данных в абсолютно прозрачные, предсказуемые и легко исправимые инциденты.

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

Исходный код проекта. Все разобранные в этой статье примеры кода вы можете в деталях изучить в репозитории проекта: never-call-apis-inside-database-transactions.

Может быть интересно:

Новости, обзоры продуктов и конкурсы от команды Timeweb.Cloud — в нашем Telegram-канале ↩

Стрельба в шутерах по-простому: от мгновенного луча до отката времени на сервере

DyadichenkoGA — Tue, 23 Jun 2026 08:04:13 +0000

DyadichenkoGA11 минут назад

Средний

21 мин

Туториал

Всем привет! Меня зовут Гриша Дядиченко, я технический директор и основатель White Label Games. Уже больше десяти лет работаю с компьютерной графикой, AR/VR и компьютерным зрением — в основном это заказная разработка, плюс собственные прототипы по вечерам, до которых дотягиваются руки.

Делал я как-то на работе, по вечерам в свободное время, VR-шутер. Стрельбу, понятное дело, заложил себе на выходные: ну а что, raycast из ствола, событие попадания, отнял здоровье — делов-то. К вечеру воскресенья оно даже работало. Только ощущалось так, будто тыкаешь противника палкой: ни веса, ни отдачи, ни чувства, что ты вообще попал. Знакомо, наверное, каждому, кто хоть раз ставил в сцену оружие и жал «выстрел» — механически всё верно, а стрельба вялая и какая-то ненастоящая. Половина лечения тут — чистая полировка: вспышки, звук, тряска камеры, импакт-эффекты. А вот вторая половина — невидимая математика под капотом: та, что решает, ощущается стрельба честной и отзывчивой или кривой и несправедливой. Спред, который мозг считывает как «нечестный». Отдача, которую можно выучить. Попадание, которое по сети то засчитывается, то нет. Вот это всё и разберём.

Сталкивались ли вы с ситуацией, когда в шутере вы точно попали по противнику, а сервер сказал «промах»? Или с тем, что AI-противник стреляет в вас сверхскоростным снарядом и ни разу не попадает в движущуюся цель? Или с тем, что AK-47 в Counter-Strike рисует «семёрку» из пуль вверх и влево — и это, конечно же, никакой не баг, а вполне продуманная механика? Под капотом у всех этих ситуаций — конкретная математика.

Чтож, давайте по порядку. Чем hitscan отличается от projectile и какой хвост последствий тянется за выбором; с какой геометрией на самом деле проверяют попадание — лучи, капсулы и почему хитбоксы это не полигональный меш; как сделать честный спред пули и почему наивный random даёт квадрат вместо круга; откуда берутся «выученные» recoil-паттерны и почему AK рисует семёрку; как AI-снайпер вычисляет упреждение через школьное квадратное уравнение; и наконец, что такое lag compensation, зачем сервер откатывает время на сотню миллисекунд назад и откуда берётся эффект «убит из-за угла». Шесть разделов, в каждом — код на C#. Сразу оговорюсь: я сознательно не лезу в баллистику снайперок с ветром, в проникающие выстрелы через стены и в физику отдачи на уровне «как трясётся ствол» — иначе статья превратится в книжку.

1. Hitscan против projectile: а в чём вообще разница

Итак, вы поставили в сцену оружие и нажали кнопку «выстрел». Что должно произойти? У вас всего два ответа, и они реализованы принципиально по-разному.

Hitscan — вы пускаете луч из ствола, в тот же кадр проверяете пересечение с миром, регистрируете попадание. Время полёта пули — ноль. Так стреляют все винтовки в Counter-Strike, Valorant, Call of Duty, и в Overwatch — Soldier 76, Widowmaker.

Projectile — вы создаёте объект-снаряд, даёте ему скорость, и каждый тик симулируете его движение, проверяя коллизии. Так стреляют ракеты в Quake и Unreal Tournament, плазма в Halo, снайперки в Apex Legends, и вообще любое оружие в Splatoon.

На C# в Unity-стиле hitscan выглядит примерно так:

void FireHitscan() {
    Ray ray = new Ray(muzzle.position, muzzle.forward);
    if (Physics.Raycast(ray, out RaycastHit hit, maxRange)) {
        ApplyDamage(hit.collider, damage);
        SpawnImpactEffect(hit.point, hit.normal);
    }
}

А projectile так:

void FireProjectile() {
    var bullet = Instantiate(bulletPrefab, muzzle.position, muzzle.rotation);
    bullet.GetComponent<Rigidbody>().linearVelocity = muzzle.forward * bulletSpeed;
}
// внутри пули — OnTriggerEnter / RaycastNonAlloc по тонкому ray-cast'у каждый
// FixedUpdate, чтобы пуля не «прошла сквозь» цель на больших скоростях.

Ключевая разница видна сразу. В hitscan-версии мы вообще не храним пулю как объект — это сразу Raycast и сразу результат. В projectile у нас живёт Rigidbody, который ест CPU каждый тик, плюс проверка на «прошивку» через тонкий ray-cast (про неё — в части 2, иначе быстрая пуля просто перепрыгнет цель между кадрами).

Зачем вообще выбор, если hitscan дешевле? Hitscan по сути — компромисс в пользу простоты и сетевой нагрузки. Серверу нужно меньше пересылать, клиенту — меньше симулировать, попадание ощущается мгновенным. Для тактических шутеров это важно: вы целились в голову, нажали — попадание должно быть бескомпромиссным. На длинных дистанциях projectile-снайперке надо реально «доехать» до цели, и игрок читает задержку как «оружие медленное и несправедливое».

Projectile, наоборот, открывает игроку возможность увернуться. В Quake вы можете шагнуть в сторону, увидев летящую ракету. В CS вы не можете «отойти от пули» — она уже попала в момент выстрела. Это совсем другое игровое ощущение, и именно ради него projectile и берут.

Гибриды встречаются часто. В Halo battle rifle — hitscan, brute shot — projectile. В Apex R301 — hitscan, Kraber — projectile. В Doom Eternal плазма ведёт себя как hitscan-импульсы, а BFG — это projectile с авто-наведением. Для аркадных шутеров и быстрых PvP обычно берут комбинированный подход: основное оружие на hitscan ради отзывчивости, а тяжёлое и «уворачиваемое» — гранатомёт, ракетница, лук — на projectile. Для тактических — только hitscan, без вариантов.

Тот самый промах из правой части — это и есть классическая боль projectile-AI: снаряд летит, а цель за время полёта уходит. Лечится упреждением — и промахи у движущейся мишени исчезнут.

2. Геометрия попадания: лучи, капсулы, и почему хитбоксы — не меши

Чтож, мы решили, что стреляем лучом или снарядом. Дальше встаёт чисто геометрический вопрос: а с чем именно проверять пересечение? С полигональным мешем персонажа? Со сферой? С прямоугольником? Вариантов много, и почти все они в индустрии стандартизированы — давайте разберём, какие и почему.

Базовые ray–shape тесты

Любая система попаданий стоит на пяти-шести примитивах. Их полезно знать наизусть: физический движок прячет их внутри себя, но иногда вы пишете collision-код сами — для предикта, для AI, для аналитики «куда стрелял противник».

Луч–плоскость. Самый простой случай: одна формула, одно скалярное произведение. Если плоскость задана точкой p0 и нормалью n, а луч — origin o и направлением d, то параметрическое расстояние до пересечения это t = ((p0 − o) · n) / (d · n). Если знаменатель ноль — луч параллелен плоскости. Это базовый кирпич, на котором стоят более сложные тесты: AABB — это шесть таких проверок, OBB — те же шесть в локальном пространстве, mesh — миллион треугольников = миллион плоскостей. Кода тут на пару строк, отдельным листингом приводить не буду.

Луч–сфера. Решаем квадратное уравнение t²(d · d) + 2t(o − c) · d + |o − c|² − r² = 0, где c — центр сферы, r — радиус. Дискриминант скажет, попали или нет. Дёшево, используется для всего, что концептуально круглое, и как грубая обёртка перед точным тестом.

// Луч–сфера: квадратное уравнение, дискриминант скажет, попали или нет.
public static bool RaySphere(Vector3 origin, Vector3 dir,
                             Vector3 c, float r,
                             out float t)
{
    Vector3 m = origin - c;
    float b = Vector3.Dot(m, dir);
    float cc = Vector3.Dot(m, m) - r * r;
    if (cc > 0f && b > 0f) { t = 0f; return false; }     // мимо и удаляемся
    float disc = b * b - cc;
    if (disc < 0f) { t = 0f; return false; }             // мимо
    t = -b - Mathf.Sqrt(disc);
    if (t < 0f) t = 0f;                                  // источник внутри сферы
    return true;
}

Луч–AABB (axis-aligned bounding box). Slab method, шесть сравнений, никаких квадратных корней. Стандарт для грубой фазы: каждый объект в сцене сначала тестируется через AABB, и только если попало — переходим к точному тесту.

// Луч–AABB: slab method, шесть сравнений, никаких квадратных корней.
public static bool RayAABB(Vector3 origin, Vector3 dir,
                           Vector3 min, Vector3 max,
                           out float t)
{
    float tmin = float.NegativeInfinity, tmax = float.PositiveInfinity;
    for (int i = 0; i < 3; i++) {
        float o = origin[i], d = dir[i];
        if (Mathf.Abs(d) < 1e-6f) {
            if (o < min[i] || o > max[i]) { t = 0f; return false; }
        } else {
            float inv = 1f / d;
            float t1 = (min[i] - o) * inv;
            float t2 = (max[i] - o) * inv;
            if (t1 > t2) (t1, t2) = (t2, t1);
            if (t1 > tmin) tmin = t1;
            if (t2 < tmax) tmax = t2;
            if (tmin > tmax) { t = 0f; return false; }
        }
    }
    t = tmin >= 0f ? tmin : tmax;
    return tmax >= 0f;
}

Луч–OBB (oriented bounding box). Это AABB, повёрнутый в локальном пространстве объекта. Решается ровно так же: переводим луч в локальные координаты объекта через InverseTransformPoint/InverseTransformDirection и зовём тот же RayAABB с ±halfExtents. Отдельного листинга не заслуживает — это три строки поверх предыдущего.

Луч–капсула. Самый интересный случай для шутеров — потому что почти все хитбоксы в современных шутерах именно капсулы, и через эту функцию проходят все ваши попадания по противникам. Геометрически капсула — это отрезок a→b плюс радиус r: цилиндрическая «колбаса» с двумя полусферами на концах. Задача разваливается на две части.

Сначала считаем пересечение луча с бесконечным цилиндром вокруг оси капсулы. Это сводится к классической задаче «кратчайшее расстояние между двумя скрещивающимися прямыми» — бесконечным лучом и осью ab; в перпендикулярной к оси плоскости получается квадратное уравнение, по структуре похожее на ray–sphere. Дискриминант скажет, попали ли в цилиндр. Если попали — проверяем, что точка пересечения внутри отрезка [a, b]: считаем параметр u вдоль оси и принимаем попадание только если u ∈ [0, 1]. Если u выскочил наружу или цилиндр промахнулся совсем — переходим к концевым полусферам: считаем ray–sphere для центров a и b с тем же радиусом и берём ближайшее попадание.

То есть «луч–капсула» — это, по сути, ray–cylinder с проверкой диапазона по оси плюс два ray–sphere как fallback на полусферах концов. У Кристера Эриксона в Real-Time Collision Detection лежит готовая формула в замкнутой форме (closed-form): пара скалярных произведений, квадратный корень, несколько ветвлений — точный ответ за фиксированное число операций, без итераций. Что критически важно для серверной валидации попаданий, где время выполнения должно быть предсказуемым.

// Луч–капсула: отрезок a→b с радиусом r.
// Сводится к скрещивающимся прямым плюс две полусферы на концах.
public static bool RayCapsule(Vector3 origin, Vector3 dir,
                              Vector3 a, Vector3 b, float r,
                              out float t)
{
    Vector3 ab = b - a;
    Vector3 ao = origin - a;
    float abLen2 = Vector3.Dot(ab, ab);
    float abDotDir = Vector3.Dot(ab, dir);
    float abDotAo  = Vector3.Dot(ab, ao);
    float A = Vector3.Dot(dir, dir) - abDotDir * abDotDir / abLen2;
    float B = Vector3.Dot(dir, ao)  - abDotDir * abDotAo  / abLen2;
    float C = Vector3.Dot(ao, ao)   - abDotAo  * abDotAo  / abLen2 - r * r;
    if (Mathf.Abs(A) < 1e-6f) return Endcaps(origin, dir, a, b, r, out t);
    float disc = B * B - A * C;
    if (disc < 0f) return Endcaps(origin, dir, a, b, r, out t);
    t = (-B - Mathf.Sqrt(disc)) / A;
    if (t < 0f) return Endcaps(origin, dir, a, b, r, out t);
    Vector3 hp = origin + dir * t;
    float u = Vector3.Dot(hp - a, ab) / abLen2;
    if (u >= 0f && u <= 1f) return true;     // попали в цилиндрическую часть
    return Endcaps(origin, dir, a, b, r, out t);
}
static bool Endcaps(Vector3 o, Vector3 d, Vector3 a, Vector3 b, float r, out float t)
{
    if (RaySphere(o, d, a, r, out float ta) && RaySphere(o, d, b, r, out float tb))
        { t = Mathf.Min(ta, tb); return true; }
    if (RaySphere(o, d, a, r, out t)) return true;
    return RaySphere(o, d, b, r, out t);
}

Это те самые пять кирпичей, на которых стоит почти вся collision-математика шутеров: плоскость, сфера, AABB, OBB и капсула. В большинстве проектов вы их в чистом виде не пишете — Unity Physics или собственный физический движок уже всё инкапсулировали. Но знать, что внутри, полезно: AI с предиктом, спекулятивные ray-cast'ы для предсказания попаданий, аналитика — везде эти функции всплывают.

Почему хитбоксы — капсулы, а не меши

В первый раз сталкиваясь с хитбоксами, многие думают: «ну как же — у нас есть полигональный меш персонажа, давайте по нему и проверять». Да? Конечно же нет.

Во-первых, стоимость. Полигональный меш персонажа — это 5000–15000 треугольников, и проверка пересечения превращается в проход по каждому из них. Капсула — отрезок и радиус, всё разрешается одной формулой. На одну проверку разница в нагрузке на CPU выходит в 50–100 раз. На сервере, где в кадр прилетает несколько сотен проверок попаданий, эта разница становится решающей.

Во-вторых, стабильность. Меш привязан к скелету и анимации, поэтому он буквально дёргается каждый кадр — пальцы, складки одежды, висящий на спине рюкзак. Капсула стоит на жёсткой кости и не дёргается. Это критически важно: если хитбокс «дрожит», игроки начинают замечать «странные» промахи и попадания, и разработчики получают вечный поток баг-репортов «вы убрали хитбокс с головы».

В-третьих, дизайн отдельно от визуала. Хитбокс — это игровая механика, а меш — это визуал, и они должны управляться независимо. С капсулами вы можете сделать голову чуть больше визуальной модели для компенсации пинга или, наоборот, сузить торс, чтобы лучшие игроки чаще промахивались по краям. С полигональным мешем вы намертво привязаны к 3D-арту: художник перенарисовал плечи — изменилась игровая механика, и сетевую часть надо тестировать заново.

Стандартный набор для шутерного персонажа — 4–8 капсул: голова, торс, две руки, две ноги. В тактических играх (CS, Valorant) ещё отдельно бёдра и голени. В CS:GO стандарты хитбоксов перерабатывали несколько раз — самая громкая итерация была в патче от 15 сентября 2015, когда Valve полностью заменили старую боксовую систему на капсульную; в архивных сравнениях «до и после» видно, как они гонялись за «той самой» геометрией.

Hit zones и multipliers

Раз у нас несколько капсул на персонажа, логично каждой дать свой множитель урона. Стандартная пропорция для тактических шутеров: голова — ×4 (одношотный хедшот из винтовки), торс — ×1 (базовый урон), конечности — ×0.5–0.75 (царапаешь, но не убиваешь). Реализуется тривиально: при попадании знаем, в какую капсулу попали (по тегу, слою или ID), у каждой свой множитель.

public class Hitbox : MonoBehaviour {
    [SerializeField] float damageMultiplier = 1f;
    [SerializeField] BodyPart part = BodyPart.Torso;
    public void OnHit(float baseDamage, Vector3 hitPoint) {
        float dmg = baseDamage * damageMultiplier;
        var enemy = GetComponentInParent<Health>();
        enemy.TakeDamage(dmg, part);
    }
}

Лайфхак: квадраты вместо sqrt

Раз мы говорим о геометрии — банально полезный лайфхак для тех мест, где collision-код выполняется сотни раз в кадр. Если вам не нужна точная дистанция, а нужно сравнение «ближе ли цель радиуса R» — никогда не считайте sqrt. Сравнивайте квадраты:

// плохо: считаем дистанцию каждый кадр для всех врагов
float dist = Vector3.Distance(player.position, enemy.position);
if (dist < range) Hit();
// хорошо: тот же результат, в 5–10 раз быстрее в часто выполняемом коде
if ((player.position - enemy.position).sqrMagnitude < range * range) Hit();

На современных CPU это сэкономит вам считанные микросекунды, и в большинстве случаев такой micro-optimization в принципе не нужен. Но в тиках сетевой проверки попаданий на сервере, где может быть несколько сотен проверок в кадр, экономия становится осязаемой.

3. Спред пули: где разработчики ломают «честность»

Собственно, любое автоматическое оружие должно мазать. Если каждая пуля летит ровно в прицел — стрельба превращается в лазерную указку, и игроку нечего «осваивать». Поэтому у пули есть спред — случайное (или заранее заданное) отклонение от центра прицела. Казалось бы, элементарно. На практике — это место, где разработчики чаще всего ломают игровое ощущение, причём незаметно для самих себя.

Наивный подход — квадрат вместо круга

Первое, что приходит в голову: «возьму два независимых random'а, один на dx, другой на dy».

// классическая ошибка
float dx = (Random.value * 2f - 1f) * spread;
float dy = (Random.value * 2f - 1f) * spread;
// итог: квадратное распределение

Получается квадрат с биасом по углам: диагональ квадрата длиннее стороны в √2 раз, поэтому пуля в угловых направлениях улетает на spread * 1.41 вместо spread. Игроки чувствуют это как «нечестно», но сформулировать почему обычно не могут — мозг просто ждёт круг, а получает квадрат. Что с этим делать — вариантов два, и оба сводятся к тому, чтобы вместо квадрата раздавать точки внутри диска.

Rejection sampling и polar coordinates

Самое прямое решение — rejection sampling: кидаем точку в квадрат, и если она вне круга — кидаем ещё раз.

public static Vector2 RejectionSpread(float spread)
{
    while (true) {
        float dx = (Random.value * 2f - 1f) * spread;
        float dy = (Random.value * 2f - 1f) * spread;
        if (dx * dx + dy * dy <= spread * spread) return new Vector2(dx, dy);
    }
}

Площадь круга — это π/4 от площади квадрата, поэтому одна попытка успешна примерно в π/4 ≈ 0.785 случаев (то есть ~78%), а в среднем на одну точку уходит 4/π ≈ 1.27 итерации. Минус — число итераций индетерминированное, в худшем случае циклов может потребоваться много. Для большинства случаев это не проблема, но если вы пилите детерминированный сетевой код (а вам этого, поверьте, рано или поздно захочется), то rejection sampling — не ваш друг: каждый клиент дёрнет random разное число раз, и стейты разойдутся.

Хочется детерминизма и красоты — берите полярные координаты. Один random на угол, один на радиус — фиксированное число операций.

public static Vector2 PolarSpread(float spread)
{
    float angle = Random.value * Mathf.PI * 2f;
    float radius = spread * Mathf.Sqrt(Random.value);   // ← важен sqrt!
    return new Vector2(Mathf.Cos(angle), Mathf.Sin(angle)) * radius;
}

Почему именно sqrt? Если просто написать radius = spread * Random.value, точки сожмутся к центру, потому что у вас линейное распределение по радиусу, а площадь круга растёт квадратично. Получится не равномерный диск, а bull's-eye с плотным центром. Чтобы плотность была равномерной по площади, нужно «растянуть» радиус через sqrt. Это та же история, что в Monte-Carlo интеграции: равномерное распределение по r не равно равномерному распределению по диску. И да — здесь sqrt, наоборот, обязателен.

Gaussian — для «честного, но рандомного» огня

Если вам нужно «большинство пуль рядом с центром, редкие — далеко», берите Box-Muller — преобразование, которое из пары равномерных чисел делает нормально распределённые. Это та самая работа Box & Muller (1958).

public static Vector2 GaussianSpread(float sigma)
{
    float u1 = Mathf.Max(Random.value, 1e-7f);  // log(0) — undefined
    float u2 = Random.value;
    float r = Mathf.Sqrt(-2f * Mathf.Log(u1)) * sigma;
    float t = 2f * Mathf.PI * u2;
    return new Vector2(r * Mathf.Cos(t), r * Mathf.Sin(t));
}

sigma контролирует ширину: меньше — точнее, больше — шире. В CS такой подход применяют для оружия sub-tier'а — FAMAS, Galil, кастомные пистолеты, — где хочется «случайно, но правдоподобно», с мягким центром и редкими далёкими выбросами.

Детерминированные паттерны — Vandal и Phantom

Теперь радикальный поворот. В Valorant у Vandal'а рандома вообще нет. Каждая пуля в очереди — это заранее заданный offset из таблицы. Pro-игроки могут учить паттерны до почти полной воспроизводимости — и это не баг, а ровно то, чего Riot хотели (студия открыто говорила, что точность оружия в Valorant детерминирована). Минус понятен: если у двух игроков одинаковая позиция и одинаковая очередь, у них будет одинаковое попадание. Поэтому Riot балансируют точность через «горизонтальный sway» — после нескольких пуль начинается случайная горизонталь, ломающая идеальную копию.

private static readonly Vector2[] VandalPattern = new Vector2[] {
    new(0, 0),    new(0, -7),   new(0, -16),  new(0, -25),
    new(-1, -34), new(-2, -42), new(-5, -48), /* ... до 30 точек */
};
public static Vector2 GetSpreadOffset(int bulletIndex, Vector2[] pattern)
{
    return pattern[Mathf.Min(bulletIndex, pattern.Length - 1)];
}

4. Recoil patterns: почему AK-47 рисует семёрку

Чтож, со спредом разобрались. Но в шутерах есть отдельная вещь — recoil, отдача. И это не то же самое, что спред. Спред — это случайный (или фиксированный) разброс пуль вокруг прицела. Recoil — это смещение самого прицела вверх и в стороны после каждого выстрела. В Counter-Strike из этой механики выросла целая киберспортивная дисциплина — изучение spray patterns: игроки годами учат, как именно после первой пули AK поднимается ровно вверх, после четвёртой — резко влево, после девятой — назад вправо.

Что вообще такое recoil-паттерн

В принципе всё просто. Каждая последующая пуля в очереди добавляет смещение прицела по фиксированному (или почти фиксированному) набору offset'ов. Через 0.3–0.5 секунды паузы между выстрелами паттерн сбрасывается. Это не баг, а механика: игрок учит паттерн и получает преимущество за мастерство.

Насколько жёстко зафиксирован паттерн — каждая игра решает по-своему. В CS он фиксирован почти полностью: есть небольшой случайный jitter, но шейп один и тот же. В Battlefield и Tarkov — наоборот, рандомизация играет большую роль.

Структура паттерна на примере AK-47 в CS

Если посмотреть на реальный spray AK-47, видна характерная форма «семёрки» (или зеркального «Z»):

Пули 1–4 — почти прямо вверх, vertical kick.
Пули 5–9 — резко влево, horizontal sway.
Пули 10–15 — назад вправо, balancing the kick.
Дальше — мелкое колебание, всё равно мажет.

Поэтому pro-игроки в CS на полной очереди тянут мышь по «обратной семёрке» — вниз и в обратные стороны, чтобы скомпенсировать паттерн.

Реализация: таблица или формула

Тут два подхода, и оба используются. Первый — lookup table, самый прямой и прозрачный: массив [(dx, dy)] на 30 элементов. Балансится через подкручивание чисел.

private static readonly Vector2[] Ak47Pattern = new Vector2[] {
    new(0, 0), new(0, -8), new(0.5f, -18), new(-0.5f, -28),
    new(-1, -38), new(-3, -46), new(-7, -52), new(-12, -56),
    /* ... до 30 точек */
};
public Vector2 GetRecoilOffset(int bulletIndex) {
    return Ak47Pattern[Mathf.Min(bulletIndex, Ak47Pattern.Length - 1)];
}

Второй — procedural: функция от bulletIndex через perlin-noise или несколько синусоид с разными фазами.

public Vector2 ProceduralRecoil(int i) {
    float verticalKick = -i * 4f;
    float horizontalSway = Mathf.Sin(i * 0.6f) * (i * 0.5f);
    return new Vector2(horizontalSway, verticalKick);
}

Procedural сложнее в балансе, но даёт «непохожесть» на конкурентов и легко скейлится по числу пуль. На практике AAA-шутеры с фиксированными узнаваемыми паттернами почти всегда сидят на lookup table — её можно вручную вылизать до миллиметра, а игрок именно эту фигуру и заучивает.

Recoil compensation — как игроки «компенсируют»

Pro-игрок в CS знает, что после выстрела AK прицел поедет вверх и влево. Он тянет мышь вниз и вправо — в реальном времени, по выученному паттерну. В результате на экране пули летят в одну точку. В играх с randomness в паттерне (Battlefield, Tarkov) полная компенсация невозможна — есть «потолок» точности, потому что часть смещения это настоящая случайность. Это сознательный выбор баланса: «мастерство имеет значение, но не отменяет случайность».

5. Упреждение: квадратное уравнение для AI-снайперов

Итак, у нас есть projectile-снаряд. Он летит со своей скоростью, и если мишень движется — целиться надо не туда, где мишень сейчас, а туда, где она окажется к моменту попадания пули. Эту точку называют упреждением, англоязычные коллеги — leading the target. Это и есть то, чем мы обещали в первой части «починить» промахи projectile-AI. По сути же — это банально квадратное уравнение, и решается оно за десять строк кода.

Постановка задачи

Снайпер стоит в точке P_s. Цель находится в точке P_t и движется со скоростью V_t (примем, что прямолинейно и с постоянной скоростью — упрощение, но именно эта модель работает в большинстве AI-снайперов). Снаряд летит со скоростью S. В какую точку нужно стрелять, чтобы попасть?

В момент попадания цель окажется в точке P_t + V_t · t, где t — время полёта снаряда. Снаряд за то же время должен пролететь расстояние, равное S · t. Значит, условие попадания:

P_t + V_t · t − P_s = S · t

Возводим в квадрат, чтобы избавиться от модуля. Обозначим D = P_t − P_s (вектор от стрелка до цели):

(D + V_t · t) · (D + V_t · t) = S² · t²

Раскрываем скалярные произведения и собираем по степеням t:

(V_t² − S²) · t² + 2(V_t · D) · t + D² = 0

Получили квадратное уравнение относительно t вида a·t² + b·t + c = 0, где:

a = V_t² − S²b = 2 · (V_t · D)c = D²,        D = P_t − P_s

b = 2 · (V_t · D)

c = D², D = P_t − P_s

Дальше — школа.

Разбираем дискриминант

Дискриминант Δ = b² − 4ac (стандартный, не путать с вектором D выше).

Δ > 0: два корня. Из них берём меньший положительный — попадаем раньше.
Δ < 0: вещественных корней нет, попасть невозможно (как правило — когда цель убегает быстрее снаряда и оторваться от неё нечем).
Δ = 0: один корень, граничный случай — тангенциальное попадание. Бывает редко, но численно стоит ловить.
a = 0: квадратное вырождается в линейное (V_t = S ровно). Корней либо один, либо нет — обработать отдельно.

Готовый код

Возвращаем Vector3? — null означает «попасть невозможно». Или кодом:

public static Vector3? AimLead(
    Vector3 shooterPos, Vector3 targetPos,
    Vector3 targetVel, float bulletSpeed)
{
    Vector3 D = targetPos - shooterPos;
    float a = Vector3.Dot(targetVel, targetVel) - bulletSpeed * bulletSpeed;
    float b = 2f * Vector3.Dot(targetVel, D);
    float c = Vector3.Dot(D, D);
    // Вырожденный случай: V_t = S — квадратное превращается в линейное.
    if (Mathf.Abs(a) < 1e-6f) {
        if (Mathf.Abs(b) < 1e-6f) return null;
        float t0 = -c / b;
        return t0 > 0f ? (Vector3?)(targetPos + targetVel * t0) : null;
    }
    float disc = b * b - 4f * a * c;
    if (disc < 0f) return null;                          // Δ < 0 — попасть нельзя
    float sd = Mathf.Sqrt(disc);
    float t1 = (-b - sd) / (2f * a);
    float t2 = (-b + sd) / (2f * a);
    // Берём меньший положительный корень — попадаем раньше.
    float t = float.MaxValue;
    if (t1 > 0f && t1 < t) t = t1;
    if (t2 > 0f && t2 < t) t = t2;
    if (t == float.MaxValue) return null;
    return targetPos + targetVel * t;
}

Где это применяют

AI-снайперы в shooter'ах с medium-fast снарядами — Halo Brutes, артиллерия в Helldivers 2.
Авто-наведение в аркадных играх и на мобиле (Free Fire, всякие метательные снаряды в духе Clash Royale).
Турели в tower defense.
Indicator упреждения в прицелах танковых симуляторов — War Thunder, World of Tanks. Там, кстати, прямо в HUD рисуют точку, в которую игроку нужно целиться.

Эта модель работает идеально только для прямолинейного движения с постоянной скоростью. Если цель ускоряется или меняет направление — результат становится приблизительным. Для более точного упреждения используют итеративные методы (повторяют вычисление с уточнённой позицией), но это уже про численные методы, и про них я как-нибудь напишу отдельно.

6. Lag compensation: где ты попал, но не засчиталось

Чтож, мы дошли до самого болезненного. До той самой ситуации, где вы стреляли в голову противника, у вас на экране попали, а сервер сказал «промах». Это не баг и не ваш плохой интернет — это netcode так устроен. И за выбором, как именно netcode устроить, стоит честный trade-off.

Откуда вообще берётся проблема

В сетевом шутере у клиента нет «настоящего» мира. Есть собственная локальная симуляция, обновляемая по snapshot'ам с сервера. Между фактической позицией игрока на сервере и тем, что видит клиент, всегда есть задержка из двух слагаемых:

Пинг — туда-обратно сетевая задержка, обычно 20–80 мс на хорошем соединении, до 200+ мс на плохом.
Interpolation buffer — клиент сознательно отстаёт от сервера на 50–100 мс, чтобы плавно интерполировать между snapshot'ами вместо джиттера.

В сумме клиент видит мир «в прошлом» примерно на 80–200 мс. Когда вы стреляете, вы стреляете в то, что видите, — то есть в позицию противника, какой она была сотню миллисекунд назад. На сервере противник за это время уже сдвинулся, и если сервер проверяет попадание по текущей позиции — вы промазали, хотя на вашем экране попали идеально.

Решение Valve: server rewind

Идея до гениальности проста, и канонически её описал Yahn Bernier из Valve ещё на GDC 2001. Сервер хранит историю позиций всех игроков за последнюю секунду — кольцевой буфер snapshot'ов. Когда клиент посылает выстрел, к пакету прикладывается метка времени: «выстрелил в момент t по своим часам». Сервер откатывает позиции хитбоксов к этому моменту, проверяет попадание и восстанавливает текущее состояние мира.

Псевдокод серверного hit-checker'а в Unity-стиле

public void ProcessShot(ShotPacket shot)
{
    // когда клиент видел эту картину, по часам сервера
    float compTime = shot.ClientTime - shot.Ping * 0.5f;
    // откатываем хитбоксы всех игроков на этот момент
    var snapshot = playerHistory.GetAtTime(compTime);
    ApplySnapshot(snapshot);
    // проверяем попадание стандартным Physics.Raycast
    if (Physics.Raycast(shot.Origin, shot.Direction, out var hit, shot.MaxRange,
                        hitboxLayerMask)) {
        var target = hit.collider.GetComponentInParent<Health>();
        if (target != null) target.TakeDamage(shot.Damage);
    }
    // возвращаем мир в текущее состояние, чтобы остальная симуляция не сошла с ума
    RestoreCurrent();
}

Маленькая оговорка к формуле compTime: в боевых движках к Ping * 0.5 обычно добавляют ещё и величину interpolation-буфера (те самые 50–100 мс), потому что клиент видит мир в прошлом не только из-за пинга. Я это опустил, чтобы не загромождать псевдокод, — но в реальном откате его учитывают.

Это стандарт Source / GoldSrc (Valve), Apex Legends на Source 2 (с поправками), у Overwatch свой netcode со своими тонкостями, но идея та же. Игрок этого механизма не видит — но именно из-за него возникает побочный эффект, который видит и ненавидит жертва.

Trade-off: «убит из-за угла»

У server rewind есть жёсткий побочный эффект. Жертва уже скрылась за угол на своём экране — а на сервере её откатили под выстрел стрелка. С точки зрения жертвы: «я была в безопасности, за углом, и всё равно умерла».

Можно ли это исправить? По сути нет — это объективное следствие выбора «приоритет за стрелком». Если бы сервер использовал текущую позицию, а не откат, то промах был бы у стрелка, и жалоб «я попал, не засчиталось» стало бы кратно больше. Это сознательное решение жанра: лучше иногда «убит из-за угла», чем регулярно «попал, не засчиталось». В CS, Apex и Valorant это считается приемлемой ценой за «попадаешь там, куда целишься». В играх с большим пингом разница становится заметнее, и это одна из причин, почему 64-tick CS:GO регулярно ругали по сравнению с 128-tick faceit-серверами — чем чаще тики, тем точнее rewind и тем меньше эффект «убит из-за угла».

Альтернатива: client authority

Можно вообще выкинуть rewind и доверить стрелку решать, попал он или нет. Клиент сам говорит «я попал», сервер просто верит.

// На стрелке:
void Fire() {
    if (Physics.Raycast(ray, out var hit)) {
        var enemy = hit.collider.GetComponent<Enemy>();
        if (enemy != null) {
            // отправляем серверу: "я попал в enemy.id, нанесите урон"
            networkClient.Send(new HitPacket { targetId = enemy.id, damage = 25 });
        }
    }
}

Минимум CPU на сервере, минимум confusion для жертвы, никакого rewind. Проблема очевидна: легко читерить. Просто отправляй «попал» каждый раз — сервер засчитает. Поэтому client authority для PvP-шутеров — табу. Где это работает: кооперативные игры против AI — Borderlands, Destiny boss fights, любой co-op шутер. Там cheating не критичен (вред от него ограничен своей же командой), и упрощённый netcode даёт лучший feel.

Что в итоге и куда копать дальше

Чтож, мы прошли шесть базовых задач шутерной стрельбы. По одному предложению на каждую — на случай, если вы листали по диагонали:

Hitscan vs projectile — выбор между лучом (мгновенно, дёшево, нет уворота) и снарядом (симуляция, дороже, можно увернуться).
Геометрия попадания — хитбоксы это капсулы, а не меши; в часто выполняемом коде сравнивайте квадраты дистанций.
Спред — два независимых random дают квадрат вместо круга; правильное решение — полярные координаты с sqrt.
Recoil patterns — детерминированная таблица offset'ов плюс компенсация мышью; это про мастерство, а не баг.
Упреждение — банально квадратное уравнение по t, корни делятся на «попасть можно» и «нельзя» через дискриминант.
Lag compensation — сервер откатывает время на момент выстрела, побочный эффект — «убит из-за угла» с точки зрения жертвы.

Чего нет в этой статье

Я сознательно оставил за бортом несколько больших тем:

Баллистика снайперок — drop пули по дистанции, ветер, температура воздуха. Отдельная тема, важная для военных шутеров и снайперских симуляторов вроде Sniper Elite.
Penetration через стены и материалы — в CS и Tarkov это глубокая система с разной плотностью материалов, замедлением пули и переменным damage falloff'ом.
Ricochet и rebound — отскоки. В Destiny, Halo, Doom Eternal на этом играют отдельные оружия.
Damage falloff — простая механика, но требует отдельного баланса. Зачем дробовику плохо стрелять на дистанции — отдельный разговор.
Звук, кросс-эффекты, partial visibility, бронирование — тут уже стык с graphics, audio и UX.

Если эта тема вам в принципе заходит — я веду телеграм-канал «математика в геймдеве по-простому»: там такие разборы выходят короче и чаще, и туда же первыми попадают анонсы новых статей. Заходите.

Что почитать дальше (только то, в чём я уверен):

Christer Ericson, Real-Time Collision Detection (Morgan Kaufmann, 2004) — библия ray–shape тестов, в том числе closed-form ray–capsule из части 2.
Yahn W. Bernier (Valve), Latency Compensating Methods in Client/Server In-game Protocol Design and Optimization (GDC 2001) — каноника по lag compensation. Плюс статья Source Multiplayer Networking в Valve Developer Community wiki — то же на пальцах.
Gabriel Gambetta, Fast-Paced Multiplayer (gabrielgambetta.com) — лучший связный разбор client prediction, server reconciliation, entity interpolation и lag compensation в одном месте.
Glenn Fiedler, gafferongames.com — теория сетевых игр, тики, снапшоты, надёжный UDP.
Box, G.E.P. & Muller, M.E. (1958), A Note on the Generation of Random Normal Deviates (Annals of Mathematical Statistics 29(2):610–611) — та самая формула Box-Muller для Gaussian-спреда.
CS:GO patch от 15 сентября 2015 (liquipedia.net/counterstrike/2015-09-15_Patch) — переход на капсульные хитбоксы.
Battle(non)sense на YouTube — практические замеры netcode современных шутеров, если хочется увидеть rewind и tickrate в цифрах.

Надеюсь, статья была полезна и хотя бы один из этих шести кусков пригодится в вашем проекте. Если хочется покрутить демки руками, а не смотреть на статичные кадры, — интерактивная версия со всеми интерактивами тут.

Хабр Курсы для всех

Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!