開發(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的全部變更包含大量可直接落地的命令、配置與遷移細(xì)節(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職責(zé)逐步清晰兼容承諾v1.0.0-rc1 明確指出希望 buf 在 v1 上穩(wěn)定十年所有命令/flag 的棄用與遷移路徑均提前警告詳見下文第九節(jié)。從倉庫的 cmd/buf/internal/command 目錄可以看到當(dāng)前命令面包括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 更自然為目標(biāo)將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 給出的遷移示例# 編譯當(dāng)前目錄文件 buf build # 等價的無參調(diào)用 buf build . # 構(gòu)建 https 上的 git 倉庫 buf build https://github.com/foo/bar.git # 檢查當(dāng)前目錄相對 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 同時將默認(rèn)配置版本從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默認(rèn)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 版本與文件職責(zé)文件職責(zé)關(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可為單字符串或字符串?dāng)?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風(fēng)格同時承諾舊格式永遠(yuǎn)繼續(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默認(rèn)不啟用遷移到 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。行為細(xì)節(jié)v1.10.0 起enabled: false不再導(dǎo)致buf generate失敗改為警告并忽略 managed mode 選項v1.62.1 修復(fù)swift_prefix無覆蓋時保持默認(rèn)未設(shè)置的默認(rèn)行為。七、lint 與 breaking 規(guī)則體系7.1 規(guī)則組織與默認(rèn)規(guī)則概念v1.40.0引入默認(rèn)規(guī)則概念——buf config ls-{breaking,lint}-rules會打印默認(rèn)規(guī)則屬性未顯式配置 lint/breaking 規(guī)則時生效的規(guī)則集同時DEFAULTlint 分類更名STANDARDDEFAULT向后兼容、永遠(yuǎn)可用。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 表達(dá)式校驗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)試?yán)鱞uf 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 默認(rèn)值JSON 響應(yīng)默認(rèn)縮進v1.26.0對安全 https URL 支持--http2-prior-knowledge配合僅支持 HTTP/2 的 gRPC 服務(wù)器 不支持 TLS 握手中協(xié)議協(xié)商的四層負(fù)載均衡器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 模塊/鏡像/遠(yuǎn)程、--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}。認(rèn)證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 起默認(rèn) 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 對編譯器升級采取先試用、可回退的謹(jǐn)慎策略。平臺矩陣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默認(rèn)值改為 0無超時v1.60.0FileAnnotation錯誤退出碼 100v0.41.0多架構(gòu) Docker 鏡像v0.41.0--exit-codev1.3.0buf format未格式化時非零退出。十二、兼容性承諾與遷移路徑v1.0.0-rc1 段落的表述是理解 buf 演進哲學(xué)的鑰匙我們對兼容性極其認(rèn)真。我們說 v1.0 就是 v1.0——希望 buf 在 v1 上穩(wěn)定十年。如果有想改變的東西保證不破壞你是我們的責(zé)任而不是你為我們的改變負(fù)責(zé)。 體現(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ī)則默認(rèn)不激活需遷移 v2 才啟用。文件格式兼容bin擴展名在binpb規(guī)范化后仍被接受bingz/jsongz/targz承諾永遠(yuǎn)繼續(xù)工作。結(jié)語從 CHANGELOG 可以清晰看到 buf 的演進邏輯先跑通核心編譯/校驗/生成閉環(huán)再穩(wěn)定 CLI 與配置面然后向 RPC 調(diào)試curl、編輯器體驗LSP、注冊表生態(tài)BSR與 Protobuf Editions 前沿擴展并以永遠(yuǎn)不破壞用戶為鐵律。對使用者而言這份文檔同時是一份遷移指南、功能清單與性能基線如 v1.9.0 編譯器數(shù)據(jù)。當(dāng)前倉庫處于 Unreleased 階段截至 v1.73.0 之后buf curlHTTP/2 prior knowledge 自動化、buf format --stdin-filepath、遠(yuǎn)程輸入去重抓取等新特性均已在源碼中落地讀者可在 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 的認(rèn)證能力變遷Azure Go SDK azidentity 版本演進與技術(shù)全解從 v0.1.0 到 v1.13.1 的認(rèn)證能力變遷 本文以 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），僅供參考