では、RAML ですか、それとも OAS (Swagger) ですか?

マイクロサービスの動的な世界では、あらゆるものが変更される可能性があり、さまざまなフレームワークやアーキテクチャを使用して、あらゆるコンポーネントを別の言語で書き直すことができます。 内部のメタモルフォーゼに関係なく、マイクロサービスが外部から永続的に対話できるようにするために、コントラクトのみを変更しないでください。 そして今日は、契約を記述するための形式を選択するという問題について話し、私たちが見つけた成果物を共有します。

投稿が準備されました アンナ・メレクホワ и ウラジミール・ラパティン

マイクロサービス。 Acronis Cyber​​ Cloud を開発するとき、私たちはそれらから逃れることはできないことに気づきました。 そして、マイクロサービスのインターフェイスを表すコントラクトを形式化することなく、マイクロサービスを設計することは不可能です。

しかし、製品に複数のコンポーネントが含まれており、受託開発が定期的な活動になると、プロセスの最適化について考えずにはいられなくなります。 インターフェイス (コントラクト) と実装 (マイクロサービス) は相互に一致する必要があり、異なるコンポーネントが同じことを同じ方法で実行する必要があり、これらすべての決定を一元的に行う意思決定がなければ、各チームは次のことを強いられることは明らかです。それらを得るために何度も時間を費やしてください。

Amazon マイクロサービスの図 つぶやき Amazon CTO、Werner Vogelis 氏
ジレンマとは何ですか? 事実上、マイクロサービスを操作するには、HTTP Rest と Google の gRPC の XNUMX つの方法があります。 Google のテクノロジー スタックに巻き込まれたくなかったので、HTTP Rest を選択しました。 HTTP REST コントラクトのアノテーションは、RAML と OAS (以前は Swagger として知られていました) の XNUMX つの形式のいずれかで記述されることが多いため、すべての開発チームは標準のいずれかを選択する必要に直面しています。 しかし、結局のところ、この選択をするのは非常に難しい場合があります。

なぜ注釈が必要なのでしょうか?

注釈は、外部ユーザーが HTTP インターフェースを通じてサービスで何ができるかを簡単に理解できるようにするために必要です。 つまり、基本レベルでは、アノテーションには少なくとも、使用可能なリソースのリスト、その HTTP メソッド、リクエスト本文、パラメータのリスト、必要なヘッダーとサポートされているヘッダーの表示、および戻りコードと応答形式が含まれている必要があります。 コントラクトのアノテーションの非常に重要な要素は、口頭での説明 (「このクエリ パラメーターをリクエストに追加すると何が起こるか?」、「どのような場合にコード 400 が返されるか?」) です。

ただし、多数のマイクロサービスを開発する場合は、書き込まれたアノテーションから追加の価値を抽出する必要があります。 たとえば、RAML/Swagger に基づいて、膨大な数のプログラミング言語でクライアント コードとサーバー コードの両方を生成できます。 マイクロサービスのドキュメントを自動的に受信して、開発者ポータルにアップロードすることもできます :)。

構造化された契約説明の例

あまり一般的ではありませんが、契約の説明に基づいてマイクロサービスをテストする習慣があります。 アノテーションとコンポーネントの両方を作成した場合は、さまざまなタイプの入力データを使用してサービスの適切性をチェックする自動テストを作成できます。 サービスはアノテーションに記載されていない応答コードを返しますか? 明らかに間違ったデータを正しく処理できるでしょうか?

また、コントラクトそのものだけでなく、アノテーションを可視化するツールも高品質に実装されているため、マイクロサービスによる作業の簡素化が可能です。 つまり、アーキテクトが契約を定性的に記述した場合、それに基づいて、デザイナーと開発者は追加の時間コストをかけずにサービスを他の製品に実装します。

追加のツールを有効にするために、RAML と OAS の両方には、標準で提供されていないメタデータを追加する機能があります (たとえば、OAS では次のように行われます。).

一般に、マイクロサービスのコントラクトを使用する際の創造性の余地は非常に大きいです...少なくとも理論上は。

ハリネズミとヘビの比較

現在、アクロニスの優先開発分野はアクロニス サイバー プラットフォームの開発です。 Acronis Cyber​​ Platform は、サードパーティ サービスと Acronis Cyber​​ Cloud およびエージェント部分を統合する新しいポイントです。 RAML で記述された内部 API には満足していましたが、API を公開する必要があるため、作業にどのアノテーション標準を使用するのが最適かという選択の問題が再び生じました。

当初、解決策は 2 つあるように見えました。最も一般的な開発は RAML と Swagger (または OAS) でした。 しかし実際には、少なくとも 3 つではなく、XNUMX つ以上の選択肢があることが判明しました。

一方では、強力で効率的な言語である RAML があります。 階層と継承が適切に実装されているため、この形式は多くの記述を必要とする大企業、つまり XNUMX つの製品ではなく、コントラクトの共通部分 (認証スキーム、同じデータ型、エラー本体) を持つ多数のマイクロサービスを必要とする大企業に適しています。 。

しかし、RAML の開発者である Mulesoft は、開発を進めている Open API コンソーシアムに参加しました。 スワガー。 したがって、RAML は開発を中止しました。 イベントの形式を想像するには、主要な Linux コンポーネントのメンテナが Microsoft に退職したと想像してください。 この状況により、Swagger を使用するための前提条件が作成されます。Swagger は動的に開発されており、最新の XNUMX 番目のバージョンでは、柔軟性と機能の点で実質的に RAML に追いつきます。

一つではないが...

結局のところ、すべてのオープンソース ユーティリティが OAS 3.0 に更新されているわけではありません。 Go のマイクロサービスにとって最も重要なことは、適応が欠如していることです。 やり手 標準の最新バージョン用。 ただし、Swagger 2 と Swagger 3 の違いは次のとおりです。 巨大。 たとえば、XNUMX 番目のバージョンでは、開発者は次のことを行います。

• 認証スキームの説明を改善
• 完成した JSONスキーマのサポート
• 例を追加する機能をアップグレードしました

この状況は面白いものです。標準を選択するときは、RAML、Swagger 2、および Swagger 3 を個別の代替手段として考慮する必要があります。 ただし、オープンソース ツールを適切にサポートしているのは Swagger 2 だけです。 RAML は非常に柔軟で複雑ですが、Swagger 3 はコミュニティによるサポートが不十分であるため、独自のツールまたは商用ソリューションを使用する必要がありますが、これらは非常に高価になる傾向があります。

さらに、既製のポータルなど、Swagger に多くの優れた機能がある場合は、 editor.swagger.io注釈をアップロードして、詳細な説明、リンク、接続を含む視覚化を取得できますが、より基本的であまりフレンドリーではない RAML の場合、そのような機会はありません。 はい、GitHub 上のプロジェクトの中から何かを検索し、そこで類似のものを見つけて自分でデプロイすることができます。 ただし、いずれの場合も、誰かがポータルを保守する必要があり、基本的な使用やテストのニーズにはあまり便利ではありません。 さらに、Swagger はより「無原則」、つまりより自由です。コード内のコメントから生成できますが、もちろん、これは API の第一原則に反しており、RAML ユーティリティのいずれでもサポートされていません。

かつて、私たちはより柔軟な言語として RAML を使い始めましたが、その結果、多くのことを自分たちで行う必要がありました。 たとえば、プロジェクトの XNUMX つは次のユーティリティを使用します。 いたずら 単体テストでは RAML 0.8 のみをサポートします。 そのため、ユーティリティが RAML バージョン 1.0 を「食べる」ことができるように松葉杖を追加する必要がありました。

選ぶ必要がありますか？

RAML のソリューションのエコシステムの完成に取り組んだ結果、RAML を Swagger 2 に変換し、すべての自動化、検証、テスト、およびその後の最適化をその中で実行する必要があるという結論に達しました。 これは、RAML の柔軟性と Swagger のコミュニティ ツール サポートの両方を活用する良い方法です。

この問題を解決するには、コントラクト変換を提供する XNUMX つのオープンソース ツールがあります。

1. oas-raml-コンバーター は現在サポートされていないユーティリティです。 作業中に、多数のファイルに「分散」した複雑な RAML に多くの問題があることがわかりました。 このプログラムは JavaScript で書かれており、構文ツリーの再帰的走査を実行します。 動的型付けにより、このコードを理解するのが難しくなるため、瀕死のユーティリティ用のパッチを作成するのに時間を無駄にしないことにしました。
2. ウェバピパーサー - 同じ会社のツールで、あらゆるものをあらゆる方向に変換できると主張しています。 現在までに、RAML 0.8、RAML 1.0、および Swagger 2.0 のサポートが発表されています。 ただし、私たちの調査時点では、そのユーティリティはまだありませんでした。 非常に 湿って使えない。 開発者は一種の IR将来的に新しい標準を迅速に追加できるようになります。 しかし、今のところそれはうまくいきません。

私たちが直面した困難はそれだけではありません。 パイプラインのステップの XNUMX つは、リポジトリからの RAML が仕様に対して正しいことを検証することです。 いくつかのユーティリティを試しました。 驚いたことに、彼らは皆、さまざまな場所で、まったく異なる悪口で私たちの注釈を罵りました。 そして、必ずしも要点を絞っているわけではありません:)。

最終的に、私たちは今では時代遅れになってしまったプロジェクトに落ち着きましたが、このプロジェクトにも多くの問題がありました (突然クラッシュしたり、正規表現を使用するときに問題が発生したりすることがあります)。 したがって、無料ツールに基づいて検証と変換の問題を解決する方法が見つからず、商用ユーティリティを使用することにしました。 将来的には、オープンソース ツールがより成熟するにつれて、この問題は解決しやすくなる可能性があります。 その間、「仕上げる」ための人件費と時間コストは、商用サービスのコストよりも重要であるように私たちには思えました。

まとめ

こうしたことを踏まえて、私たちは経験を共有し、契約を説明するためのツールを選択する前に、そのツールに何を求めるのか、どのくらいの予算を投資するつもりなのかを明確に定義する必要があることに注意したいと思いました。 オープンソースのことを忘れても、チェック、変換、検証に役立つサービスや製品がすでに多数存在します。 しかし、それらは高価であり、場合によっては非常に高価です。 大企業の場合、このようなコストは許容範囲ですが、新興企業にとっては大きな負担となる可能性があります。

後で使用するツールのセットを決定します。 たとえば、コントラクトを表示するだけの場合は、RAML ではサービスを自分で構築して保守する必要があるため、美しい API を備えた Swagger 2 を使用する方が簡単です。
タスクが増えれば増えるほど、ツールの必要性も広がります。ツールはプラットフォームごとに異なります。将来のコストを最小限に抑える選択をするために、利用可能なバージョンをすぐに理解することをお勧めします。

しかし、今日存在するすべての生態系は不完全であることを認識する価値があります。 したがって、社内に「より柔軟に考えを表現できる」という理由でRAMLで作業することを好むファンや、逆に「より明確である」という理由でSwaggerを好むファンがいる場合は、彼らに任せるのが最善です。どの形式のツールもファイルによる変更が必要なため、彼らはそれに慣れており、それを望んでいます。

私たちの経験に関しては、次の投稿で、RAML-Swagger アーキテクチャに基づいてどのような静的チェックと動的チェックを実施するか、契約からどのようなドキュメントを生成するか、そしてそれがどのように機能するかについて説明します。

登録ユーザーのみがアンケートに参加できます。 ログインお願いします。

マイクロサービス コントラクトに注釈を付けるために使用する言語は何ですか?

• RAML 0.8

• RAML 1.0

• スワガー 2

• OAS3 (別名)

• 青写真

• Другой

• 使用しない

100 人のユーザーが投票しました。 24名のユーザーが棄権した。

出所： habr.com