So-net無料ブログ作成
  • ブログをはじめる
  • ログイン

API仕様を書く(6)ー gRPC protoファイル(2) ー [API仕様を書く]

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

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

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

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章 防御的プログラミング」)。

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

(続く予定)



スポンサーリンク





コメント(0) 

コメント 0

コメントを書く

お名前:[必須]
URL:
コメント:
画像認証:
下の画像に表示されている文字を入力してください。

Facebook コメント