Документация для разработчиков
Темная тема

Новое API CRM

Критерии и цели

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

Критерии, на которые мы ориентировались, при проектировании нового API:

  • Уменьшение дублирования кода.
  • Уменьшение связности классов.
  • Покрытие тестами.

Основные цели, которые были поставлены:

  • Повышение качества кода.
  • Уменьшение количества ошибок.
  • Ускорение процесса разработки и внедрения нового функционала.

Чтобы сделать код более структурированным, было решено разбить его на сервисы.


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

Сервисы должны строго следовать принципу единой ответственности. Это означает, что их должно быть довольно много.

Экземпляры сервисов получаются через Service\Container.

Категории

Помимо сервисов, было написано и существенное количество вспомогательного кода. Весь код можно разделить на несколько категорий:

Точкой входа при работе с новым API является Service\Container.

Через него получается нужный сервис и у него вызываются нужные методы.

В том случае, если логика программы привязана к какому-то конкретному типу сущности, точкой входа является Service\Factory.

Концепции

Ниже приведены некоторые базовые концепции, которые надо иметь в виду при работе с этим API.


Developer Experience

При проектировании API большое внимание уделялось положительному Developer Experience.

При работе с кодом не должно возникать сложностей с пониманием, как и что работает. Зачем вызывается тот или иной метод.

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


Правила именования

Для нового API мы старались следовать следующим правилам именования:

  • Базовый класс находится в "общем" неймспейсе. Например, \Bitrix\Crm\Service\Operation.
  • Его наследники находятся в папке с таким же названием, как и имя базового класса. Например, \Bitrix\Crm\Service\Operation\Add.
  • При использовании реализаций базового класса в коде необходимо указывать родительский неймспейс. Например,
    use Bitrix\Crm\Service\Operation;
    
    $addOperation = new Operation\Add();
    

Сервисы

В CRM сосредоточено большое количество функционала. Чтобы уменьшить связность между классами, большая часть функционала была разбита на сервисы.

Каждый сервис решает какую-то одну задачу. Сервисов получилось довольно много, но так с ними легче работать.


Отделение бизнес-логики

При проектировании API большое внимание уделялось расслоению классов по трем базовым слоям.

  • Данные.
  • Бизнес-логика.
  • Интерфейсы.

Классы и методы работы с бизнес-логикой не должны сами загружать данные. Данные должны приходить на вход в уже готовом виде, это существенно облегчает процесс покрытия тестами.


Unit-тесты

Проектирование классов таким образом, чтобы их можно было протестировать, улучшает структуру классов. И наличие тестов, само по себе, говорит о хорошем качестве кода.

Мы написали довольно много тестов для новых классов (и для некоторых старых тоже).


Обработка ошибок

Большая часть методов, которые выполняют какие-либо изменения, возвращает объект Bitrix\Main\Result или его наследников.

Это позволяет корректно обработать/отобразить возникшие при работе ошибки.

Дополнительно



Пользовательские комментарии

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

Для этого нужно всего лишь авторизоваться на сайте

Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
© «Битрикс», 2001-2021, «1С-Битрикс», 2021
Наверх