マイクロサービスアーキテクチャにおける多くのアプリケーションのAPIエンドポイントの維持と文書化

マイクロサービスを使用する上での最大の問題点の1つは、APIが十分に文書化され、APIがダウンストリームアプリケーションに影響を与えずに動作を変更しないことを確認することです。この問題は、相互に依存し合うサービスが多数ある場合に増幅されます。多分その時点であなたは間違ったマイクロサービスをやっていますが、私は余談です。

異なるチームが所有する20のマイクロサービスを継承していて、どのアプリケーションが他のどのアプリケーションのAPIエンドポイントを使用するかについての明確なドキュメントがないとします。これを文書化する規定された方法はありますか？最初に、各アプリケーションのエンドポイントを分析してデータベーステーブルに追加し、多対多テーブル（ほとんどすべてがRailsアプリケーションです）で各アプリケーションとアプリケーションのルート間にFK関係を作成することを考えました。しかし、これがこれを処理するための良い方法であるかどうか、または私はここで車輪を再発明しているかどうかわかりません。

振り返ってみると、マイクロサービスをゼロから始めている場合、これはアプリケーションの相互作用を文書化するのにそれほど悪くない方法かもしれません。これにより、データベースを使用して単一の信頼できる情報源が維持され、エンドポイントへの変更は、データベースの変更と連動してアプリケーションで実行されます。考え？

「マイクロサービスアーキテクチャ」の利点の大部分は、それらの関係のすべてを文書化していないことです。各サービスは独自の製品です。また、各サービスの所有者は、独立した製品としてのサービスの運用に責任があります。これには次のようなものが含まれます。

• 「マーケティング」ドキュメント、ユーザードキュメント、変更ログ（非推奨を含む）の公開
• 顧客/消費者が機能をリクエストする方法/バグを報告する方法を提供する
• SLAの維持
• 可能な限り下位互換性のある更新を行い、変更を壊す
• 彼らが直接利用するサービスのニュースフィードを知り、視聴する
• 可能な場合は依存関係のプルーニング
• 保守に関連性がなくなったり、コストがかかりすぎたりした場合のサービス全体の廃止

等々。

とりわけ、私は、マイクロサービスの主要な利点の1つとして、サービス所有者がサービスが行う「1つのこと」に本当に焦点を当てて専門化する機会を強調します。

各製品またはサービスの所有者が独自の依存関係を文書化する場所については、それらがコンパイラの構成（またはビルドスクリプト）に追加されるときに「自然に」発生するはずです。ServiceAが依存しているものを知る必要がある場合はServiceA/Configuration.xml（または何でも）教えてくれます。また、通常、各サービスの所有者は最初に自分の直接の依存関係を図に示しますが、依存関係の依存関係などは想定していません。また、情報が既にコードに含まれている場合、これらの図が今後も維持されるとは必ずしも期待していません。

^{本当に全体像が必要な場合は、configs / buildスクリプトをスキャンしてください。その出力で何をするか、どのように保存するかなどは、データがどのような決定を下すのに役立つかに完全に依存します。}

統合の図を作成し、これをリポジトリに含めることをお勧めします。図をXMLまたはJSONファイルにエクスポートして、このファイルをリポジトリにコミットできる無料のツール（draw.ioなど）を選択します。GithubまたはGitlabを使用している場合は、この図からイメージを生成し、WikiまたはREADME.mdファイルに含めれば、開発者がブラウザーからリポジトリーを視覚化するたびにイメージが表示されます。

同じ戦略をデータベースに使用できます。

APIリソースのドキュメントについては、Swaggerが適切なオプションです。

この問題は、相互に依存し合うサービスが多数ある場合に増幅されます。多分その時点であなたは間違ったマイクロサービスをやっていますが、私は余談です。

これは確かに問題です。