Привет! Меня зовут Юрий Влад, я Android-разработчик в компании Badoo и принимаю участие в создании библиотеки Reaktive — Reactive Extensions на чистом Kotlin.

Любая библиотека должна по возможности соблюдать бинарную совместимость. Если разные версии библиотеки в зависимостях несовместимы, то результатом будут краши в рантайме. С такой проблемой мы можем столкнуться, например, при добавлении поддержки Reaktive в MVICore.

В этой статье я вкратце расскажу, что такое бинарная совместимость и каковы её особенности для Kotlin, а также о том, как её поддерживают в JetBrains, а теперь и в Badoo.

Проблема бинарной совместимости в Kotlin

Предположим, у нас есть замечательная библиотека com.sample:lib:1.0 с таким классом:

data class A(val a: Int)

На базе неё мы создали вторую библиотеку com.sample:lib-extensions:1.0. Среди её зависимостей есть com.sample:lib:1.0. Например, она содержит фабричный метод для класса A:

fun createA(a: Int = 0): A = A(a)

Теперь выпустим новую версию нашей библиотеки com.sample:lib:2.0 со следующим изменением:

data class A(val a: Int, val b: String? = null)

Полностью совместимое с точки зрения Kotlin изменение, не так ли? С параметром по умолчанию мы можем продолжать использовать конструкцию val a = A(a), но только в случае полной перекомпиляции всех зависимостей. Параметры по умолчанию не являются частью JVM и реализованы специальным synthetic-конструктором A, который содержит в параметрах все поля класса. В случае получения зависимостей из репозитория Maven мы их получаем уже в собранном виде и перекомпилировать их не можем.

Выходит новая версия com.sample:lib, и мы сразу же подключаем её к своему проекту. Мы же хотим быть up to date! Новые функции, новые исправления, ~~новые баги~~!

dependencies {
    implementation 'com.sample:lib:2.0'
    implementation 'com.sample:lib-extensions:1.0'
}

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

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

Подробнее про бинарную совместимость вы можете почитать в статьях «Бинарная совместимость в примерах и не только» пользователя gvsmirnov, «Evolving Java-based APIs 2» от создалей Eclipse и в недавно вышедшей статье «Public API challenges in Kotlin» Джейка Уортона.

Способы обеспечения бинарной совместимости

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

Java API Compliance Checker
Clirr
Revapi
Japicmp
Japitools
Jour
Japi-checker
SigTest

Они принимают два JAR-файла и выдают результат: насколько они совместимы.

Однако мы разрабатываем Kotlin-библиотеку, которую пока есть смысл использовать только из Kotlin. А значит, нам не всегда нужна 100%-ная совместимость, например для internal классов. Хоть они и являются публичными в байт-коде, но их использование вне Kotlin-кода маловероятно. Поэтому для поддержания бинарной совместимости kotlin-stdlib JetBrains использует Binary compatibility validator. Основной принцип такой: из JAR-файла создаётся дамп всего публичного API и записывается в файл. Этот файл является baseline (эталоном) для всех дальнейших проверок, а выглядит он так:

public final class kotlin/coroutines/ContinuationKt {
    public static final fun createCoroutine (Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)Lkotlin/coroutines/Continuation;
    public static final fun createCoroutine (Lkotlin/jvm/functions/Function2;Ljava/lang/Object;Lkotlin/coroutines/Continuation;)Lkotlin/coroutines/Continuation;
    public static final fun startCoroutine (Lkotlin/jvm/functions/Function1;Lkotlin/coroutines/Continuation;)V
    public static final fun startCoroutine (Lkotlin/jvm/functions/Function2;Ljava/lang/Object;Lkotlin/coroutines/Continuation;)V
}

После внесения изменений в исходный код библиотеки baseline заново генерируется, сравнивается с текущим — и проверка завершается с ошибкой, если появились любые изменения в baseline. Эти изменения можно перезаписать, передав -Doverwrite.output=true. Ошибка возникнет, даже если произошли бинарно совместимые изменения. Это нужно для того, чтобы своевременно обновлять baseline и видеть его изменения прямо в pull request.

Binary compatibility validator

Давайте разберём, как работает этот инструмент. Бинарная совместимость обеспечивается на уровне JVM (байт-кода) и не зависит от языка. Вполне возможно заменить реализацию Java-класса на Kotlin-, не сломав бинарную совместимость (и наоборот).
Сначала нужно вообще понять, какие классы есть в библиотеке. Мы помним, что даже для глобальных функций и констант создаётся класс с именем файла и суффиксом Kt, например ContinuationKt. Для получения всех классов воспользуемся классом JarFile из JDK, получим указатели на каждый класс и передадим их в org.objectweb.asm.tree.ClassNode. Этот класс позволит нам узнать видимость класса, его методы, поля и аннотации.

val jar = JarFile("/path/to/lib.jar")
val classStreams = jar.classEntries().map { entry -> jar.getInputStream(entry) }
val classNodes = classStreams.map { 
    it.use { stream ->
        val classNode = ClassNode()
        ClassReader(stream).accept(classNode, ClassReader.SKIP_CODE)
        classNode
    }
}

Kotlin при компиляции добавляет свою рантайм-аннотацию @Metadata к каждому классу, чтобы kotlin-reflect смог восстановить вид Kotlin-класса до его преобразования в байт-код. Выглядит она так:

@Metadata(
   mv = {1, 1, 16},
   bv = {1, 0, 3},
   k = 1,
   d1 = {"\u0000 \n\u0002\u0018\u0002\n\u0002\u0010\u0000\n\u0000\n\u0002\u0010\b\n\u0002\b\u0006\n\u0002\u0010\u000b\n\u0002\b\u0003\n\u0002\u0010\u000e\n\u0000\b\u0086\b\u0018\u00002\u00020\u0001B\r\u0012\u0006\u0010\u0002\u001a\u00020\u0003¢\u0006\u0002\u0010\u0004J\t\u0010\u0007\u001a\u00020\u0003HÆ\u0003J\u0013\u0010\b\u001a\u00020\u00002\b\b\u0002\u0010\u0002\u001a\u00020\u0003HÆ\u0001J\u0013\u0010\t\u001a\u00020\n2\b\u0010\u000b\u001a\u0004\u0018\u00010\u0001HÖ\u0003J\t\u0010\f\u001a\u00020\u0003HÖ\u0001J\t\u0010\r\u001a\u00020\u000eHÖ\u0001R\u0011\u0010\u0002\u001a\u00020\u0003¢\u0006\b\n\u0000\u001a\u0004\b\u0005\u0010\u0006¨\u0006\u000f"},
   d2 = {"Lcom/sample/A;", "", "a", "", "(I)V", "getA", "()I", "component1", "copy", "equals", "", "other", "hashCode", "toString", "", "app_release"}
)

Из ClassNode можно получить @Metadata аннотацию и распарсить её в KotlinClassHeader. Приходится делать это вручную, поскольку kotlin-reflect не умеет работать с ObjectWeb ASM.

val ClassNode.kotlinMetadata: KotlinClassMetadata?
    get() {
        val metadata = findAnnotation("kotlin/Metadata", false) ?: return null
        val header = with(metadata) {
            KotlinClassHeader(
                kind = get("k") as Int?,
                metadataVersion = (get("mv") as List<Int>?)?.toIntArray(),
                bytecodeVersion = (get("bv") as List<Int>?)?.toIntArray(),
                data1 = (get("d1") as List<String>?)?.toTypedArray(),
                data2 = (get("d2") as List<String>?)?.toTypedArray(),
                extraString = get("xs") as String?,
                packageName = get("pn") as String?,
                extraInt = get("xi") as Int?
            )
        }
        return KotlinClassMetadata.read(header)
    }

kotlin.Metadata понадобится для того, чтобы правильно обрабатывать internal, ведь его не существует в байт-коде. Изменения internal классов и функций не могут повлиять на пользователей библиотеки, хоть они и являются публичным API с точки зрения байт-кода.

Из kotlin.Metadata можно узнать о companion object. Даже если вы его объявите приватным, он всё равно будет храниться в публичном статическом поле Companion, а значит, это поле попадает под требование наличия бинарной совместимости.

class CompositeException() {
    private companion object { }
}

public final static Lcom/badoo/reaktive/base/exceptions/CompositeException$Companion; Companion
  @Ljava/lang/Deprecated;()

Из необходимых аннотаций стоит отметить ещё @PublishedApi для классов и методов, которые используются в публичных inline функциях. Тело таких функций остаётся в местах их вызова, а значит, классы и методы в них должны быть бинарно совместимы. При попытке использовать не публичные классы и методы в таких функциях компилятор Kotlin выдаст ошибку и предложит их пометить аннотацией @PublishedApi.

fun ClassNode.isPublishedApi() = findAnnotation("kotlin/PublishedApi", includeInvisible = true) != null

Для поддержки бинарной совместимости важны дерево наследования классов и реализация интерфейсов. Мы не можем, например, просто удалить какой-то интерфейс из класса. А получить родительский класс и реализуемые интерфейсы довольно просто.

val supertypes = listOf(classNode.superName) - "java/lang/Object" + classNode.interfaces.sorted()

Из списка удалён Object, так как его отслеживание не несёт в себе никакого смысла.

Внутри валидатора содержится очень много различных дополнительных специфичных для Kotlin проверок: проверка методов по умолчанию в интерфейсах через Interface$DefaultImpls, игнорирование $WhenMappings классов для работы when оператора и другие.

Далее необходимо пройтись по всем ClassNode и получить их MethodNode и FieldNode. Из сигнатуры классов, их полей и методов мы получим ClassBinarySignature, FieldBinarySignature и MethodBinarySignature, которые объявлены локально в проекте. Все они реализуют интерфейс MemberBinarySignature, умеют определять свою публичную видимость методом isEffectivelyPublic и выводить свою сигнатуру в читабельном формате val signature: String.

classNodes.map { with(it) {
    val metadata = kotlinMetadata 
    val mVisibility = visibilityMapNew[name]
    val classAccess = AccessFlags(effectiveAccess and Opcodes.ACC_STATIC.inv())

    val supertypes = listOf(superName) - "java/lang/Object" + interfaces.sorted()

    val memberSignatures = (
        fields.map { with(it) { FieldBinarySignature(JvmFieldSignature(name, desc), isPublishedApi(), AccessFlags(access)) } } +
        methods.map { with(it) { MethodBinarySignature(JvmMethodSignature(name, desc), isPublishedApi(), AccessFlags(access)) } }
    ).filter {
        it.isEffectivelyPublic(classAccess, mVisibility)
    }

    ClassBinarySignature(name, superName, outerClassName, supertypes, memberSignatures, classAccess, isEffectivelyPublic(mVisibility), metadata.isFileOrMultipartFacade() || isDefaultImpls(metadata)
} }

Получив список ClassBinarySignature, его можно записать в файл или в память методом dump(to: Appendable) и сравнить с baseline, что и происходит в тесте RuntimePublicAPITest:

class RuntimePublicAPITest {

    @[Rule JvmField]
    val testName = TestName()

    @Test fun kotlinStdlibRuntimeMerged() {
        snapshotAPIAndCompare("../../stdlib/jvm/build/libs", "kotlin-stdlib")
    }

    private fun snapshotAPIAndCompare(
        basePath: String,
        jarPattern: String,
        publicPackages: List<String> = emptyList(),
        nonPublicPackages: List<String> = emptyList()
    ) {
        val base = File(basePath).absoluteFile.normalize()
        val jarFile = getJarPath(base, jarPattern, System.getProperty("kotlinVersion"))

        println("Reading binary API from $jarFile")
        val api = getBinaryAPI(JarFile(jarFile)).filterOutNonPublic(nonPublicPackages)

        val target = File("reference-public-api")
            .resolve(testName.methodName.replaceCamelCaseWithDashedLowerCase() + ".txt")

        api.dumpAndCompareWith(target)
    }

Закоммитив новый baseline, мы получим изменения в читабельном формате, как, например, в этом коммите:

    public static final fun flattenObservable (Lcom/badoo/reaktive/single/Single;)Lcom/badoo/reaktive/observable/Observable;
}

+ public final class com/badoo/reaktive/single/MapIterableKt {
+   public static final fun mapIterable (Lcom/badoo/reaktive/single/Single;Lkotlin/jvm/functions/Function1;)Lcom/badoo/reaktive/single/Single;
+   public static final fun mapIterableTo (Lcom/badoo/reaktive/single/Single;Lkotlin/jvm/functions/Function0;Lkotlin/jvm/functions/Function1;)Lcom/badoo/reaktive/single/Single;
+ }

public final class com/badoo/reaktive/single/MapKt {

Использование валидатора в своём проекте

Использовать крайне просто. Скопируйте в свой проект binary-compatibility-validator и измените его build.gradle и RuntimePublicAPITest:

plugins {
    id("org.jetbrains.kotlin.jvm")
}

dependencies {
    implementation(Deps.asm)
    implementation(Deps.asm.tree)
    implementation(Deps.kotlinx.metadata.jvm)

    testImplementation(Deps.kotlin.test.junit)
}

tasks.named("test", Test::class) {

    // В оригинале для зависимостей используются артефакты, но по какой-то причине в моем случае Gradle не смог правильно разрешить зависимости мультиплатформенных библиотек:
    dependsOn(
        ":coroutines-interop:jvmJar",
        ":reaktive-annotations:jvmJar",
        ":reaktive:jvmJar",
        ":reaktive-annotations:jvmJar",
        ":reaktive-testing:jvmJar",
        ":rxjava2-interop:jar",
        ":rxjava3-interop:jar",
        ":utils:jvmJar"
    )

    // Не кешируем этот тест, так как он с побочным эффектом в виде создания baseline-файла:
    outputs.upToDateWhen { false }

    // Задаём параметры теста
    systemProperty("overwrite.output", findProperty("binary-compatibility-override") ?: "true")
    systemProperty("kotlinVersion", findProperty("reaktive_version").toString())
    systemProperty("testCasesClassesDirs", sourceSets.test.get().output.classesDirs.asPath)
    jvmArgs("-ea")
}

В нашем случае одна из тестовых функций файла RuntimePublicAPITest выглядит так:

@Test fun reaktive() {
    snapshotAPIAndCompare("../../reaktive/build/libs", "reaktive-jvm")
}

Теперь для каждого pull request запускаем ./gradlew :tools:binary-compatibility:test -Pbinary-compatibility-override=false и заставляем разработчиков вовремя обновлять baseline-файлы.

Ложка дёгтя

Однако у этого подхода есть и плохие стороны.

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

- public final class com/test/A {
+ public final class com/test/A : Comparable {

Во-вторых, используются инструменты, которые для этого не предназначены. Тесты не должны иметь сайд-эффекты в виде записи какого-то файла на диск, который будет впоследствии использован этим же тестом, и тем более передавать в него параметры через переменные окружения. Было бы здорово использовать этот инструмент в Gradle-плагине и создавать baseline с помощью задачи. Но очень не хочется самостоятельно что-то менять в валидаторе, чтобы потом легко было подтягивать все его изменения из Kotlin-репозитория, ведь в будущем в языке могут появиться новые конструкции, которые нужно будет поддерживать.

Ну и в-третьих, поддерживается только JVM.

Заключение

С помощью Binary compatibility validator можно добиться бинарной совместимости и вовремя реагировать на изменение её состояния. Для его использования в проекте потребовалось изменить всего два файла и подключить тесты к нашему CI. У этого решения есть некоторые недостатки, но оно всё равно довольно удобно в использовании. Теперь Reaktive будет стараться поддерживать бинарную совместимость для JVM так же, как это делает JetBrains для Kotlin Standard Library.

Спасибо за внимание!

UPD: Разработчики Kotlin наконец-то выпустили Binary compatibility validator в виде отдельного Gradle Plugin. Он работает так же, как я описал в статье, но теперь для подключения не нужно копировать его к себе в проект, а настраивать стало еще легче

Бинарная совместимость Reaktive: как мы её обеспечиваем