Правила доработки коробочной версии Битрикс24

Приветствую всех на Хабре. Я Сергей Михнов, CEO компании Пуск, интегратора Битрикс24. В свое время мы выбрали особый путь — специализацию на коробочной версии Битрикс24. В коммуникациях на сайте или паблишинг площадках мы всегда пишем, что дорабатываем коробку бережно. Решил поделиться, что это значит для нас.

За 9 лет работы мы насмотрелись на доработанные порталы. Не оптимально написан код, модернизировано ядро там, где не должно быть и т.д. В этой статье решил поделиться конкретным списком правил, которые мы вывели для себя и придерживаемся их, чтобы обеспечить качественную разработку без ошибок.

Для начала поделюсь требованием к доработкам:  

  • Ядро не модифицируется.

  • Шаблон портала / компоненты / шаблоны компонентов не копируется.

  • Все доработки находятся в папке local, с соблюдением правил описанных в разделе «Организация кода в папке local».

  • В доработке не используются конкретные id, все что может измениться при переносе на другую копию портала вынесено в настройки модуля, с возможностью изменять через интерфейс.

  • Доработка не должна нарушать работу портала, в случае ее некорректной настройки. 

  • К каждой доработке есть инструкция по переносу без участия исполнителя. 

  • Запуск нужных скриптов.

  • Подробная инструкция какие изменения нужно произвести на портале. Например: создать пользовательские поля с указанием всех нужных параметров (название, тип, символьный код, и т.д.).

  • Файлы логов располагаются в папке logs или за пределами директории портала. Также предусмотрены механизмы отключения и ротация файлов.

  • События агентов логируются в «Журнале событий».

  • Ошибки в блоках БП логируются в «Журнал бизнес-процесса»

Правила оформления кода

Контроль качества кода производится при помощи платформы анализа Sonar. Проверка осуществляется посредством интеграции кода в ветку develop, а также при создании / изменении запросов на слияние. 

  • Соблюдается стандарт PSR-12. 

  • Для массивов используется сокращенная запись.

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

Для качественной и комфортной работы требуется:

  • Установить плагин SonarLint, который нужно будет подключить к порталу

  • В IDE настроить code style 

e9da171eb5b5bcce7ef2cac8fb28273b.png

В этом случае замечания будут отображаться в среде разработки, а большая часть будет автоматически устраняться IDE.

Также в проекте устанавливается «php-cs-fixer», который правит код в соответствии с конфигурацией local/.php-cs-fixer.php.

Для запуска в директории local выполняется команда «php ./vendor/bin/php-cs-fixer fix», и только после этого следует commit. В этом случае замечания будут отображаться в среде разработки, а большая часть будет автоматически устраняться IDE.

Это правило является основополагающим.

Теперь рассмотрим детально все нюансы осуществления качественных доработок для технических специалистов. 

#NOSONAR

Отключение проверок допускается в следующих случаях:

  • Подключение файлов.

  • Название классов которые соответствуют требованиям Bitrix Framework.

  • Легаси код.

Реализация задач (Git)

Для реализации проектов наша компания использует «git-flow».
Перед выполнением задачи мы создаем ветку от develop с id задачи на портале.

Коммиты в процессе именуются по следующему шаблону:

»[P-{id}] {summary} {note }», где

{id} — id задачи на портале;

{summary} — название задачи на портале;

{note} — дополнительная информация, при необходимости.

После завершения работы создается запрос на слияние в ветку develop, с включенными опциями «Удалить исходную ветку» и «Объединить историю коммитов». А вслед за созданием запроса на слияние автоматически запустится проверка «sonarqube-check». Если проверка завершится успешно —  проводится ревью кода. 

Если проверка имеет негативный исход —  задача не рассматривается, пока замечания не будут устранены. После их исправления в ходе ревью, код переносится на тестовый стенд по предоставленной инструкции к задаче (по умолчанию это переустановка модуля pusk.ext), и проводится проверка функционала. В случае возникновения замечаний задача возвращается на доработку. 

Перенос доработок

df4fb7f4e7a6ce66f02a22c3d5112016.png

Перенос изменений в файлах происходит только через git. В случае, если нужны настройки или выполнение скриптов, доработка дополняется инструкцией. 

  • Исполнитель реализует доработку и делает запрос на слияние в ветку develop.

  • После прохождения автоматической проверки кода и ревью доработка переносится на Test. 

  • Происходит тестирование доработки. Если появляются замечания по описанному в задаче функционалу или ломается уже реализованный функционал, то она возвращается на доработку (возвращаемся к шагу 1). 

  • Задача завершается.

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

Организация кода в папке local

Структура каталога выглядит следующим образом:

b62cf781f71d89ecb401697c9f6e25a7.png

Допускается

  • Создание дополнительных модулей

  • Подключение через автозагрузку каталога классов с соблюдением PSR-4.

Ниже подробнее разберем функционал каждой папки

Activities

Пользовательские блоки для бизнес-процессов

Components

Папка с компонентами. На первом уровне пространство имен должно соответствовать id нашего модуля с которым связан компонент. Они реализуются только на классах (через component.php  категорически запрещено). 

Js

Содержит расширения (extensions). Используется во всех случаях когда нужен js код, который будет использоваться в нескольких компонентах или для подключения на событиях.

Modules / pusk.ext

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

Agent

Содержит агенты, реализованные в модуле.

Cli

Содержит все консольные скрипты, реализованные на базе пакета symfony/console. 

Handler

Содержит обработчики событий. На первом уровне мы создаём папку с id модуля к которому относится событие. 

Infrastructure

Содержит все классы, которые используются при установке/удалении модуля или относятся к базовым функциям модуля. 

Orm

Содержит классы, которые описывают структуру таблиц в базе данных.

ResultModifier

Содержит классы, которые используются при кастомизации компонентов через шаблон. (См. раздел «templates»).

ServiceLocator

Содержит классы для подмены через сервис локатор.

Php_interface

Данный каталог должен содержать исключительно подключение файлов или конфигурирование объектов. Реализация логики в нем категорически запрещена. 

В файле init.php подключаются нужные файлы или модули.

При потребности подмены классов через сервис локатор необходимо использовать файл local/php_interface/include/crm_services.php. В нем реализуется только регистрация классов, вся логика реализуется в пространстве имен Pusk\Ext\ServiceLocator модуля. 

Templates

В файле components.php описана логика встройки в компонент перед выводом шаблона. Для мы создаем в папке templates/.default/components/bitrix аналогичную структуру целевого компонента. Для комплексных компонентов вместо файла template.php указывается соответствующий файл. 

23b0947a6db402abee8b9cfe3d784d0a.png

template.php — содержит только проверку на подключение из ядра (B_PROLOG_INCLUDED). Он нужен для идентификации шаблона и не будет подключаться при его обработке.

25540b530b57cc1fbbe3971c62fdc5d9.png

result_modifier.php —в этом файле реализуется необходимая логика. Если число строк кода более 5 — она выносится в Pusk\Ext\ResultModifier

82015a4dabda04651c4dca189ac9f701.png

Tests

Содержит тесты. Структура соответствует пространству имен тестируемых классов.

Как итог могу сказать, если хотите, чтобы сделанная доработка служила клиенту годами и ее не приходилось править от раза к разу — следуйте правилам разработки. А мы в компании для себя зафиксировали качественную доработку кода как одну из ключевых ценностей.

© Habrahabr.ru