開發(fā)工具代碼生成API設(shè)計【免費下載鏈接】bufThe best way of working with Protocol Buffers.項目地址https://gitcode.com/GitHub_Trending/bu/buf點擊查看免費下載本文以倉庫根目錄的 CHANGELOG.md 為骨架系統(tǒng)梳理 buf 從 2019 年 v0.1.0 到 v1.73.0 的完整演進脈絡(luò)。文章覆蓋核心命令build / lint / breaking / generate / format / curl / lsp、配置體系v1beta1 → v1 → v2、格式與輸入輸出能力binpb / txtpb / yaml / json、Protobuf Editions 支持、managed mode、lint/breaking 規(guī)則體系、BSR 注冊表命令與多平臺發(fā)布等主題并結(jié)合倉庫源碼如 curl 命令實現(xiàn)、format 命令實現(xiàn)、buf.yaml給出源碼級佐證幫助讀者快速掌握 buf 的能力邊界、遷移路徑與版本演進邏輯。一、為什么 CHANGELOG 值得讀版本即路線圖buf 是面向 Protocol Buffers 的現(xiàn)代化工具鏈定位為處理 Protocol Buffers 的最佳方式項目描述原文 The best way of working with Protocol Buffers。其 CHANGELOG 記錄了從 2019 年 10 月 v0.1.0 初始 beta 發(fā)布到 v1.73.02026-09-11的全部變更包含大量可直接落地的命令、配置與遷移細節(jié)新增能力如buf curlv1.12.0、buf formatv1.2.0、buf exportv0.48.0、LSPv1.43.0 beta / v1.59.0 stable等配置演進配置文件版本從v1beta1走向v1、v2buf.yaml/buf.gen.yaml/buf.lock職責逐步清晰兼容承諾v1.0.0-rc1 明確指出希望 buf 在 v1 上穩(wěn)定十年所有命令/flag 的棄用與遷移路徑均提前警告詳見下文第九節(jié)。從倉庫的 cmd/buf/internal/command 目錄可以看到當前命令面包括alpha/、beta/、breaking/、config/、convert/、curl/、dep/、export/、format/、generate/、lint/、lsfiles/、lsp/、mod/、plugin/、policy/、push/、registry/、source/、stats/等 20 個命令包與 CHANGELOG 中逐版本新增的命令一一對應(yīng)。二、核心工作流命令的建立與穩(wěn)定2019–20222.1 從 beta 到 v1.0.0命令體系的兩次大清洗buf 的命令演進經(jīng)歷了兩次大規(guī)模重命名第一次v0.29.02020-10-30以讓 CLI 更自然為目標將buf image build遷移為buf build并支持 image 作為輸入buf check lint→buf lint、buf check breaking→buf breakingv0.34.0 完成遷移同時protoc-gen-buf-check-*更名protoc-gen-buf-*--fileflag 更名--path并擴展為可接受目錄v0.31.0。CHANGELOG 給出的遷移示例# 編譯當前目錄文件 buf build # 等價的無參調(diào)用 buf build . # 構(gòu)建 https 上的 git 倉庫 buf build https://github.com/foo/bar.git # 檢查當前目錄相對 master 分支是否有破壞性變更 buf check breaking --against .git#branchmaster第二次v1.0.02022-02-17正式移除 v1 前全部棄用項包括buf login→buf registry login、buf config init→buf mod init、buf protoc被移除CHANGELOG 說明其沒有帶來超出主流 protoc 的價值只是更快并支持并行編譯、buf config migrate-v1beta1→buf beta migrate-v1beta1等。v1.0.0 同時將默認配置版本從v1beta1提升為v1并新增buf completionshell 自動補全腳本生成、buf mod open、--disable-symlinks、--include-wkt等能力。2.2 命令的持續(xù)補全v1.0.0 之后buf generate在 v1.14.0 將--include-types統(tǒng)一為--type舊 flag 保持兼容v1.32.0 起支持strategy、--clean、protoc_path數(shù)組形式首元素為路徑其余為每次調(diào)用傳給 protoc 的附加參數(shù)。buf config系列v1.32.0整合了buf config migrate、buf config ls-lint-rules、buf config ls-breaking-rules、buf config ls-modulesv1.34.0、buf config init。buf dep系列v1.32.0 穩(wěn)定承接buf mod update/prune與buf dep graph源自 v0.23.0 的buf beta graphv1.42.0 起支持--format默認dot、可選json。buf exportv0.48.0導(dǎo)出可被 protoc 免-I直接構(gòu)建的文件集支持--exclude-imports與--pathv1.56.0 新增--all以包含非 proto 源文件。buf statsv1.17.0 起buf beta statsv1.55.0 轉(zhuǎn)正輸出模塊統(tǒng)計信息。三、配置體系的演進v1beta1 → v1 → v23.1 版本與文件職責文件職責關(guān)鍵里程碑buf.yaml模塊/工作區(qū)配置lint、breaking 規(guī)則、依賴、includes/excludesv0.25.0 引入v1beta1版本概念v0.44.0 曾短暫改名buf.mod又回退v0.55.0 起強制要求version:字段v1.32.0 支持v2buf.gen.yaml代碼生成模板plugins、managed mode、cleanv1.32.0 支持v2v1.34.0 支持protoc_path數(shù)組buf.work.yaml多模塊工作區(qū)v0.45.0 從buf.work統(tǒng)一為buf.work.yamlbuf.lock依賴鎖定ModulePin、b3 digestv1.0.0-rc12 移除branch字段v1.0.0-rc9 起 digest 編碼buf.yaml中的 name/lint/breaking 配置buf.policy.yamlBSR 策略v1.65.0 起buf registry policy與 LSP 聯(lián)動倉庫自身根目錄的 buf.yaml 就是一份v2配置的活樣例version: v2 modules: - path: proto name: buf.build/bufbuild/buf lint: use: - STANDARD - UNARY_RPC disallow_comment_ignores: true breaking: use: - WIRE_JSON ignore_unstable_packages: true3.2 v2 配置的關(guān)鍵新增v1.32.0 是配置體系的分水嶺引入v2版本同時提供buf config migrate一鍵遷移includes鍵v1.39.0模塊配置可指定目錄列表proto 文件只有位于其中才屬于該模塊與excludes并用時在 include 內(nèi)且不在 exclude 內(nèi)才算模塊成員允許多個模塊配置共享同一目錄路徑。clean頂層選項v1.36.0等價于buf generate --clean生成前刪除各插件out指向的目錄/jar/zip。插件path數(shù)組化v1.34.0path: [go, run, ./cmd/protoc-gen-foo]支持為本地插件傳參數(shù)。opt雙形態(tài)v0.35.0opt可為單字符串或字符串數(shù)組兩種寫法結(jié)果一致均產(chǎn)生foobar,baz,bat。3.3 依賴與鎖文件行為v1.70.0向buf.yaml添加依賴但缺少對應(yīng)buf.lock條目時直接報錯。v1.38.0buf dep update無新依賴且不存在buf.lock時不再創(chuàng)建空鎖文件。v1.28.0讀取含 b1/b3 digest 的buf.lock時警告建議運行buf mod update升級 digest。v1.24.0buf mod update會阻止會導(dǎo)致依賴間.proto沖突的更新。四、格式與輸入輸出能力的擴展binpb / txtpb / yaml / jsonbuf 對 Protobuf 二進制/文本序列化格式的支持經(jīng)歷了清晰的命名規(guī)范化v0.14.0引入 zip 源格式、zstd 壓縮棄用bingz/jsongz/targz改用formatbin,compressiongzip風格同時承諾舊格式永遠繼續(xù)工作。v1.24.0bin格式正式更名binpb.binpb成為二進制編碼的規(guī)范擴展名.bin繼續(xù)被接受。v1.25.0新增txtpb格式Protobuf 文本格式.txtpb文件被自動識別可用于build、convert、curl等所有 image 輸入/輸出命令。v1.29.0新增yaml格式示例buf build -o image.yaml、buf ls-files image.yaml、buf convert --type foo.Bar --from input.binpb --to output.yamlyaml與json格式新增use_proto_names、use_enum_numbers兩個序列化選項如output.yaml#use_proto_namestrue。v1.26.1修復(fù)buf build -o對.txtpb擴展名的正確輸出。v1.30.0buf generate填充CodeGeneratorRequest的source_file_descriptors字段讓插件可訪問僅在源碼中保留的選項buf build新增--exclude-source-retention-options剝離此類選項。五、Protobuf Editions 支持v1.32.02024-05-16正式支持 Protobuf Editionsedition 2023protoc-gen-buf-breaking與protoc-gen-buf-lint同步支持。v1.34.0本地代碼生成代理到protoc時允許使用 Editions 語法針對 Java/C/Python 等生成邏輯內(nèi)置于 protoc 的語言。v1.68.02026-04-14使用新編譯器支持 Editions 2024 特性buf format支持 Edition 2024 語法v1.68.1 回滾新編譯器報告格式并properly ungate Editions 2024 featuresv1.68.3 修復(fù) Edition 2024 的buf format錯誤處理。v1.73.0修復(fù) managed mode 在 Edition 2024 文件上設(shè)置java_multiple_files該選項在 Edition 2024 下不被允許、會導(dǎo)致代碼生成失敗的問題。5.1 Editions 對 breaking 規(guī)則的影響v1.32.0 大改Editions 引入了 feature 概念導(dǎo)致 breaking 規(guī)則體系結(jié)構(gòu)性調(diào)整且所有舊規(guī)則保持兼容FIELD_SAME_CTYPE→FIELD_SAME_CPP_STRING_TYPE同時考慮ctype選項與(pb.cpp).string_typefeature。FIELD_SAME_LABEL→ 三個cardinality規(guī)則FIELD_SAME_CARDINALITYFILE/PACKAGE、FIELD_WIRE_COMPATIBLE_CARDINALITYWIRE、FIELD_WIRE_JSON_COMPATIBLE_CARDINALITYWIRE_JSON可區(qū)分 map 與其他 repeated 字段、隱式與顯式 presence。FILE_SAME_JAVA_STRING_CHECK_UTF8→FIELD_SAME_JAVA_UTF8_VALIDATION。新增 feature 相關(guān)規(guī)則MESSAGE_SAME_JSON_FORMAT、ENUM_SAME_JSON_FORMAT、FIELD_SAME_UTF8_VALIDATION、ENUM_SAME_TYPEopen vs. closed enum。新增擴展extension支持字段規(guī)則適用于擴展新增EXTENSION_NO_DELETE、PACKAGE_EXTENSION_NO_DELETE默認不啟用遷移到 v2 配置才生效lint 也支持頂層擴展檢查新增FIELD_NOT_REQUIRED規(guī)則禁止 proto2 的 required 與 Editions 的LEGACY_REQUIRED。六、managed mode自動設(shè)置文件選項managed modev0.42.0 引入 beta在生成代碼時自動設(shè)置文件選項逐版本擴展能力v0.42.0managed mode betav0.44.0 完善 v1 規(guī)范。選項擴展軌跡java_package_prefixv0.54.0→objc_class_prefix、csharp_namespacev0.45.0/v0.46.0 前后→ruby_package、php_namespace、java_string_check_utf8v0.48.0→optimize_for支持 default/except/override 三形態(tài)v1.11.0→objc_class_prefix、ruby_package的 except/overridev1.12.0→csharp_namespace的 except/overridev1.10.0→swift_prefixv1.62.0。行為細節(jié)v1.10.0 起enabled: false不再導(dǎo)致buf generate失敗改為警告并忽略 managed mode 選項v1.62.1 修復(fù)swift_prefix無覆蓋時保持默認未設(shè)置的默認行為。七、lint 與 breaking 規(guī)則體系7.1 規(guī)則組織與默認規(guī)則概念v1.40.0引入默認規(guī)則概念——buf config ls-{breaking,lint}-rules會打印默認規(guī)則屬性未顯式配置 lint/breaking 規(guī)則時生效的規(guī)則集同時DEFAULTlint 分類更名STANDARDDEFAULT向后兼容、永遠可用。v1.54.0breaking 規(guī)則新增CSR分類。v0.36.0/v0.43.0// buf:lint:ignore ID注釋忽略支持向上級級聯(lián)enum 級、message 級、service 級等并區(qū)分忽略指令與普通注釋。v1.52.0buf lint/buf breaking在無 source code info 時也輸出文件路徑從而在 CI 場景下也能尊重ignore/ignore_only配置。7.2 PROTOVALIDATE 規(guī)則v1.28.0 起buf lint會校驗 protovalidate 規(guī)則的有效性單條PROTOVALIDATE規(guī)則加入DEFAULT組能力持續(xù)增強(buf.validate.field).required語義修正v1.28.1、repeated校驗v1.30.1、CEL 表達式校驗v1.64.0、field mask 規(guī)則v1.63.0、oneof規(guī)則v1.70.0、NaN 檢查于const/in/not_in/gt/gte/lt/ltev1.70.0、自定義規(guī)則無id/message也允許v1.60.0、IGNORE_IF_ZERO_VALUEpresence 檢查v1.58.0、example 字段選項校驗v1.44.0、預(yù)定義規(guī)則編譯校驗v1.44.0、不可執(zhí)行的required規(guī)則檢查v1.65.0。7.3 自定義插件與 WASM 運行時v1.42.0支持自定義 lint/breaking 插件v1.54.0 起protoc-gen-buf-lint/protoc-gen-buf-breaking支持本地 bufplugins。v1.44.0引入 Wasm 運行時用.wasm擴展名指定自定義 lint/breaking 插件路徑v1.48.0 起buf plugin push/update/prune管理buf.lock中的插件僅 WebAssembly check 插件v1.16.0 曾以BUF_ALPHA_ENABLE_WASM環(huán)境變量做過 alpha 實驗后廢棄該門控v1.69.0 將 check 插件 WASM 內(nèi)存上限提升至 1GiB。v1.68.2buf lint的 CEL 編譯錯誤改用結(jié)構(gòu)化錯誤 API不再解析 cel-go 文本輸出。7.4 錯誤格式支持junitv1.8.0、github-actionsv1.19.0、config-ignore-yamlv0.3.0把 lint 錯誤直接轉(zhuǎn)成可粘貼進配置的格式、gitlab-code-qualityv1.57.0適用于buf lint/buf breaking、Visual Studio 格式v0.19.0。八、buf curlRPC 調(diào)試利器buf curlv1.12.0 引入通過 Connect / gRPC / gRPC-Web 協(xié)議調(diào)用 RPC能力逐版本增強版本能力v1.12.0引入buf curl支持 Connect/gRPC/gRPC-Webv1.18.0--user、--netrc與 cURL 同名 flag 行為一致修復(fù)--user/--netrc導(dǎo)致 Authorization 頭畸形的問題v1.20.0--emit-defaults輸出 JSON 默認值JSON 響應(yīng)默認縮進v1.26.0對安全 https URL 支持--http2-prior-knowledge配合僅支持 HTTP/2 的 gRPC 服務(wù)器 不支持 TLS 握手中協(xié)議協(xié)商的四層負載均衡器v1.28.1支持多 schema多個--schema和/或--reflect組合用于解析 RPC 結(jié)果中的擴展與google.protobuf.Any值v1.36.0--list-services、--list-methods列出 RPC schema 中的服務(wù)/方法而非發(fā)起調(diào)用v1.38.0--http3強制 HTTP/3 傳輸v1.41.0gRPC 的 HTTP/3 支持v1.57.2 / v1.58.0修復(fù) HTTP/2 服務(wù)相關(guān) bugUnreleased 段最重要的變更buf curl在 server reflection、gRPC 協(xié)議或雙向流方法均要求 HTTP/2下對httpURL 自動啟用 HTTP/2 prior knowledge--http2-prior-knowledge在這些場景不再必需。源碼佐證見 curl.go 的 L578-L584if !isSecure !f.HTTP2PriorKnowledge (f.Reflect || f.Protocol connect.ProtocolGRPC) { // Server reflection uses a bidirectional stream and the gRPC protocol // requires HTTP/2, neither of which works over HTTP 1.1. Since a // plain-text URL can only use HTTP/2 via prior knowledge, enable it // automatically rather than requiring the flag. f.HTTP2PriorKnowledge true }此外 curl 還支持--schema本地 buf 模塊/鏡像/遠程、--reflect服務(wù)端反射、TLS 系列 flag--key/--cert/--cacert/--servername/--insecure、--user-agent、--data、--output等flag 常量定義見 curl.go 頂部。九、LSP編輯器內(nèi)的 buf 體驗v1.43.0實驗性 LSP 支持buf beta lspv1.59.0 轉(zhuǎn)正為buf lsp servebeta 命令棄用并新增textDocument/References、基礎(chǔ)關(guān)鍵字/語法/package/import 補全、workspace symbol 查詢、診斷定位與格式更新修復(fù)。能力擴展軌跡textDocument/documentSymbolv1.60.0、textDocument/renameprepareRenamev1.62.0、折疊區(qū)間與文檔鏈接v1.64.0、organize imports code actionv1.64.0補缺失 import、刪冗余 import、按字母排序、語義 token 語法高亮v1.64.0、document highlightv1.64.0、補全選項與全限定類型引用v1.64.0、字段編號補全v1.63.0、deprecate code actionv1.65.0、注釋忽略 code actionv1.66.0、CEL hoverv1.66.0/v1.67.0、buf.gen.yamlcode lensesv1.69.0Run buf generate/Check for plugin updates、lint/breaking ignore 路徑警告v1.69.0、buf.yamldeps 文檔鏈接與 code lensesv1.68.0、命名生成模板buf.go.gen.yaml/buf.gen.go.yaml支持Unreleased、依賴/well-known-type 文件間跳轉(zhuǎn)與引用子集修復(fù)v1.73.0。調(diào)試支持v1.68.2 為buf lsp serve增加--debug-address。十、BSR 注冊表命令與推送能力命令家族演變v1.36.0 建立buf registry organization/module/label/commit穩(wěn)定命令并移除 beta 版本v1.47.0 將buf registry commit→buf registry module commit、buf registry label→buf registry module label舊命令棄用v1.48.0 新增buf registry plugin {create,delete,info,update}、buf plugin push、buf registry plugin commit/label系列v1.65.0 新增buf registry policy {commit,create,delete,info,label,settings}。認證buf registry loginv0.46.0、BUF_TOKEN環(huán)境變量v0.55.0 起v1.13.0 支持多實例TOKEN1BSRHOSTNAME1,TOKEN2...、buf registry whoamiv1.46.0、瀏覽器登錄流程v1.36.0WSL2 修復(fù)見 v1.61.0、v1.35.0 起登錄不再需要用戶名。push 增強--create--create-visibilityv1.19.0v1.32.0 起默認 private、--git-metadatav1.32.0 自動設(shè)置 label/source-control-url/create-default-label、--label、--source-control-url、--create-default-labelv1.32.0、--exclude-unnamedv1.33.0、--draftv1.7.0。buf push自動攜帶 LICENSE/doc 文件v1.38.0 起允許從模塊目錄向上查找buf.md/README.mdv1.18.0 引入 fallback 路徑。診斷與 SDKbuf registry {module,plugin} commit的 json 輸出增加source_control_urlv1.57.0--digest-changes-onlyv1.49.0buf registry sdk infov1.55.0、buf registry sdk versionv1.32.0buf beta pricev1.16.0。十一、編譯器性能與平臺支持新編譯器v1.9.02022-10-19更快、內(nèi)存占用更低。CHANGELOG 給出的對比數(shù)據(jù)生成 source code info 時快 20%、分配少 13%不生成時快 50%、分配少 35%大型編譯過程結(jié)束時堆上存活內(nèi)存不足原來一半。同時修復(fù)了 protoc 會拒絕但 buf 先前接受的若干語法問題JSON 名沖突校驗、全限定名與包名沖突、空 oneof/extend 語句、包名 ≥512 字符或 100 個點、消息嵌套 32 層、字段類型指向合成 map entry 消息等。v1.68.0切換新編譯器并支持 Editions 2024v1.68.1 因新報告格式問題回滾說明 buf 對編譯器升級采取先試用、可回退的謹慎策略。平臺矩陣arm64 發(fā)布v0.42.0→ Windows 支持v0.54.0→ Linux s390xv1.56.0、ppc64le 修復(fù)v1.56.0 修正此前誤發(fā)布為 x86_64 的問題v1.54.0 正式新增 ppc64le→ RISC-V 64-bitv1.54.0→ OpenBSD/FreeBSD amd64/arm64v1.67.0。其他--timeout默認值改為 0無超時v1.60.0FileAnnotation錯誤退出碼 100v0.41.0多架構(gòu) Docker 鏡像v0.41.0--exit-codev1.3.0buf format未格式化時非零退出。十二、兼容性承諾與遷移路徑v1.0.0-rc1 段落的表述是理解 buf 演進哲學(xué)的鑰匙我們對兼容性極其認真。我們說 v1.0 就是 v1.0——希望 buf 在 v1 上穩(wěn)定十年。如果有想改變的東西保證不破壞你是我們的責任而不是你為我們的改變負責。 體現(xiàn)在所有棄用均提前警告且提供遷移路徑v1.0.0 之前約兩年 beta 期持續(xù)打印棄用警告v1.0.0 一次性移除buf login、--log-level全局 flag、舊buf check *命令等。命令遷移鏈完整可追溯buf check lint→buf lint→未再變buf image build→buf buildbuf beta graph→buf dep graphbuf mod *→buf dep */buf config *。規(guī)則/配置向后兼容DEFAULTlint 分類更名STANDARD后繼續(xù)工作Editions 相關(guān)的 breaking 規(guī)則替換后舊規(guī)則仍可用v1 與 v1beta1 配置繼續(xù)被讀取新規(guī)則默認不激活需遷移 v2 才啟用。文件格式兼容bin擴展名在binpb規(guī)范化后仍被接受bingz/jsongz/targz承諾永遠繼續(xù)工作。結(jié)語從 CHANGELOG 可以清晰看到 buf 的演進邏輯先跑通核心編譯/校驗/生成閉環(huán)再穩(wěn)定 CLI 與配置面然后向 RPC 調(diào)試curl、編輯器體驗LSP、注冊表生態(tài)BSR與 Protobuf Editions 前沿擴展并以永遠不破壞用戶為鐵律。對使用者而言這份文檔同時是一份遷移指南、功能清單與性能基線如 v1.9.0 編譯器數(shù)據(jù)。當前倉庫處于 Unreleased 階段截至 v1.73.0 之后buf curlHTTP/2 prior knowledge 自動化、buf format --stdin-filepath、遠程輸入去重抓取等新特性均已在源碼中落地讀者可在 cmd/buf/internal/command 對應(yīng)子目錄curl、format中查看實現(xiàn)與測試作為理解最新功能的起點。贊分享開發(fā)工具代碼生成API設(shè)計【免費下載鏈接】bufThe best way of working with Protocol Buffers.項目地址https://gitcode.com/GitHub_Trending/bu/buf點擊查看免費下載相關(guān)推薦postgresql-event-sourcing完全指南如何用Spring Boot構(gòu)建事件驅(qū)動系統(tǒng)postgresql event sourcing完全指南如何用Spring Boot構(gòu)建事件驅(qū)動系統(tǒng) postgresql event sourcing是一Azure Go SDK azidentity 版本演進與技術(shù)全解從 v0.1.0 到 v1.13.1 的認證能力變遷Azure Go SDK azidentity 版本演進與技術(shù)全解從 v0.1.0 到 v1.13.1 的認證能力變遷 本文以 buildkit 倉庫中 ve構(gòu)建工具云原生后端gridstack.js 版本演進全覽從 v0.1.0 到 v13.3.0 的核心能力變遷與遷移指南gridstack.js 版本演進全覽從 v0.1.0 到 v13.3.0 的核心能力變遷與遷移指南 本篇文章以倉庫內(nèi) doc/CHANGES.md http前端UI組件上一篇GoCV代碼質(zhì)量工具靜態(tài)分析與代碼規(guī)范檢查下一篇引用其他Vault的筆記創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考