Новое API CRM

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

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

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

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

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

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

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

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

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

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

Категории

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

• Сервисы
  • \Bitrix\Crm\Service\Accounting
  • \Bitrix\Crm\Service\Container
  • \Bitrix\Crm\Service\Context
  • \Bitrix\Crm\Service\Converter
  • \Bitrix\Crm\Service\Director
  • \Bitrix\Crm\Service\DynamicTypesMap
  • \Bitrix\Crm\Service\EditorAdapter
  • \Bitrix\Crm\Service\EventHandler
  • \Bitrix\Crm\Service\EventHistory
  • \Bitrix\Crm\Service\Factory
  • \Bitrix\Crm\Service\FileUploader
  • \Bitrix\Crm\Service\Localization
  • \Bitrix\Crm\Service\ParentFieldManager
  • \Bitrix\Crm\Service\Router
  • \Bitrix\Crm\Service\Scenario
  • \Bitrix\Crm\Service\TypesMap
  • \Bitrix\Crm\Service\UserPermissions
• Доступ к данным
  • \Bitrix\Crm\Item
  • \Bitrix\Crm\Category\Entity\Category
  • \Bitrix\Crm\Service\TypePreset
  • \Bitrix\Crm\Service\Broker
  • Идентификаторы
  • Связи
• Операции над элементами
  • \Bitrix\Crm\Field
  • \Bitrix\Crm\Service\Operation
• Интерфейсы
  • \Bitrix\Crm\Service\EditorAdapter
  • \Bitrix\Crm\Component\EntityDetails\FactoryBased
  • crm.item-details-component
  • crm.model

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

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

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

Концепции

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

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

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

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

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

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

  use Bitrix\Crm\Service\Operation;
  
  $addOperation = new Operation\Add();
  

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

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

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

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

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

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

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

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

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

Сущности

Новое API на данный момент поддерживается сущностями:

• лиды,
• сделки,
• контакты,
• компании,
• коммерческие предложения,
• новые счета,
• смарт-процессы.