» » Пишем GraphQL API сервер на Yii2 с клиентом на Polymer + Apollo. Часть 1. Сервер

 

Пишем GraphQL API сервер на Yii2 с клиентом на Polymer + Apollo. Часть 1. Сервер

Автор: admin от 31-08-2017, 17:31, посмотрело: 104

Статья рассчитана на широкий круг читателей и требует лишь базовых знаний PHP и javascript. Если вы занимались программированием и вам знакома аббревиатура API, то вы по адресу.

Изначально статья предполагала лишь описание отличительных особенностей GraphQL и RESTful API, с которыми мы столкнулись на практике, но в итоге она вылилась в объемный туториал на несколько частей.
эту страницу, чтобы понять с чем его едят.

Почему он решает вышеописанную проблему? Потому что при использовании GraphQL, серверный разработчик описывает атомарные сущности и связи так, как ему это нравится, а UI строит кастомные запросы в зависимости от потребностей конкретного элемента. И вроде бы и овцы сыты и волки целы, но, к счастью, мы не живем в идеальном мире и подстраиваться все равно приходится. Но обо всем по-порядку.

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


На Хабре уже была хорошая статья о том, как подружить 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 сервера:

schema — директория в корне фреймворка, которая будет хранить сущности для GraphQL сервера: типы и мутации. Название директории и расположение не принципиально, можете назвать как угодно и расположить в другом неймспейсе (например api/ или components/).

schema/QueryType.php, schema/MutationType.php — “корневые” типы.

schema/Types.php — некий агрегатор для инициализации наших кастомных типов.

schema/mutations — мутации предпочтительно хранить в отдельной директории для удобства.

Ну и собственно controllers/api/GraphqlController.php — точка входа. Все запросы к GraphQL серверу идут через одну точку входа — /api/graphql. Таким образом ничего не мешает вам параллельно содержать RESTful API (если уж на то пошло, то, грубо говоря, GraphQL сервер это один API-метод, принимающий на вход параметрами GraphQL-запросы).

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


Создадим новую директорию schema и в ней классы для наших моделей.

/schema/CityType.php:

<?php

namespace appschema;

use GraphQLTypeDefinitionObjectType;
use GraphQLTypeDefinitionType;

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 — принимаемые аргументы (ассоциативные массив, где ключ — имя аргумента, значение — GraphQL-тип).

resolve($root, $args) — функция, которая возвращает значение поля. Аргументы: $root — объект соответствующего ActiveRecord (в данном случае в него будет приходить объект modelsCity); $args — ассоциативный массив аргументов (описанных в $args).

Все поля кроме type — опциональны.

/schema/UserType.php:

<?php

namespace appschema;

use GraphQLTypeDefinitionObjectType;
use GraphQLTypeDefinitionType;
use appmodelsUser;

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 appschema;

use GraphQLTypeDefinitionObjectType;
use GraphQLTypeDefinitionType;

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. schema/Types.php


Дело в том, что GraphQL схема не может иметь несколько одинаковых (одноименных) типов. Именно за этим призван следить агрегатор Types.php. Название нарочно было выбрано именно Types, чтобы было похоже, и, в тоже время, отличалось от стандартного класса библиотеки GraphQL — Type. Таким образом обратиться к стандартному типу можно через Type::int(), Type::string(), а к кастомному — Types::query(), Types::user(), и т.д.

schema/Types.php:

<?php 

namespace appschema;

use GraphQLTypeDefinitionObjectType;

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 appschema;

use GraphQLTypeDefinitionObjectType;
use GraphQLTypeDefinitionType;
use appmodelsUser;
use appmodelsAddress;

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

C MutationType.php разберемся немного позже.

Шаг 3.4. Создаем controllers/api/GraphqlController.php


Теперь доделаем последнюю часть, чтобы к нашим новосозданным типам можно было достучаться.

GraphqlController.php:

<?php

namespace appcontrollersapi;

use appschemaTypes;
use GraphQLGraphQL;
use GraphQLSchema;
use yiibaseInvalidParamException;
use yiihelpersJson;

class GraphqlController extends yiirestActiveController
{
    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», которое имеет более расширенный функционал (сохраненные запросы, кастомные хедеры). Правда последнее иногда имеет проблемы с выводом ошибок, а точнее просто ничего не выводит в случае ошибки на сервере.

Вводим в поля необходимые данные и радуемся результату:

[img]http://habrahabr.ru/https:/www.dropbox.com/s/taw7uqvk3hkzxwi/debug1.png?raw=1[/img]

Таким образом, после всего имеем:


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

  • вывод дескрипшна подсвеченного поля

  • автоматическая справка с серфингом в правой части

  • моментальное получение результата


Примечание. Если у вас не заработал красивый URL, это значит, что вы недоконфигурили UrlManager и .htaccess, т.к. в первозданном Yii это не работает. Как это сделать гляньте в репозитории к статье.

Автокомплит аргументов:

[img]http://habrahabr.ru/https:/www.dropbox.com/s/3guxegxhp1ff6vt/debug2.png?raw=1[/img]

Полностью кастомный запрос с полностью кастомным результатом — мечта frontend разработчика:

[img]http://habrahabr.ru/https:/www.dropbox.com/s/b0py0o8yw47bn9c/debug3.png?raw=1[/img]

Могли ли вы об этом всем мечтать разрабатывая свой RESTful, при том что вы для этого ничего и не делали? Конечно же нет.

Также важно обратить внимание на то, что для того, чтобы вытащить адреса и пользователя, нам не нужно делать два отдельных запроса, а можно (и нужно) всё сделать сразу:

[img]http://habrahabr.ru/https:/www.dropbox.com/s/raszpkg1qugyu2m/debug4.png?raw=1[/img]

Возможность дебага запросов лично я считаю одним из весомых преимуществ GraphQL. Дело в том, что он автоматически генерирует схему, которую втягивает расширение, и у вас включается валидация и автокомплит. Таким образом имея лишь адрес точки входа в GraphQL сервер, вы можете полностью изучить его возможности. Несекьюрно? Как по мне, секьюрность реализуется немного на другом уровне. Имея доступ к документации любого API, мы точно так же имеем полную его схему. Некоторые RESTful API имеют подобные JSON или XML схемы, к сожалению не многие, а для GraphQL это стандарт, к тому они же активно используются клиентами.

To be continued…


В следующей(их) части(ях) статьи я опишу как это всё по-красивому использовать в UI, и конечно же мы затронем еще одну тему без которой API не API — это мутации.

Источник: Хабрахабр

Категория: Программирование, Веб-разработка

Уважаемый посетитель, Вы зашли на сайт как незарегистрированный пользователь.
Мы рекомендуем Вам зарегистрироваться либо войти на сайт под своим именем.

Добавление комментария

Имя:*
E-Mail:
Комментарий:
Полужирный Наклонный текст Подчеркнутый текст Зачеркнутый текст | Выравнивание по левому краю По центру Выравнивание по правому краю | Вставка смайликов Выбор цвета | Скрытый текст Вставка цитаты Преобразовать выбранный текст из транслитерации в кириллицу Вставка спойлера
Введите два слова, показанных на изображении: *