buf

緩衝液

buf CLI 是使用 Protocol Buffer 的最佳工具。它提供：

• 強制執行良好 API 設計選擇和結構的 linter。
• 一種重大變更偵測器，可在原始碼或線路層級強制執行相容性。
• 一個根據可配置模板調用插件的生成器。
• 一個格式化程序，可根據業界標準格式化 Protobuf 檔案。
• 與 Buf 架構註冊表集成，包括完整的依賴關係管理。

安裝

自製

您可以使用 Homebrew（macOS 或 Linux）安裝buf ：

brew install bufbuild/buf/buf

這將安裝：

• buf 、 protoc-gen-buf-breaking和protoc-gen-buf-lint二進位文件
• Bash、Fish、Powershell 和 zsh 的 Shell 完成腳本

其他方法

其他安裝方法，請參閱我們的官方文檔，其中包括：

• 透過 npm 安裝buf
• 在 Windows 上安裝buf
• 使用buf作為 Docker 映像
• 從 tarball 以及透過 GitHub Releases 從原始碼安裝為二進位文件
• 使用 minisign 公鑰驗證版本

用法

Buf 的幫助介面提供指令和標誌的摘要：

buf --help

有關更全面的使用信息，請參閱 Buf 的文檔，尤其是這些指南：

• buf breaking
• buf build
• buf generate
• buf lint
• buf format
• buf registry （用於使用 BSR）

CLI 重大變更政策

我們永遠不會在給定的 CLI 主要版本中進行重大更改。 buf達到 v1.0 後，您可以預期在 v2.0 之前不會發生重大變更。但由於我們沒有計劃發布 v2.0，因此我們可能永遠不會破壞buf CLI。

此重大更改策略不適用於buf beta門後面的命令，您應該預期對buf beta registry等命令進行重大更改。然而，當這些命令或標誌升級到測試版之外時，該策略就會生效。

我們對 Protobuf 的目標

Buf 的目標是以模式驅動的範例取代目前以 REST/JSON 為中心的 API 開發範例。與 REST/JSON 相比，使用 IDL 定義 API 具有許多優勢，而 Protobuf 是迄今為止業界最穩定且廣泛採用的 IDL。我們選擇建立在這個廣泛信任的基礎上，而不是從頭開始建立新的 IDL。

儘管 Protobuf 具有技術優勢，但實際使用它長期以來一直比它需要的更具挑戰性。 Buf CLI 和 BSR 是我們努力永久改變這種狀況並使 Protobuf 可靠且易於服務所有者和客戶使用的基石，換句話說，創建一個現代的 Protobuf 生態系統。

雖然我們打算逐步改進buf CLI 和 BSR，但我們相信這樣一個生態系統的基本基礎已經就位。

Buf 模式註冊表

Buf 架構註冊表 (BSR) 是一個用於管理 Protobuf API 的 SaaS 平台。它為您的所有 Protobuf 資產提供集中式註冊表和單一事實來源，不僅包括您的.proto文件，還包括遠端插件。儘管 BSR 提供​​了直覺的瀏覽器 UI， buf可讓您從命令列執行大多數與 BSR 相關的任務，例如將 Protobuf 來源推送到註冊表以及管理使用者和儲存庫。

BSR 不需要使用buf 。我們已向所有Protobuf 用戶提供buf CLI 的核心功能。

更進階的 CLI 功能

雖然buf的核心功能應該涵蓋大多數用例，但我們添加了一些更高級的功能來涵蓋邊緣情況：

• 自動文件發現。 Buf 遍歷您的文件樹並根據您提供的建置配置建置.proto文件，這表示您不再需要手動指定--proto_paths 。但是，在需要停用檔案發現的情況下，您仍然可以透過 CLI 標誌手動指定.proto檔案。
• 用於檢查和破壞性變更的細粒度規則配置。雖然我們確實有建議的預設值，但您始終可以選擇您的用例所需的確切規則集，其中有 40 個 lint 規則和 53 個重大更改規則可用。
• CLI 輸出的可設定錯誤格式。 buf預設以file:line:column:message形式輸出每個 lint 錯誤和遇到的重大變更的訊息，但您也可以選擇 JSON、MSVS、JUnit 和 Github Actions 輸出。
• 由buf的精細錯誤輸出驅動的編輯器整合。目前，我們為 Vim 和 Visual Studio Code 以及 IntelliJ 和 GoLand 等 JetBrains IDE 提供 linting 集成，但我們計劃將來支援 Emacs 等其他編輯器。
• 通用輸入定位。 Buf 讓您不僅可以針對本機.proto文件，還可以針對各種其他輸入（例如 tarball 和 ZIP 檔案、遠端 Git 儲存庫以及預先建置的映像檔）執行 linting 和重大變更偵測等操作。
• 速度。 Buf 的內部 Protobuf 編譯器使用所有可用核心編譯 Protobuf 原始碼，而不影響確定性輸出，這比protoc快得多。這允許近乎即時的回饋，這對於編輯器整合等功能特別重要。

後續步驟

安裝buf後，我們建議您完成 CLI 教程，該教程提供了 CLI 核心功能的廣泛但實用的概述。遊覽大約需要 10 分鐘即可完成。

完成導覽後，請查看您感興趣的特定領域的其餘文件。

社群

如需有關 Protobuf、最佳實踐等的協助和討論，請加入我們的 Slack。

有關 Buf CLI 的更新，請關注 GitHub 上的此儲存庫。

對於功能請求、錯誤或技術問題，請發送電子郵件至 [email protected]。對於一般查詢或包含在我們即將推出的功能測試版中，請發送電子郵件至 [email protected]。