【protocol buffers】protoファイルにコメントを書く

protocol buffers proto

protocol buffers は割と使うのですが、protoファイルにコメントを書くと生成したコードにも各言語のコメントをつけてくれることを最近知りました。
全く難しいことないのですが、メモがてら。

目次

protoファイルにコメントを書く

// コメントのような感じで、コメントを書くことができます。
rpcやmessage、messageのfieldsなどに書いてみます。

syntax = "proto3";

option go_package = "pkg/proto";

package comment;

service CommentService {
  // Comment is the method for comment.
    rpc Comment(CommentRequest) returns (CommentResponse);
}

// CommentRequest is the request message for Comment method.
message CommentRequest {
  // id is the id of the comment.
  string id = 1;
}

// CommentResponse is the response message for Comment method.
message CommentResponse {
  // id is the id of the comment.
    string id = 1;
  string name = 2;
  User user = 3;
}

// User is the user message.
message User {
  string id = 1;
  string name = 2;
  string email = 3;
  string password = 4;
  string created_at = 5;
  string updated_at = 6;
}

以下のコマンドで、goファイルを生成します。comment.pb.goとcomment_grpc.pb.goというファイルができます。

protoc --proto_path=. --go_out=. --go-grpc_out=. ./comment.proto

※ protocコマンドがない場合には、先に以下を実行してインストールします。

go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2
export PATH="$PATH:$(go env GOPATH)/bin"
...
// CommentRequest is the request message for Comment method.
type CommentRequest struct {
    state         protoimpl.MessageState
    sizeCache     protoimpl.SizeCache
    unknownFields protoimpl.UnknownFields

    // id is the id of the comment.
    Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
}
...

// CommentServiceServer is the server API for CommentService service.
// All implementations must embed UnimplementedCommentServiceServer
// for forward compatibility
type CommentServiceServer interface {
    // Comment is the method for comment.
    Comment(context.Context, *CommentRequest) (*CommentResponse, error)
    mustEmbedUnimplementedCommentServiceServer()
}

protoファイルに書いたコメントが反映されています。

deprecatedオプション

非推奨の旨をコメントに書く場合には、deprecatedオプションが使えます。
deprecatedオプションを使うと、コンパイル。。。。

先程のprotoファイルのコメントを変更します。

...
// CommentResponse is the response message for Comment method.
message CommentResponse {
  // id is the id of the comment.
    string id = 1;
  string name = 2;
  // user is deprecated.
  User user = 3 [deprecated = true];
}

// User is the user message.
message User {
  option deprecated = true;
  string id = 1;
  string name = 2;
  string email = 3;
  string password = 4;
  string created_at = 5;
  string updated_at = 6;
}
...

生成したGoファイルは以下のようになりました。

...
// CommentResponse is the response message for Comment method.
type CommentResponse struct {
    state         protoimpl.MessageState
    sizeCache     protoimpl.SizeCache
    unknownFields protoimpl.UnknownFields

    // id is the id of the comment.
    Id   string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
    Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
    // user is deprecated.
    //
    // Deprecated: Do not use.
    User *User `protobuf:"bytes,3,opt,name=user,proto3" json:"user,omitempty"`
}

...

// User is the user message.
//
// Deprecated: Do not use.
type User struct {
    state         protoimpl.MessageState
    sizeCache     protoimpl.SizeCache
    unknownFields protoimpl.UnknownFields

    Id        string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"`
    Name      string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
    Email     string `protobuf:"bytes,3,opt,name=email,proto3" json:"email,omitempty"`
    Password  string `protobuf:"bytes,4,opt,name=password,proto3" json:"password,omitempty"`
    CreatedAt string `protobuf:"bytes,5,opt,name=created_at,json=createdAt,proto3" json:"created_at,omitempty"`
    UpdatedAt string `protobuf:"bytes,6,opt,name=updated_at,json=updatedAt,proto3" json:"updated_at,omitempty"`
}

Deprecated: コメントがつくことで、呼び出し側でも警告が出るのでわかりやすいですね。

おわりに

protoファイルにコメントを書いてみました。適切なコメントを残せるようになりたいですね。