buf generate: кодогенерация

buf.gen.yaml лежит в корне проекта рядом с buf.yaml — это отдельный файл с отдельной ролью: buf.yaml описывает модуль схем, buf.gen.yaml — рецепт генерации. Актуальная версия — v2, и секция plugins — это список шагов: каждый элемент описывает один плагин. У плагина три главных поля. local или remote — откуда взять программу-плагин: локальный бинарник на вашей машине или сервис на buf.build (об этом ниже). out — каталог, куда пишутся результаты. opt — опции, которые передаются плагину как аргументы командной строки. Порядок плагинов в списке не важен — buf запускает их независимо, каждый со своим образом дескрипторов на входе. Заметьте, чего в конфиге нет: списка файлов. Buf сам находит все .proto внутри корней модуля из buf.yaml — вы уже видели это свойство в третьем уроке, когда eliza.proto подхватился без единой правки конфига. И это принципиально отличается от старого protoc-пути, где файлы перечисляли руками и забывали добавить новый — классическая грабелька, из-за которой половина кода молча не генерировалась.

Локальный плагин — это обычный исполняемый файл, который buf запускает как дочерний процесс: ищет его в PATH и передаёт образ дескрипторов на stdin. Отсюда все вопросы установки. Go-плагины ставятся go install-ом и попадают в каталог бинов Go (GOBIN или GOPATH/bin — он должен быть в PATH): protoc-gen-go из модуля google.golang.org/protobuf и protoc-gen-connect-go из connectrpc.com/connect. TypeScript-плагин protoc-gen-es ставится npm-ом в devDependencies проекта, и buf умеет находить его в node_modules/.bin — специально заходить в этот каталог в PATH не нужно. Если buf пишет, что не нашёл исполняемый файл плагина — это всегда история про PATH, а не про конфиг: либо плагин не установлен, либо каталог с ним не виден shell-у. Второй типовой грабль — рассинхрон версий: плагин генератора и рантайм-библиотека развиваются парой, и старый protoc-gen-go при свежем runtime может выдать код, который не соберётся. Держите версии плагинов зафиксированными в go.mod и package.json — вы уже видели в девятом уроке, как рассинхрон рантайма и генератора рождает самые невнятные ошибки.

Второй способ подключить плагин — remote: buf отправит образ дескрипторов на серверы buf.build, там прогонит нужный плагин и вернёт готовые файлы. Имена удалённых плагинов — это ссылки на их страницы в реестре: remote: buf.build/protocolbuffers/go для Go-типов и remote: buf.build/bufbuild/connect-go для Connect-слоя — те же самые плагины, что вы ставили локально, только в облаке. Выгоды три. Ноль установки: новый разработчик и CI-агент не ставят тулчейн вообще — конфиг самодостаточен. Воспроизводимость: версию плагина можно закрепить прямо в конфиге суффиксом после двоеточия, и вся команда генерирует код одной и той же версией — ничего не «плавает» от машины к машине. Скорость CI: не нужен шаг go install перед генерацией. Но есть и честная цена: удалённый плагин получает вашу схему целиком — образ дескрипторов уезжает на сервер buf.build. Для публичных схем это неважно, для приватных коммерческих контрактов — уже решение о безопасности, и его надо принимать осознанно: такие проекты держат локальные плагины. Второй нюанс — сеть: каждый прогон buf generate ходит по сети, на большом модуле это медленнее локального прогона и требует доступа к buf.build из CI.

Опция go_package в схеме из первого урока была вынужденной: protoc-gen-go без неё не знает, в какой Go-пакет положить код и под каким путём его импортировать. Проблема в том, что go_package — это языковая опция внутри языко-независимой схемы: для каждого нового целевого языка придётся добавлять свои опции, и proto-файлы обрастают мусором. Managed mode решает это централизованно: секция managed в buf.gen.yaml со значением enabled: true включает режим, в котором buf сам проставляет опции плагинам. Самая ходовая — override go_package_prefix: единый префикс импорта для всех схем модуля. В многоязычном проекте managed-секция растёт по одному override на язык, а схемы остаются чистыми: только контракты, ничего про Go, TypeScript или Kotlin. Это особенно ценно, когда одну схему потребляют несколько команд с разными соглашениями об импортах — каждому свой buf.gen.yaml с managed-настройками поверх общих протофайлов. Для нашего курса managed не обязателен: go_package уже зашит в схемы и работает с первого урока, но знать о режиме нужно — на собеседованиях и в чужих репозиториях вы его встретите постоянно.

Три приёма, которые делают генерацию гибкой. Первый — отдельные шаблоны: файл buf.gen.yaml не обязан быть единственным, и для многоязычных проектов удобно держать buf.gen.yaml для Go и buf.gen.ts.yaml для фронтенда — плагин protoc-gen-es тогда живёт в своём рецепте, и Go-разработчики не запускают TypeScript-генерацию лишний раз. Выбор шаблона — флаг --template с путём к файлу. Второй приём вы уже видели в predict-задании: --path фильтрует вход по путям модуля. Третий — опция clean: true в buf.gen.yaml: buf удалит из каталогов out файлы, которые не были созданы текущим прогоном. Это лечит проблему осиротевших файлов: переименовали схему или удалили rpc — старый сгенерированный код без clean остаётся в gen/ и продолжает собираться, маскируя правку. И последний мост к следующему уроку: в buf.gen.yaml v2 можно описать и вход — секция inputs умеет брать модуль прямо из реестра, например module: buf.build/acme/notes, и тогда вы генерируете код из опубликованных чужих схем, не скачивая их в репозиторий. Это вторая половина истории про BSR — там и продолжим.

Сгенерированный код — артефакт, и вокруг него два лагеря, оба с аргументами. Первый: коммитить gen/ в репозиторий — так делает наш курс, вы видели gen/ в дереве проекта со второго урока. Плюсы: потребитель кода не должен уметь собирать тулчейн — клиент вашего API подключают через go get, и сгенерированные пакеты приходят с обычными исходниками; локальная сборка не требует buf; diff-ы видны в ревью. Второй лагерь: не коммитить, генерировать в CI — каталог чист, историю не пылит, но каждый потребитель обязан поставить buf и плагины. Третий путь, примиряющий оба, — проверка свежести в CI: buf generate прогоняется на чистом чекауте, затем git diff --exit-code — если сгенерированный код отличается от закоммиченного, PR падает. Это ловит две классические аварии: разработчик забыл перегенерировать после правки схемы (сервер едет с устаревшим кодом) и подредактировал gen/ руками (правка затрётся следующим прогоном). Работает при одном условии: генерация должна быть идемпотентной — одинаковые входы и версии плагинов дают одинаковый вывод. Поэтому версии плагинов фиксируются в go.mod, package.json или прямо в конфиге для remote — и buf generate превращается в детерминированную функцию от схем.

Тулчейн закрыт: рецепты генерации описаны декларативно, плагины — локальные с зафиксированными версиями или удалённые с нулём установки, managed mode держит схемы чистыми от языковых опций, а CI проверяет, что gen/ соответствует схемам. Осталась последняя деталь конвейера — откуда брать чужие схемы. В двенадцатом уроке встречаем Buf Schema Registry: модули buf.build, публикация buf push-ом, зависимости с buf.lock, готовые SDK для Go и TypeScript — и секция inputs в buf.gen.yaml, которая умеет генерировать прямо из опубликованного модуля. Ссылки для глубины: дисциплина охраны схем из урока про buf lint и breaking ложится поверх генерации как предохранитель, а эволюция контрактов руками — в уроке про совместимость proto курса gRPC. Программа всех двадцати пяти уроков — на странице курса.