API仕様を書く（6）ー gRPC protoファイル（2） ー

（「API仕様を書く（5）ー gRPC protoファイル ー」からの続き）

gRPCから返すコードについては、Go言語用のこちらの定義が分かりやすいです。個々のコードは定義を読めば使い方は分かるかと思います。

API仕様には、gRPCで提供するサービスが提供する機能に応じて、どのような場合にどのコードが返されるかを書く必要があります。ただし、UnknownとInternalに関しては注意が必要です。

Go言語のgRPC用のミドルウェアでは、statusパッケージ※1を使わずに生成したerrorを返すと、コードとしてUnknownが返されます。たとえば、DBへのアクセスして返されたerrorをそのままRPCのerrorとして返すと、コードはUnknownとなります。つまり、Unknownとは適切にコードが指定されなかったことを意味します。RPCが提供する機能に対する適切なコードを返すためには、「エラー翻訳」（Javaで言うところの「例外翻訳」※）を行う必要があります。適切なエラー翻訳を行うためには、RPCが提供する機能に対して概念的に正しいコードを仕様に定義する必要があります。
※1 google.golang.org/grpc/status
※2 『Effective Java 第3版』の「項目 73 抽象概念に適した例外をスローする」

返すコードとしてのでInternalは、呼び出した側の問題ではなく、呼び出された側の何らかの不変式（invariant）が成立していないときに返します。言い換えると、設計上のバグと考えられるものはInternalを返すことになります。Java言語で言えばAssertionErrorが明示的にスローされるような場合です（『API設計の基礎』の「第3章 防御的プログラミング」）。

UnknownとInternalは、どのRPCでも返される可能性があるので、個別のRPCの説明（前の記事の③）に書く必要はなく、サービス全体の説明（前の記事の①）に書けばよいと思います。どちらも、「呼び出し側の問題ではなく、呼び出された側の実装の問題なので、開発者への報告を求める」の旨が書かれていればよいかと思います。

（続き）