Esquemas¶

Al realizar un reeingenieria de la arquitectura dirigida por eventos EDA es necesario encontrar un formato adecuado para los eventos. Se define utilizar Avro el cual es un sistema de serializacion muy utilizado dentro del ecosistema Kafka. Avro se basa en esquemas los cuales seran importantes de ahora en mas.

¿Por que elegimos Avro?¶

¿Que es Avro?

Apache Avro ™ es un sistema de serialización de datos.

Los esquemas Avro son generados para poder ser incorporados en la registry que utilizaremos como fuente de validacion de los mensajes que publicaremos en los topicos de Kafka.

Los esquemas Avro tambien son utlizados para poder generar el codigo fuente necesario para poder trabajar con lenguajes como C# o Go.

Repositorio¶

Todo lo relacionado a esquemas y codigo fuente generado se encuentra en el siguiente repositorio de github Integracion.Esquemas.Avro.

¿Como se generan los schemas Avro?¶

Los esquemas Avro que son incorporados a la registry se generan a partir de los archivos .avdlque se encuentran en la carpeta ./idl, estos archivos de protocolo estan escritos en un lenguaje de alto nivel llamado idl que sirve para crear schemas Avro en formato json. Aqui se puede ver un ejemplo de como queda un schema declarado en idl.

Template

  record EnvioEntregado{

    Traza traza;
    Integracion.Esquemas.Referencias.   TipoDeEntrega tipoDeEntrega;
  }

Ejemplo real

  @namespace("Muestra.Ejemplo")
  protocol DatoDeReferenciaProtocol {

  record Contrato{
     string codigoDeContratoInterno;
     union { null, string } descripcion=null;
     boolean estaActivo;
     union { null, string } tipoDeServicio=null;
     union { null, string } codigoDeDireccion=null;
     string codigoDeClienteInterno;
     union { null, string } vigenciaDesde=null;
     union { null, string } vigenciaHasta=null;
   }    
  }

Una vez que tenemos definidos nuestros esquemas en el archivo .avdl se debera usar una herramienta para la generacion de esquemas en formato json los cuales utilizaremos para incorporar a la registry. Para la generacion de los schemas se utiliza el siguiente comando:

java -jar avro-tools-{version}.jar idl2schemata {archivo}.idl ./{carpeta destino}

Este comando nos generar tantos archivos .avsc como tipos tengamos declarados en el archivo .avdl. Luego podremos utilizar estos archivos para agregar o actualizar los esquemas en la registry.

Descarga la herramienta avro-tools

Como se genera el codigo fuente incluido en las librerias?¶

Por el momento solo se esta generando codigo fuente en el lenguaje C#.

Una vez obtenido el archivo .avsc usaremos una netcore tool llamada avrogen para generar codigo fuente C#.

avrogen -s {archivo}.avsc ./{carpeta destino}

Este comando nos generar tantos archivos .cs como tipos tengamos declarados en el archivo .avdl. Luego utilizaremos estos archivos para genera un paquete nuget el cual utilizaremos dentro de nuestros desarrollos.

A tener en cuenta¶

Debemos tener instalada la libreria Apache.Avro.Tools para utilizar avrogen. Para instalarla debemos...
dotnet tool install --global Apache.Avro.Tools --version 1.11.0

Generacion Automatica de Schemas y librerias¶

La generacion de schemas, su posterior sincronizacion con la registry y la generacion de librerias para los lenguajes de programacion se realiza automaticamente utilizando Github Actions. Por lo cual, cada vez que generemos un pull request con cambios en los archivos .avdl, una accion de github generara los esquemas y realizara una validacion contra la registry. Este proceso nos dira si algunos de los esquemas fue modificado y dejo de respetar las reglas de validacion y compatibilidad que tenemos establecidas en la registry.

Una vez que la validacion sea exitosa, se procedera con el merge del pull request (Operacion manual). Terminado el merge se ejecutara otra accion de Github que se encargara de:

Registrar nuevos esquemas en la registry.
Actualizar esquemas existentes solo si se realizaron cambios.
Generacion de paquete Nuget y publicacion del mismo dentro de Github Packages.