buf

Buff

Die buf CLI ist das beste Tool für die Arbeit mit Protokollpuffern. Es bietet:

• Ein Linter, der gute Entscheidungen und Strukturen für das API-Design erzwingt.
• Ein Breaking-Change-Detektor, der die Kompatibilität auf Quellcode- oder Wire-Ebene erzwingt.
• Ein Generator, der Ihre Plugins basierend auf konfigurierbaren Vorlagen aufruft.
• Ein Formatierer, der Ihre Protobuf-Dateien gemäß Industriestandards formatiert.
• Integration mit der Buf-Schema-Registrierung, einschließlich vollständiger Abhängigkeitsverwaltung.

Installation

Homebrew

Sie können buf mit Homebrew (macOS oder Linux) installieren:

brew install bufbuild/buf/buf

Dies installiert:

• Die Binärdateien buf , protoc-gen-buf-breaking und protoc-gen-buf-lint
• Shell-Vervollständigungsskripte für Bash, Fish, Powershell und zsh

Andere Methoden

Weitere Installationsmethoden finden Sie in unserer offiziellen Dokumentation, die Folgendes behandelt:

• buf über npm installieren
• buf unter Windows installieren
• Verwendung von buf als Docker-Image
• Installation als Binärdatei, von einem Tarball und von der Quelle über GitHub Releases
• Verifizierung von Veröffentlichungen mithilfe eines öffentlichen Minisign-Schlüssels

Verwendung

Die Hilfeoberfläche von Buf bietet Zusammenfassungen für Befehle und Flags:

buf --help

Ausführlichere Informationen zur Verwendung finden Sie in der Dokumentation von Buf, insbesondere in diesen Leitfäden:

• buf breaking
• buf build
• buf generate
• buf lint
• buf format
• buf registry (für die Verwendung des BSR)

CLI-Break-Change-Richtlinie

Wir werden niemals bahnbrechende Änderungen innerhalb einer bestimmten Hauptversion der CLI vornehmen. Nachdem buf v1.0 erreicht hat, können Sie bis v2.0 mit keinen wichtigen Änderungen rechnen. Da wir jedoch keine Pläne haben, jemals eine Version 2.0 zu veröffentlichen, werden wir die buf CLI wahrscheinlich nie kaputt machen.

Diese Breaking-Change-Richtlinie gilt nicht für Befehle hinter dem buf beta Gate, und Sie sollten mit Breaking-Changes an Befehlen wie buf beta registry rechnen. Die Richtlinie tritt jedoch in Kraft, wenn diese Befehle oder Flags aus der Betaversion herausgehoben werden.

Unsere Ziele für Protobuf

Bufs Ziel ist es, das aktuelle Paradigma der API-Entwicklung, das sich auf REST/JSON konzentriert, durch ein schemagesteuertes Paradigma zu ersetzen. Die Definition von APIs mithilfe einer IDL bietet zahlreiche Vorteile gegenüber REST/JSON, und Protobuf ist bei weitem die stabilste und am weitesten verbreitete IDL in der Branche. Wir haben uns dafür entschieden, auf dieser weithin bewährten Grundlage aufzubauen, anstatt eine neue IDL von Grund auf zu erstellen.

Doch trotz seiner technischen Vorzüge war die tatsächliche Nutzung von Protobuf schon lange schwieriger als nötig. Die Buf-CLI und das BSR sind die Eckpfeiler unserer Bemühungen, dies endgültig zu ändern und Protobuf sowohl für Serviceeigentümer als auch für Kunden zuverlässig und benutzerfreundlich zu machen – mit anderen Worten, um ein modernes Protobuf-Ökosystem zu schaffen.

Obwohl wir beabsichtigen, die buf -CLI und das BSR schrittweise zu verbessern, sind wir zuversichtlich, dass die grundlegenden Grundlagen für ein solches Ökosystem bereits vorhanden sind.

Die Buf-Schema-Registrierung

Die Buf Schema Registry (BSR) ist eine SaaS-Plattform zur Verwaltung Ihrer Protobuf-APIs. Es bietet eine zentralisierte Registrierung und eine einzige Quelle der Wahrheit für alle Ihre Protobuf-Assets, einschließlich nicht nur Ihrer .proto Dateien, sondern auch Remote-Plugins. Obwohl der BSR eine intuitive Browser-Benutzeroberfläche bietet, können Sie buf die meisten BSR-bezogenen Aufgaben über die Befehlszeile ausführen, z. B. Protobuf-Quellen in die Registrierung übertragen und Benutzer und Repositorys verwalten.

Der BSR ist für die Verwendung buf nicht erforderlich. Wir haben die Kernfunktionen der buf CLI für alle Protobuf-Benutzer verfügbar gemacht.

Erweiterte CLI-Funktionen

Während die Kernfunktionen von buf die meisten Anwendungsfälle abdecken sollten, haben wir einige erweiterte Funktionen hinzugefügt, um Randfälle abzudecken:

• Automatische Dateierkennung . Buf durchsucht Ihren Dateibaum und erstellt Ihre .proto Dateien gemäß Ihrer bereitgestellten Build-Konfiguration, was bedeutet, dass Sie --proto_paths nicht mehr manuell angeben müssen. Sie können .proto Dateien jedoch weiterhin manuell über CLI-Flags angeben, wenn die Dateierkennung deaktiviert werden muss.
• Feinkörnige Regelkonfiguration für Linting und Breaking Changes. Obwohl wir empfohlene Standardwerte haben, können Sie jederzeit genau den Regelsatz auswählen, den Ihr Anwendungsfall erfordert. Es sind 40 Lint-Regeln und 53 Breaking-Change-Regeln verfügbar.
• Konfigurierbare Fehlerformate für die CLI-Ausgabe. buf gibt standardmäßig Informationen im Format file:line:column:message für jeden Lint-Fehler und jede auftretende Breaking Change aus, Sie können jedoch auch die Ausgabe von JSON, MSVS, JUnit und Github Actions auswählen.
• Editor-Integration, gesteuert durch die granulare Fehlerausgabe von buf . Wir bieten derzeit Linting-Integrationen sowohl für Vim und Visual Studio Code als auch für JetBrains-IDEs wie IntelliJ und GoLand an, planen aber, in Zukunft auch andere Editoren wie Emacs zu unterstützen.
• Universelles Input-Targeting . Buf ermöglicht Ihnen die Durchführung von Aktionen wie Linting und Breaking Change Detection nicht nur für lokale .proto Dateien, sondern auch für eine Vielzahl anderer Eingaben, wie z. B. Tarballs und ZIP-Dateien, Remote-Git-Repositorys und vorgefertigte Bilddateien.
• Geschwindigkeit . Der interne Protobuf-Compiler von Buf kompiliert Ihre Protobuf-Quellen mit allen verfügbaren Kernen, ohne die deterministische Ausgabe zu beeinträchtigen, was erheblich schneller als protoc ist. Dies ermöglicht ein nahezu sofortiges Feedback, was besonders für Funktionen wie die Editor-Integration wichtig ist.

Nächste Schritte

Sobald Sie buf installiert haben, empfehlen wir Ihnen, das CLI-Tutorial zu absolvieren, das einen umfassenden, aber praktischen Überblick über die Kernfunktionen der CLI bietet. Die Tour dauert etwa 10 Minuten.

Schauen Sie sich nach Abschluss der Tour die restlichen Dokumente für Ihre spezifischen Interessengebiete an.

Gemeinschaft

Wenn Sie Hilfe und Diskussionen rund um Protobuf, Best Practices und mehr benötigen, besuchen Sie uns auf Slack.

Für Aktualisierungen der Buf-CLI folgen Sie diesem Repo auf GitHub.

Für Funktionswünsche, Fehler oder technische Fragen senden Sie uns eine E-Mail an [email protected]. Für allgemeine Anfragen oder die Aufnahme in unsere bevorstehenden Feature-Betas senden Sie uns eine E-Mail an [email protected].