web-dev-qa-db-ja.com

APIエンドポイントコントラクトをどのように整理しますか

サービス間のコミュニケーションで私たちが持っている「信頼」を向上させようとしているところ。

Background：「契約」は、実装するインターフェースを定義するコードの一部を共有する問題でしたが、長年にわたって、共有コードが変更され、多くの異なる実装（soap、msmq、残りなど）すべてが同じインターフェイスを実装しているとは言えますが、マッピングが適切に機能していないため、「マッピング」マイクロサービスのフォレストが実装されましたが、これも異なるバージョンで表示されます。開発と運用の両方がこれに苦しんでいます。

Intention： SwaggerやAPIブループリントなどを使用して、外部のエンドポイントのコントラクトを定義したいと思います。 swaggerを使用すると、swagger.jsonの「contract」とswagger.jsonを比較して、サービスの実装を主張し、APIブループリントでは「dredd」を比較できます。 MSMQベースのトランスポートの場合、他のアプローチが必要になりますが、メッセージ内の構造の規約は、httpエンドポイントと同じ理由で準拠する必要がある/準拠する必要があると思います。

確認方法の詳細は問題ではありません。問題は次のとおりです。これらの契約をどのように整理しますか？変更することはできず、新しいバージョンでのみ発生するコントラクトの内部リポジトリを用意し、検証プロセスにどのコントラクトが（おそらく）実装されているかを通知する必要がありますか？上記の契約レポは、検証プロセスおよび私たち（および外部）の開発者が読み取りアクセスできる必要があります...

背景で説明されている問題に関する入力はありがたいですが、おそらく私は解決策を間違った方法で探していますか？

apiapi-designsoamaintainabilityweb-api
7
Julian

IMOの最も簡単なソリューションは、プルリクエストと優れた自動テストカバレッジを利用することです。これは、使用されていない人にとってはパラダイムシフトですが、利点は否定できません。

Githubにはいくつかの優れたドキュメントがあります： https://help.github.com/articles/creating-a-pull-request/ BitBucketと同様： https://www.atlassian.com/git/tutorials/making-a-pull-request /

PRは、チーム全体が参加している場合にのみ機能します。新しいPRが送信されると、クリティカルパス上の開発者以外のすべての開発者は、現在行っていることを中止し、PRを確認してthis code will break the current contract for the Xyz method, please revisitまたはlooks goodのようなコメントを残すために数分かかる必要があります。多くの開発者は、コードをマージする必要があると考える場合、単に+1を残します。コードについて十分な目と承認を得たら、それをdevelopmentブランチにマージできます。

さらに、チームが適切な自動テストを維持することを確認します。

git、GithubまたはBitBucketを使用せず、変更できない、または変更したくない場合...

あなたはいくつかの異なる方法でこれに取り組むことができます：

  1. 内部システム：これにより、メソッドの署名とコメントに基づいてAPI /エンドポイントのドキュメントが生成および提供されます。自動化ツールを使用して、ドキュメントをHTML形式で生成できます。これの問題は、開発者がコントラクト（メソッドシグネチャ）を簡単に変更し、コードをコミットして問題を解決できることです。利点は、実質的にゼロのメンテナンスと、開発者が既存のエンドポイントコントラクトを発見するための読み取り可能/検索可能なインターフェイスです。

  2. 外部システム：これはあなたが望むものに似ています。これはいくつかの方法で実行できます。 1つの方法は、Yardなどのドキュメントツールを使用して現在のベースラインドキュメントを生成し、契約を変更する必要がある場合はいつでもそれらを変更するタスクを割り当てることです。この方法でこれを行うと、個別の（外部）Webスタックをサービスとしてセットアップできます。もう1つの方法は、必要な機能をモデル化した別のアプリを作成することです。 KlassおよびMethodモデルがあります。不利な点は、誰かがそれを維持しなければならないことです。利点は、開発者がコントラクトを簡単に変更できなかったり、コードへのアクセスを制限した場合にはまったく変更できないことです。

上記のユースケースに基づいて、私は別のアプリを使用する傾向があります。チームリーダーまたは管理者がAPI /エンドポイントの契約とバージョンを変更するためのメンテナンスインターフェイスを持つことができます。また、開発者が物事を検索するための読み取り専用のインターフェースを持つこともできます。

ワークフロー：

  • バグが開発者のデスクに到着しました。
  • 開発者は、特定の方法で問題の根本を発見します。
  • 開発者は外部の契約サイトでメソッドを検索し、戻り値を変更する必要があることを発見しました。これにより、契約が破られます。
  • 開発者はチームリードまたは変更管理委員会に発見をもたらします
  • チームリーダーは、変更に応じて中断するコードも適宜変更するよう開発者に割り当てます
  • 開発者はバグを修正するコードを記述します（うまくいけば自動テスト）
  • この時点で、開発者は完全なリグレッションテストスイートを実行して、新しいコードが予期しないものを壊していないことを確認する必要があります。
  • 開発者は（テスト済みの）バグ修正をコミットします
2
Midwire

最終的に、契約の内部開発ドキュメントとしてテストを使用してこれを行いました https://Gist.github.com/JulianMay/899d7cc7a82f1ca7c893547d37732f86

0
Julian