14-5 · Глава 14 · 6 мин. чтения

Когда изменение API ломает то, о чём пользователи даже не подозревали

Как незаметное изменение API может сломать работу мобильных приложений, фронтендов и сервисов других команд. Разбираем breaking changes, автоматическое обнаружение в CI/CD, версионирование и проектирование API для эволюции.

Когда изменение API ломает то, о чём пользователи даже не подозревали

Вы выкатываете новую версию бэкенд-сервиса. Пайплайн зелёный. Логи чистые. Через пять минут чат команды взрывается: мобильное приложение показывает пустые экраны, веб-фронтенд не отображает данные, а сервис соседней команды сыпет 500-ми ошибками на каждый запрос.

Что случилось? Вы переименовали поле nama в full_name в ответе API. Казалось бы, мелочь. Но мобильное приложение парсило это поле по имени, веб-фронтенд выводил его напрямую, а сервис другой команды маппил его на колонку в своей базе. Никто не получил предупреждения, потому что вы даже не знали об их существовании.

Такова реальность поддержки API. В отличие от фонового воркера или запланированной задачи, которые трогает только ваша команда, у API есть потребители, о которых вы можете даже не догадываться. Мобильное приложение, выпущенное в прошлом году. Интеграция с партнёром, настроенная другим отделом. Фронтенд, который нельзя обновить до следующей проверки в App Store. Когда вы меняете API, вы меняете не просто свой код. Вы меняете контракт, на который полагаются другие системы.

Проблема, которую вы не видите

Ключевая проблема — отсутствие видимости. В крупной организации один API-эндпоинт могут потреблять десятки команд. Даже если ваш API обслуживает только одно приложение, оно уже может быть в руках пользователей, которые не могут обновиться мгновенно. Невозможно скоординировать одновременный релиз для всех потребителей. О некоторых вы даже не подозреваете.

Именно здесь обратная совместимость становится практической необходимостью, а не теоретическим идеалом. Обратная совместимость означает, что новая версия API всё ещё может обрабатывать запросы в том же формате, что и старая. Если ваш эндпоинт /users раньше возвращал поле nama, новая версия не может внезапно переименовать его в full_name без переходного периода. Если параметр page принимал целое число, новая версия не может внезапно потребовать строку. Такие изменения нарушают контракт, а нарушенный контракт означает сломанных потребителей.

Что считается ломающим изменением

Ломающие изменения бывают разными, и некоторые очевиднее других. Удаление эндпоинта — однозначно ломающее изменение. Переименование поля — ломающее. Изменение типа данных — ломающее. Добавление обязательного поля в тело запроса — ломающее. Изменение формата ответов об ошибках — ломающее.

Но есть и более тонкие моменты. Изменение порядка полей в JSON-ответе может сломать код, который полагается на индексацию массива. Добавление нового обязательного заголовка может сломать клиентов, которые его не отправляют. Даже изменение HTTP-статуса для конкретной ошибки может сломать логику, проверяющую точные значения статусов.

Рассмотрим простой пример. Раньше ваш API возвращал объект пользователя так:

{
  "id": 42,
  "nama": "Ani Wijaya",
  "email": "ani@example.com"
}

После вашего «приведения в порядок» он возвращает:

{
  "id": 42,
  "full_name": "Ani Wijaya",
  "email": "ani@example.com"
}

Для вас это лучшее имя. Для мобильного приложения, которое парсит response["nama"], это undefined. Для фронтенда, отображающего user.nama, — пустота. Для партнёрского сервиса, мапящего nama на колонку в БД, — молчаливый null. Поле по сути осталось, но контракт нарушен.

Сложность в том, что такие изменения часто выглядят безобидно со стороны сервера. Вы просто чистите код, добавляете функциональность или исправляете несогласованность имён. Но с точки зрения потребителя поведение изменилось так, как они не просили и к чему не могут адаптироваться без изменения своего кода.

Ловите ломающие изменения до попадания в продакшен

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

Если вы используете формат спецификации API, например OpenAPI, такие инструменты, как OpenAPI Diff или Spectral, могут сравнивать старую и новую версии вашей спецификации. Они точно указывают, что изменилось и является ли это ломающим изменением. Если ваш фреймворк генерирует спецификацию автоматически (FastAPI, SpringDoc, ASP.NET Core со Swashbuckle), вы можете запускать это сравнение на каждом pull request.

Рабочий процесс выглядит так: когда разработчик открывает pull request, CI-пайплайн собирает новую спецификацию API, сравнивает её со спецификацией из основной ветки и сообщает о любых ломающих изменениях. Если их нет, PR может идти дальше. Если есть, команда может обсудить, действительно ли изменение необходимо или его можно сделать постепенно.

Это смещает фокус с «надеюсь, ничего не сломается» на «вот что именно изменилось и нарушает ли это контракт». Невидимый риск превращается в видимую точку принятия решения.

Когда ломающих изменений не избежать

Не все ломающие изменения можно предотвратить. Иногда бизнес-требования вынуждают к перепроектированию. Иногда архитектура должна эволюционировать. Иногда старый дизайн был просто ошибочным и требует замены.

Когда ломающее изменение неизбежно, стандартный подход — версионирование API. Идея проста: вы поддерживаете несколько версий API одновременно. Старые потребители продолжают использовать старую версию, пока новые переходят на новую. Вы даёте всем время на миграцию.

Есть несколько способов реализации версионирования, каждый со своими компромиссами.

Версионирование в URL — самый распространённый подход. Вы помещаете версию в путь: /v1/users и /v2/users. Это легко понять, легко маршрутизировать и легко тестировать. Минус — URL становятся длиннее, и вы поддерживаете отдельные пути кода для каждой версии.

Версионирование через заголовки сохраняет URL чистыми, но требует от потребителей установки кастомного заголовка, например Accept: application/vnd.myapi.v1+json. Теоретически это более RESTful, но добавляет сложности для потребителей, которым нужно правильно настроить заголовки.

Версионирование через параметры запроса использует что-то вроде ?version=1. Это просто, но менее распространено, так как может засорять строки запроса и усложнять кеширование.

Какой бы метод вы ни выбрали, версионирование не бесплатно. Каждая поддерживаемая версия — это код, который нужно запускать, тестировать, отлаживать и в конечном счёте выводить из эксплуатации. Нужна политика, определяющая, как долго поддерживаются старые версии. Шесть месяцев — обычный срок. Год — щедрый. Что бы вы ни выбрали, сообщите об этом чётко и заранее. Дайте потребителям окно для миграции, а не внезапное отключение.

Лучший путь: проектирование для эволюции

Версионирование — это запасной вариант, а не стратегия. Лучший подход — проектировать API так, чтобы он мог эволюционировать без необходимости в новых версиях. Это означает осознанный подход к тому, что и как вы выставляете наружу.

Не возвращайте поля, которые не нужны потребителям. Каждое добавленное поле — это поле, от которого кто-то может зависеть. Если вы не уверены, нужно ли поле, оставьте его. Вы всегда можете добавить его позже, но удаление — это ломающее изменение.

Используйте гибкие типы данных там, где это возможно. Принимайте и строки, и числа для параметров, которые могут быть и тем, и другим. Возвращайте дополнительные поля в ответах, не требуя от потребителей их использовать. Принцип прост: будьте либеральны в том, что принимаете, и консервативны в том, что обещаете.

Когда нужно добавить новую функциональность, добавляйте новые поля или новые эндпоинты. Не изменяйте существующие. Новое поле в ответе не ломает старых потребителей — они его просто игнорируют. Новый эндпоинт не ломает старых потребителей — они его никогда не вызывают. Пока вы не удаляете и не переименовываете существующее, вы можете эволюционировать без увеличения версии.

Практический чек-лист для изменений API

Перед тем как смержить pull request, пройдитесь по этим пунктам:

Вы удалили или переименовали какое-либо существующее поле, параметр или эндпоинт?
Вы изменили тип данных какого-либо существующего поля или параметра?
Вы добавили обязательное поле в тело запроса?
Вы изменили формат ответов об ошибках?
Вы изменили HTTP-статусы для существующих сценариев?
Вы запустили автоматическое сравнение с предыдущей спецификацией API?

Если вы ответили «да» на любой из первых пяти вопросов, у вас ломающее изменение. Решите, отложить ли его, версионировать или чётко сообщить всем известным потребителям.

Вывод

Ваш API — это контракт. Каждый потребитель, который от него зависит, заключил неявное соглашение на основе его текущего поведения. Изменение этого контракта без предупреждения — не техническая ошибка. Это сбой координации, который подрывает доверие между командами.

Цель не в том, чтобы никогда не делать ломающих изменений. Цель — знать, когда вы их делаете, осознанно решать, стоят ли они того, и давать потребителям путь вперёд. Автоматизируйте обнаружение, сообщайте об изменениях и проектируйте для эволюции с самого начала. Ваши потребители никогда не поблагодарят вас за поддержание обратной совместимости, но они точно заметят, когда её нет.