buf

Буф

Интерфейс командной строки buf — лучший инструмент для работы с буферами протоколов. Он обеспечивает:

• Линтер, который обеспечивает хороший выбор дизайна и структуры API.
• Детектор критических изменений, обеспечивающий совместимость на уровне исходного кода или проводной версии.
• Генератор, который вызывает ваши плагины на основе настраиваемых шаблонов.
• Программа форматирования, которая форматирует ваши файлы Protobuf в соответствии с отраслевыми стандартами.
• Интеграция с реестром Buf Schema, включая полное управление зависимостями.

Установка

Домашнее пиво

Вы можете установить buf с помощью Homebrew (macOS или Linux):

brew install bufbuild/buf/buf

Это устанавливает:

• Бинарные файлы buf , protoc-gen-buf-breaking и protoc-gen-buf-lint
• Скрипты завершения оболочки для Bash, Fish, Powershell и zsh

Другие методы

Информацию о других методах установки см. в нашей официальной документации, в которой описаны:

• Установка buf через npm
• Установка buf в Windows
• Использование buf в качестве образа Docker
• Установка в виде двоичного файла, из архива и из исходного кода через выпуски GitHub.
• Проверка выпусков с использованием открытого ключа minisign

Использование

Интерфейс справки Buf предоставляет сводку по командам и флагам:

buf --help

Для получения более подробной информации об использовании обратитесь к документации Buf, особенно к этим руководствам:

• buf breaking
• buf build
• buf generate
• buf lint
• buf format
• buf registry (для использования BSR)

Политика внесения изменений в CLI

Мы никогда не будем вносить критические изменения в данную основную версию CLI. После того, как buf достиг версии 1.0, вы не можете ожидать серьезных изменений до версии 2.0. Но поскольку у нас нет планов когда-либо выпускать версию 2.0, мы, скорее всего, никогда не сломаем интерфейс командной строки buf .

Эта политика критических изменений не применяется к командам, находящимся за buf beta , и вам следует ожидать критических изменений в таких командах, как buf beta registry . Однако политика вступает в силу, когда эти команды или флаги выходят из бета-версии.

Наши цели для Protobuf

Цель Буфа — заменить текущую парадигму разработки API, основанную на REST/JSON, парадигмой, управляемой схемой . Определение API с использованием IDL дает множество преимуществ по сравнению с REST/JSON, а Protobuf на сегодняшний день является наиболее стабильным и широко распространенным IDL в отрасли. Мы решили опираться на этот широко пользующийся доверием фундамент, а не создавать новый IDL с нуля.

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

Хотя мы намерены постепенно улучшать интерфейс командной строки buf и BSR, мы уверены, что базовая основа для такой экосистемы уже заложена.

Реестр схемы Buf

Реестр схемы Buf (BSR) — это SaaS-платформа для управления вашими API-интерфейсами Protobuf. Он обеспечивает централизованный реестр и единый источник достоверной информации для всех ваших ресурсов Protobuf, включая не только файлы .proto , но и удаленные плагины. Несмотря на то, что BSR предоставляет интуитивно понятный пользовательский интерфейс браузера, buf позволяет выполнять большинство задач, связанных с BSR, из командной строки, например загружать источники Protobuf в реестр и управлять пользователями и репозиториями.

BSR не обязательно использовать buf . Мы сделали основные функции интерфейса командной строки buf доступными для всех пользователей Protobuf.

Более продвинутые функции CLI

Хотя основные функции buf должны охватывать большинство случаев использования, мы включили несколько более продвинутых функций для крайних случаев:

• Автоматическое обнаружение файлов . Buf просматривает ваше файловое дерево и создает файлы .proto в соответствии с предоставленной вами конфигурацией сборки, что означает, что вам больше не нужно вручную указывать --proto_paths . Однако вы все равно можете указать файлы .proto вручную с помощью флагов CLI в тех случаях, когда обнаружение файлов необходимо отключить.
• Детализированная конфигурация правил для анализа и внесения изменений. Хотя у нас есть рекомендуемые значения по умолчанию, вы всегда можете выбрать именно тот набор правил, который требуется для вашего варианта использования: доступны 40 правил проверки и 53 правила критического изменения.
• Настраиваемые форматы ошибок для вывода CLI. buf выводит информацию в file:line:column:message по умолчанию для каждой ошибки lint и критических изменений, с которыми он сталкивается, но вы также можете выбрать вывод JSON, MSVS, JUnit и Github Actions.
• Интеграция редактора, основанная на детальном выводе ошибок buf . В настоящее время мы предоставляем интеграцию проверки как для Vim, так и для Visual Studio Code, а также для IDE JetBrains, таких как IntelliJ и GoLand, но мы планируем поддерживать другие редакторы, такие как Emacs, в будущем.
• Таргетинг на универсальный ввод . Buf позволяет вам выполнять такие действия, как анализ и обнаружение взломанных изменений, не только с локальными файлами .proto , но также с широким спектром других входных данных, таких как архивы и ZIP-файлы, удаленные репозитории Git и предварительно созданные файлы изображений.
• Скорость . Внутренний компилятор Protobuf Buf компилирует исходные коды Protobuf, используя все доступные ядра без ущерба для детерминированного вывода, что значительно быстрее, чем protoc . Это обеспечивает практически мгновенную обратную связь, что имеет особое значение для таких функций, как интеграция редактора.

Следующие шаги

После установки buf мы рекомендуем пройти руководство по CLI, в котором представлен широкий, но практический обзор основных функций CLI. Экскурсия занимает около 10 минут.

После завершения тура ознакомьтесь с оставшейся документацией по интересующим вас областям.

Сообщество

Чтобы получить помощь и обсудить Protobuf, лучшие практики и многое другое, присоединяйтесь к нам в Slack.

Для получения обновлений Buf CLI следуйте этому репозиторию на GitHub.

Если у вас есть запросы на добавление новых функций, обнаружение ошибок или технические вопросы, пишите нам по адресу [email protected]. По общим вопросам или по включению в наши предстоящие бета-версии функций напишите нам по адресу [email protected].