Polymer + Apolloのクライアントを使用してYii2のGraphQL APIサーバーを作成しています。 パート1.サーバー

パート1.サーバー

パート2.クライアント

パート3.突然変異

パート4.検証。 結論



この記事は幅広い読者を対象としており、PHPとJavascriptの基本的な知識のみが必要です。 プログラミングを行っていて、略語APIに精通している場合は、その通りです。



当初、この記事では、GraphQLの特徴的な機能と実際に遭遇したRESTful APIの説明のみを想定していましたが、最終的にはいくつかのパートでボリュームチュートリアルになりました。



そしてすぐに、GraphQLをすべての病気の万能薬であり、RESTful APIキラーとは見なさないことを付け加えます。

私たちは誰ですか？

私たちはモバイルアプリケーションを開発する会社であり、原則として、これらのアプリケーションにはiOS（もちろん）、Android、およびWeb用のクライアントがあります。 個人的に、私はこの会社でPHPでサーバー側を書いています。

背景

それはすべて、1つのアプリケーションの開発を完了したという事実から始まりました（完了した時点で、アプリケーションの開発を終了することはできません。アプリケーションは途中で中断されたためです）。 幸いなことに、同社は開発者をテクノロジーの選択に制限しておらず（当然、合理的な範囲内で）、過去に発生した問題を回避するために特定の変更を加えることが決定されました。 結局のところ、あなたが知っているように、あなたがあなたがすることを続ければ、あなたはあなたが受け取るものを受け取り続けます。

RESTful APIの問題

RESTに大きな問題はありませんでしたが、私は定期的にそれらの1つに遭遇しました。 実際、私たちのプロジェクトの開発者は高い資格を持っているため、各開発者が特定のレベルで自分の分野の専門家であると考えているのはこのためです。 APIは、バックエンドとフロントエンドのスペシャリストをつなぐテクノロジーの薄いスレッドであり、開発方法に関する多くの論争の原因です。

プロジェクト構造

たとえば、典型的なデータ構造を考えてみましょう。







ここでは、実際には、このようなテーブルには20以上のフィールドがあり、GraphQLの使用がさらに魅力的で正当化されることを理解する必要があります。 なぜ正確に、私は記事で説明しようとします。

バックエンド開発者が作成したいAPIメソッドは何ですか？

もちろん、サーバー側の開発者は、包括的で包括的なオブジェクトと可能な限り一貫性のある方法でAPIメソッドを記述したいと考えています。 例：



GET / api / user /：id

{ id email firstName lastName createDate modifyDate lastVisitDate status }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

GET / api / address /：id

 { id userId street zip cityId createDate modifyDate status }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

GET / api / city /：id

 { id name }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

...など そのようなアーキテクチャを書くことは、単純で高速であるだけでなく（これらすべてが何らかの足場になっていると言わない限り）、それはまた、アーキテクチャ上および美学的により美しく、より正確です（少なくとも開発者自身はそう考えています）。 最良の場合、バックエンドはネストされたオブジェクトに同意するため、addressIdの代わりに、ネストされたアドレスオブジェクトまたは（「1対多」接続の場合）アドレスの配列が返されます。

UI開発者が呼び出したいAPIメソッドは何ですか？

クライアント開発者は、生きている人々（アプリケーションのユーザー）とそのニーズに少し近づいています。その結果、同じデータの異なるセットが必要なアプリケーション内にいくつかの場所（多くを読む必要があります）があります。 したがって、彼は各機能要素がメソッドによって持つことを望んでいます：



GET / api / listOfUsersForMainScreen

 [ { firstName lastName dateCreated city street } ... ]
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

...等々。 もちろん、そのような欲求は、作業を削減したいだけでなく、アプリケーションのパフォーマンスを改善したいという欲求によって完全に正当化されます。 まず、UIは3つではなく1つの呼び出しを行います（最初のユーザー、次に住所、次に市）。 第二に、この方法により、多くの（多くの場合かなりの）冗長データを取得する必要がなくなります。 同時に、dateCreatedは、データベースのフィールドから取得した元の形式ではなく、人間の形式で返すことが非常に望ましいです（そうでない場合は、Unix時間も変換する必要があります）。



私は証人であり、時には参加者であった紛争が生まれるのは、これに基づいています。 優れた開発者は、互いのニーズを部分的に満たすために妥協を求め、もちろん妥協を見つけます。 ただし、たとえば、フロントエンドが1つとバックエンドが2つある場合、単独でカリスマ性を最大限に高め、すべての外交スキルを使用して、アプリケーションのライフサイクル全体で1回呼び出される無意味なメソッドの記述を進める必要があります。

GraphQLとは何ですか？なぜ問題を解決する必要があるのですか？

GraphQLに慣れていない人のために、5〜10分以内で過ごすことをお勧めします。 このページにアクセスして、GraphQLの用途を理解してください 。



なぜ彼は上記の問題を解決するのですか？ GraphQLを使用する場合、サーバー開発者はアトミックエンティティとリレーションシップを好きなように記述し、UIは特定の要素のニーズに応じてカスタムクエリを構築するためです。 そして、羊は十分に餌を与えられ、狼は無傷であるように見えますが、幸いなことに、私たちは理想的な世界に住んでおらず、私たちはまだ順応しなければなりません。 しかし、まず最初に。

コードを見せて

Habréには、PHPとGraphQLの友達を作る方法についての良い記事がありました。そこから多くの有用なことを学び、繰り返しを謝ります。この記事の主なポイントは基本を教えることではなく、長所と短所を示すことです。



サーバーパーツの完成したデモプロジェクトをここで見ることができます 。



実際に、サーバーの作成を始めましょう。 GraphQL自体に関する情報を含まないフレームワークと環境の構成をスキップするには、すぐに構造の作成に進みます（ステップ2）。

ステップ1. Yii2のインストールと構成

このステップはGraphQLとは関係ありませんが、さらなるアクションのために必要です。

ステップ2. GraphQLの拡張機能をインストールする

このプロジェクトでは、基本的な拡張webonyx / graphql-php（https://github.com/webonyx/graphql-php）を使用します。

 $> composer require webonyx/graphql-php
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

また、GitHubでYii2の拡張された拡張機能を見つけることができますが、一見しただけでは刺激されませんでした。 彼を知っているなら、コメントであなたの経験を共有してください。

ステップ3.プロジェクト構造を作成します。

GraphQLサーバーの実装に関与する主な構造要素：



スキーマ -GraphQLサーバーのエンティティを格納するフレームワークのルートにあるディレクトリ：タイプと突然変異。 ディレクトリの名前と場所は重要ではありません。好きな名前を付けて別の名前空間に配置できます（たとえば、api /またはcomponents /）。



schema / QueryType.php、schema / MutationType.php- 「ルート」タイプ。



schema / Types.phpは、カスタムタイプを初期化する特定のアグリゲーターです。



スキーマ/ミューテーション -ミューテーションは、便宜上、別のディレクトリに保存することが望ましい。



さて、実際にはcontrollers / api / GraphqlController.phpがエントリーポイントです。 GraphQLサーバーへのすべての要求は、1つのエントリポイント-/ api / graphqlを通過します。 したがって、RESTful APIを同時に維持することを妨げるものは何もありません（その点に関して、おおまかに言えば、GraphQLサーバーは、GraphQLクエリをパラメーターとして受け入れるAPIメソッドの1つです）。

ステップ3.1 モデルのタイプを作成します。

新しいスキーマディレクトリとその中のモデルのクラスを作成します。



/schema/CityType.php：

 <?php namespace app\schema; use GraphQL\Type\Definition\ObjectType; use GraphQL\Type\Definition\Type; class CityType extends ObjectType { public function __construct() { $config = [ 'fields' => function() { return [ 'name' => [ 'type' => Type::string(), ], ]; } ]; parent::__construct($config); } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

フィールドの説明には、次のパラメーターが関与します。



type -GraphQLフィールドタイプ（Type :: string（）、Type :: int（）など）。



description-説明（テキストのみ。スキームで使用されるため、リクエストのデバッグが容易になります）。



args-受け入れられる引数（連想配列、keyは引数の名前、valueはGraphQLタイプ）



resolve（$ root、$ args）は、フィールドの値を返す関数です。 引数：$ root-対応するActiveRecordのオブジェクト（この場合、models \ Cityオブジェクトが入ってくる）; $ argsは、引数の連想配列です（$ argsで説明）。



タイプを除くすべてのフィールドはオプションです。



/schema/UserType.php：

 <?php namespace app\schema; use GraphQL\Type\Definition\ObjectType; use GraphQL\Type\Definition\Type; use app\models\User; class UserType extends ObjectType { public function __construct() { $config = [ 'fields' => function() { return [ 'firstname' => [ 'type' => Type::string(), ], 'lastname' => [ 'type' => Type::string(), ], 'createDate' => [ 'type' => Type::string(), //  ,  //     //         // (       ) 'description' => 'Date when user was created', //     ,  //   format 'args' => [ 'format' => Type::string(), ], //        //  'resolve' => function(User $user, $args) { if (isset($args['format'])) { return date($args['format'], strtotime($user->createDate)); } //    format  , //    return $user->createDate; }, ], //       //    ,   //   ,  ,   'modityDate' => [ 'type' => Type::string(), ], 'lastVisitDate' => [ 'type' => Type::string(), ], 'status' => [ 'type' => Type::int(), ], //      - //  'addresses' => [ //      , //     //  Type::listOf,  //   ,     //   ,  //   'type' => Type::listOf(Types::address()), 'resolve' => function(User $user) { //  ,      //    $user    // ,    ,  .. //       ,   //        return $user->addresses; }, ], ]; } ]; parent::__construct($config); } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

/schema/AddressType.php：

 <?php namespace app\schema; use GraphQL\Type\Definition\ObjectType; use GraphQL\Type\Definition\Type; class AddressType extends ObjectType { public function __construct() { $config = [ 'fields' => function() { return [ 'user' => [ 'type' => Types::user(), ], 'city' => [ 'type' => Types::city(), ], //      //      //   ]; } ]; parent::__construct($config); } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

AddressType.phpの場合、ヘルパークラスTypes.phpが必要です。これについては以下で説明します。

ステップ3.2 スキーマ/ Types.php

実際のところ、GraphQLスキーマには、同じ名前の複数の同一タイプを含めることはできません。 これは、Types.phpアグリゲーターが監視するために設計されたものです。 この名前は、GraphQLライブラリの標準クラスであるTypeとは異なるように見えるように、Typesによって意図的に正確に選択されています。 したがって、Type :: int（）、Type :: string（）、およびカスタムタイプTypes :: query（）、Types :: user（）などを使用して標準タイプにアクセスできます。



schema / Types.php：

 <?php namespace app\schema; use GraphQL\Type\Definition\ObjectType; class Types { private static $query; private static $mutation; private static $user; private static $address; private static $city; public static function query() { return self::$query ?: (self::$query = new QueryType()); } public static function user() { return self::$user ?: (self::$user = new UserType()); } public static function address() { return self::$address ?: (self::$address = new AddressType()); } public static function city() { return self::$city ?: (self::$city = new CityType()); } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ステップ3.3 スキーマ/ QueryType.php

 <?php namespace app\schema; use GraphQL\Type\Definition\ObjectType; use GraphQL\Type\Definition\Type; use app\models\User; use app\models\Address; class QueryType extends ObjectType { public function __construct() { $config = [ 'fields' => function() { return [ 'user' => [ 'type' => Types::user(), //   ,  //     'args' => [ //     //   Type::nonNull() 'id' => Type::nonNull(Type::int()), ], 'resolve' => function($root, $args) { //        //   $args      // `id`,    ,       //     ,     `id` //       //     return User::find()->where(['id' => $args['id']])->one(); } ], //     user  ,   //          //          //     'addresses' => [ //    //      //  'type' => Type::listOf(Types::address()), //     'args' => [ 'zip' => Type::string(), 'street' => Type::string(), ], 'resolve' => function($root, $args) { $query = Address::find(); if (!empty($args)) { $query->where($args); } return $query->all(); } ], ]; } ]; parent::__construct($config); } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

MutationType.phpについては少し後で説明します。

ステップ3.4 コントローラー/ api / GraphqlController.phpを作成します

これで最後のパートを終了して、新しく作成したタイプに到達できるようにします。



GraphqlController.php：

 <?php namespace app\controllers\api; use app\schema\Types; use GraphQL\GraphQL; use GraphQL\Schema; use yii\base\InvalidParamException; use yii\helpers\Json; class GraphqlController extends \yii\rest\ActiveController { public $modelClass = ''; /** * @inheritdoc */ protected function verbs() { return [ 'index' => ['POST'], ]; } public function actions() { return []; } public function actionIndex() { //      //   MULTIPART,    POST/GET $query = \Yii::$app->request->get('query', \Yii::$app->request->post('query')); $variables = \Yii::$app->request->get('variables', \Yii::$app->request->post('variables')); $operation = \Yii::$app->request->get('operation', \Yii::$app->request->post('operation', null)); if (empty($query)) { $rawInput = file_get_contents('php://input'); $input = json_decode($rawInput, true); $query = $input['query']; $variables = isset($input['variables']) ? $input['variables'] : []; $operation = isset($input['operation']) ? $input['operation'] : null; } //    variables  null,    //     if (!empty($variables) && !is_array($variables)) { try { $variables = Json::decode($variables); } catch (InvalidParamException $e) { $variables = null; } } //          $schema = new Schema([ 'query' => Types::query(), ]); // ! $result = GraphQL::execute( $schema, $query, null, null, empty($variables) ? null : $variables, empty($operation) ? null : $operation ); return $result; } }
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

また、try-catch GraphQLでのラッピング：エラー出力をフォーマットするためのexecute（）は機能しません。 彼はすでに内部で可能なすべてを傍受し、間違いをどうするかについては、少し後で説明します。

ステップ4.テスト。

実際、私たちが達成したことを実現し、見て、触れてみる時が来ました。



Chome-GraphiQLの拡張機能でクエリを確認しましょう。 個人的には、より高度な機能（クエリの保存、カスタムヘッダー）を備えたGraphiQL Feenを好みます。 確かに、後者にはエラー出力に関する問題がある場合があります。むしろ、サーバー上でエラーが発生しても何も表示されません。



フィールドに必要なデータを入力し、結果を楽しんでください：







したがって、結局のところ、次のようになります。

• フィールドと引数によるオートコンプリート（無効なパラメーターにはもちろん下線を付けます）
• ハイライトされたフィールドの説明を出力
• 右側のサーフィンの自動ヘルプ
• 瞬時の結果

ご注意 美しいURLを取得していない場合は、UrlManagerと.htaccessを設定していないことを意味します。 元のYiiでは、これは機能しません。 これを行う方法については、記事リポジトリをご覧ください 。



オートコンプリート引数：







完全にカスタム化された結果を持つ完全にカスタム化されたリクエストは、フロントエンド開発者の夢です。







RESTfulを開発している間に、何もしなかったという事実にもかかわらず、すべてを夢見てもらえますか？ もちろん違います。



また、アドレスとユーザーを引き出すために、2つの個別の要求を行う必要はありませんが、すぐにすべてを実行できる（必要な）という事実に注意を払うことも重要です。







私は個人的に、GraphQLの重要な利点の1つとしてクエリをデバッグできることを考慮しています。 実際には、拡張機能が取り込むスキームが自動的に生成され、検証とオートコンプリートがオンになります。 したがって、GraphQLサーバーへのエントリポイントのアドレスのみがあれば、その機能を完全に探索できます。 セキュリティではない？ 私に関しては、セキュリティはわずかに異なるレベルで実装されています。 任意のAPIのドキュメントにアクセスできるほか、完全なスキームも用意されています。 一部のRESTful APIには類似したJSONまたはXMLスキーマがありますが、残念ながら多くはありませんが、GraphQLでは標準であり、さらにクライアントによって積極的に使用されています。

継続するには...

記事の次の部分では、UIですべてを美しい方法で使用する方法を説明します。もちろん、APIがAPIでない別のトピック、つまり突然変異です。