Protobufとサービス定義
protoでAPIを記述します。
「Protobufとサービス定義」はCoddyKit上の無料Learn Rust Codingレッスンです。 これはレッスン1/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはLearn Rust Coding学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Learn Rust Codingコースには全4レッスンが含まれています。
gRPCとProtobufを使う理由
gRPCはHTTP/2とProtocol Buffersを基盤とする高性能なRPCフレームワークです。Rustでは、tonicクレートがgRPCを端から端まで実装します。
Protobufはインターフェース定義言語（IDL）です。.protoファイルにメッセージとサービスを一度記述すると、コード生成ツールが型安全なクライアントとサーバーのスタブを生成します。
.protoファイルの構造
すべてのprotoファイルでは、構文バージョンとパッケージを宣言します。パッケージによって生成された型を名前空間で分け、衝突を避けられます。
tonicではproto3を使用します。パッケージ名は、生成後のRustモジュールパスに対応します。
syntax = "proto3";
package greeter.v1;メッセージを定義する
メッセージは型付きのレコードです。各フィールドには、型、名前、ワイヤーエンコーディングで使用する一意のフィールド番号があります。
フィールド番号は安定していなければなりません。データが存在するフィールドの番号を再利用したり変更したりすると、互換性が壊れるため、決して行わないでください。
message HelloRequest {
string name = 1;
int32 age = 2;
}スカラー型とRustへの対応
Protobufのスカラー型は、prostを通じてRustの型に対応付けられます。stringはStringに、int32はi32に、boolはboolに、bytesはVec<u8>になります。
proto3では、すべてのスカラー型にデフォルト値（空文字列、0、false）があります。明示的に指定しない限り、オプショナルではありません。
message Metric {
string label = 1;
double value = 2;
bool active = 3;
}サービスを定義する
serviceはRPCメソッドをまとめます。各rpcでは、メソッド名、リクエストメッセージ、レスポンスメッセージを宣言します。
tonicはこのブロックからサーバートレイトとクライアント構造体を生成します。動作を提供するには、そのトレイトを実装します。
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloReply {
string message = 1;
}4種類のRPCメソッド
gRPCには、単項、サーバーストリーミング、クライアントストリーミング、双方向ストリーミングという4種類のストリーミング形式があります。
リクエスト側、レスポンス側、または両方にstreamキーワードを付けることで、ストリームであることを示します。
service Chat {
rpc Unary (Msg) returns (Msg);
rpc ServerStream (Msg) returns (stream Msg);
rpc ClientStream (stream Msg) returns (Msg);
rpc BiDi (stream Msg) returns (stream Msg);
}Protobufの列挙型
列挙型は整数を基盤とします。proto3では、最初の値に0を割り当てる必要があり、それがデフォルトになります。
prostはRustの列挙型と、基になるi32との変換用ヘルパーを生成します。未知の値がワイヤー経由で届く可能性があるためです。
enum Status {
STATUS_UNKNOWN = 0;
STATUS_ACTIVE = 1;
STATUS_BANNED = 2;
}ネストされたフィールドと繰り返しフィールド
repeatedフィールドはリストであり、RustではVec<T>に対応します。メッセージはネストすることも、名前で参照することもできます。
これにより、余分な記述を増やさずにコレクションや複合ペイロードをモデル化できます。
message Order {
string id = 1;
repeated Item items = 2;
}
message Item {
string sku = 1;
int32 qty = 2;
}Emptyと既知の型
何も受け取らない、または何も返さないメソッドでは、google/protobuf/empty.protoをインポートしてEmptyを使用します。
その他の既知の型にはTimestampやDurationがあります。tonicにはこれらの定義が含まれているため、ビルド時にインポートできます。
import "google/protobuf/empty.proto";
service Health {
rpc Ping (google.protobuf.Empty) returns (google.protobuf.Empty);
}パッケージによるバージョン管理
greeter.v1のようにパッケージ名へバージョンを含めると、APIを安全に発展させられます。互換性を壊す変更はgreeter.v2に追加し、v1は提供し続けられます。
この慣例により、生成されるRustモジュールも整理されます。greeter::v1とgreeter::v2を共存させられます。
package greeter.v1;
// later, a parallel file:
// package greeter.v2;フィールドの互換性ルール
新しい番号でフィールドを追加することには後方互換性があります。古いクライアントはそのフィールドを無視します。フィールドを削除する場合は、その番号と名前をreserveしないと危険です。
予約しておくことで、廃止したフィールド番号が再利用され、デコードが壊れるのを防げます。
message User {
reserved 3, 5;
reserved "legacy_token";
string id = 1;
string email = 2;
}理解度チェック
proto3のサービス定義についての理解を確認しましょう。
まとめ
proto3でサービスとメッセージを定義しました。安定したフィールド番号、スカラー型からRust型への対応、列挙型、繰り返しフィールドとネストされたフィールド、4種類のRPC形式、既知の型、パッケージによるバージョン管理について学びました。
次は、tonic-buildを使ってこれらの定義をRustコードに変換します。
よくある質問
「Protobufとサービス定義」レッスンは無料ですか？
はい。「Protobufとサービス定義」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Learn Rust Codingコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Learn Rust Codingコースには全4レッスンが含まれています。
「Protobufとサービス定義」で何を学びますか？
protoでAPIを記述します。 ブラウザで直接実行するハンズオンコードでLearn Rust Codingを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
Learn Rust Codingを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのLearn Rust Codingは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン1/4です。
「Protobufとサービス定義」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このLearn Rust Codingレッスンでコードを書いて実行できますか？
はい。すべてのLearn Rust Codingレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。
このコースのすべてのレッスン
- Protobufとサービス定義
- tonic-buildでコードを生成する
- gRPCサーバーを実装する
- gRPCクライアントから呼び出す