Contentsプロトコルって何?メタって何?なにか帰ってきたけど・・・サーバー側でいくつかのケースが想定できる場合サーバーからクライアントに指示をだすじゃぁサーバーは何を返すべきか?まとめこんにちは、殿内(@tonoccho)ですIBM社の製品にWebSphereMQというのがあります。この製品はとにかくログの出方が凄まじく、また、マニュアルにも「こういうのが出たらこうしましょう」ということもよく書かれていました。この製品では「理由コード」というのと「完了コード」というのが設定されており、これを見ることで「一体何がどうなったのか」というのがわかるようになっています。このアイデアって普遍的だなと言う話です。プロトコルって何?メタって何?この話はtech的なものなので、まずは用語の話です。プロトコルというのは「処理に参加する当事者の間でやり取りするデータの形式」くらいでいいと思います。ウェブブラウザとウェブザーサーの間ではHTTPというプロトコルが使われていて、送受信されるデータのどこからどこまでにどんな情報が入っているかと言うのがきっちり消えられています。次にメタですが、これは情報の情報なんて言われて昔煙に巻かれた気分になっていましたが、その情報が一体何かを説明するものです。1234567という数字があったとします。(単位:円)となれば1234567がお金だとわかります。このようにデータに付随してそれがないかを説明するのがメタと思えばいいでしょう。アニメで「メタ発言」とか言うのと見るんですがこのメタが何かはちょっとわかりません。なにか帰ってきたけど・・・REST、RMI、CORBA、SOAPなどなどリモートサーバーに処理をしてもらって値を受け取るという方式はたくさんあるんですけど、その結果って「何?」というのがつきまといます。この「何?」というのは処理って成功した?失敗した?失敗したなら原因は?ユーザー起因?サーバーエラー?失敗したとしてリトライしてもいいの?良いなら何秒後が良い?リトライできないならどんなメッセージ表示すればいい?値は想定したものが全部帰ってきている?それとも部分的に返した?などなどとにかくいろいろあるわけです。この中には普遍的に必要なものもあれば処理に応じて必要なものもあると思います。クライアントとしては「受け取ったデータが一体どういうものかを検査しないと次の処理ができない」というのは筋が悪いわけです。「APIからデータが来たけど処理が失敗したしリトライも不可なのでエラーメッセージ出して終わろう」というのを一発で終わらせられるのが良いわけです。余計なサーバーリクエストもしないで済むでしょうし。サーバーが更に別のサーバーにアクセスするような場合です。すると向こうのサーバーが一体どうなったのかなんていうのはクライアントにはわかろうはずもありません。「向こうのサーバーがあるならこう、ないならこう」というのをしっかりと戻り値に表現させる必要があります。顧客リストをRESTで取得する、APIサーバーはSOAPで顧客DBにアクセスして一覧を作成して返す、というようなケースですね。APIが仮に空っぽのリストをぽんと返してきたとします。その時戻り値にリストしかない場合どう書きますか?リストが空の場合は、顧客が0件、または、SOAPサーバーのエラーですと書くことになると思います。クライアントとしてはこれでは困るわけです。顧客が0件ならUIに「まだ顧客が登録されていません」と出したいかもしれないし、SOAPサーバーのエラーなら「サーバーエラーです、しばらくしてからもう一度操作してください」と出したいかもしれません。いうと例えば「プロセスID」でもあれば「このIDに紐づく処理は成功しましたか?」と最悪聞けますが、それすらできないわけです。「データは帰ってきたけどどうなったのかよくわからんなぁ」ということになります。サーバーからクライアントに指示をだすこういったメタ情報は別の視点で見ると「サーバーはクライアントにこうしてほしい」ということでもあります。「失敗したけどリトライしてもいいよ」とか「失敗したしリトライもしないでね」とか。クライアントはこういった仕様に対してコーディングをすることになるので、変更にも強くなりそうです。返す情報が増える分には別に良いけど、変えたり減らしたりするときはどうしよう?ということですね。顧客一覧をリストで返していたのが急に文字列になるとかはありえないですがこれはパブリックインターフェースにおける契約の問題でもあるのでここでは触れません。サーバーは何を返すべきか?世の中にはいろんな優秀なWebAPIがあるのでそれらに習うのも手ですが、かと言ってこれらを全部完全にコピーすると実装が大変です。最低限以下のものがあれば社内システムでは困らないのではと思います。処理の結果データ処理の結果(成功、失敗)結果の理由(失敗のときのユーザー起因、システム起因区分)失敗時のメッセージID(問い合わせ時に使用する)他にはこういうのがあってもいいと思います。リトライの可否(リトライ間隔はどこかに書いても良い)ユーザーに表示してほしいメッセージ(この辺統一しとくとユーザーがググるときに便利)大事なのは「一つのプロパティにたくさんの意味を載せない」ことです。リトライの可否については「秒数で返す」としながら「-1のときはリトライ不可という意味」にするのは良くないと思います。リトライ可否をbooleanで持たせて次にリトライ可能な経過秒数を数字で、だったら良いと思います。失敗時のメッセージIDでログを検索したらそれが出ていることも大事です。まとめリモートなAPIでなにか情報をやり取りするときは、クライアントにどういうことかをきちんと知らせるようにしないと筋が悪いと思いました。考え20192019/062019/06/26技術の最新記事Jekyllで静的サイトを4ヶ月ほどやったのでここ迄で感じたことを書いてみます。2019)平成のエントリーをすべて消しました。今別サイトに移行中です。