Версионирование API

Контракт API — это обещание: клиенты, написанные сегодня, заработают и завтра. AIP-180, гайд Google по обратной совместимости, формулирует базовое правило: «Old clients must be able to work against newer servers (with the same major version number)» — старые клиенты обязаны работать с новыми серверами, пока у них одинаковый major-номер версии. Само понятие «сломал — не сломал» раскладывается на три вида совместимости. «Source compatibility: Code written against a previous version must compile against a newer version, and successfully run with a newer version of the client library» — код обязан компилироваться и работать против новой клиентской библиотеки. «Wire compatibility: Code written against a previous version must be able to communicate correctly with a newer server» — сериализация и десериализация обязаны совпадать. «Semantic compatibility: Code written against a previous version must continue to receive what most reasonable developers would expect» — самое коварное: разумный разработчик продолжает получать то, что ожидал. Любое изменение, роняющее хотя бы один из трёх видов, — это breaking change, и версионирование начинается с честного ответа: минорное улучшение или слом? Англоязычные гайды зовут эту дисциплину evolution proto — эволюция proto-схем по явным правилам, а не по догадкам. Байтовую механику — unknown fields, reserved, Last One Wins — вы уже знаете из девятнадцатого урока; сегодня достраивается второй этаж: организация кода и время жизни версий.

Раскладка версий начинается с пакета. Стиль-гайд Buf формулирует правила, которые потом подхватывают линтеры: «All files should have a package defined»; «All files of the same package should be in the same directory, and every file should live in a directory that matches its package name»; «The last component of a package should be a version». Пакеты пишутся в нижнем регистре с подчёркиваниями: «Packages should be in lower_snake_case format» — поэтому shop.v1, а не ShopV1 или shopV1. Для нашего магазина это пакет shop.v1 и файл proto/shop/v1/order.proto — путь дублирует пакет, и по имени файла уже видно, какая версия перед вами. Ещё одно правило связывает файлы одного пакета между собой: «All of the file options below should have the same value, or all be unset, across every file that shares a package» — go_package обязан быть одинаковым у всех файлов пакета. За этим следят правила линтера Buf: PACKAGE_SAME_GO_PACKAGE — совпадение go_package, PACKAGE_DIRECTORY_MATCH — соответствие каталога пакету, PACKAGE_VERSION_SUFFIX — версия на конце пакета. Это скучная гигиена ровно до того момента, когда вы захотите выкатить v2: без неё не было бы видно, где кончается одна версия и начинается другая.

Внутри одной major-версии растить API можно почти свободно — но с оговорками. AIP-180: «In general, new components (interfaces, methods, messages, fields, enums, or enum values) may be added to existing APIs in the same major version» — новые интерфейсы, методы, сообщения, поля, перечисления и значения перечислений добавлять можно. Ограничения следуют сразу. «New required fields must not be added to existing request messages or resources» — новые обязательные поля в старые запросы не добавляют: клиент, который о них не знает, отправит запрос без них и получит отказ — это ломает его молча. Любое поле, которое заполняют клиенты, обязано иметь дефолтное поведение, совпадающее с прежним. Дефолты сервера менять тоже нельзя: «Default values are the values set by servers for resources when they are not specified by the client», и эти значения «must not change across minor versions». С enum'ами отдельная осторожность: клиентский switch может не знать нового значения — свободно добавляйте значения только в перечисления для запросов, а для ответов документируйте расширение заранее. С байтовой точки зрения всё это — переформулировка девятнадцатого урока: добавленное поле старый парсер пропустит как unknown fields. Разница в том, что AIP смотрит шире провода — на компиляцию и на ожидания людей.

Девятнадцатый урок показал: на проводе правит номер поля, поэтому переименование не меняет ни одного байта. Но AIP-180 смотрит и на остальное: «Renaming a component is semantically equivalent to 'remove and add'» — переименование компонента семантически эквивалентно удалению и добавлению. Уточнение важное: «a service may add the new component, but must not remove the existing one» — добавить новое можно, убирать старое нельзя. Имя поля живёт не только в байтах: JSON-кодирование ходит по именам (вспомните совет резервировать имя вместе с номером), исходники клиентов генерируются по именам, и переименованное поле в чужом языке перестаёт находиться компилятором. Поэтому Buf содержит отдельное правило FIELD_SAME_NAME в категории WIRE_JSON: переименование в живой схеме билд не пройдёт, хотя байты не изменились бы вовсе. Практика: новое поле добавляется, старое помечается deprecated и живёт до конца срока жизни версии; если поле решено держать видимым в схеме, ему дают префикс OBSOLETE_, как советовал девятнадцатый урок. Само удаление — через reserved номера и имени; это процедура, а не новый факт, повторять её механику здесь не будем.

Сервер gRPC хранит службы по их полным именам, а полное имя включает пакет. Отсюда главный разворот версионирования. Первый путь — один сервис: контракт shop.v1 эволюционирует совместимыми изменениями, служба остаётся одна, клиенты живут спокойно. Второй путь — два сервиса: рядом с shop.v1.OrderService регистрируется shop.v2.OrderService, полное имя у каждого своё, и маршрутизация по пакету раскладывает вызовы сама: /shop.v1.OrderService/GetOrder уходит в старый хендлер, /shop.v2.OrderService/GetOrder — в новый. Один порт, один процесс, один health-check — но два контракта с независимым циклом жизни. Два сервиса — это ещё и гигиена: новый контракт не тащит на себе деприкации старого, а хендлеры можно вести разными командами и выпускать по разным графикам. Цена — дублирование: конвертация сообщений между версиями, двойная телеметрия, два набора тестов. Отдельный триггер для major — смена типа поля: AIP-180 требует «Existing fields and messages must not have their type changed, even if the new type is wire-compatible, because type changes alter generated code in a breaking way» — даже проводно-совместимая смена типа ломает сгенерированный код, а значит source-совместимость. Правило практиков простое: пока изменения совместимы — живите в одной версии и растите её по правилам AIP-180; два сервиса заводите, когда совместимость больше не выдерживается — сменой типа поля, сменой семантики ответа или сменой формата данных.

Пометка deprecated — не украшение, а начало процедуры. Гайд Google по версионированию: «API elements (fields, messages, RPCs) may be marked deprecated in any channel to indicate that they should no longer be used» — пометить можно поле, сообщение или RPC в любом канале. Дальше — время. Для бета-канала гайд называет цифру: функциональность «may be removed after it has been deprecated for a sufficient period; we recommend 180 days» — полгода на миграцию. Есть и правило гигиены в обе стороны: «Deprecated API functionality must not graduate from alpha to beta, nor beta to stable» — помеченное устаревшим не должно мигрировать между каналами, иначе в стабильный выпуск попадает «заранее устаревшее». Для целых версий логика та же, но масштабнее: «An older version must go through a reasonable, well-communicated deprecation period before being shut down» — версия уходит через объявленный, заранее оговорённый период. Отдельно зафиксируйте для себя: помеченное deprecated поле продолжает работать. Это приглашение к переезду с датой отселения, а не выселение с момента подписи.

Гайд Google фиксирует право клиента, а не только обязанность сервера: «Different versions of the same API must be able to work at the same time within a single client application for a reasonable transition period» — обе версии живут в одном приложении одновременно. Это значит, что клиентская сторона версионирования — не «переключили импорт и перекомпилировали», а мост. Внутри приложения заводится доменная структура, которая не знает о proto-версиях; над ней — конвертеры в обе стороны и клиент, умеющий говорить и с v1, и с v2. Переключение версий прячется за флаг миграции: включили v2 для одного процента трафика, посмотрели метрики, расширили охват. Мост — не вечная постройка: его судьба — умереть в конце переходного периода, когда последний вызов v1 уйдёт и импорт shopv1 удалят. Пока он жив, он единственное место в коде, где оба пакета импортированы одновременно, — и это осознанная изоляция: если где-то и придётся касаться обоих контрактов, то лучше в одном файле, чем по всему репозиторию.

Как это выглядит у крупнейшего оператора gRPC API. Гайд Google по версионированию: «All Google API interfaces must provide a major version number, which is encoded at the end of the protobuf package, and included as the first part of the URI path for REST APIs» — major-версия живёт в конце пакета и в первой части пути REST-моста: пакет google.firestore.v1, а запрос выглядит как GET /v1/projects/my-project/topics. Миноров и патчей на поверхности нет: «Google APIs use v1, not v1.0, v1.1, or v1.4.2» — для пользователя версия обновляется на месте, новые возможности приезжают без миграции. Для экспериментов — каналы: к версии приписывается уровень стабильности, v1beta и v1alpha легальны, но «v1 is an acceptable version for the stable channel, but v1beta or v1alpha are not» — стабильный канал всегда чистый v1, а бета обязана быть надмножеством стабильного. И архитектурное правило с зубами: «A new major version of an API must not depend on a previous major version of the same API» — новая major-версия не должна зависеть от предыдущей: копируйте контракты, а не связывайте версии в цепочку зависимостей.

Все правила эволюции не стоят ничего, пока проверяются памятью и надеждой. Buf превращает их в шаг CI. Документация: «buf breaking compares a Protobuf schema against an earlier version and reports any rules that the newer version breaks» — каждая проверка принимает две схемы: текущую и базовую, переданную через --against. Типовая команда: buf breaking --against '.git#branch=main' — схему в вашей ветке сверяют с main: сломаете контракт, билд падает до ревью, а не после выката. Правила сгруппированы по категориям: WIRE проверяет проводную совместимость, WIRE_JSON добавляет сверху JSON-слой. Внутри — имена, которые вы теперь читаете как словарь: FIELD_NO_DELETE, FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED (удаление с reserved номером — легально), FIELD_SAME_NAME, FIELD_SAME_TYPE, FILE_NO_DELETE. Безопасная эволюция из девятнадцатого урока и пакетная гигиена из сегодняшнего — это один шаг пайплайна: сломал — увидел имя правила и номер файла, а не тикет от клиента через месяц.

Последний слой — тесты, которые держат матрицу: клиент v1 против сервера v1, клиент v1 против сервера v2, клиент v2 против сервера v1, клиент v2 против сервера v2. Все четыре ячейки обязаны работать в течение переходного периода — это исполняемая версия правила AIP-180 про старых клиентов на новых серверах. Добавьте к этому golden-тесты сериализации: зафиксированные байты сообщений из девятнадцатого урока не дадут случайно переехать номеру поля. Как запускать сервер в тесте без порта и сети — отдельная наука: в gRPC для этого есть bufconn, поднимающий сервер на in-memory соединении. Это тема следующего урока — 21-testirovanie «Тестирование gRPC-сервисов»: bufconn, тесты хендлеров и стримов; сегодняшняя матрица версий станет там набором тестовых случаев. Версионирование без тестов на совместимость — конституция без суда: красиво, но не исполняется.

Честная оговорка про формат, одна на урок: в самоучителе есть песочница с интерпретатором Go, но сеть в браузере недоступна — protoc, gRPC-сервер и Buf в браузере не запустить, поэтому runner-ов в этом уроке, как и во всём gRPC-курсе, нет; каждое упражнение делается локально за несколько минут. Три эксперимента. Первый: соберите сервер из этого урока, зарегистрируйте только v2 и достучитесь клиентом v1 — получите дословный «unknown service shop.v1.OrderService», затем верните регистрацию v1 и убедитесь, что оба пути отвечают. Второй: пометьте metadata как deprecated = true, перегенерируйте код и найдите комментарий «Deprecated: Do not use.» в pb-файле; сверьте, что вывод grpcurl describe не изменился. Третий: поставьте Buf, запустите buf lint на модуль с v1 и v2, затем buf breaking --against против ветки без v2-каталога и разберите каждую строку отчёта. Дальше по маршруту: двадцать первый урок — тестирование gRPC-сервисов: bufconn, тесты хендлеров и стримов — там сегодняшняя матрица совместимости станет набором тестов. А перед этим загляните в сериализацию и оптимизацию proto — правила, которые buf breaking проверяет за вас, вы выводили руками, и в proto3 — там началась схема Order. Полный маршрут — в курсе gRPC на Go.