buf CLI: линтинг и breaking changes

Конфигурация buf-а живёт в buf.yaml — файле, который мы завели ещё в втором уроке, объявив в нём модуль с path: proto. Актуальная версия конфига — v2: секция modules перечисляет корни модулей, а секции lint и breaking задают, какие категории правил применять. Категории — это уровни строгости: MINIMAL — только то, что влияет на совместимость и генерацию; BASIC добавляет правила стиля и структуры; STANDARD — рекомендуемый уровень, включающий BASIC плюс правила API-дизайна вроде уникальности имён rpc; COMMENTS требует комментариев на публичные элементы; UNARY_RPC — спорное правило, отговаривающее от unary rpc без reason. В конфиге пишут use: [STANDARD] — и при необходимости выключают или добавляют отдельные правила: кроме except-списка, есть enum-правила и опции по умолчанию. Заметьте, что buf.yaml v2 вытеснил старую пару buf.yaml + buf.work.yaml из v1: если вы встретите в документации проекты с workspace-файлом, знайте, что это legacy-раскладка, и migrated конфиг выглядит проще. Для нашего курса достаточно одного модуля proto — и ровно одного файла buf.yaml в корне репозитория.

Команда buf lint без аргументов проходит по всем файлам модуля и печатает находки в формате path:line:column: message — ровно как компилятор, только про стиль. Правил несколько десятков, но они запоминаются семьями. Имена: PACKAGE_VERSION_SUFFIX требует версии в конце пакета — наш notes.v1 из первого урока проходил бы, а голый package notes — нет; PACKAGE_DIRECTORY_MATCH требует, чтобы каталог повторял пакет — proto/notes/v1 для notes.v1, и именно это правило мы впервые увидели в третьем уроке при добавлении eliza; FIELD_LOWER_SNAKE_CASE следит за полями, MESSAGE_PASCAL_CASE и SERVICE_PASCAL_CASE — за типами и сервисами. Дизайн API: SERVICE_SUFFIX требует Service на конце имени сервиса, ENUM_ZERO_VALUE_SUFFIX — суффикс _UNSPECIFIED у нулевого значения enum, ENUM_VALUE_PREFIX — префикс с именем enum, RPC_REQUEST_RESPONSE_UNIQUE запрещает переиспользовать один message в разных rpc — потому что схема с общим запросом не может эволюционировать независимо. COMMENTS-категория добавит требований к документации, если вы её включите. buf lint — отдельная команда, а не шаг генерации: она стартует быстрее компиляции и хорошо ставится в pre-commit; большинство команд гоняет buf lint в CI на каждый PR.

Линт охраняет стиль, но главная угроза контракту — не стиль, а изменение смысла. buf breaking сравнивает текущую схему с эталонной версией и рапортует о несовместимостях по категориям строгости. FILE — самая строгая, уровень по умолчанию: ловит переименования файлов, пакетов, типов и полей — даже те, что совместимы на проводе, но ломают компиляцию клиентов с чужими импортами. WIRE — совместимость формата на проводе: изменение номера поля, его типа, смена скалярного типа. PACKAGE — правила вокруг пакета: версию нельзя удалить, пакет не должен терять совместимость со своими прошлыми версиями. TYPE — консистентность типов: enum не должен терять значения (клиенты со старым кодом не поймут новый wire-статус), поле не должно менять имя. WIRE_JSON добавляет контроль JSON-представления: переименование поля меняет JSON-имя, и фронтенд, сериализующий по имени, сломается. Эталон задаётся флагом --against, и источник — не обязательно файл: это может быть каталог, git-ветка в нотации .git#branch=main или модуль в BSR — реестре схем Buf, о котором пойдёт речь в двенадцатом уроке. Команда buf breaking --against .git#branch=main — это и есть минимальная страховка совместимости, которую стоит поставить в CI сегодня.

Две команды имеют смысл только тогда, когда они запускаются автоматически — вручную их забудут на третий день. Разумный расклад из трёх точек. Первая — pre-commit: buf lint на изменённых файлах, быстро и локально, стиль не доезжает до ревью. Вторая — CI на pull request: buf lint по всему модулю плюс buf breaking --against .git#branch=main; теперь несовместимое изменение не пройдёт ревью молча — оно упадёт с конкретным path:line:col и именем правила. Третья — релиз: при публикации модуля и генерации артефактов buf breaking против последней опубликованной версии, потому что ветка main может уйти вперёд с тех пор, как схема выехала к клиентам. Отдельно стоит договориться о политике: что делать, когда breaking нужен по-настоящему — правильный путь в proto-мире не обходить проверку, а выпускать новую версию пакета (notes.v2 рядом с notes.v1) или расширять сообщение совместимым способом — новое поле вместо смены типа. Категории use в buf.yaml и есть ваш договор с командой: STRICT-набор запрещает почти всё, WIRE — разрешает косметику, если она честно не трогает провод. Запишите политику в сам buf.yaml и в CONTRIBUTING — конфигурация, которую никто не понимает, превращается в шум, который в конце концов просто выключают.

Есть у buf lint и вторая, менее очевидная роль: правила — это выжимка лучших практик protobuf-сообщества, и чтение их списка само по себе учит дизайну схем. RPC_REQUEST_RESPONSE_UNIQUE — потому что общий message в двух rpc превращает любое расширение одного вызова в ломку другого; ENUM_ZERO_VALUE_SUFFIX — потому что нулевое значение enum обязано означать «неизвестно», и только его; ENUM_VALUE_PREFIX — потому что C++-скоупы и мультиязычные генераторы превращают безымянные значения в коллизии; SERVICE_SUFFIX и PASCAL-правила — потому что генераторы разных языков выводят из них имена своих типов. Когда линтер ругается, полезно не просто молча исправить, а понять, какую аварию правило предотвращает — это быстрее, чем наступать на грабли самому. И у этого есть организационное следствие: новый разработчик, подключившийся к проекту с включённым STANDARD, получает весь накопленный опыт в виде машины, которая отклоняет плохие схемы до ревью — дешевле любой Wiki. Если в проекте есть уникальные ограничения — например, обязательный префикс пакетов компании или запрет сторонних импортов, — buf позволяет объявлять собственные правила, но это уже тема продвинутых конфигов, а базового STANDARD для 90 процентов проектов хватает с головой.

Контракт под охраной: buf lint держит стиль и структуру схем, buf breaking не пускает несовместимые правки мимо ревью, а CI превратил дисциплину из надежды в механизм. Осталось автоматизировать соседний труд — кодогенерацию, и в одиннадцатом уроке мы дожмём buf generate: buf.gen.yaml во всех подробностях, локальные и удалённые плагины, воспроизводимость генерации без установки тулчейна. После этого — реестр схем BSR в двенадцатом, где buf breaking уже умеет сравнивать с опубликованной версией модуля. Для глубины полезно держать под рукой, как те же вопросы эволюции решаются руками в gRPC-мире: урок про оптимизацию и совместимость proto из курса gRPC — buf breaking автоматизирует ровно те правила, которые там выписаны. Программа всех двадцати пяти уроков — на странице курса.