mcpField
P
protobuf

protobuf

github.com/bufbuild開発20544 回インストール19 週間前に更新
リポジトリ

protobuf について

protobufは、Protocol Buffersのスキーマやサービスの作成・保守を支援するスキルです。プロジェクト規約、検証、コード生成設定、bufによる確認を案内します。

主な機能

  1. 01.protoスキーマの作成と編集
  2. 02bufとコード生成の設定
  3. 03protovalidate制約の追加
  4. 04gRPCおよびConnectサービスの設計
  5. 05フォーマット、lint、互換性変更の確認

活用シーン

  1. 01本番APIスキーマへのフィールド追加
  2. 02新しいprotobufプロジェクトの設定
  3. 03buf lintや互換性エラーの調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/bufbuild/claude-plugins --skill protobuf

インストール後、Claude Code で/protobufを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

assets/
buf.gen.go-connect.yaml
buf.gen.go.yaml
buf.gen.java.yaml
buf.gen.python.yaml
buf.gen.ts.yaml
buf.gen.yaml
buf.lock
buf.yaml
Makefile.example
assets/proto/example/v1/
book_service.proto
book.proto
references/
best_practices.md
buf_toolchain.md
examples.md
migration.md
protoc_toolchain.md
protovalidate.md
quick_reference.md
review_checklist.md
troubleshooting.md

詳細

Protocol Buffers

このスキルが必要な場合

  • .proto ファイルの作成や編集
  • buf.yaml または buf.gen.yaml の設定
  • gRPC または Connect サービスの設計
  • protovalidate 制約の追加
  • buf lint または破壊的変更エラーのトラブルシューティング

基本的なワークフロー

1. プロジェクトのスタイルに合わせる

proto コードを書く前に、プロジェクト内の既存の .proto ファイルを確認してください。 命名規則、フィールドの順序、構造パターン、バリデーション、ドキュメントのスタイルに合わせてください。 既存ファイルがない場合は、どのスタイルを使うか、または参考にする既存のライブラリがあるかをユーザーに尋ねてください。

2. Proto コードを書く
  • best_practices.md の普遍的なベストプラクティスを適用します
  • すべてのフィールドに protovalidate 制約を追加します。本番環境の API では必須です
  • サービスのテンプレートについては、assets/ を参照してください
3. 変更を検証する

変更を行った後は、必ず次を実行してください：

buf format -w && buf lint

まず Makefile を確認してください。多くのプロジェクトでは make lint または make format を使用しています。

変更を完了とする前に、すべてのエラーを修正してください。

クイックリファレンス

タスクリファレンス
フィールド型、列挙型、oneof、マップquick_reference.md
スキーマの進化、破壊的変更best_practices.md
バリデーション制約protovalidate.md
サービスの完全な例examples.md、assets/
buf CLI、buf.yaml、buf.gen.yamlbuf_toolchain.md
protoc からの移行migration.md
lint エラー、よくある問題troubleshooting.md
Proto API レビューのチェックリストreview_checklist.md

プロジェクトのセットアップ

新規プロジェクト

  1. ディレクトリ構造を作成します：

    proto/
├── buf.yaml
├── buf.gen.yaml
└── company/
    └── domain/
        └── v1/
            └── service.proto

  2. assets/buf.yaml を出発点として使用します

  3. buf.yaml の依存関係として buf.build/bufbuild/protovalidate を追加し、buf dep update を実行します

  4. コード生成の設定には assets/buf.gen.*.yaml を使用します

コード生成テンプレート
テンプレート用途
buf.gen.go.yamlgRPC を使用する Go
buf.gen.go-connect.yamlConnect を使用する Go
buf.gen.ts.yamlConnect を使用する TypeScript
buf.gen.python.yamlgRPC を使用する Python
buf.gen.java.yamlgRPC を使用する Java
Proto ファイルのテンプレート

assets/proto/example/v1/ にあります：

テンプレート説明
book.protoエンティティメッセージ、BookRef oneof、列挙型
book_service.protoバッチ操作、ページネーション、並べ替えを含む完全な CRUD

よくあるタスク

新しいフィールドを追加する
  1. 次の連続したフィールド番号を使用します
  2. protovalidate 制約を追加します。すべてのフィールドに、その型に適したバリデーション（形式のバリデーター、長さの範囲、数値の範囲、列挙型の制約など）が必要です
  3. フィールドの説明を記述します
  4. buf format -w && buf lint を実行します
フィールドを削除する
  1. フィールド番号と名前の両方を予約します： 
    reserved 4;
reserved "old_field_name";
  2. buf breaking --against '.git#branch=main' を実行して確認します
protovalidate 制約を追加する

本番環境の API では、すべてのフィールドに適切なバリデーションを設定してください。 詳しくは、リファレンス全体が記載された protovalidate.md を参照してください。

よく使われる制約：

  • 文字列の形式：.string.uuid、.string.email、.string.uri、.string.pattern
  • 文字列の長さ：.string.min_len、.string.max_len
  • 数値の範囲：.int32.gte、.uint32.lte
  • 列挙型のバリデーション：.enum.defined_only、.enum.not_in = 0
  • 繰り返しの範囲：.repeated.min_items、.repeated.max_items
  • 必須フィールド：(buf.validate.field).required = true
  • 必須の oneof：(buf.validate.oneof).required = true

検証チェックリスト

変更を行った後：

  • すべてのフィールドに適切な protovalidate 制約が設定されている
  • buf format -w（フォーマットを適用）
  • buf lint（スタイルルールを確認）
  • buf breaking --against '.git#branch=main'（既存のスキーマを変更する場合）

コメント

Markdown 対応