フレームワークが社内で密かなブームとなっています。使ったエラー定義まわりの話をしたいと思います。概要については先日ちょうど社内勉強会用に資料を作ったのでこちらを見てもらえるのが早いです。言えばシンプルなインターフェースとドキュメント(OpenAPI)の自動生成が強力なフレームワークになります。今回注目したいのはドキュメントの自動生成のほうです。開発チームでもドキュメントとAPIの実際の仕様が一致しない問題が時々発生していて、どうドキュメントを管理していくかが課題となっています。形式のドキュメントを出力してくれます。アクセスするときのソースを自動生成をしたりできます。作ってドキュメントが実用に耐えうるのかやってみました。動かすサンプルを検証してくれており、スムーズにプロジェクトに投入できました。仕様書として渡してみたところ、正常系に関してはうまく機能することができました。判別できず、別途仕様を共有する必要がありました。記載されていませんでした。認証が不正なのか、渡してるパラメータがおかしいのか、それとも権限・状態がおかしいのかという情報はクライアント側の挙動を適切にするためにも不可欠なものです。系のエラーについてはドキュメントとして明記しておきたいです。定義を付加情報として加えてあげる必要がありました。構造をそのまま記述)することで、生成されるドキュメントにエラー情報を付与することができます。ステータスコードとしては同じだがエラーの理由が異なるケースがあるといったことがあげられます。インターフェースを記述するためのドキュメントなので、エラー内容まで関与しないというのは正しいのですが、そうするとエラー管理のための別のドキュメントを用意しなくてはなりません。上でエラーの種別まで列挙するようにしたいです。実際にやってみたやっと本題になります。実現できないかをやってみました。ドキュメントとしては上記のようなイメージになります。応答するステータスコードが列挙され、200以外のときはそのレスポンスの内容も網羅されているのが理想的です。叩く側がどんなエラーをハンドリングしなくてはならないのかが明確になり、連携を円滑に進めることが出来ます。(HTTPステータスコードとは別にエラーコードを定義するのもよさそうです。側のコードも複雑になりすぎないということを目標とします。定義をそのままコードに埋め込めてしまうので、愚直に返しうるエラーを文字列で手動編集する、みたいなことは避けたいです。認証のエラー文言が変わる度、全部のビューを編集するのはつらい...。独自のエラーを定義していきます。いう共通のエラーを定義してあげて、これを継承して具体的なエラーを列挙していきます。ステータスコードを吐くので、ここで一緒に定義してしまいます。このパラメータを設定していたら強制的にエラーを発生。入力が不正であればエラー。中でその例外を利用するようにします。関数の中でのみ利用するようにするとエラーの管理が簡単です。エラーになってしまいます。扱えるようエラーハンドラを追加します。内部のエラーとも構造を共通化できるため、インターフェースとしてすっきりします。独自の構造を定義して返してあげてもよいです。ステータスコードとは別にユニークなエラーコードを振って返すようにすると、クライアントでもハンドリングしやすそうです。仕様書にはまだエラー情報が反映されてません。自動でエラーを登録できると理想的なのですが、コードを静的に解析したりしない限りはどんな例外が発せられるかは把握できません。半手動でエラーレスポンスを列挙することにします。書式に変換するユーティリティ関数を用意してあげます。追記を行うだけにしています。...のように変更します。ユーティリティ関数へ渡しているだけです。発生させないみたいなルールとともに実装すれば管理しやすいかと思われます。エラー定義を統一して扱えるようにできました。定義を生成することが出来ます。して出力し外部のツールから利用することも可能です。コンソールを出力できます。付きで表示してくれるので便利です。エラーも含めてドキュメント化することができました。管理のコストを下げつついい感じの仕様書をつくれるので便利ですね。活用していきたいと思いました。説明に利用したコードのサンプルはこちら。Corp.引用をストックしましたストック一覧を見る閉じる引用するにはまずログインしてくださいログイン閉じる引用をストックできませんでした。再度お試しください閉じる限定公開記事のため引用できません。