Старый клиент отклоняет ответ из-за нового необязательного поля, хотя все прежние поля сохранены. Какое правило обработки неизвестных полей должен закрепить HTTP-контракт?
HTTP-контракт должен требовать, чтобы клиент игнорировал неизвестные необязательные поля ответа и продолжал обработку известных полей. Это обеспечивает обратную совместимость при безопасном расширении формата поставщиком.
Контрактный тест должен добавить в корректный ответ новое поле и проверить, что старый клиент не завершается ошибкой и сохраняет ожидаемое поведение.
Форматы API со временем расширяются: поставщик добавляет метаданные, признаки или новые атрибуты, не меняя смысл уже существующих полей. Если потребитель принимает только строго известную структуру, любое такое расширение превращается в несовместимое изменение.
Правило tolerant reader, или «терпимого читателя», появилось как практический способ развивать распределённые системы независимо: поставщик может добавлять данные, а потребитель использует только ту часть контракта, которая ему известна.
Старый клиент обычно знает обязательные поля и умеет работать с ними. Новый сервер добавляет необязательное поле, но не удаляет прежние поля, не меняет их типы и не нарушает их смысл.
При строгом отклонении неизвестных полей обычное расширение ответа вызывает ошибку десериализации или валидации. В результате поставщик не может безопасно развивать API без одновременного обновления всех потребителей, что повышает связанность релизов и риск простоя.
Контракт должен разделять обязательные известные поля, которые клиент обязан проверить и обработать, и допустимые расширения, которые клиент может не распознавать. Неизвестное поле не должно считаться ошибкой само по себе, если оно не изменяет значение существующих полей и не требуется для выполнения операции.
Интеграционная проверка обычно строится так: берётся совместимый ответ текущей версии, в него добавляется неизвестное поле, после чего проверяется успешная обработка ответа и неизменность результата для уже поддерживаемых данных. Такой тест проверяет поведение потребителя, а не только формальную JSON-схему.
Это правило не означает, что клиент должен игнорировать всё подряд. Отсутствие обязательного поля, изменение типа известного поля, нарушение ограничений значения или изменение семантики должны приводить к контролируемой ошибке. Также неизвестные поля нельзя бездумно игнорировать в областях, где они влияют на безопасность, подпись сообщения, маршрутизацию или принятие критического решения.
Есть и компромисс: строгая проверка неизвестных полей раньше обнаруживает опечатки и неожиданные изменения, но ухудшает совместимость. Практичный вариант — терпимо обрабатывать расширения на границе интеграции, регистрировать неизвестные поля для наблюдаемости и отдельно проверять критичные структуры, где закрытая схема действительно является частью безопасности.
Сервис профилей добавил в ответ поле displayName, тогда как старый мобильный клиент использовал только идентификатор, электронную почту и статус пользователя. После релиза часть клиентов начала показывать ошибку загрузки профиля: библиотека разбора ответа была настроена на отказ при любом неизвестном поле.
Рассматривались два варианта. Сохранить строгий разбор можно было быстро, но это потребовало бы синхронного обновления всех версий клиента и сделало бы будущие расширения опасными. Удалять новое поле или выпускать отдельную версию API означало бы усложнить контракт и увеличить стоимость сопровождения.
Выбрали обработку неизвестных полей с сохранением строгой проверки обязательных полей и типов известных значений. В интеграционный тест добавили ответ с дополнительным полем и проверку успешной обработки старым клиентом; отдельно настроили журналирование неизвестных полей. После этого поставщик смог расширять ответ без отказа старых клиентов, а потенциальные ошибки формата по обязательным полям по-прежнему выявлялись.
Нет. Схема может описывать, что дополнительные поля разрешены, но не доказывает, что конкретный клиент действительно переживает их появление. Нужен поведенческий интеграционный тест: старый потребитель получает расширенный ответ, успешно его разбирает и выдаёт тот же результат по известным данным.
Нет, если потребитель обязан учитывать это значение по смыслу операции. В таком случае поле должно стать частью явно версионируемого контракта или должна появиться новая возможность протокола, которую старый клиент безопасно не использует. Игнорирование допустимо только для действительно необязательных расширений, отсутствие которых не меняет корректность решения старого клиента.
Это разрушает проверку минимального контракта: клиент может получить формально допустимый, но фактически бесполезный ответ. Совместимость требует не безусловной терпимости, а чёткого разделения: обязательные поля и их типы проверяются строго, неизвестные расширения игнорируются, а несовместимые изменения выявляются отдельными контрактными тестами.