web-dev-qa-db-ja.com

大規模なエンジニアリングチームは、WebサービスとクライアントJavaScriptコード間のインターフェース/契約をどのように説明しますか？

フロントエンドチームとバックエンドチームがJSON Web APIの形で通信するための正式な方法を探しています。たとえば、クライアント側のチームがAJAX SPAアプリのJavaScriptとHTMLを作成しているとします。別のチームがバックエンドをJavaなどで作成しているとします。これらのサービスから返されたデータは、特定の「形状」を満たしています。たとえば、

/Person/Read/79

戻るはずです

{
    "id": 79
    "firstName": "Anita",
    "lastName": "Hero"
}

サーバーチームはどのようにしてこの「インターフェース」をJavaScriptチームに伝達できますか？何かのようなもの;

interface person {
    firstName: string;
    lastName: string;
    id: int;
}

JavaScriptチームがコンポーネント、ページ、およびテストを構築できるように、チーム間の正式な契約を探しています。サーバーチームが実際のデータを期待どおりの形で提供することを確信しています。

これは、両側に大規模なチームが存在する状況ではすでに行われていると思いますが、現在のアプローチについては知りません。

私は現在これらの標準を認識していますが、どちらがアクティブであるかはわかりません。

  • [〜＃〜] wsdl [〜＃〜] はXMLベースの説明ですが、XML WebサービスはJSONに有利になりつつあり、WSDLは常に重いと思われるため、JSONベースには無関係です。 dev？
  • WebIDL はHTML5を指定するために使用される言語であるため、最新のものになっていますが、そのためのツールはありますか？
  • JSONSchema は有望に見えますが、やはり、ツールはどのようなものですか？
  • Swagger 良さそう-ポインターの@Laivに感謝します。

では、クライアント側とサーバー側の異なるチーム間でこれがどのように通信されるかについての説明はありますか？

architectureinterfacesclient-server
7
user62575

フロントエンドとバックエンドのチームがJSON Web APIの形で通信するための正式な方法を探しています

@RobertHarveyが頭に釘を打ちました。

これがパブリックAPIでない限り、契約を通信する通常の方法は、それを文書化することです。チームの規模に関係なく機能します。実際、チームが大きければ大きいほど、うまく機能します

コメントでSwaggerを提案しました。 Swaggerを使用して、開発者に優しいアプローチを提案します。開発者が対話できる何か。また、取り組み、消費します。テストのために Swagger Editor および Swagger-Inspector を見てください（一種の郵便配達員）

プロトタイピングによるドキュメントです。 Swagger Editorは、クライアントとスタブサーバージェネレーターも提供することに注意してください。ただし、重要な機能は Swagger-UI です。これは、APIの呼び出しを可能にする web UI です。 Swagger-Inspectorとは異なり、Swagger-UIはよりユーザーフレンドリーです。

では、クライアント側とサーバー側の異なるチーム間でこれがどのように通信されるかについての説明はありますか？

NodeJS Webサーバーをデプロイし、Swagger-UIとAPIスキーマ（JSONファイル）の両方の要素をデプロイするために、かなり実行可能である必要があります。開発の初期段階で提供するサーバーデータがない場合でも心配しないでください。SwaggerEditorを使用してスタブサーバーを生成するか、Nodeを使用してスタブサーバーを構築できます。私はホイールを再発明するのが嫌いなので、テストダブルスとスタブサーバーについて検索しているときに Mountebank を見つけました。

後で、Swagger-UIの設定を切り替えて、偽のAPIサーバーではなく実際のAPIサーバーにフィードします。

このアイデアは、開発者がAPIに慣れると同時に、消費方法についての感想を得たり、改善を提案したり、それに取り組むために、APIのプロトタイプを作成することです。ドキュメンテーションがオンラインで入手できる場合、誰でもアクセスできるようにするのは簡単です。

各ドキュメントは通常、特定の消費者を対象としています。 Swaggerは、開発者にとって優れたドキュメンテーションおよび設計ツールです。常連またはエンドユーザーの場合は、HTMLまたはPDFの従来のドキュメントを検討します。APIとその使用方法に関する文献も多くあります。しかし、心配しないでください。SwaggerDataモデルをHTML、PDF、ASCIIDOC、およびMarkdownに変換するための利用可能なコンバーターがあります。

8
Laiv

まだ使用していないため、これらを保証することはできませんが、RAML RESTfulインターフェース仕様の一部として使用されている JSONスキーマ 仕様があります。さまざまな言語で [〜＃〜] raml [〜＃〜] for web services を生成するツールがあることは知っていますが、繰り返しになりますが、その方法については保証できませんうまく機能します。

ツールがJSONスキーマを取り巻く限り、私の経験ではそれは重要ではないとしています。これは少し物議を醸しています、そして私がこれを言うとき私はクレイジーだと多くの人が思っていますが、スキーマ（ペダントのスキーマ）からコードを作成しようとするツールとコードからスキーマを使用する価値はありませんが、私の経験では、前者は高レベルでは問題が少なくなります。 SOAP/WSDLはget-goから間違った方法で考え出された であり、XMLは統合タスクのために絶望的に複雑すぎますが、これは実際にXMLで本当に問題があった場所だと私は信じています。

SOAP/WSDLとXMLの失敗は参考になると思います。重要な教訓は、あなたを導くためではなく、あなたを助けるためのツールが存在することだと思います。クライアントのニーズを満たす高速で論理的なインターフェースを作成することが、あなたの第一の関心事です。不思議なコード生成を実行するために多くの時間を費やしたとしても、より少ない時間とより多くの制約で、すべての困難な作業を行うことになります。

3
JimmyJames

私たちの組織には、TypeScriptとそこで利用可能な interfaces を使用して成功する開発者が何人かいます。これにより、インターフェースを次のように定義できます。

interface SquareConfig {
    color?: string;
    width?: number;
}

TypeScriptをコードで使用することの追加の利点は、フィールドの名前を変更すると、古いフィールド名を参照するコードが機能しなくなることです。

1
Matthew Will

WebIDL はHTML5を指定するために使用される言語であるため、最新のものになっていますが、そのためのツールはありますか？

WebIDLフラグメントの例は次のようになります。

exception GraphicsException {
  DOMString reason;
};

interface Paint { };

interface SolidColor : Paint {
  attribute float red;
  attribute float green;
  attribute float blue;
};

interface Pattern : Paint {
  attribute DOMString imageURL;
};

[Constructor]
interface GraphicalWindow {
  readonly attribute unsigned long width;
  readonly attribute unsigned long height;

  attribute Paint currentPaint;

  void drawRectangle(float x, float y, float width, float height);

  void drawText(float x, float y, DOMString text);
};
0
user62575

JSONにこだわる必要がない場合は、プロトコルバッファをご覧ください。これらのいわゆるprotoを使用すると、メッセージの形式を記述し、JSおよびJavaクラスを生成して、そのようなメッセージを読み書きすることができます。そして、それらはより高速であるようです。クイックリファレンス： https://developers.google.com/protocol-buffers/

0
Rahul Kumar