Обратная совместимость

Не добавляйте аргументы в существующие функции API

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

Нарушение обратной совместимости продемонстрировано ниже на примере двух классов: lib.kt представляющего «библиотеку», и client.kt представляющего «клиента» этой «библиотеки». Такая конструкция для библиотек и их клиентов распространена в реальных приложениях. В этом примере «библиотека» имеет одну функцию, которая вычисляет пятый член последовательности Фибоначчи. Файл lib.kt содержит:

fun fib() = … // Returns the fifth element

Давайте вызовем эту функцию из другого файла, client.kt:

fun main() {
    println(fib()) // Returns 3
}

Давайте скомпилируем классы:

kotlinc lib.kt client.kt 

Компиляция приводит к двум файлам: LibKt.class и ClientKt.class.

Давайте вызовем клиента, чтобы убедиться, что всё работает:

$ kotlin ClientKt.class
3

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

lib.kt:

fun fib(numberOfElement: Int = 5) = … // Returns requested member

Давайте перекомпилируем только «библиотеку»: kotlinc lib.kt.

Давайте запустим «клиента»:

$ kotlin ClientKt.class

Результат:

Exception in thread "main" java.lang.NoSuchMethodError: 'int LibKt.fib()'
       at LibKt.main(fib.kt:2)
       at LibKt.main(fib.kt)
       …

Возникла ошибка NoSuchMethodError, потому что сигнатура функции fib() изменилась после компиляции.

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

❯ javap LibKt
Compiled from "lib.kt"
public final class LibKt {
 public static final int fib();
}

❯ javap LibKt
Compiled from "lib.kt"
public final class LibKt {
 public static final int fib(int);
 public static int fib$default(int, int, java.lang.Object);
}

Не используйте классы данных в API

Классы данных заманчивы, потому что они короткие, лаконичные и предоставляют некоторые удобные функции «из коробки». Однако из-за некоторых особенностей работы с классами данных лучше не использовать их в API библиотек. Практически любое изменение делает API несовместимым с предыдущими версиями.

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

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

data class User(
    val name: String,
    val email: String
)

Например, со временем вы понимаете, что пользователи должны пройти процедуру активации, поэтому вы хотите добавить новое поле «активный», со значением по умолчанию «true». Это новое поле должно позволить существующему коду работать в основном без изменений.

Как уже обсуждалось в разделе выше, вы не можете просто добавить новое поле таким образом:

data class User(
    val name: String,
    val email: String,
    val active: Boolean = true
)

Потому что это изменение не бинарно совместимо.

Давайте добавим новый конструктор, который принимает только два аргумента и вызывает первичный конструктор с третьим аргументом по умолчанию:

data class User(
    val name: String,
    val email: String,
    val active: Boolean = true
) {
    constructor(name: String, email: String) :
            this(name, email, active = true)
}

В этот раз есть два конструктора, и сигнатура одного из них совпадает с конструктором класса до изменения:

public User(java.lang.String, java.lang.String);

Но проблема не в конструкторе – она в функции copy. Её сигнатура изменилась с:

public final User copy(java.lang.String, java.lang.String);

До:

public final User copy(java.lang.String, java.lang.String, boolean);

И это сделало код не бинарно совместимым.

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

Если вам необходимо использовать класс данных по какой-либо причине, вам нужно переопределить конструктор и метод copy(). Кроме того, если вы добавите поле в тело класса, вам нужно переопределить методы hashCode() и equals().

Не сужайте типы возвращаемых значений

Иногда, особенно когда вы не используете явный режим API, объявление типа возвращаемого значения может неявно измениться. Но даже если это не так, вы можете захотеть сузить сигнатуру. Например, вы можете понять, что вам нужна индексация элементов вашего набора и захотите изменить тип возвращаемого значения с Collection на List. Расширение типа возвращаемого значения обычно нарушает совместимость исходного кода; например, преобразование с List на Collection нарушает весь код, использующий индексацию. Сужение типов возвращаемых значений обычно является изменением, сохраняющим совместимость исходного кода, но оно нарушает бинарную совместимость, и этот раздел описывает, как.

Рассмотрим функцию библиотеки в файле library.kt:

public fun x(): Number = 3

И пример её использования в файле client.kt:

fun main() {
    println(x()) // Prints 3
}

Давайте скомпилируем его с kotlinc library.kt client.kt и убедимся, что всё работает:

$ kotlin ClientKt
3

Давайте изменим тип возвращаемого значения функции "библиотеки" x() с Number на Int:

fun x(): Int = 3

И перекомпилируем только клиента: kotlinc client.kt. ClientKt больше не работает должным образом. Он больше не печатает 3 и вместо этого выбрасывает исключение:

Exception in thread "main" java.lang.NoSuchMethodError: 'java.lang.Number Library.x()'
    	at ClientKt.main(call.kt:2)
    	at ClientKt.main(call.kt)
    	…

Это происходит из-за следующей строки в байткоде:

0: invokestatic  #12 // Method Library.x:()Ljava/lang/Number;

Эта строка означает, что вы вызываете статический метод x(), возвращающий тип Number. Но такого метода больше нет, и поэтому была нарушена бинарная совместимость.

Валидатор бинарной совместимости

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

Этот инструмент может сэкономить значительное количество времени и усилий, которые вы бы иначе потратили на ручное тестирование и проверку. Он также может помочь предотвратить проблемы, которые могут возникнуть из-за нарушений обратной совместимости в API. В конечном счете, это может привести к лучшему пользовательскому опыту, поскольку пользователи смогут полагаться на стабильность и совместимость библиотеки или фреймворка.

japicmp

Если вы нацеливаетесь только на JVM как платформу, вы также можете использовать japicmp. japicmp работает на другом уровне, чем валидатор бинарной совместимости: он сравнивает два файла jar — старый и новый — и сообщает о несовместимостях между ними.

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

class Calculator {
    fun add(a: Int, b: Int): Int = a + b
    fun multiply(a: Int, b: Int): Int = a * b
}

Если вы добавите новый метод без нарушения совместимости, как в этом примере:

class Calculator {
    fun add(a: Int, b: Int): Int = a + b
    fun multiply(a: Int, b: Int): Int = a * b
    fun divide(a: Int, b: Int): Int = a / b
}

Тогда japicmp сообщит об этом изменении:

Это просто изменение аннотации @Metadata, что не очень интересно, но japicmp не зависит от языка JVM и должен сообщать обо всём, что видит.