はじめに

.proto ファイルの記述をサクっと始めるための記事。
基礎的な内容のみに絞り記述する。

公式ドキュメントは Language Guide (proto3) である。

.proto ファイルの書き方

構文

ファイルの全体像を先に示す。

syntax = "proto3";

package myapp;

service AddressBookService {
  rpc Search (SearchRequest) returns (SearchResponse);
}

message SearchRequest {
  string name = 1;
}

message SearchResponse {
  Person person = 1;
}

message Person {
  int32 id = 1;
  string name = 2;
  string email = 3;
}

バージョン

バージョンを指定する。

syntax = "proto3;

パッケージ

パッケージを指定する。
名前の衝突を避けるための名前空間の役割を果たす。

pakcage myapp;

import

import 文で他のパッケージを読み込むことができる。
対象には パッケージ名.オブジェクト でアクセスすることができる。

import "../other_app/addressbook.proto";

message OtherApp {
	other_app.Person = 1;
}

サービスとメソッド

サービスとはメソッドを論理的にまとめたものである。
メソッドは1つのエンドポイントとなる。

service AddressBookService {
  rpc Search (SearchRequest) returns (SearchResponse);
}

スカラー型

型には主にスカラー型とメッセージ型の2つがある。
その他にはリスト、マップ、Enum などがある。

本記事ではではよく使いそうなスカラー型を抜粋する。
全てのスカラー型は Scalar Value Types に書いてある。

整数

int32
int64

float
double

文字列

string

真偽値

bool

バイト文字列

bytes

メッセージ型

メッセージ型と呼ばれる複数のフィールドを持つ型を定義できる。
コードを自動生成する際に、構造体やクラスとして書き出される。

message Person {
	int32 id = 1;
	string name = 2;
	repeated string items = 4;

    string phone_number = 5 [deprecated = true]

	reserved 3, 6 to 10;
	reserved "fax_number";
}

タグナンバー

なぜ 1 や 2　を代入しているのかと感じるが、これはタグナンバーと呼ばれるものである。
コードのシリアライズ後のフォーマットでフィールドを識別するために使用される。

メッセージ内で一意である必要がある。

廃盤

運用中にフィールドを削除した場合、そのタグナンバーは廃盤とすることが望ましい。
再利用すると、フィールド識別上の不具合につながる可能性があるためである。

reserved

廃盤であることを明示する識別子。

deprecated

非奨励であることを明示するオプション。

列挙型

0始まりで記述する。

enum PhoneType {
	option allow_alias = true;

	UNKOWN = 0;
	MOBILE = 1;
	OFFICE = 2;
	SCHOOL = 2;
}

allow_alias

同じ値に異なるラベルを割り当てることを許可するオプション。
ラベルを2つ以上指定した場合、エイリアスとして動作する。

リスト

いわゆる配列である。

repeated string items = 1;

repeated

リスト（配列）を表現する識別子。
スカラー型、メッセージ型のどちらにも適用可能。

マップ

いわゆる連想配列である。

map<string, AddressBook> address_books = 1;

キー

キーには整数値、文字列、真偽値のみ指定可能。

Well Known Types

Build-in で事前定義された便利なメッセージ型郡。
日時、期間、Any などが揃っている。
google.prorotbuf パッケージで定義されている。

import "google/protobuf/timestamp.proto";
import "google/protobuf/duration.proto";

終わりに

gRPC の記事も書いたのでよかったらぜひ。