buf Proto Code Generation¶
概念概覽
buf v2 inputs.paths 限制¶
核心知識¶
buf v2 inputs.paths 限制¶
buf v2 的 inputs.paths 只支援目錄層級過濾，無法白名單單個 .proto 檔案。這意味著你無法寫 paths: [matchrpg/v1/common.proto] 來精確排除同目錄的其他 proto，必須用目錄結構本身來解決分隔問題。
解法：按交付對象拆目錄¶
# 重構前（無法精確過濾）
matchrpg/v1/
common.proto ← 客戶端需要
errors.proto ← 客戶端需要
admin.proto ← 只有伺服器需要
config.proto ← 只有伺服器需要
# 重構後（目錄即邊界）
matchrpg/common/v1/ ← buf.gen.client.yaml 指向此處
common.proto
errors.proto
matchrpg/internal/v1/ ← 不加入 client codegen
admin.proto
config.proto
buf breaking check 注意¶
package rename（如 matchrpg.v1 → matchrpg.common.v1）會導致 buf breaking check CI 失敗。處理方式：在 Preview 階段於 buf.yaml 加 breaking.ignore 臨時例外，PR 合併後再移除。
經驗教訓¶
-
buf v2 inputs.paths 無法細到單檔層級，目錄結構設計必須反映生成邊界
-
先更新 proto 內容再跑 make proto，讓編譯錯誤自動引導找出所有需要更新的 Go 檔案
-
用 grep -r 'matchrpg/v1' --include='*.go' 驗證所有舊 import 已替換完畢
常見陷阱¶
-
inputs.paths 設定為混合目錄時，CI 會意外把內部服務代碼打包進 client SDK
-
buf breaking check 對 package rename 敏感，即使 wire format 相容也會報錯
最佳實踐¶
-
buf.gen.client.yaml 的 inputs.paths 應指向 common/ 目錄，而非混合目錄
-
CI 生成完後明確檢查 generated/csharp/ 不含 Admin.cs、Config.cs、Health.cs 等內部服務檔案
-
package rename 的重構應在 feature branch 進行，避免影響 main 的 breaking check CI
相關概念¶
- gRPC Proto Pool Resource Design
- Proto Delivery Boundary Design
- protobuf-monorepo-design----dangling-------dangling---
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-20 | ce632061-4850-4646-b2a2-cd5752d01b26 | 揭示 buf v2 inputs.paths 僅支援目錄級過濾的限制，以及如何透過目錄結構設計繞過此限制 |