开发工具代码生成API设计【免费下载链接】bufThe best way of working with Protocol Buffers.项目地址https://gitcode.com/GitHub_Trending/bu/buf点击查看免费下载本文以仓库根目录的 CHANGELOG.md 为骨架系统梳理 buf 从 2019 年 v0.1.0 到 v1.73.0 的完整演进脉络。文章覆盖核心命令build / lint / breaking / generate / format / curl / lsp、配置体系v1beta1 → v1 → v2、格式与输入输出能力binpb / txtpb / yaml / json、Protobuf Editions 支持、managed mode、lint/breaking 规则体系、BSR 注册表命令与多平台发布等主题并结合仓库源码如 curl 命令实现、format 命令实现、buf.yaml给出源码级佐证帮助读者快速掌握 buf 的能力边界、迁移路径与版本演进逻辑。一、为什么 CHANGELOG 值得读版本即路线图buf 是面向 Protocol Buffers 的现代化工具链定位为处理 Protocol Buffers 的最佳方式项目描述原文 The best way of working with Protocol Buffers。其 CHANGELOG 记录了从 2019 年 10 月 v0.1.0 初始 beta 发布到 v1.73.02026-09-11的全部变更包含大量可直接落地的命令、配置与迁移细节新增能力如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 上稳定十年所有命令/flag 的弃用与迁移路径均提前警告详见下文第九节。从仓库的 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 中逐版本新增的命令一一对应。二、核心工作流命令的建立与稳定2019–20222.1 从 beta 到 v1.0.0命令体系的两次大清洗buf 的命令演进经历了两次大规模重命名第一次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 # 等价的无参调用 buf build . # 构建 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 命令的持续补全v1.0.0 之后buf generate在 v1.14.0 将--include-types统一为--type旧 flag 保持兼容v1.32.0 起支持strategy、--clean、protoc_path数组形式首元素为路径其余为每次调用传给 protoc 的附加参数。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 稳定承接buf mod update/prune与buf dep graph源自 v0.23.0 的buf beta graphv1.42.0 起支持--format默认dot、可选json。buf exportv0.48.0导出可被 protoc 免-I直接构建的文件集支持--exclude-imports与--pathv1.56.0 新增--all以包含非 proto 源文件。buf statsv1.17.0 起buf beta statsv1.55.0 转正输出模块统计信息。三、配置体系的演进v1beta1 → v1 → v23.1 版本与文件职责文件职责关键里程碑buf.yaml模块/工作区配置lint、breaking 规则、依赖、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数组buf.work.yaml多模块工作区v0.45.0 从buf.work统一为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 联动仓库自身根目录的 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 配置的关键新增v1.32.0 是配置体系的分水岭引入v2版本同时提供buf config migrate一键迁移includes键v1.39.0模块配置可指定目录列表proto 文件只有位于其中才属于该模块与excludes并用时在 include 内且不在 exclude 内才算模块成员允许多个模块配置共享同一目录路径。clean顶层选项v1.36.0等价于buf generate --clean生成前删除各插件out指向的目录/jar/zip。插件path数组化v1.34.0path: [go, run, ./cmd/protoc-gen-foo]支持为本地插件传参数。opt双形态v0.35.0opt可为单字符串或字符串数组两种写法结果一致均产生foobar,baz,bat。3.3 依赖与锁文件行为v1.70.0向buf.yaml添加依赖但缺少对应buf.lock条目时直接报错。v1.38.0buf dep update无新依赖且不存在buf.lock时不再创建空锁文件。v1.28.0读取含 b1/b3 digest 的buf.lock时警告建议运行buf mod update升级 digest。v1.24.0buf mod update会阻止会导致依赖间.proto冲突的更新。四、格式与输入输出能力的扩展binpb / txtpb / yaml / jsonbuf 对 Protobuf 二进制/文本序列化格式的支持经历了清晰的命名规范化v0.14.0引入 zip 源格式、zstd 压缩弃用bingz/jsongz/targz改用formatbin,compressiongzip风格同时承诺旧格式永远继续工作。v1.24.0bin格式正式更名binpb.binpb成为二进制编码的规范扩展名.bin继续被接受。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修复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 等生成逻辑内置于 protoc 的语言。v1.68.02026-04-14使用新编译器支持 Editions 2024 特性buf format支持 Edition 2024 语法v1.68.1 回滚新编译器报告格式并properly ungate Editions 2024 featuresv1.68.3 修复 Edition 2024 的buf format错误处理。v1.73.0修复 managed mode 在 Edition 2024 文件上设置java_multiple_files该选项在 Edition 2024 下不被允许、会导致代码生成失败的问题。5.1 Editions 对 breaking 规则的影响v1.32.0 大改Editions 引入了 feature 概念导致 breaking 规则体系结构性调整且所有旧规则保持兼容FIELD_SAME_CTYPE→FIELD_SAME_CPP_STRING_TYPE同时考虑ctype选项与(pb.cpp).string_typefeature。FIELD_SAME_LABEL→ 三个cardinality规则FIELD_SAME_CARDINALITYFILE/PACKAGE、FIELD_WIRE_COMPATIBLE_CARDINALITYWIRE、FIELD_WIRE_JSON_COMPATIBLE_CARDINALITYWIRE_JSON可区分 map 与其他 repeated 字段、隐式与显式 presence。FILE_SAME_JAVA_STRING_CHECK_UTF8→FIELD_SAME_JAVA_UTF8_VALIDATION。新增 feature 相关规则MESSAGE_SAME_JSON_FORMAT、ENUM_SAME_JSON_FORMAT、FIELD_SAME_UTF8_VALIDATION、ENUM_SAME_TYPEopen vs. closed enum。新增扩展extension支持字段规则适用于扩展新增EXTENSION_NO_DELETE、PACKAGE_EXTENSION_NO_DELETE默认不启用迁移到 v2 配置才生效lint 也支持顶层扩展检查新增FIELD_NOT_REQUIRED规则禁止 proto2 的 required 与 Editions 的LEGACY_REQUIRED。六、managed mode自动设置文件选项managed modev0.42.0 引入 beta在生成代码时自动设置文件选项逐版本扩展能力v0.42.0managed mode betav0.44.0 完善 v1 规范。选项扩展轨迹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 三形态v1.11.0→objc_class_prefix、ruby_package的 except/overridev1.12.0→csharp_namespace的 except/overridev1.10.0→swift_prefixv1.62.0。行为细节v1.10.0 起enabled: false不再导致buf generate失败改为警告并忽略 managed mode 选项v1.62.1 修复swift_prefix无覆盖时保持默认未设置的默认行为。七、lint 与 breaking 规则体系7.1 规则组织与默认规则概念v1.40.0引入默认规则概念——buf config ls-{breaking,lint}-rules会打印默认规则属性未显式配置 lint/breaking 规则时生效的规则集同时DEFAULTlint 分类更名STANDARDDEFAULT向后兼容、永远可用。v1.54.0breaking 规则新增CSR分类。v0.36.0/v0.43.0// buf:lint:ignore ID注释忽略支持向上级级联enum 级、message 级、service 级等并区分忽略指令与普通注释。v1.52.0buf lint/buf breaking在无 source code info 时也输出文件路径从而在 CI 场景下也能尊重ignore/ignore_only配置。7.2 PROTOVALIDATE 规则v1.28.0 起buf lint会校验 protovalidate 规则的有效性单条PROTOVALIDATE规则加入DEFAULT组能力持续增强(buf.validate.field).required语义修正v1.28.1、repeated校验v1.30.1、CEL 表达式校验v1.64.0、field mask 规则v1.63.0、oneof规则v1.70.0、NaN 检查于const/in/not_in/gt/gte/lt/ltev1.70.0、自定义规则无id/message也允许v1.60.0、IGNORE_IF_ZERO_VALUEpresence 检查v1.58.0、example 字段选项校验v1.44.0、预定义规则编译校验v1.44.0、不可执行的required规则检查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环境变量做过 alpha 实验后废弃该门控v1.69.0 将 check 插件 WASM 内存上限提升至 1GiB。v1.68.2buf lint的 CEL 编译错误改用结构化错误 API不再解析 cel-go 文本输出。7.4 错误格式支持junitv1.8.0、github-actionsv1.19.0、config-ignore-yamlv0.3.0把 lint 错误直接转成可粘贴进配置的格式、gitlab-code-qualityv1.57.0适用于buf lint/buf breaking、Visual Studio 格式v0.19.0。八、buf curlRPC 调试利器buf curlv1.12.0 引入通过 Connect / gRPC / gRPC-Web 协议调用 RPC能力逐版本增强版本能力v1.12.0引入buf curl支持 Connect/gRPC/gRPC-Webv1.18.0--user、--netrc与 cURL 同名 flag 行为一致修复--user/--netrc导致 Authorization 头畸形的问题v1.20.0--emit-defaults输出 JSON 默认值JSON 响应默认缩进v1.26.0对安全 https URL 支持--http2-prior-knowledge配合仅支持 HTTP/2 的 gRPC 服务器 不支持 TLS 握手中协议协商的四层负载均衡器v1.28.1支持多 schema多个--schema和/或--reflect组合用于解析 RPC 结果中的扩展与google.protobuf.Any值v1.36.0--list-services、--list-methods列出 RPC schema 中的服务/方法而非发起调用v1.38.0--http3强制 HTTP/3 传输v1.41.0gRPC 的 HTTP/3 支持v1.57.2 / v1.58.0修复 HTTP/2 服务相关 bugUnreleased 段最重要的变更buf curl在 server reflection、gRPC 协议或双向流方法均要求 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服务端反射、TLS 系列 flag--key/--cert/--cacert/--servername/--insecure、--user-agent、--data、--output等flag 常量定义见 curl.go 顶部。九、LSP编辑器内的 buf 体验v1.43.0实验性 LSP 支持buf beta lspv1.59.0 转正为buf lsp servebeta 命令弃用并新增textDocument/References、基础关键字/语法/package/import 补全、workspace symbol 查询、诊断定位与格式更新修复。能力扩展轨迹textDocument/documentSymbolv1.60.0、textDocument/renameprepareRenamev1.62.0、折叠区间与文档链接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 文件间跳转与引用子集修复v1.73.0。调试支持v1.68.2 为buf lsp serve增加--debug-address。十、BSR 注册表命令与推送能力命令家族演变v1.36.0 建立buf registry organization/module/label/commit稳定命令并移除 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环境变量v0.55.0 起v1.13.0 支持多实例TOKEN1BSRHOSTNAME1,TOKEN2...、buf registry whoamiv1.46.0、浏览器登录流程v1.36.0WSL2 修复见 v1.61.0、v1.35.0 起登录不再需要用户名。push 增强--create--create-visibilityv1.19.0v1.32.0 起默认 private、--git-metadatav1.32.0 自动设置 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更快、内存占用更低。CHANGELOG 给出的对比数据生成 source code info 时快 20%、分配少 13%不生成时快 50%、分配少 35%大型编译过程结束时堆上存活内存不足原来一半。同时修复了 protoc 会拒绝但 buf 先前接受的若干语法问题JSON 名冲突校验、全限定名与包名冲突、空 oneof/extend 语句、包名 ≥512 字符或 100 个点、消息嵌套 32 层、字段类型指向合成 map entry 消息等。v1.68.0切换新编译器并支持 Editions 2024v1.68.1 因新报告格式问题回滚说明 buf 对编译器升级采取先试用、可回退的谨慎策略。平台矩阵arm64 发布v0.42.0→ Windows 支持v0.54.0→ Linux s390xv1.56.0、ppc64le 修复v1.56.0 修正此前误发布为 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多架构 Docker 镜像v0.41.0--exit-codev1.3.0buf format未格式化时非零退出。十二、兼容性承诺与迁移路径v1.0.0-rc1 段落的表述是理解 buf 演进哲学的钥匙我们对兼容性极其认真。我们说 v1.0 就是 v1.0——希望 buf 在 v1 上稳定十年。如果有想改变的东西保证不破坏你是我们的责任而不是你为我们的改变负责。 体现在所有弃用均提前警告且提供迁移路径v1.0.0 之前约两年 beta 期持续打印弃用警告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 *。规则/配置向后兼容DEFAULTlint 分类更名STANDARD后继续工作Editions 相关的 breaking 规则替换后旧规则仍可用v1 与 v1beta1 配置继续被读取新规则默认不激活需迁移 v2 才启用。文件格式兼容bin扩展名在binpb规范化后仍被接受bingz/jsongz/targz承诺永远继续工作。结语从 CHANGELOG 可以清晰看到 buf 的演进逻辑先跑通核心编译/校验/生成闭环再稳定 CLI 与配置面然后向 RPC 调试curl、编辑器体验LSP、注册表生态BSR与 Protobuf Editions 前沿扩展并以永远不破坏用户为铁律。对使用者而言这份文档同时是一份迁移指南、功能清单与性能基线如 v1.9.0 编译器数据。当前仓库处于 Unreleased 阶段截至 v1.73.0 之后buf curlHTTP/2 prior knowledge 自动化、buf format --stdin-filepath、远程输入去重抓取等新特性均已在源码中落地读者可在 cmd/buf/internal/command 对应子目录curl、format中查看实现与测试作为理解最新功能的起点。赞分享开发工具代码生成API设计【免费下载链接】bufThe best way of working with Protocol Buffers.项目地址https://gitcode.com/GitHub_Trending/bu/buf点击查看免费下载相关推荐postgresql-event-sourcing完全指南如何用Spring Boot构建事件驱动系统postgresql event sourcing完全指南如何用Spring Boot构建事件驱动系统 postgresql event sourcing是一Azure Go SDK azidentity 版本演进与技术全解从 v0.1.0 到 v1.13.1 的认证能力变迁Azure Go SDK azidentity 版本演进与技术全解从 v0.1.0 到 v1.13.1 的认证能力变迁 本文以 buildkit 仓库中 ve构建工具云原生后端gridstack.js 版本演进全览从 v0.1.0 到 v13.3.0 的核心能力变迁与迁移指南gridstack.js 版本演进全览从 v0.1.0 到 v13.3.0 的核心能力变迁与迁移指南 本篇文章以仓库内 doc/CHANGES.md http前端UI组件上一篇GoCV代码质量工具静态分析与代码规范检查下一篇引用其他Vault的笔记创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考