API Gateway не магия: как не сломать JSON, пока он летит через хендлер

API Gateway не магия: как не сломать JSON, пока он летит через хендлер

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

Рабочий минимум:
— whitelisting полей, а не blacklisting;
— явная маппинг-таблица: input_path → output_path;
— дефолты только для безопасных значений;
— отдельная ветка для невалидного JSON с 4xx, а не ретраями в никуда.

Если трансформация сложная, не тащите логику в gateway до состояния мини-ETL. Шлюз должен быть тонким: принять, проверить, переписать структуру, проставить correlation_id и отправить дальше. Всё, что требует бизнес-решений, уезжает в сервис или очередь. Идемпотентность — это не роскошь, а база: один и тот же payload может прилететь повторно после таймаута.

Пример куска Nginx/OpenResty-подобной идеи: body = json_decode(req.body); body.user_id = body.user.id; body.remove("debug"); — выглядит просто, пока не прилетает кривой массив. Поэтому добавляйте схему, тесты на граничные значения и отдельный лог преобразований. Ретрай-политика решает всё: 5xx — можно повторить, 4xx из-за мусорного JSON — нет.

Делайте преобразование детерминированным и прозрачным: тогда шлюз останется шлюзом, а не комбайном для поисков причины в проде.