- PVSM.RU - https://www.pvsm.ru -
Данная статья является продолжением ранее опубликованной статьи, которую можно найти здесь [1].
В текущей статье я уделю больше внимания тому, как, не смотря на ограничения, которые вводит политика обратной совместимости, не идти на компромисс в качестве кода. И выполнять непрерывный рефакторинг в ходе любых изменений кода, а не откладывать рефакторинг до тех пор когда будет позволено внести обратно несовместимые изменения, т.к. только непрерывный рефакторинг, который производится при каждом изменении кода, ведет к постоянному улучшению дизайна кода и архитектуры приложения, что ведет к улучшению расширяемости и поддержки кода в целом.
Откладывание рефакторинга на потом ведет к увеличению технического долга и созданию задач (user story) на рефакторинг, которые не имеют business value для product owner-a, а соответственно такие задачи не будут попадать в топ продуктового беклога.
Вместо удаления класса либо интерфейса мы отмечаем данную сущность аннотацией @deprecated
. Отмечаем также все методы этой сущности как @deprecated
для того, чтобы все IDE подсвечивали правильно все deprecated методы.
Причина, по которой сущность стала @deprecated
, должна быть указана после аннотации. @see
аннотация должна быть использована для рекомендации нового API, которое должно быть использовано вместо устаревшего.
/**
* @deprecated because new api was introduced
* @see NewApi
*/
Вместо удаления метода, который может служить публичным контрактом либо контрактом для наследования, нужно пропаркировать метод как @deprecated
. При этом нужно сохранить контракт метода.
Так как Magento не знает как будет использоваться интерфейс как API или как точка расширения (SPI) (подробнее об этом читайте в части 1 [1]), то добавление нового метода в контракт также является обратно несовместимым изменением (дальше — BiC), потому что если интерфейс используется как SPI, т.е. сторонние разработчики (дальше — 3PD) предоставляют свою реализацию для него, и подменяют через DI конфигурацию реализацию из коробки. Введя новый метод в контракт сущности — мы принесем проблемы для класса 3PD, у которого нет реализации для нового контракта.
В случае класса — мы всегда можем попасть на коллизию имен, если кто-то наследует этот класс и расширяет его контракт.
В этом случае нужно:
@deprecated
с добавлением аннотации @see
, которая будет указывать на контракт во вновь созданном интерфейсе.@api
Исходя из того, что 3PD по прежнему могут использовать Inheritance Based API и наследовать Magento классы расширяя их контракт, то добавление параметра в метод может привести к тому, что мы поломаем класс-наследник, который также добавил опциональный параметр к изначальному контракту.
Вместо изменения кода старого метода мы должны ввести новый интерфейс в котором будет указана новая сигнатура метода, которая отвечает нашим измененным бизнес требованиям.
Дальше см. процедуру описанную в пункте «Добавление нового метода в класс или интерфейс».
Сохраняем метод как есть. Создаем новый метод с новой сигнатурой, и помечаем старый метод как @deprecated
. Если возможно создаем новый метод как private.
*только в случае если новый тип исключительной ситуации не является подтипом старого контракта.
Для того, чтобы добавить новый параметр в конструктор необходимо сделать параметр опциональным и добавить его последним в список принимаемых аргументов.
В теле конструктора должна быть проверка передана ли новая зависимость, и если новая зависимость не была передана (значение переданного аргумента — null) — извлечь зависимость используя статический метод MagentoFrameworkAppObjectionManager::getInstance()
.
Пример:
class ExistingClass
{
/**
* @var NewDependencyInterface $newDependency
*/
private $newDependency;
public function __construct(
OldDependencyIntreface $oldDependency,
$oldRequiredConstructorParameter,
$oldOptinalConstructorParameter = null,
NewDependencyInterface $newDependency = null
) {
...
$this>newDependency = $newDependency ?: MagentoFrameworkAppObjectManager::getInstance()
->get(NewDependencyInterface::class);
...
}
public function existingFunction() {
// Existing functionality
...
// Use $this->newDependency wherever the new dependency is needed
...
}
}
И как проводить рефакторинг, когда нельзя удалять старые зависимости переданные в конструктор, а можно только добавлять новые. Тем самым мы приближаем Dependency Hell, когда классы принимают огромное колличество внешних зависимостей нарушая при этом SOLID принципы.
Во-первых, нужно категорически запретить подавление ошибок в статических тестах, которые говорят о превышение coupling для вновь созданного кода. Т.е. такие SuppressWarning не должны добавляться после выполнения баг фикса или реализации новой функциональности.
Если же мы вносим новую валидную зависимость в класс, например, для того чтобы пофиксить баг, и после этого мы переходим порог количества допустимых внешних зависимостей (13 [3]).
Мы должны:
@deprecated
с указанием @see
аннотации на вновь созданные методы в новом классе.@deprecated
После выполнения действий описанных выше наш код кран засияет новыми красками. И что самое важное — контракт останется таким же как и был до изменений, а соответственно клиенты не заметят этих изменений!
Автор: Игорь Миняйло
Источник [4]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/php-2/251262
Ссылки в тексте:
[1] здесь: https://habrahabr.ru/post/324450/
[2] cohesion: https://en.wikipedia.org/wiki/Cohesion_(computer_science)
[3] 13: https://phpmd.org/rules/design.html#couplingbetweenobjects
[4] Источник: https://habrahabr.ru/post/325124/
Нажмите здесь для печати.