{
  "index": 226,
  "slug": "editorial-2021-09-field-api-versioning",
  "title": "Когда поле исчезло: как диагностировать несовместимость API",
  "excerpt": "Клиент получил успешный HTTP-ответ, но не смог прочитать данные. Разбираем missing field, смену семантики и unknown request field, а затем выбираем обратимое действие.",
  "contentHtml": "<p>Клиент получает HTTP 200, но экран заказа остаётся пустым. В логах нет сетевой ошибки. Через несколько минут выясняется: backend заменил поле <code>totalMinor</code> на <code>amountMinor</code>, а старый reader всё ещё ищет первое имя. Похожий симптом возникает и при другой причине: сервер оставил имя, но поменял значение <code>status</code> с <code>confirmed</code> на <code>accepted</code>. В обоих случаях транспорт работает. Ломается договор о данных.</p>\n<p>Цена ошибки — не только один красный экран. Если откатить сервер вслепую, можно вернуть старое поле, но потерять уже опубликованный новый путь. Если молча игнорировать неизвестное поле запроса, пользователь выберет доставку, а заказ сохранит прежнюю настройку. Если повторить state-changing request без проверки идемпотентности, система может создать второй эффект. Поэтому версия API должна описывать совместимость представления и операций, а не только номер в URL.</p>\n<p><strong>Тезис:</strong> сначала нужно зафиксировать конкретный body и первое нарушенное правило, затем проверить старого reader-а на candidate response. Только после этого выбирается действие: сохранить legacy-поле, вернуть прежнее значение, отклонить неизвестный key или поставить retirement на паузу.</p>\n<h2>Что именно считается изменением</h2>\n<p>Рассмотрим учебный endpoint <code>POST /api/orders/{orderId}/confirm</code>. Пример ограничен проверкой формы и семантики JSON. Он не изображает реальный production-трафик, базу данных или работу авторизации.</p>\n<p>Ответ v1 содержит обязательные поля <code>id</code>, <code>status</code> и <code>totalMinor</code>. Для <code>status</code> reader принимает значение <code>confirmed</code>. Ответ v2 может дополнительно содержать <code>deliveryWindow</code>. Если v1 reader получает это дополнительное поле, он может его не использовать: обязательные поля остались на месте, а смысл прежних полей не изменился.</p>\n<p>Удаление обязательного поля — structural break. Переименование <code>totalMinor</code> — тот же break, даже если новое поле содержит ровно ту же сумму. Замена <code>confirmed</code> на <code>accepted</code> — semantic break. Она требует решения о vocabulary, а не нового JSON-пути. Добавление optional-поля — additive change только для reader-а, который действительно умеет пережить неизвестный ключ.</p>\n<p>У request другой набор правил. <code>confirmationCode</code> обязателен. <code>deliveryPreference</code> optional: отсутствие означает «не менять», а <code>null</code> означает «очистить». Опечатка <code>deliveryPrefrence</code> — неизвестный key. Если сервер его молча пропустит, запрос формально завершится, но намерение пользователя исчезнет.</p>\n<h2>Механизм проверки</h2>\n<p>Разделите ответ на transport layer, shape и meaning. HTTP status говорит, дошёл ли запрос и какой общий результат сообщил сервер. JSON reader проверяет обязательные keys и их типы. Доменный слой проверяет допустимые значения и связывает их с действием интерфейса. Успешный status на первом слое не доказывает успех на двух следующих.</p>\n<pre><code>function readV1Response(body) {\n  for (const key of ['id', 'status', 'totalMinor']) {\n    if (!(key in body)) return { ok: false, error: 'missing:' + key };\n  }\n\n  if (body.status !== 'confirmed') {\n    return { ok: false, error: 'unsupported-status:' + body.status };\n  }\n\n  if (!Number.isInteger(body.totalMinor) || body.totalMinor &lt; 0) {\n    return { ok: false, error: 'invalid-totalMinor' };\n  }\n\n  return { ok: true, value: {\n    id: body.id,\n    status: body.status,\n    totalMinor: body.totalMinor,\n  } };\n}\n\n// Учебный reader: неизвестные response fields не используются.\n// Это правило нужно подтвердить для конкретного parser-а проекта.</code></pre>\n<p>Функция намеренно не делает fetch и не повторяет запрос. Она принимает уже полученное представление и возвращает первую проверяемую причину отказа. Такой порядок важен: сообщение <code>missing:totalMinor</code> полезнее общего «не удалось разобрать ответ». Он связывает симптом с контрактом, но не утверждает, почему backend изменил body.</p>\n<p>Для request нужно отдельно решить политику unknown keys. Строгий validator лучше молчаливого игнорирования, если операция меняет состояние. В учебной модели он различает отсутствие optional-поля, явный <code>null</code> и неизвестное имя:</p>\n<pre><code>function readConfirmRequest(body) {\n  const allowed = new Set(['confirmationCode', 'deliveryPreference']);\n  const unknown = Object.keys(body).filter((key) =&gt; !allowed.has(key));\n  if (unknown.length) return { ok: false, error: 'unknown-request-field' };\n  if (typeof body.confirmationCode !== 'string' || !body.confirmationCode) {\n    return { ok: false, error: 'missing-confirmationCode' };\n  }\n\n  return {\n    ok: true,\n    preference: Object.prototype.hasOwnProperty.call(body, 'deliveryPreference')\n      ? body.deliveryPreference\n      : 'unchanged',\n  };\n}</code></pre>\n<p>Этот код не задаёт универсальную политику для всех API. В одном проекте неизвестные поля могут быть разрешены для forward compatibility. В другом они должны приводить к 400, чтобы опечатка не превращалась в потерянное намерение. Решение нужно записать в контракте и проверить на реальном parser-е, а не выводить из одного примера.</p>\n<h2>Симптом → причина → проверка → действие</h2>\n<div class=\"table-scroll\"><table><caption>Минимальная матрица диагностики</caption><thead><tr><th scope=\"col\">Симптом</th><th scope=\"col\">Причина</th><th scope=\"col\">Проверка</th><th scope=\"col\">Действие</th></tr></thead><tbody><tr><td>v1 не показывает сумму</td><td><code>totalMinor</code> удалили или переименовали</td><td>Запустить v1 reader на сохранённом candidate body</td><td>Сохранить legacy field и остановить retirement</td></tr><tr><td>HTTP 200, но клиент выбрал другую ветку</td><td><code>status</code> изменил семантику</td><td>Сверить vocabulary и допустимые значения reader-а</td><td>Вернуть прежнее значение или подготовить явный переход</td></tr><tr><td>Новое предпочтение не применилось</td><td>Опечатка или unknown request field</td><td>Проверить keys, presence, absence и <code>null</code></td><td>Отклонить запрос и исправить contract или client</td></tr><tr><td>v2 не показывает окно доставки</td><td>Перепутали absent, <code>null</code> и неполный object</td><td>Проверить три формы одним reader-ом</td><td>Уточнить смысл optional field и сохранить старый response</td></tr></tbody></table></div>\n<p>Матрица ускоряет сортировку, но не заменяет исходный body. Для каждого случая сохраните method, endpoint, revision, sanitized request, status, response body и версию reader-а. Секреты и персональные данные удаляйте до записи. Не заменяйте эти данные пересказом вроде «после релиза всё сломалось»: такой пересказ не позволяет отличить удаление поля от смены значения.</p>\n<figure><img src=\"/assets/editorial/2021/api-versioning-diagnosis-2021.svg\" alt=\"Диагностическое дерево несовместимости API: response и request проходят проверки формы, семантики и неизвестных полей\" loading=\"lazy\" /><figcaption>Рисунок 1. Диагностика начинается с сохранённого request и response. Rollback или retirement идут после проверки совместимости.</figcaption></figure>\n<h2>Почему retirement нужно уметь остановить</h2>\n<p>Предположим, команда хочет удалить <code>totalMinor</code> после перехода на <code>amountMinor</code>. Сначала запускается старый reader на candidate response. Если он возвращает <code>missing:totalMinor</code>, это не повод менять данные или повторять операцию. Это сигнал: старый consumer ещё зависит от поля либо переходный договор не доказан.</p>\n<p>Безопасное действие — зафиксировать <code>retirement-paused-before-change</code>, оставить legacy representation и указать условие повторной проверки. Такой шаг обратим: он не требует восстанавливать состояние после уже выполненной мутации. Если причина — semantic change, нужно вернуть прежнее значение или расширить reader с явным маппингом. Если причина — unknown request key, нельзя добавлять молчаливый fallback только ради зелёного HTTP status.</p>\n<p>Заголовок deprecation тоже не заменяет проверку. Он может сообщить потребителю, что ресурс планируют вывести, но не доказывает, что потребитель найден, миграция завершена или старый parser принимает новую форму. Retirement имеет смысл только после проверки всех известных consumers и условия отката.</p>\n<h2>Порядок действий</h2>\n<ol><li><strong>Зафиксируйте симптом.</strong> Запишите один contract case: endpoint, method, revision, sanitized request, response, HTTP status и видимое поведение клиента. Не смешивайте в один вывод несколько приложений.</li><li><strong>Назовите первое нарушенное правило.</strong> Проверьте обязательный response key, тип, допустимое значение, форму optional object и неизвестные request keys. Отделите отсутствие от <code>null</code>.</li><li><strong>Сравните представления.</strong> Запустите старый и новый reader на base, additive и candidate response. Для request отдельно проверьте обязательное поле, optional absence, optional <code>null</code> и опечатку.</li><li><strong>Выберите обратимое действие.</strong> При failed retirement gate сохраните legacy field и остановите removal. При semantic break согласуйте vocabulary. При unknown request field верните явный отказ, если этого требует contract.</li><li><strong>Добавьте защиту.</strong> Оставьте compatibility test для старого reader-а, проверку нового reader-а и наблюдаемый сигнал для rejected request. Повтор state-changing operation разрешайте только по отдельному правилу идемпотентности.</li></ol>\n<h2>Ограничения</h2>\n<p>Примеры выше учебные. Они не доказывают результат в production и не моделируют авторизацию, rate limit, cache, proxy, сериализацию <code>undefined</code>, retry policy, базу или фактическое распространение мобильного клиента. Не каждый JSON parser игнорирует неизвестные response fields. Не каждый сервер обязан отвергать неизвестные request fields. Эти свойства нужно проверить в конкретном стеке.</p>\n<p>OpenAPI описывает форму входа и выхода, но сама спецификация не выполняет миграцию и не находит всех потребителей. Версия URL также не гарантирует совместимость: два разных пути могут использовать один несовместимый reader, а один путь может безопасно обслуживать additive response. Готовность retirement нельзя выводить из даты релиза или единственного успешного запроса.</p>\n<h2>Проверяемый критерий готовности</h2>\n<p>Изменение готово к рассмотрению, когда старый reader проходит на каждом сохранённом response, новый reader проходит на новой форме, request validator различает отсутствие, <code>null</code> и unknown key, а отрицательные проверки возвращают ожидаемые ошибки. Для removal отдельно доказано, что известные consumers больше не зависят от legacy field и что есть обратимое действие до первой несовместимой мутации. Если хотя бы одно условие не выполнено, retirement остаётся на паузе.</p>\n<h2>Проверяемые источники</h2>\n<ul><li><a href=\"https://spec.openapis.org/oas/v3.1.0.html\" target=\"_blank\" rel=\"noopener noreferrer\">OpenAPI Specification 3.1.0</a> — официальное описание схем входа и выхода API; оно задаёт форму контракта, но не подтверждает совместимость конкретного reader-а.</li><li><a href=\"https://www.rfc-editor.org/rfc/rfc8594.html\" target=\"_blank\" rel=\"noopener noreferrer\">RFC 8594: The Sunset HTTP Header Field</a> — первичный документ IETF о сигнале будущей недоступности ресурса; заголовок остаётся подсказкой и не заменяет договор с потребителем.</li></ul>"
}