обсудить архитектуру SDK и подходы к реализации с vudaltsov

mesilov commented 3 years ago

Вводная информация

Библиотека представляет собой обёртку для работы с rest-api Bitrix24 https://dev.1c-bitrix.ru/rest_help/
я не являюсь сотрудником Битрикс и это мой пет-проект
обсуждаем новую версию sdk - 2.x https://github.com/mesilov/bitrix24-php-sdk/tree/2.x
официальный PHP клиент Б24 выглядит так - https://github.com/bitrix-tools/crest, они его промоутят в документации и учебных курсах.

какие подходы закладываю при разработке 2 версии

хороший DX (Developer Experience)
- автодополнение методов на уровне IDE
- типизированные сигнатуры вызова методов
- типизированные результаты вызова методов – используются нативные типы: int, array, bool, string
- хелперы для типовых операций
хорошая документация
- документация по работе конкретного метода содержащая ссылку на офф документацию
- документация по работе с SDK
производительность:
- минимальное влияние на клиентский код
- возможность работать с большими объёмами данных с константным потреблением памяти
- эффективная работа c API с использованием батч-запросов
современный стек технологий:
- библиотеки для работы с сетью и возможностью асинхронной работы
- фичи новых версий PHP
надёжной:
- покрытие тестами: unit, интеграционные, контрактные
- есть типовые примеры характерные для разных режимов работы и они оптимизированы по памяти \ быстродействию

текущий вариант второй версии SDK - WIP

Service – API-интерфейс для работы с конкретной сущностью

Зона ответственности:

контракт на API-методы сущности

Входящие данные:

сигнатура вызова конкретного API-метода

Возвращаемый результат:

Core\Response (????) к обсуждению

В зависимости от метода может быть разный возвращаемый результат:

результат выполнения операции типа bool
идентификатор созданной сущности типа int
сущность + пользовательские поля с префиксами UF_ типа array
массив сущностей типа array
пустой массив как результат пустого фильтра.

Если возвращать Core\Response, то в клиентском коде будут проблемы:

длинные цепочки в клиентском коде для получения возвращаемого результата

// добавили сделку в Б24
$dealId = $dealsService->add($newDeal)->getResponseData()->getResult()->getResultData()[0];
// получили массив сделок
$deals = $dealsService->list([], [], [], 0)->getResponseData()->getResult()->getResultData();

отсутствие релевантной вызываемому методу типизации возвращаемого результата.

Ожидание:

 add(array $newDeal):int // идентификатор новой сделки
 list(array $order, array $filter, array $select, int $start):array //массив сделок + постраничка
 get(int $dealId):array // конкретная сделка

Текущая реализация — возвращается унифицированный результат:

add(array $newDeal):Core\Response
list(array $order, array $filter, array $select, int $start):Core\Response

Core – вызов произвольных API-методов

Зона ответственности:

вызов произвольных API-методов
обработка ошибок уровня API
запрос нового токена и повторение запроса, если получили ошибку expired_token

Входящие данные:

string $apiMethod – название api-метода
array $parameters = [] – аргументы метода

Возвращаемый результат: Core\Response – унифицированный объект-обёртка, содержит:

Symfony\Contracts\HttpClient\ResponseInterface — объект ответа от сервера, может быть асинхронным
Core\Commands\Command — информация о команде\аргументах которая была исполнена, используется при разборе пакетных запросов.

Для получения результата запроса к API используется метод Response::getResponseData, который декодирует тело ответа вызвав метод Symfony\Contracts\HttpClient::toArray Возвращается стандартизированный DTO ResponseData от API-сервера с полями:

Result - DTO c результатом исполнения запроса;
Time — DTO c таймингом прохождения запроса через сервера Битрикс24;
Pagination — DTO постраничной навигации с полями next и total;

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

Объект Result содержит метод getResultData, который возвращает массив с результатом исполнения API-запроса. В зависимости от вызванного метода там может быть:

результат выполнения операции типа bool
идентификатор созданной сущности типа int
сущность + пользовательские поля с префиксами UF_ типа array
массив сущностей типа array
пустой массив как результат пустого фильтра.

ApiClient — работа с сетью и эндпоинтами API-серверов

Зона ответственности:

передача данных по сети
соблюдение контракта на эндпоинты с которыми идёт работы
«подпись» запросов токенами \ передача их в нужные входящие адреса если используется авторизация по вебхукам

Используется: Symfony HttpClient

Входящие данные:

тип http-запроса
массив с параметрами

Возвращаемые результаты: — Symfony\Contracts\HttpClient\ResponseInterface

Формат передачи данных по сети

JSON по HTTP/2 или HTTP/1.1

вопросы к обсуждению

какие улучшения в архитектуре и DX могут быть?
какие ожидания к хорошему SDK?

референсы:

рекомендовали посмотреть

https://async-aws.com/ – пробуют в асинхронность там, где это разумно
https://github.com/amocrm/amocrm-api-php - работа с моделями и DTO
https://github.com/stripe/stripe-php – финтех, дожно быть всё хорошо

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

https://github.com/zendesk/zendesk_api_client_php - апи как апи
https://github.com/zoho/zohocrm-php-sdk - мрак
https://github.com/freshworks/fresh-samples/tree/master/PHP - привет curl

какой php-sdk* можно считать эталоном?

Отакзываемся от DTO\моделей и работаем с массивами? 3.1 Как можно сделать автокомплит без DTO?

Не хочется на уровне сервиса работать с DTO Слишком много трудозатрат на SDK, пробовал в c48 (закрытая версия SDK), не всегда нужен полный объект

предложения по развитию к обсуждению: 4.1 сервисный слой переименовать в транспортный и отказаться от идеи напилить 100500 DTO (разве что в платной версии, лол)

4.2. в транспортном слое попробовать возвращать типизированный результат для сущности которую этот транспорт обслуживает

варианты:

массив + постраничка
массив
идентификатор сущности
булев забив на асинхронные фичи HTTP-клиента, т.е. разбирая сразу ответ и делая DTO

4.3. в транспортном слое сделать расширение методов для типовых операций с конкретной сущностью: 4.3.1 поддержка батч-режима для выборки возвращающая генератор 4.3.2 поддержка батч-режима для записи 4.3.3 поддержка записи с выборкой результата (сократится max число записываемых объектов с 50 до 49 + 1 запрос на выборку) 4.3.4 подумать над возможностью регистрации команд в нескольких транспортах и получении их за один зпрос пример: deals - получение сделки (транспорт 1) dealProductRows - получение табличной части сделки (транспорт 2) решение 1: возврат результата в callback \ промис ? решение 2: расширить транспорт родительской сущности специфическими методами - то, что чаще всего требуется: сущность + табличная часть

4.4. сервисный слой работающий с DTO (с48 в текущей реализации) оставить приватным и сконцентрироваться на других вещах:

тесты
хелперы
маркетинг sdk etc

советы по сборке бандла для symfony
текущий формат работы - по субботам (в любом случае отбирает достаточно много личного времени) какие варианты могут быть:
- пойти на контракт в Б24 и пилить её уже как заказной проект \ просить доп. руки у вендора
- продажа консультаций по работе с SDK-разработке приложений корпам
- забить и пилить только то что инетерсно самому себе, а не пытаться сделать цельный продукт)
- патреон\спонсорство etc.
работа с комьюнити и маркетинг опенсорса:
- чем лучше официальной
- как монивировать людей контрибьютить в проект?
- народ как правило пользует стандартные примеры из документации

mesilov commented 3 years ago

Примеры хороших sdk от Валентина:

amazon официальная генерят инфу по методам автогенерённым phpdoc
ленивое создание объектов (базовый класс) до перехода по свойству массив не нормализуется в DTO. как только начали обходить- разложили.

большая экономия на создание объектов. доступ к свойствам за счёт php-док свойств, а на уровне магических геттеров. если api развивается быстрее api.

mesilov commented 3 years ago

советы по сборке бандла для symfony

делаем либу как либу
- используем http-contracts, а не клииент!
делаем бандл и объявляет сервисы

mesilov commented 3 years ago

убрать из requre http-client и диспатчер
PSR-14, в конструктор эвент диспатчер
null event-dispatcher
null logger пробрасывать как опциональные.

mesilov commented 3 years ago

подумать про дискавери в гугле

mesilov commented 3 years ago

https://github.com/ruvents/runet-id-php-client -пример ленивых респонсов с автокомплитом.

https://github.com/symfony/contracts/tree/main/HttpClient

mesilov / bitrix24-php-sdk