API Gateway не должен быть прокладкой: он обязан ломать и собирать JSON без боли

API Gateway не должен быть прокладкой: он обязан ломать и собирать JSON без боли

Если gateway просто прокидывает payload дальше — это не слой интеграции, а дорогой TCP-проброс. Нормальная схема: на входе валидируем обязательные поля, режем мусор, переименовываем ключи, проставляем correlation_id и нормализуем типы. Смотрим в тело запроса, а не в красивое имя endpoint.

Типовой пайплайн трансформации:
— raw JSON → schema check
— map полей: customer_id → user.id
— обогащение из headers: source, trace_id
— фильтрация: выкинуть лишние поля, чтобы не тащить внутренности наружу

Пример полезной нагрузки после gateway:
{
"user": {"id":"123"},
"event":"order.created",
"meta":{"trace_id":"a1b2","source":"shop"}
}

Дальше не геройствуем: если поле пустое или тип не тот — 400 с понятной ошибкой. Если downstream лег, gateway не должен «почти принять» событие. Либо кладём в очередь, либо честно отвечаем 5xx. Идемпотентность — это не роскошь, а база: ключ из event_id или хеша бизнес-полей спасает от дублей при ретраях.

Отдельно про безопасность: whitelist полей, лимит на размер body, запрет на произвольные вложенные структуры и маскирование секретов в логах. Иначе в три часа ночи будете искать, кто протащил лишний токен через «удобный» JSON-маппинг.

Практика простая: трансформируйте только то, что умеете проверить и откатить. Всё остальное — в очередь или в отказ.