JSON APIのカスタムバイク

みなさんこんにちは！ 最近のSuperjob IT Meetupで、私は Superjobで何百万人の聴衆と多くの異なるプラットフォームを持つプロジェクトのためにAPIを開発していることについて話しました。

この記事では、何十もの既製のソリューションで停止できない理由、独自のソリューションを作成するのがどれほど苦痛だったか、そしてあなたが私たちの道を繰り返した場合に何が待っているかについてお話したいと思います。 猫に興味がある人は誰でも聞いてください。

参加する代わりに

SuperjobのAPIの歴史は、厳しいXML APIから始まりました。 それから簡潔なJSONに移行し、後に、より正確なものに関する論争にうんざりしました-{success：true}または{result：true}、 JSON APIを実装しました。 時間が経つにつれて、その機能の一部を放棄し、データ形式に同意し、オリジナルとの後方互換性を維持した独自のバージョンの仕様を作成しました。 まさにこの仕様では、APIの最後の3番目のバージョンが実行され、そこにすべてのサービスが徐々に移行されます。

私たちのタスクでは、APIのほとんどのエンドポイントが特定のオブジェクトを受け入れるか返すときに、JSON APIがほぼ完璧なソリューションであることが判明しました。 この仕様の中心-本質とその関係。 エンティティは典型的なものであり、属性と関係の固定されたセットを持ち、本質的にはコードでの作業に慣れているモデルに非常に似ています。 エンティティの操作は、RESTの原則（HTTPを介したプロトコル、たとえば、SOAPまたはJSON-RPCなど）に従って実行されます。 リクエスト形式はほぼ完全にレスポンス形式を繰り返すため、サーバーとクライアントの両方の寿命が大幅に簡素化されます。 たとえば、典型的なJSON API応答は次のようになります。

{ "data": { "type": "resume", "id": 100, "attributes": { "position": "" }, "relationships": { "owner": { "data": { "type": "user", "id": 200 } } } }, "included": [ { "type": "user", "id": 200, "attributes": { "name": " " } } ] } 

ここでは、再開タイプのエンティティがあり、所有者はユーザータイプのエンティティにリンクしています。 クライアントがそのようなエンティティを送信することを望んだ場合、彼はリクエスト本体にまったく同じjsonを入れます。

最初のステップ

当初、APIの実装は非常に単純でした。エンドポイントの回答はアクションで直接形成され、クライアントからのデータはサーバーアプリケーションを実行するYii1の小さなアドオンを使用して取得され、ドキュメントは手作業で記入された別のファイルに格納されていました。

JSON APIへの移行により、アドインは、本質的にモデルの変換（マッピング）を制御し、トランスポートレイヤー（要求の解析と応答の生成）を管理する本格的なフレームワークに変わりました。

モデルをエンティティにマッピングするには、2つの追加クラスを記述する必要があります。エンティティのDTOと、モデルからのデータでDTOを埋めるハイドレーターです。 このアプローチにより、マッピングプロセスは十分に柔軟になりましたが、実際には、この柔軟性は悪であることが判明しました。時間が経つにつれて、ハイドレーターはコピーアンドペーストが大きくなり始め、各モデルが別の2つのクラスを開始する必要性がコードベースの膨張につながりました。

トランスポート層も理想からかけ離れていました。 開発者は、JSON APIの内部構造について絶えず考えることを余儀なくされました。モデルマッピングの場合と同様に、プロセスを完全に制御することにより、アクションからアクションにほとんど同一のコードをドラッグする必要が生じました。

JSON APIで動作するサードパーティのソリューションへの切り替えを検討し始めました。 JSON API Webサイトには、サーバーとクライアントの両方のさまざまな言語での仕様実装のかなり印象的なリストがあります。 この記事を書いている時点では、PHPでサーバー部分を実装しているプロジェクトが18ありましたが、そのうちのどれも私たちには適していませんでした。

• 第一に、サードパーティのソリューションには、私たちのソリューションと同じ問題がすべてありました。余分なコードが多すぎ、自動化がほとんどありません。 場合によっては、特定の要件がモデル（たとえば、インターフェイスの実装）に課せられ、コードボリュームでは深刻なリファクタリングが発生する可能性がありました。 リクエストとレスポンスを処理するには、いずれにしても、選択したソリューションをYiiに接続するアダプターを作成する必要があります。
  
  
• 第二に、圧倒的な数のサードパーティソリューションが1対1のマッピングをサポートしていました。1つのモデルがあれば、それを1つのエンティティに変えることができます。 これは、モデル内のデータがクライアントに提供したい形式で保存されている通常のケースですが、実際には常にそうであるとは限りません。 たとえば、履歴書モデルには連絡先の属性がありますが、クライアントは特定の条件下でのみこれらの連絡先を受信できます。 連絡先を履歴書自体の本質に関連する別のエンティティにして、1つのモデルを複数のエンティティに変換することは素晴らしいことですが、サードパーティのソリューションでは、これは松葉杖を介してのみ実行できます。
  
  
• 第三に、データベースからモデルを選択してクライアントに送信するエンドポイントを作成するタスクに直面しているプログラマーが毎回同じタイプのコードを作成する必要がないように、標準エンドポイントの開発を可能な限り簡素化したかったのです。 ただし、サードパーティのソリューションはDBALとの統合を提供しませんでした。
  
  
• 最後に、第4に、ドキュメントとテストの記述を単純化することを望みましたが、サードパーティソリューションの大部分は、エンティティが持つ属性と関係に関する情報を提供しませんでした。

再び決定を書き始める必要性が明らかになりました:)

フレームワーク開発

以前の開発およびサードパーティソリューションの欠点を分析した後、新しいフレームワークがどうあるべきかというビジョンを形成しました。

• まず、DTOとハイドレーターを記述する代わりに、構成全体でマッピング全体を記述することにしました。
• 開発者には知られていませんが、この設定はPHPコードにコンパイルされている必要があり、PHPコードはエンティティをハイドレートするために使用されます。
• JSON APIを使用したすべての作業は、舞台裏で実行する必要がありました。通常のエンドポイントでは、すべての作業はビジネスロジックの記述とモデルの取得に限定されると想定されていました。
• 最後に、前述のように、ソリューションをDBAL、ドキュメント、およびテストと統合したいと考えました。

コア

このフレームワークは、コンパイルされたハイドレーター、つまりモデルを埋めてエンティティを構築するオブジェクトに基づいています。 ハイドレーターはタスクに対処するためにどのような知識が必要ですか？ まず最初に、彼はどのモデルとどのエンティティが構築されるかを知らなければなりません。 エンティティが持つプロパティと関係、およびソースモデルのプロパティと関係にどのように関係するかを理解する必要があります。

そのようなハイドレーターの設定を説明してみましょう。 設定形式はYAMLです。これは、記述しやすく、読みやすく、解析しやすいです（ 自宅でsymfony / yamlを使用しました ）。

 entities: TestEntity: classes: - TestModel attributes: id: type: integer accessor: '@getId' mutator: '@setId' name: type: string accessor: name mutator: name relations: relatedModel: type: TestEntity2 accessor: relatedModel relatedModels: type: TestEntity3[] accessor: '@getRelatedModels' 

ここで、TestEntityエンティティはTestModelモデルから組み立てられます。 エンティティには2つの属性があります。idはgetIdゲッターから取得され、nameはnameプロパティから取得されます。 エンティティには、2つの関係があります。TestEntity2型のエンティティで構成される単一のrelatedModelと、TestEntity3のエンティティで構成される複数のrelatedModelです。

この構成を使用してコンパイルされたハイドレーターは次のとおりです。

 class TestEntityHydrator extends Hydrator { public static function getName(): string { return 'TestEntity'; } protected function getClasses(): array { return [Method::DEFAULT_ALIAS => TestModel::class]; } protected function buildAttributes(): array { return [ 'id' => (new CompiledAttribute('id', Type::INTEGER)) ->setAccessor( new MethodCallable( Method::DEFAULT_ALIAS, function (array $modelArray) { return $modelArray[Method::DEFAULT_ALIAS]->getId(); } ) ) ->setMutator( new MethodCallable( Method::DEFAULT_ALIAS, function (array $modelArray, $value) { $modelArray[Method::DEFAULT_ALIAS]->setId($value); } ) ), 'name' => (new CompiledAttribute('name', Type::STRING)) ->setAccessor( new MethodCallable( Method::DEFAULT_ALIAS, function (array $modelArray) { return $modelArray[Method::DEFAULT_ALIAS]->name; } ) ) ->setMutator( new MethodCallable( Method::DEFAULT_ALIAS, function (array $modelArray, $value) { $modelArray[Method::DEFAULT_ALIAS]->name = $value; } ) ) ->setRequired(false), ]; } protected function buildRelations(): array { return [ 'relatedModel' => (new CompiledRelation('relatedModel', TestEntity2Hydrator::getName()))->setAccessor( new MethodCallable( Method::DEFAULT_ALIAS, function (array $modelArray) { return $modelArray[Method::DEFAULT_ALIAS]->relatedModel; } ) ), 'relatedModels' => (new CompiledRelation('relatedModels', TestEntity3Hydrator::getName()))->setAccessor( new MethodCallable( Method::DEFAULT_ALIAS, function (array $modelArray) { return $modelArray[Method::DEFAULT_ALIAS]->getRelatedModels(); } ) )->setMultiple(true), ]; } } 

実際、この巨大なコードはすべて、本質的なデータのみを記述しています。 同意して、これを手書きで書いてください。プロジェクト内の各エンティティでさえ、それは素晴らしいことではないでしょう。

上記のすべてが機能するためには、構成パーサー、バリデーター、コンパイラーの3つのサービスを実装する必要がありました。

パーサーは設定の変更に従うことにコミットし（ symfony / configがこれを助けてくれました）、そのような変更が検出された場合、すべての設定ファイルを再読み込みし、それらをマージしてバリデーターに渡しました。

バリデーターは、構成の正確性をチェックしました：最初に、jsonスキーマの対応をチェックしました。これは、構成（ここではjustinrainbow / json-schemaを使用しました ）について説明し、次に、言及したすべてのクラス、それらのプロパティ、およびメソッドの存在を確認しました

最後に、コンパイラーは検証された構成を取得し、そこからPHPコードをコンパイルしました。

DBALとの統合

歴史的な理由から、プロジェクトでは2つのDBAL（Yii1 ActiveRecordとDoctrineの標準的なDBAL）が近くにあり、両方のフレームワークを友達にしたかったのです。 統合により、Mapperはデータベースから独立してデータを受信し、保存できることが理解されました。

これを実現するために、まず設定に小さな変更を加える必要がありました。 一般的な場合、モデル内の接続の名前は、この接続を返すゲッターまたはプロパティの名前と異なる場合があるため（これは特にDoctrineに当てはまります）、この名前またはそのDBAL接続を知っている名前でMapperに伝えることができる必要がありました。 このため、通信の説明にパラメーターinternalNameを追加しました。 後に、同じinternalNameが属性に表示されたため、マッパーは独立してフィールド選択を実行できました。

internalNameに加えて、エンティティが属するDBALに関する知識を構成に追加しました。アダプタパラメータで、サービスの名前が指定され、マッパーがDBALとやり取りできるようにするインターフェイスを実装しました。

インターフェイスは次のとおりです。

 interface IDbAdapter { /** * Statement  . * * @param string $className * @param mixed $context * @param array $relationNames * * @return IDbStatement */ public function statementByContext(string $className, $context, array $relationNames): IDbStatement; /** * Statement   . * * @param string $className * @param array $attributes * @param array $relationNames * * @return IDbStatement */ public function statementByAttributes(string $className, array $attributes, array $relationNames): IDbStatement; /** *    . * * @param string $className * * @return mixed */ public function create(string $className); /** *  . * * @param mixed $model */ public function save($model); /** *      . * * @param mixed $parent * @param mixed $child * @param string $relationName */ public function link($parent, $child, string $relationName); /** *     . * * @param mixed $parent * @param mixed $child * @param string $relationName */ public function unlink($parent, $child, string $relationName); } 

DBALとの対話を簡素化するために、コンテキストの概念を導入しました。 コンテキストは特定のオブジェクトであり、それを受信すると、DBALはどのクエリを実行する必要があるかを理解する必要があります。 ActiveRecordの場合、CDbCriteriaはDoctrine-QueryBuilderのコンテキストとして使用されます。

DBALごとに、IDbAdapterを実装する独自のアダプターを作成しました。 驚きがありました。たとえば、Yii1の存在全体にわたって、あらゆる種類の接続の保存をサポートする単一の拡張機能が記述されていないことが判明しました。私は独自のラッパーを作成する必要がありました。

ドキュメントとテスト

自宅では、統合テストにBehatを使用し、ドキュメントにSwaggerを使用しています。 どちらのツールもネイティブにJSONスキーマをサポートしているため、Mapperサポートを問題なく統合できます。

Behatのテストはガーキンで書かれています。 各テストは一連のステップであり、各ステップは自然言語の文です。

JSON APIとMapperのサポートをBehatに統合する手順を追加しました。

 #   When I have entity "resume" And I have entity attributes: | name | value | | profession |  | #   And I have entity relationship "owner" with data: | name | value | | id | 100 | #    ,    resume Then I send entity via "POST" to "/resume/" and get entity "resume" 

このテストでは、再開エンティティを作成し、その属性と関係を記入し、リクエストを送信してレスポンスを検証します。 同時に、ルーチン全体が自動化されています。リクエストの本文を作成する必要はありません。Behatのヘルパーがこれを行うため、予想されるレスポンスのJSONスキーマはMapperによって生成されるため、記述する必要はありません。

ドキュメントを使用すると、状況はやや興味深いものになります。 SwaggerのJSONスキーマファイルは元々、YAMLソースからその場で生成されました。すでに述べたように、YAMLは同じJSONよりもはるかに簡単に記述できますが、SwaggerはJSONのみを理解します。 YAMLファイルのコンテンツだけでなく、マッパーからのエンティティの説明も最終的なJSONスキーマに入るように、このメカニズムを補足しました。 したがって、たとえば、フォームのリンクを理解するようにSwaggerに教えました。

$ref: '#mapper:resume'

または：

$ref: '#mapper:resume.collection.response'

Swaggerは、再開エンティティオブジェクトまたはサーバー応答オブジェクト全体を、それぞれ再開エンティティのコレクションでレンダリングしました。 このようなリンクのおかげで、マッパーの構成が変更されるとすぐに、ドキュメントが自動的に更新されました。

結論

多大な努力を払って、開発者の作業を楽にするツールを作成しました。 ささいなエンドポイントを作成するには、構成でエンティティを記述し、数行のコードをスローするだけで十分です。 テストとドキュメントを書く際のルーチンを自動化することで、新しいエンドポイントの開発にかかる時間を節約でき、Mapper自体の柔軟なアーキテクチャにより、必要に応じて機能を簡単に拡張できました。

記事の冒頭で述べた基本的な質問に答える時が来ました-自転車を作るのに費用はかかりましたか？ そして、あなたはあなた自身のものを作る必要がありますか？

Mapperの集中的な開発フェーズには、約3か月かかりました。 引き続き新しい機能を追加しますが、それほど集中的ではありません。 一般に、私たちは結果に満足しています。マッパーはプロジェクトの機能を考慮して設計されているため、割り当てられたタスクをサードパーティのソリューションよりもはるかにうまく処理します。

私たちの道を行くべきですか？ あなたのプロジェクトがまだ若く、コードベースが小さい場合、あなたのために自転車を書くことは不当な時間の無駄になる可能性が非常に高く、最良の選択はサードパーティのソリューションを統合することです。 ただし、コードが長年にわたって記述されており、深刻なリファクタリングを実行する準備ができていない場合は、独自の決定について明確に検討する必要があります。 開発の初期の困難にもかかわらず、将来の時間と労力を大幅に節約できます。