API Gateway не должен «уметь всё»: только переписать JSON и не сломать поток

API Gateway не должен «уметь всё»: только переписать JSON и не сломать поток

Gateway удобен как точка, где входная полезная нагрузка приводится к внутреннему контракту. Но если там начинается бизнес-логика, пайплайн превращается в свалку. Нормальная задача шлюза — принять сырой JSON, вычистить мусор, переименовать поля, добавить метаданные и передать дальше. Смотрим в тело запроса, а не в фантазии интегратора.

Типовые трансформации:
• flatten вложенных объектов, если downstream ждёт плоскую схему;
• map status/payment_state/error_code в единый enum;
• подставить correlation_id, source, received_at;
• отрезать лишние поля, чтобы не тащить мусор между сервисами.
Идемпотентность — это не роскошь, а база: если gateway может получить повтор, он должен отдавать тот же результат на тот же вход.

Главная ловушка — «тихая» порча данных. Если поле стало строкой вместо числа, или пустой массив превратился в null, downstream падает уже не на шлюзе, а где-то глубже. Поэтому трансформация должна валидировать схему до и после маппинга, а ошибку отдавать с явным 4xx, не маскируя косяк под успешный прокси. Ретрай-политика решает всё, но только если ошибка действительно временная, а не кривой JSON.

Практика простая: держите маппинг декларативным, логи — с исходным и нормализованным payload, секреты — вне шаблонов, а на нестабильные интеграции ставьте очередь между gateway и обработчиком. Так проще ловить 5xx на ровном месте и не гадать, кто сломал контракт в очередной раз.