RESTful サービスを構築するとき、私は常に、システムのユーザーに配布できるクライアント ライブラリをどのように開発するかという問題に直面します。
簡単な例を挙げると、エンティティの呼び出し担当者がいて、RESTFul サービスを通じて基本的な CRUD 機能をサポートしたいとします。
人を保存するには、クライアントは POST メソッドを呼び出し、JSON などの適切なデータ構造を渡す必要があります。
誕生日で人を見つけるために、サービスは人のオブジェクトのリストを含む応答で応答します
- 個人を削除するために、サービスは成功または失敗のメッセージで応答します。
上記の例から、クライアントと共有できる 2 つのオブジェクトが既に存在します: person オブジェクトと response オブジェクトです。これを達成するためにいくつかの方法を試しました：
サーバー呼び出しからの Person オブジェクトをクライアント ライブラリに含めます。このアプローチの欠点は次のとおりです。
クライアント コードは、サーバー コードと密結合になります。サーバー側からの変更には、同じリリース中にクライアントが更新を行う必要があります。
Person のオブジェクトには、永続化またはシリアル化に使用される依存関係または注釈が含まれる場合があります。クライアントはこのライブラリを気にしません
が、それらを含めることを強制されます。
Person のオブジェクトに直接関係しないが、必須フィールドを設定するヘルパー クラスを含む Map のサブクラスを含めます。
- 疎結合ですが、サーバーからのデータ構造が変更されたときにサイレント エラーが発生する可能性があります。
- Apache Thrift、WADL、Json Schemaなどの記述ファイルを使用して、コンパイル時にクライアント オブジェクトを生成します。これにより、オブジェクトの依存関係の問題は解決されますが、依然として強い依存関係が作成されます。これは、SOAP の WSDL を作成するのとほとんど同じです。ただし、このアプローチは広く使用されておらず、例を見つけるのが難しい場合もあります。
アプリケーションのクライアント jar を公開する最良の方法は何ですか?
- クライアントが使いやすい
- 密結合を作成せず、サーバー側の変更に対するある程度の許容度を作成しません
API のドキュメントの方が優れていると答えた場合、Java アノテーションと POJO からこれらのドキュメントを生成するための優れたツールは何ですか。