Кто мы?

Предыстория

Проблемы RESTful API

Структура проекта

Какие API методы хочет создавать backend разработчик?

{
	id
	email
	firstName
	lastName
	createDate
	modifyDate
	lastVisitDate
	status
}

{
	id
	userId
	street
	zip
	cityId
	createDate
	modifyDate
	status
}

{
	id
	name
}

Какие API методы хочет вызывать разработчик UI?

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

Что такое GraphQL и почему он должен решать мои проблемы?

Покажите мне код

Шаг 1. Установка и настройка Yii2

$> yii migrate

$> yii migrate/create init

<?php

use yii\db\Migration;

class m170828_175739_init extends Migration
{
    public function safeUp()
    {
        $this->execute("CREATE TABLE IF NOT EXISTS `user` (
          `id` INT NOT NULL,
          `firstname` VARCHAR(45) NULL,
          `lastname` VARCHAR(45) NULL,
          `createDate` DATETIME NULL,
          `modityDate` DATETIME NULL,
          `lastVisitDate` DATETIME NULL,
          `status` INT NULL,
          PRIMARY KEY (`id`))
        ENGINE = InnoDB;");

        $this->execute("CREATE TABLE IF NOT EXISTS `city` (
          `id` INT NOT NULL,
          `name` VARCHAR(45) NULL,
          PRIMARY KEY (`id`))
        ENGINE = InnoDB;");

        $this->execute("CREATE TABLE IF NOT EXISTS `address` (
          `id` INT NOT NULL,
          `street` VARCHAR(45) NULL,
          `zip` VARCHAR(45) NULL,
          `createDate` DATETIME NULL,
          `modifyDate` DATETIME NULL,
          `status` INT NULL,
          `userId` INT NOT NULL,
          `cityId` INT NOT NULL,
          PRIMARY KEY (`id`),
          INDEX `fk_address_user_idx` (`userId` ASC),
          INDEX `fk_address_city1_idx` (`cityId` ASC),
          CONSTRAINT `fk_address_user`
            FOREIGN KEY (`userId`)
            REFERENCES `user` (`id`)
            ON DELETE NO ACTION
            ON UPDATE NO ACTION,
          CONSTRAINT `fk_address_city1`
            FOREIGN KEY (`cityId`)
            REFERENCES `city` (`id`)
            ON DELETE NO ACTION
            ON UPDATE NO ACTION)
        ENGINE = InnoDB;");
    }

    public function safeDown()
    {
        echo "m170828_175739_init cannot be reverted.\n";

        return false;
    }
}

$> yii migrate

$> yii gii/model --tableName=user --modelClass=User
$> yii gii/model --tableName=city --modelClass=City
$> yii gii/model --tableName=address --modelClass=Address

Шаг 2. Установка расширения для GraphQL

$> composer require webonyx/graphql-php

Шаг 3. Создаем структуру проекта.

Шаг 3.1. Создадим типы для наших моделей.

<?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);
    }

}

<?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);
    }

}

<?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);
    }

}

Шаг 3.2. 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. schema/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);
    }
}

Шаг 3.4. Создаем controllers/api/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;
    }
}

Шаг 4. Тестируем.

• автокомплит по полям и аргументам (с подчеркиванием неверных параметров, конечно же)
• вывод дескрипшна подсвеченного поля
• автоматическая справка с серфингом в правой части
• моментальное получение результата

To be continued…