Формализация принципа Open/Closed: как сохранить обратную совместимость с помощью SOLID

Привет, Хабр! Меня зовут Дмитрий Сурков, я iOS-разработчик приложения для среднего и малого бизнеса ПСБ.

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

Реализация фич осуществляется в отдельных модулях — фреймворках и библиотеках. При разработке мы руководствуемся принципами SOLID. Разработку выделенного модуля важно вести в соответствии с принципом Открытости/Закрытости (система должна быть открыта для расширения, но закрыта для изменения). 

Каждое изменение фиксируется определенной версией по СемВер. Изменения в коде, которые изменяют публичный интерфейс, обязывают вносить правки во всех потребителях данного модуля. Чем чаще такие изменения делаем — тем хуже стабильность системы, а время разработки заметно возрастает. Необходимо стараться вносить изменения в код, которые не будут изменять существующий публичный интерфейс.

В данной статье, мы рассмотрим:

• Пример на библиотеке дизайн-системы с компонентами, так как она используется в основном приложении и дополнительном фреймворке построения UI.

• Что такое семантическое версионирование и как мы его используем.

• Анализ и поиск решения наиболее частых нарушений обратной совместимости.

• Итоги проделанной работы.

Исходная точка

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

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

Наш ci настроен на многочисленные автоматизации: проверка сборки, покрытие тестами, связи с задачами, автоподнятие версии и т.д. При создании мердж реквеста запускается пайплайн, в котором выполняются все эти проверки. Также стоит брать во внимание человеческий фактор и загруженность.

На основе этого можно выделить следующую цепочку действий:

1. Необходимо завести задачу на поднятие версии (≈ 5 мин).

2. Создать ветку, внести изменения и проверить работоспособность, а еще внести правки, если необходимо (≈ 15-20 мин).

3. Отправить на код-ревью (≈ 2-3 мин).

4. Подвинуть задачу по статусам, в нашем случае необходим ресурс тестировщика (1-∞ мин).

5. Пройти ревью, дождаться успешного выполнения пайплайна (≈ 60 мин).

6. Влить в мастер.

7. И снова по кругу...

Последний пункт говорит о повторении процесса для всех остальных клиентов, для которых также необходимо поднять версию зависимости. В итоге весь процесс может занимать от 2 до 3 часов, потом умножаем на количество клиентов и получаем 4-6 часов.

Это довольно много для простого поднятия версии, поэтому мы решили разобраться, как мы можем сократить это время и свести к минимуму мажорные изменения. Давайте приступать!

Семантическое версионирование

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

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

Мы придерживаемся данных правил. Кроме того, организовали автоподнятие версий.
Перед влитием задачи в мастер, происходит выполнение пайплайна, где в логах отображается результат проверки ABI и выставляется соответствующая версия.

Желтым выделен warning = поднятие минорной версии.
Красным выделен error = поднятие мажорной версии.
А далее идет описание того, что вызвало данные изменения. Если ничего нет, то это обычно патч.

Благодаря такой наглядности мы можем проанализировать всё, что вызывает повышение той или иной версии, и вот что у нас получилось:

Major версия

Изменения в public протоколе:

• Удаление протокола

• Изменение названия

• Расширение новым типом, требующим реализации обязательных методов / свойств / соответствия, без дефолтной реализации в расширении протокола

• Добавление или удаление метода / свойства

• Изменение названия метода / свойства

• Изменение типа возвращаемого значения метода / свойства

• Изменение сигнатуры метода — добавление обязательных аргументов, изменение типов или названий аргументов

Изменения в public классах и структурах:

• Удаление класса / структуры

• Изменение названия

• Понижение уровня доступа методов, свойств

• Изменение типа данных свойств

• Удаление метода или свойства

Изменения в public перечислениях:

• Удаление случая (case)

• Добавление случая (case)

• Переименование случая (case)

• Изменение ассоциированных значений (associated values)

• Изменение методов / свойств и их названий / типов / аргументов

Изменения во внешних зависимостях (зависимости SPM пакета):

• Добавление и удаление зависимости — в случае, когда зависимость используется в коде и вызывает мажорные изменения

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

Minor версия

Изменения в public протоколе:

• Добавление нового public протокола

• Добавление свойства или метода с дефолтной реализацией через расширение протокола

Изменения в public классах и структурах:

• Добавление нового public класса или структуры

• Добавление инициализатора

• Добавление свойств в инициализаторы с дефолтными значениями

• Добавление свойств с дефолтным значением или вычисляемым свойством

• Увеличение уровня доступа методов и свойств

Изменения в public перечислениях:

• Добавление свойств с дефолтным значением или вычисляемым свойством

Изменения во внешних зависимостях (зависимости SPM пакета):

• Добавление и удаление зависимости — в случае, когда зависимость используется в коде и вызывает минорные изменения

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

Patch версия

Изменения в public протоколе:

• Расширение типом, который не нарушает обратную совместимость, не требует обязательной реализации и соответствия, а также не добавляет новый функционал, например добавление 'Sendable'

• Изменение порядка объявления методов / свойств / типов

• Изменение дефолтного значения свойства

Изменения в public классах и структурах:

• Аналогичные 'Патч' изменениям в протоколах

• Добавление не публичных методов / свойств / сущностей

Изменения в public перечислениях:

• Аналогичные 'Патч' изменениям в протоколах

• Добавление непубличных методов / свойств / сущностей

Изменения во внешних зависимостях (зависимости SPM пакета):

• Удаление и добавление зависимостей — в случае, когда зависимость используется в коде и не вызывает мажорных и минорных изменений 

• Повышение версии зависимости — при условии ненарушения совместимости, которая влечет к поднятию мажорной версии

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

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

Нарушение обратной совместимости

Добавление обязательных методов/свойств в публичный протокол

❌error: ABI breakage: func OldProtocol.makeSomething2() has been added as a protocol requirement

  public protocol OldProtocol {
    func makeSomething()
+   func makeSomething2()
}

Решения:

1. Еще раз подумать, а нужен ли вам этот метод. Это не шутка. Бывает, понимаешь, что данная доработка и вовсе не нужна.

2. Объявление метода в расширении протокола. Простой вариант обратной совместимости, но имеет ограничение — можно использовать только интерфейсы, объявленые в протоколе, нельзя переопределять.

public protocol OldProtocol {
    func makeSomething()
}
 
extension OldProtocol {

   public func makeSomething2() {
      // do something
      makeSomething()
   }
}

3. Дефолтная реализация в расширении протокола. Простой вариант обратной совместимости, можно переопределять, но имеет ограничение — можно использовать только интерфейсы, объявленные в протоколе.

public protocol OldProtocol {
    func makeSomething()
+   func makeSomething2()
}
 
extension OldProtocol {

   public func makeSomething2() {
      // do something
      makeSomething()
   }
}

4. Создать новый протокол. Такое решение можно применять, если новый метод не имеет зависимостей на старый протокол.

public protocol OldProtocol {
    func makeSomething()
}
 
public protocol NewProtocol {
   func makeSomething2()
}
 
extension SomeViewModel: NewProtocol {

   public func makeSomething2() {
      // do something
   }
}

Данное решение позволяет расширять функционал, не затрагивая старых клиентов.

let value: OldProtocol & NewProtocol

5. Сделать метод опциональным. Такое решение можно применять только для objc протоколов, если вы хотите расширить функционал необязательным в реализации методом.

@objc public protocol OldProtocol {
    func makeSomething()
+   @objc optional func makeSomething2()
}

Добавление обязательных свойств в публичный протокол

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

Добавление параметра в публичный метод или инициализатор

❌error: ABI breakage: constructor init(title:identifier:) has been removed

❌error: ABI breakage: func perform(title:) has been removed

public init(
   title: String? = nil,
+  subtitle: String? = nil
   identifier: String = String(describing: Self.self)
) {
   self.title = title
+  self.subtitle = subtitle
   self.identifier = identifier
}
 
public func perform(
    title: String,
+   subtitle: String? = nil
) {
    // do something
}

Установка дефолтного значения не помогает избежать ошибки. Решением является создать отдельный инициализатор / метод.

public struct ViewModel {

    public let title: String?
+   public let subtitle: String?
    public let identifier: String  
 
    // Will be removed in the future major versions.
    public init(
        title: String? = nil,
        identifier: String
    ) {
        self.init(
            title: title,
            subtitle: nil,
            identifier: identifier
        )
    }
     
+    public init(
+        title: String? = nil,
+        subtitle: String? = nil,
+        identifier: String
+    ) {
+        self.title = title
+        self.subtitle = subtitle
+        self.identifier = identifier
+    } 
 
    // Will be removed in the future major versions.     
    public func perform(
        title: String
    ) {
        // do something
    }
 
+    public func perform(
+        title: String,
+        subtitle: String? = nil
+    ) {
+        // do something
+    }
 }

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

public class ViewModel {

    public let title: String?
+   public private(set) var subtitle: String?
    public let identifier: String
 
    // Will be removed in the future major versions.
    public convenience init(
        title: String? = nil,
        identifier: String
    ) {
        self.init(
           title: title,
           subtitle: nil,
           identifier: identifier
        )
    }
     
+    public init(
+        title: String? = nil,
+        subtitle: String? = nil,
+        identifier: String
+    ) {
+        self.title = title
+        self.subtitle = subtitle
+        self.identifier = identifier
+    }
 
    // Will be removed in the future major versions.
    public func perform(
        title: String
    ) {
        // do something
    }
 
+    public func perform(
+        title: String,
+        subtitle: String? = nil
+    ) {
+        // do something
+    }
 }

⚠️ Обратите внимание! При вызове нового инициализатора внутри старого обязательно нужно указывать все параметры, иначе может произойти рекурсивный вызов, и компилятор выведет: warning - Function call causes an infinite recursion.

Удаление public протокола/сущности/метода/свойства

Если функционал устарел и существует новый аналог.

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

❌error: ABI breakage: protocol MyProtocol has been removed

@available(*, deprecated, message:"Will be removed in the future major versions. Use `MyProtocolV2`")
public protocol MyProtocol {...}
 
public protocol MyProtocolV2 {
    @available(*, deprecated, message:"Will be removed in the future major versions. Use `MyProtocolV2.makeSomething2()`")
    func makeSomething()
    func makeSomething2()
    @available(*, deprecated, message:"Will be removed in the future major versions. Use `MyProtocolV2.somePropertyV2`")
    var someProperty { get }
    var somePropertyV2 { get }
}

Изменение названия public протокола

❌error: ABI breakage: protocol MyProtocol has been renamed to protocol MyProtocolV2

Добавляем 'typealias' со старым названием и помечаем протокол 'deprecated', чтобы клиенты не использовали в новом функционале.

@available(*, deprecated, message:"Will be removed in the future major versions. Use `MyProtocolV2`")
public typealias MyProtocol = MyProtocolV2
 
public protocol MyProtocolV2 { ... }

Поднятие версии платформы

Поднятие версии платформы, например, версии iOS в настройках SPM пакета — это мажорное изменение. Хоть явного упоминания о мажорной версии может и не быть.

Заключение

Ведя разработку таким образом, мы соблюдаем принцип Open / Closed. Не затрагиваем существующий функционал, а только расширяем его, добавляя дополнительные инициализаторы и методы, делая расширения на протоколы и сущности.

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

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

• За три месяца в мастер было влито 27 мердж реквестов.

• Из них 1 Major, 17 Minor,  9 Patch версий

• Удалось исправить 6 мердж реквестов с мажорных на минорные

• Учитывая данные, количество времени на процесс поднятия версии у клиента и их количество, мы сэкономили 6 мердж реквестов * 3 часа * 2 модуля ≈ 24 - 36 часов

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