<b>API Gateway не должен «уметь всё» — только безопасно резать JSON на входе</b>

<b>API Gateway не должен «уметь всё» — только безопасно резать JSON на входе</b>

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

Рабочая схема: клиент шлёт сырой JSON, Gateway делает маппинг в канонический формат, дальше событие уходит в очередь или в сервис. Пример входа:
<pre>{
"event": "order.created",
"payload": {"id": 42, "sum": "10.50", "meta": {"utm": "x"}}
}</pre>
На выходе лучше иметь:
<pre>{
"type": "order.created",
"order_id": 42,
"amount": 10.5
}</pre>

Обязательные проверки на Gateway: — content-type; — размер тела; — whitelist полей; — дефолты для пустых значений; — жёсткий reject при невалидном JSON. Идемпотентность — это не роскошь, а база: прокидывайте request_id или event_id дальше, иначе ретраи будут плодить дубли. Для ошибок: 4xx на плохую схему, 5xx только если сам Gateway реально сломан. Ловим 5xx на ровном месте обычно там, где трансформатор начинает «догадываться», что имел в виду отправитель.

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

Итог простой: Gateway должен быстро и предсказуемо приводить JSON к канону, а не интерпретировать чужую фантазию.