Utilice el complemento de validación binaria de Kotlin para verificar la API pública | Autor: Matten Braun | Julio de 2021

En el proyecto SDK de Android Stream Chat, usamos el complemento Validador de compatibilidad binaria de Kotlin para rastrear todos los cambios que hacemos en la API pública. Este es un complemento propio para JetBrains, aunque todavía se encuentra en la etapa experimental (es el proyecto de incubadora de JetBrains en GitHub).

En este artículo, aprenderá sobre la función del complemento, cómo instalarlo y configurarlo, y cómo usarlo para mejorar su proyecto de biblioteca.

Comencemos con el TL; DR de la función de complemento:

Produce .api Un archivo que describe la API pública de cada módulo. Si se realizan cambios en la API pública, el contenido del módulo debe actualizarse explícitamente. .api Archivo (de lo contrario, la verificación fallará y le alertará de cambios inesperados en la API).

Al hacer esto, puede garantizar que los desarrolladores del proyecto siempre conozcan los cambios exactos que realizaron en la API pública. Dado que el complemento funciona con API binarias, captura cambios incompatibles que pueden no ser obvios al ver el código fuente. Por ejemplo, al escribir código Kotlin, el uso de clases de datos, implementaciones predeterminadas u objetos complementarios puede crear API binarias que normalmente no conoce.

El validador binario se puede usar como un simple complemento de Gradle, lo que hace que la configuración sea muy rápida.Simplemente agregue este código a su nivel superior build.gradle expediente:

buildscript 
dependencies 
classpath 'org.jetbrains.kotlinx:binary-compatibility-validator:0.6.0'

apply plugin: 'binary-compatibility-validator'

Después de agregar el complemento, es hora de configurarlo.Puedes hacer esto en él apiValidation Obstruido. Aquí está la configuración que usamos en el SDK como ejemplo:

apiValidation 
ignoredPackages += [ // 1
'com/getstream/sdk/chat/databinding',
'io/getstream/chat/android/ui/databinding',
]    ignoredProjects += [ // 2
'stream-chat-android-docs',
'stream-chat-android-sample',
'stream-chat-android-ui-components-sample',
'stream-chat-android-test',
]    nonPublicMarkers += [ // 3
'io.getstream.chat.android.core.internal.InternalStreamChatApi',
]

Veamos cada opción que usamos:

1. ignoredPackages Le permite excluir algunos paquetes de la verificación. En nuestro caso, no queremos rastrear los archivos generados por el enlace de vista.También puedes usar ignoredClasses Excluir clases individuales por nombre.
2. De forma predeterminada, los complementos se habilitarán para todos los módulos del proyecto.usamos ignoredProjects Excluya los módulos no publicados, como la documentación y las aplicaciones de muestra.
3. Esto nonPublicMarkers La entrada le permite especificar cualquier anotación de Kotlin Opt-in que utilice en la API. Estas anotaciones no se consideran disponibles públicamente. Para obtener más información sobre estos, vea Mastering API Visibility in Kotlin.

Para (re) generar .api Archivo, tienes que ejecutar apiDump Tareas de Gradle.Cuando haga esto por primera vez, debe revisar todos los .api Archivo para asegurar todo lo que contiene Realmente debería ser API pública, luego envíelos a su repositorio.

Aquí hay una pequeña muestra de lo que verá en estos archivos:

public abstract interface class io/getstream/chat/android/ui/StyleTransformer 
public abstract fun transform (Ljava/lang/Object;)Ljava/lang/Object;
public final class io/getstream/chat/android/ui/common/Debouncer 
public fun <init> (J)V
public final fun shutdown ()V
public final fun submit (Lkotlin/jvm/functions/Function0;)V
public final fun submitSuspendable (Lkotlin/jvm/functions/Function1;)V
public abstract interface class io/getstream/chat/android/ui/common/UrlSigner 
public abstract fun signFileUrl (Ljava/lang/String;)Ljava/lang/String;
public abstract fun signImageUrl (Ljava/lang/String;)Ljava/lang/String;

Entonces puedes usar apiCheck Tarea de Gradle para verificar si su código fuente actual todavía tiene la misma API que la que envió .api expediente.Esta tarea creará la última .api Viértalos en una carpeta de compilación temporal y compárelos con .api Archivos en el repositorio. Si no coinciden, fallará y notificará la diferencia detectada.

Por ejemplo, vea el siguiente error generado por la tarea después de mover el atributo del constructor de la clase de datos a su cuerpo:

Execution failed for task ':stream-chat-android-client:apiCheck'.
> API check failed for project stream-chat-android-client.
@@ -218,9 +218,8 @@
public final class io/getstream/chat/android/client/api/models/AutocompleteFilterObject : io/getstream/chat/android/client/api/models/FilterObject {
public final fun component1 ()Ljava/lang/String;
- public final fun component2 ()Ljava/lang/String;
- public final fun copy (Ljava/lang/String;Ljava/lang/String;)Lio/getstream/chat/android/client/api/models/AutocompleteFilterObject;
+ public final fun copy (Ljava/lang/String;)Lio/getstream/chat/android/client/api/models/AutocompleteFilterObject;
public fun equals (Ljava/lang/Object;)Z
public final fun getFieldName ()Ljava/lang/String;
public final fun getValue ()Ljava/lang/String;
You can run :stream-chat-android-client:apiDump task to overwrite API declarations

Si estas diferencias son intencionales, debe ejecutar apiDump Vuelva a realizar la tarea y actualice los datos almacenados. .api El archivo ahora incluye cualquier cambio en la API que creó al cambiar el código fuente.correr apiCheck La tarea en este momento se completará con éxito porque la fuente y .api Los archivos se vuelven a sincronizar.

Este es el objetivo del complemento: permitir a los desarrolladores ejecutar explícitamente la tarea de actualizar los archivos de descripción de API cuando entren en contacto con API públicas.

Entonces debes enviar los cambios que introdujiste .api expediente. Estos se mostrarán en envíos y solicitudes de extracción, lo que permitirá a los revisores determinar fácilmente cuándo realizó cambios en la API binaria y capturar cualquier cambio no intencional.

El poder del complemento realmente muestra que si tiene Verificación automática Para asegurarse de que siempre que cambie la API pública, realmente haya actualizado .api El archivo para que coincida.

En Stream, realizamos comprobaciones de dos formas:

• Use un gancho de git previo a la confirmación para ejecutarlo en nuestro repositorio apiCheck Tarea (y ejecutar automáticamente apiDump Si falla, se le proporcionará) cuando intente crear una nueva confirmación en el repositorio.
• Verifique los pasos de operación de GitHub en el flujo de trabajo a través de nuestro PR para asegurarse api Antes de fusionar los cambios, el archivo está actualizado.

Este complemento es un Binario Validador. Esto significa que no rastreará los cambios de API públicas que no afecten la compatibilidad binaria. Por ejemplo, la función materializada es parte de la API de nivel de fuente, pero no existe en la API binaria. Afortunadamente, estos cambios deberían ser obvios a partir de los cambios del archivo fuente de todos modos (y no son muy frecuentes).

También hay algunos problemas conocidos en la biblioteca, que puede ver en GitHub. Hemos informado de algunos de ellos nosotros mismos, principalmente sobre el respeto de las etiquetas no públicas, que usamos ampliamente en nuestros proyectos (ver # 36 y # 58).

Incluso con estas limitaciones en mente, el complemento Validador de compatibilidad binaria es una gran herramienta para garantizar que no realizará ningún cambio accidental en la API binaria pública al crear la biblioteca. Compruébalo en GitHub.

También puede encontrar nuestro SDK de chat de Android en GitHub, y puede probar nuestro tutorial de mensajería en la aplicación para comenzar.

Más temas de desarrollo de bibliotecas que podrían interesarle: