Версионирование схем

Прежде чем правил, механика. Сообщение по wire-формату — это последовательность пар номер-значение: получатель читает номер, смотрит в своей версии схемы, что за поле под этим номером, и декодирует. Отсюда два вида совместимости, и их полезно различать. Wire-совместимость: старый бинарник читает новое сообщение без ошибок — незнакомые номера он пропускает (сохранив при желании в unknown fields), знакомые декодирует; отсутствующие поля получают нулевые значения. Source-совместимость: перегенерированный код старой схемой компилируется — имена полей и типов важны здесь. Клиенты не перегенерируются одновременно с сервером — браузер из девятого урока шлёт JS-код месячной давности, мобильное приложение — годичной, — поэтому по умолчанию вы проектируете под wire-совместимость и бережёте source-совместимость по возможности. Из механики следуют все правила урока. Добавить поле со свежим номером — безопасно: старые клиенты его пропустят. Убрать поле — безопасно для чтения (старые клиенты пришлют его, сервер молча проигнорирует), но опасно для будущего: номер выбывшего поля нельзя отдать другому полю, пока где-то жив клиент, который помнит под этим номером старый тип. Изменить тип поля — почти всегда поломка: получатель декодирует байты по старой схеме и получает мусор, который не заметен как ошибка. Это худший жанр поломки — не отказ, а тихая порча данных.

Каталог разрешённого — короткий и стоит его выучить наизусть. Добавление нового поля со свежим номером — базовая операция эволюции: клиенты старой версии не увидят поле, новые прочитают; число в protobuf3 всегда имеет нулевое значение по умолчанию, поэтому отсутствие поля неотличимо от пустого — это свойство и есть фундамент совместимости. Переименование идентификатора поля — безопасно на wire-уровне, потому что имя по сети не ездит; но с оговоркой: JSON-кодек из четвёртого урока сериализует поля именем (нижнекэмельным по умолчанию), и браузерные клиенты, читающие JSON, заметят переименование. Если меняете имя, меняйте для JSON-потребителей через явную опцию json_name, сохранив старое. Добавление значения в enum — безопасно с оговоркой: старый клиент, получив незнакомое числовое значение, увидит его как число (в proto3 незнакомые enum-значения сохраняются), и ваш код должен переживать незнакомца без паники — проверяйте ветку default. Помечать поле опцией deprecated = true — безопасность в чистом виде: метка для людей и генераторов, wire-формат не трогается. И резервирование выбывшего — не изменение, а гигиена после удаления, следующий блок. Отдельно — что безопасно на чтении: сервер может начать игнорировать поле, которое раньше использовал; клиенты переживают это без труда. Общий знаменатель каталога: вы только расширяете словарь, ничего не переиначивая в существующем.

Удаление поля создаёт самую коварную угрозу курса: номер освобождается, и через полгода кто-то добавляет новое поле, взяв красивый освободившийся номер. Пока жив хоть один клиент со старой схемой, он под этим номером ждёт старого типа — и получает новый: поломка без единой ошибки на проводе. Защита — reserved: директива, после которой компилятор запрещает использовать зарезервированные номера и имена. Резервируйте всегда оба измерения: reserved 3; блокирует номер, reserved «body»; блокирует имя (чтобы никто не вернул поле с тем же именем под другим номером — риск другой поломки на JSON-уровне). Можно списком: reserved 2, 3, 5; и reserved «a», «b». Та же дисциплина для enum: удалённое значение резервируется и номером, и именем, потому что переиспользование enum-номера ломает так же тихо. Правило срока резерва: навсегда. Резерв бесплатен, не влияет на wire-формат, не мешает ничему — а история про «точно никто не помнит старый номер» всегда оказывается ложью: старые клиенты живут годами, билды откапываются из архивов, фичи откатываются. В buf-линте из десятого урока есть готовые правила, которые требуют резервов при удалении — включённый lint сделает гигиену автоматической, и собеседование по схеме перестанет быть нужным.

У enum-значений номера те же контракты, что у полей, с одним усилением: значение по умолчанию — ноль — фиксировано. Первое значение enum обязано быть нулевым, и оно должно быть осмысленным «неизвестно/не задано» — NAME_UNSPECIFIED; менять номер нулевого значения нельзя никогда, это ломает всех сразу. Добавление значения — безопасная операция при одном условии: клиентский код обязан переживать незнакомые значения — в Go перегенерированный enum примет число, в TypeScript из девятого урока вы получите значение, которого нет в union-типе, и switch без default упадёт не сразу, а в рантайме. Удаление значения — через резерв пары номер-имя, как у полей; при живых клиентах вместо удаления — депрекация. Oneof эволюционирует как набор полей: добавлять ветки можно со свежими номерами, удалять с резервом, менять тип существующей ветки — нельзя. Отдельная ловушка oneof: код с type switch (в Go — switch msg.Which...Case) при добавлении ветки не сломается компиляцией, а молча уйдёт в ветку отсутствия значения; при добавлении ветки в oneof просматривайте все type switch в кодовой базе — это источник тихих багов, который buf breaking не видит, потому что схема формально совместима. Механика завершена: дальше — когда эволюцией одной схемы уже не обойтись.

Правила выше закрывают подавляющее большинство изменений, но есть класс, который совместимым сделать нельзя: смена типа поля, изменение смысла существующего поля, изменение семантики процедуры (метод был синхронным — стал асинхронным), удаление метода. Для них честный инструмент — новая пакетная версия: notes.v2 со своей схемой, своим генерируемым кодом и своим хендлером. Версии схем в этом жанре живут параллельно, и это не позор, а дизайн: пакет — единица совместимости, вы объявляете, что v2 не обязана быть совместимой с v1 внутри пакета, а между пакетами совместимость не требуется вовсе. Что важно решить честно. Первое: v2 — копия с эволюцией, а не «схема мечты»: неубиваемые номера полей, те же уроки резервов, свой список депрекаций с первого дня. Второе: обмен сообщениями между версиями — явный слой конвертации в коде сервера; хендлер v2 не должен импортировать сообщения v1 напрямую, мост из схемы в схему пишется руками и покрывается тестами из шестнадцатого урока. Третье: не плодите версии — v3 возможна только когда v1 похоронена; каждая живая версия — это два SDK, две документации, два контура тестов. В gRPC-мире запрос grpc версия api решается точно так же — новый пакет в пути процедуры: смена пакета меняет путь вызова целиком, и маршрутизация разделяет версии без единой настройки.

Правила работают, когда их проверяет машина на каждом коммите — контур вы собирали в десятом и двенадцатом уроках, здесь он соединяется в цикл. Первый рубеж — buf breaking в CI: сравнение локальной схемы с опубликованной (buf.build/acme/notes из BSR или коммитом git) ловит смену номера, снятый резерв, изменение типа, удаление метода — каждое нарушение до того, как схема уехала в релиз; красный пайплайн означает «это изменение требует новой версии, а не правки текущей». Второй рубеж — публикация: buf push с меткой; релизные метки v1.3.0, v2.0.0 из двенадцатого урока — точки, против которых будут сравниваться следующие изменения, и координаты, по которым клиенты закрепляют зависимость. Третий рубеж — депрекация как процесс, а не метка: deprecated = true в схеме — начало отсчёта, дальше — письмо владельцам, срок в доках и наблюдение. Наблюдение — это мост к семнадцатому уроку: метки procedure в счётчике calls показывают живой трафик по каждому пути, и решение «v1 пуста, можно выключать» принимается по данным, а не по настроению: доля v1-трафика падает неделями, последние клиенты упираются — их владельцы известны по списку рассылки. Четвёртый рубеж — выключение: когда трафик нулевой на протяжении согласованного окна, v1-хендлер снимается с mux, схема v1 получает пометку deprecated в репозитории, а попытки вызвать несуществующий путь честно вернут unimplemented из прошлого блока. Полный цикл занимает месяцы — и это нормально: версии схем — медленная дисциплина.

Схема отныне эволюционирует по правилам: расширение со свежими номерами, резервы на выбывших, депрекация с данными, пакетные версии для несовместимого — и всё под машиной buf breaking и метриками трафика версий. Следующий урок — интеграция с фреймворками: хендлер Connect — обычный http.Handler, и мы встанем в чужие mux, цепочки middleware chi и Echo, разберём h2c и graceful shutdown: девятнадцатый. Потом — миграция с gRPC на Connect: двадцатый урок соберёт весь материал курса в пошаговый план переезда. Для повторения: buf breaking и правила линта — в десятом уроке, метки и публикация BSR — в двенадцатом, коды и HTTP-маппинг, включая unimplemented, — в шестом, генерация кода из схем — в одиннадцатом. Программа всех двадцати пяти уроков — на странице курса.