Guía de desarrollo de microservicios

Arquitectura de microservicios

Información general

Icono guías
Recursos
Arquitectura de referencia de microservicios
Norma para el desarrollo de microservicios
Modelo de despliegue de microservicios
Tipo de recurso
Guía
Etiquetas
Arquitectura

Herramientas de desarrollo

Entornos de desarrollo

El entorno de desarrollo integrado es esencial para los desarrolladores de cualquier tipo de componentes software, incluyendo microservicios. La elección de un IDE (Integrated Development Environment) adecuado y la configuración de los plugins y herramientas correctas puede mejorar significativamente la eficiencia y la calidad del desarrollo. 

Existen diversas soluciones en el mercado, y desde la Agencia no se impone ninguna en particular, entendiendo que es una cuestión de preferencias de cada desarrollador. De todas las opciones existentes, se identifican tres de las más populares para desarrollo Java: IntelliJ IDEA, Eclipse y Visual Studio Code,  cada una con sus propias fortalezas y conjuntos de herramientas recomendadas. 

Asegúrate de configurar tu entorno de desarrollo para que se adapte a tus necesidades y flujos de trabajo específicos.
 

IntelliJ IDEA

IntelliJ IDEA es uno de los IDEs más reconocidos y utilizados para el desarrollo en Java. Se destaca por su capacidad de ofrecer asistencia inteligente al escribir código, potentes herramientas de refactorización, y una amplia gama de funcionalidades avanzadas que ayudan a los desarrolladores a ser más productivos y escribir código de alta calidad. 

También ofrece integración nativa con sistemas de control de versiones como Git, lo que simplifica la gestión del código fuente y mejora la colaboración entre equipos. Además de su versión comercial, IntelliJ IDEA cuenta con una versión Community Edition que es libre y de código abierto, licenciada bajo Apache 2.0, proporcionando una funcionalidad más que suficiente para la construcción de microservicios sin coste alguno.

Plugin recomendados

 

Eclipse

Eclipse es uno de los IDEs más veteranos y todavía ampliamente utilizado para el desarrollo en Java. Conocido por su entorno flexible y extensible, Eclipse permite a los desarrolladores personalizar su experiencia de desarrollo a través de una biblioteca de plugins y herramientas. Ofrece características para la edición de código, depuración, y refactorización, haciendo que el desarrollo en Java sea más eficiente. Eclipse también integra de forma nativa sistemas de control de versiones como Git, facilitando la gestión del código y la colaboración en proyectos. Además, Eclipse es un software libre y de código abierto, licenciado bajo la Eclipse Public License.

Plugin recomendados

  • SonarLint: Asegura la calidad del código dentro del IDE, proporcionando feedback inmediato sobre posibles errores y malas prácticas. Disponible en: https://sonarlint.org/eclipse/
  • Maven Integration for Eclipse (m2e): Gestiona proyectos Maven directamente desde Eclipse, facilitando la construcción y gestión de dependencias. Disponible en: https://eclipse.org/m2e/
  • Spring Tools (STS): Facilita el desarrollo con Spring Framework, ofreciendo asistentes y herramientas específicas. Disponible en: https://spring.io/tools
  • EclEmma: Plugin que analiza el porcentaje de código cubierto con test unitarios. Disponible en: https://eclemma.org/
  • Docker Tooling: Maneja y ejecuta contenedores Docker desde el IDE. Disponible en: https://marketplace.eclipse.org/content/docker-tooling
  • EGit: Integra Git en Eclipse, permitiendo una gestión completa del control de versiones. Disponible en: https://eclipse.org/egit/

 

Visual Studio Code

Visual Studio Code (VS Code) es un editor de código fuente ligero pero potente, ampliamente adoptado por desarrolladores de diversas disciplinas, incluido el desarrollo en Java. Con su enfoque modular, VS Code permite a los usuarios personalizar su entorno de desarrollo a través de extensión de plugins, que abarcan desde soporte para lenguajes de programación hasta herramientas de depuración y control de versiones. 

Aunque no es un IDE completo en el sentido tradicional, VS Code ofrece características robustas como autocompletado inteligente, integración con Git y soporte para depuración, lo que lo hace altamente eficiente para el desarrollo de aplicaciones en Java. Además, Visual Studio Code es libre y de código abierto, bajo la licencia MIT, lo que lo convierte en una opción accesible para desarrolladores individuales y equipos que buscan una herramienta flexible y extensible.

Plugin recomendados

 

Aplicaciones para facilitar el desarrollo

Maven 3.8 o superior

Para la compilación del microservicio y la descarga de dependencias se recomienda tener instalado maven en el entorno local de desarrollo.

 

Docker

Docker es una plataforma de contenedores que permite empaquetar, distribuir y ejecutar aplicaciones en contenedores ligeros y portátiles. Es ampliamente utilizado en el desarrollo de microservicios debido a su capacidad para garantizar que el software se ejecute de manera consistente en cualquier entorno.

Docker facilita la creación y gestión de contenedores, que encapsulan una aplicación y sus dependencias, asegurando que se ejecuten de manera uniforme en cualquier sistema operativo.

  • Docker Desktop: proporciona una interfaz gráfica y una integración completa con el sistema operativo, aunque es una aplicación que conlleva un licenciamiento. Rancher Desktop ofrece una alternativa gratuita, ya que se distribuye bajo una licencia de código abierto
  • Docker Compose: Permite definir y ejecutar aplicaciones de Docker con múltiples contenedores. 

 https://docs.docker.com/

 

Rancher Desktop

Rancher Desktop permite a los desarrolladores ejecutar y gestionar Kubernetes y Docker en su máquina local. Ofrece una interfaz gráfica para simplificar el proceso de despliegue y gestión de contenedores y clusters, ideal para trabajar con Kubernetes en entornos de desarrollo. 

Aunque Rancher Desktop interactúa con los contenedores utilizando su propio lenguaje, tiene la opción de configurarse para que use el “Container Engine” de Docker permitiendo utilizar su juego de comandos básicos. 

https://rancherdesktop.io/

 

Helm

Helm es una herramienta de gestión de paquetes que simplifica la instalación, actualización y gestión de contenedores desplegados en clústeres de Kubernetes. 

Helm permite a los desarrolladores y operadores automatizar y estandarizar el proceso de despliegue, facilitando la administración de aplicaciones complejas con múltiples componentes. 

https://helm.sh/

 

Desarrollo de microservicios

Diseño de microservicios

Antes de acometer el desarrollo de un microservicio, utilizando como base el documento de arquitectura de referencia de microservicios y los documentos de normas, debe realizarse un diseño apropiado que tenga en cuenta los siguientes aspectos:

  • Tipología del microservicio: El tipo de microservicio que se va a desarrollar dependerá del caso de uso, necesidades del negocio y el dominio funcional que deba implementar. El framework ada-fwk-ms publica un conjunto de arquetipos con diferentes tipo de microservicios.
  • Estructura del microservicio: Debe decidirse, en base al tipo de microservicio elegido y las circunstancias del negocio que va a implementar, qué estructura interna va a tener. Se recomienda consultar el documento de arquitectura de referencia para obtener más información sobre las diferentes estructuras disponibles.
  • Patrones de diseño: Se recomienda consultar el conjunto de patrones de diseño indicados en el documento de arquitectura de referencia y escoger aquellos que mejor se adaptan a las necesidades que debe cubrir el microservicio.

 

Construcción del microservicio

Una vez finalizada la fase de diseño del microservicio es necesario antes de acometer su implementación elegir el framework de desarrollo con el que se va a implementar.

Se recomienda utilizar como framework de desarrollo el activo ada-fwk-ms aunque Spring Boot y Quarkus son también framework de desarrollo autorizados para la implementación de microservicios Java. 

Una vez escogido el framework de desarrollo se dan unas directrices básicas para la implementación del microservicio poniendo especial énfasis en el desarrollo con el framework ada-fwk-ms que además de ser la opción recomendada, al ser de desarrollo interno, es el único del que no puede obtenerse información fuera de los canales autorizados por la Junta de Andalucía.

 

Elección del framework de desarrollo

Spring Boot

El uso del framework ada-fwk-ms no es obligatorio dentro de la Junta de Andalucía, pero se recomienda como opción preferente por los motivos indicados en el apartado anterior. El equipo de desarrollo puede utilizar directamente Spring Boot  para implementar sus microservicios

No obstante, como parte del Modelo Global de Soluciones, existe un activo denominado Framework de desarrollo para microservicios (ada-fwk-ms), disponible para su uso en cualquier proyecto de desarrollo. 

Este activo es un acelerador y framework de desarrollo basado en Spring Boot 3, que simplifica el uso de Spring Boot y proporciona herramientas, como arquetipos maven, módulos y servicios, que agilizan y simplifican el desarrollo de microservicios Java.

Al estar basado en Spring Boot 3 incorpora todas las características y beneficios de este framework como, por ejemplo: la gestión centralizada de dependencias en el pom.xml, la inyección de dependencias mediante beans y la posibilidad de realizar despliegues nativos.

Además, al usar ada-fwk-ms, están disponibles módulos y funcionalidades especialmente diseñadas para agilizar y unificar los desarrollos. El framework implementa gran parte de los aspectos técnicos que debe cumplir un microservicio en la ADA, permitiendo al equipo centrarse en el negocio y facilitando el cumplimiento de las normas.

* Permite simplificar el mantenimiento de los proyectos dentro de la Junta de Andalucía

* Reducir la curva de aprendizaje de los desarrolladores

La norma Alineamiento con la pila tecnológica de la ADA incluye información sobre las versiones aprobadas para su uso

 

Quarkus

El framework Quarkus también está aprobado como opción válida, autorizado y puede usarse para los desarrollos. En caso de que el equipo de desarrollo decida utilizarlo, se recomienda consultar la documentación oficial y utilizar la versión recomendada en la norma Alineamiento con la pila tecnológica de la ADA.

 

Implementación usando ada-fwk-ms como framework de desarrollo

Paso 1. Elección y ejecución del arquetipo

El primer paso que debe realizarse es elegir un arquetipo maven del conjunto de arquetipos publicados por el framework

El arquetipo a elegir se basará en el tipo y estructura de microservicio definido en la fase de diseño. Se recomienda revisar la documentación del arquetipo seleccionado para obtener toda la información relevante para su uso.

Para generar el microservicio a partir del arquetipo elegido deben cumplirse los siguientes requisitos:

  1. Identificar qué versión del framework  se va a utilizar. Se recomienda utilizar la última versión estable.
  2. Verificar que el equipo local tiene conexión con Artifactory donde está alojado el arquetipo. Si el equipo local está fuera de la red de la Junta de Andalucía será necesario disponer de conexión VPN.
  3. Verificar que el desarrollador tiene credenciales y los permisos necesarios para acceder a Artifactory.

Una vez verificado que se cumplen con todos los requisitos se debe ejecutar el comando maven indicado en la documentación del arquetipo. Cuando la ejecución del comando haya finalizado se creará en el equipo local la versión inicial del microservicio.

A continuación, partiendo del supuesto de que el microservicio que se va a construir publicará una API, se muestra un ejemplo del comando maven que habría que ejecutar si el arquetipo elegido es fwk-crud-apifirst-archetype:

mvn archetype:generate -DarchetypeGroupId=es.juntadeandalucia.ada.oda.ada-fwk-ms -DarchetypeArtifactId=fwk-crud-apifirst-archetype -DarchetypeVersion=X.X.X.RELEASE

Finalizado este proceso el desarrollador dispondrá en su equipo local de un microservicio básico listo para ejecutar con las características indicadas en la documentación del arquetipo seleccionado.

 

Paso 2. Implementación de la funcionalidad de negocio del microservicio

Dado que el microservicio generado por el arquetipo es una versión inicial con gran parte de los aspectos técnicos necesarios ya implementados, el desarrollador debe centrarse ahora en dotar al microservicio del negocio que quiere ejecutar.

Para ello, se recomienda revisar los puntos que se indican:

Incluir los módulos del framework necesarios para el correcto funcionamiento del microservicio

Los arquetipos incorporan los módulos básicos y en cierta manera obligatorios según la tipología de microservicio elegida al escoger el arquetipo. Se recomienda revisar el conjunto de módulos publicados por el framework e incorporar en el fichero pom.xml aquellos módulos que se detecten necesarios para implementar la funcionalidad del microservicio. e incorporar en el fichero pom.xml aquellos módulos que se detecten necesarios para implementar la funcionalidad del microservicio.

A continuación, siguiendo el ejemplo anterior, se va a suponer que el microservicio que se va a desarrollar,  requiere además de la publicación de una api REST el almacenamiento en una caché redis. Por lo tanto, se muestra cómo en el fichero pom.xml generado por el arquetipo se incorpora el módulo que falta.

<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	....
	<dependencies>
			....
		<dependency>
			<groupId>es.juntadeandalucia.ada.oda.ada-fwk-ms</groupId>
			<artifactId>fwk-cache-redis</artifactId>
		</dependency>
	</dependencies>
	.....
</project>
 
Revisar las clases generadas por el arquetipo

Debe tenerse en cuenta que el arquetipo se ejecuta bajo una plantilla por lo que siempre deben revisarse las clases autogeneradas y modificarse para adecuarlas a las necesidades del proyecto. También, utilizando como base la estructura generada por el arquetipo, deben crearse el resto de clases necesarias utilizando como ejemplo, si es necesario, aquellas que proporciona el arquetipo.

Puede darse el caso que alguna clase generada por el arquetipo no fuese necesaria para el microservicio final, en ese caso, se recomienda eliminarla para mantener el código ordenado y facilitar su mantenimiento.

 

Revisar la configuración generada por el arquetipo

A continuación se indican los diferentes puntos que hay que verificar en la configuración del microservicio creado por el arquetipo:

  • La configuración del microservicio se encuentra en el fichero application.yml. Se recomienda revisar esta configuración, ajustarla a las necesidades del negocio que se está implementando y eliminar aquellas propiedades de configuración que no apliquen.

  • Al inicio del fichero puede verse un bloque de código comentado. Este código se corresponde con la configuración que deberá tener el microservicio para poder utilizar la funcionalidad de configuración centralizada. 

    Mientras se trabaje en local no es necesario utilizar la configuración centralizada, e incluso es mejor no utilizarla para agilizar el desarrollo. Sin embargo, sí es recomendable utilizar este tipo de configuración cuando se despliegue el microservicio en cualquier entorno. Se recomienda mantener el bloque comentado mientras dure la fase de implementación en local y seguir las instrucciones del apartado correspondiente a la configuración centralizada cuando llegue el momento de desplegar el microservicio en un entorno.

  • Durante el desarrollo en local, como buena práctica, se recomienda poner en el fichero application.yml solo la configuración que es común y que no depende de un entorno específico. La configuración específica para el entorno local deberá extraerse al fichero application-local.yml y configurar el arranque del microservicio con el perfil local para que Spring Boot arranque correctamente y procese la configuración de ambos ficheros.

    No se recomienda configurar le perfil de arranque directamente en el fichero application.yml. Para configurar el arranque del microservicio con el perfil local añadir en el IDE el siguiente parámetro de arranque para la JVM:

    -Dspring.profiles.active=local


 Revisar la configuración de observabilidad

Dentro de la configuración generada automáticamente por arquetipo en el fichero application.yml existe una configuración definida para la observabilidad aunque está desactivada por defecto. Al igual que con la configuración centralizada, durante el desarrollo en local para simplificar, se recomienda abstraerse de esta cuestión y mantenerla desactivada. 

Es recomendable, sin embargo, activarla y revisar los valores generados por el arquetipo antes del despliegue del microservicio en un entorno. Para ello se recomienda seguir las instrucciones que se indican en el apartado de Observabilidad.
 

Paso 3. Gestión de errores y excepciones

Un paso fundamental en el desarrollo de un microservicio es implementar una correcta gestión de errores y excepciones. Habitualmente los errores que suelen producirse en un microservicio se dividen en dos tipos:

  • Excepciones técnicas: Se producen cuando durante la ejecución del código se produce un problema. La generación de estas excepciones siempre es en tiempo de ejecución y será responsabilidad del desarrollador capturarlas y gestionarlas correctamente para que no provoquen un fallo en cadena que impida la ejecución del microservicio.

    Algunos ejemplos de este tipo de excepciones son: NullPointerException, ConnectionRefusedException, AccessDeniedException…

    Las excepciones técnicas que se producen durante la comunicación HTTP en una api REST son capturadas y gestionadas automáticamente por el framework ada-fwk-ms mediante la implementación de un ExceptionHandler específico (RestResponseEntityExceptionHandler). Para obtener más información sobre la gestión de errores por parte del framework se recomienda leer la documentación del módulo fwk-core.

  • Excepciones de negocio: Este tipo de excepciones están relacionadas con la funcionalidad de negocio del microservicio y deberá generarlas manualmente el desarrollador a partir de validaciones en el flujo y los datos. El framework ada-fwk-ms recomienda que para gestionar este tipo de excepciones se cree una clase de tipo Exception que extienda de la clase ArchException. Esta clase es propia del framework y permite centralizar todas las excepciones generadas en una clase padre común lo que facilita su mantenimiento y permite al framework, en caso necesario, dotar a las excepciones de cierto comportamiento común.

    Existe un ejemplo completo que ilustra la creación de excepciones de negocio y extensión del ExceptionHandler proporcionado por el framework ada-fwk-ms en el showcase-module-swagger-apifirst.

 

Paso 4. Implementación de test unitarios y de integración

Para la implementación de tests unitarios y de integración, se recomienda seguir las directrices indicadas por Spring Boot en su documentación oficial.

Para garantizar la calidad del software y asegurar que los microservicios desarrollados funcionen correctamente, es necesario implementar tanto tests unitarios como tests de integración. La realización de estos tests requiere el uso de entornos de ejecución y librerías que faciliten la definición y ejecución de las pruebas de manera eficiente y mantenible.

El framework ada-fwk-ms se basa en Spring Boot 3, lo que simplifica la configuración del entorno de pruebas. Al utilizar Spring Boot 3, el proceso de configuración de un entorno de pruebas compatible con las últimas versiones de JUnit y Mockito se simplifica enormemente.

Para habilitar el entorno de pruebas en un microservicio que utilice el framework ada-fwk-ms, lo único que se necesita es añadir la dependencia spring-boot-starter-test al archivo pom.xml.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>

Esta dependencia agrupa todas las librerías necesarias para ejecutar tanto tests unitarios como de integración en un entorno basado en Spring Boot 3. La dependencia incluye:

  • JUnit 5: Para la ejecución de tests unitarios que aprovecha al máximo las funcionalidades de Java.
  • Mockito: Para la creación de mocks y pruebas de comportamiento.
  • AssertJ: Para aserciones más expresivas y fáciles de leer.
  • Spring Test: Para facilitar los tests de integración que requieren el contexto de Spring Boot. 

A continuación se define una clase que permitirá realizar ejemplos de Test Unitarios y de Integración:

@Service
public class ProductService {
    private final ProductRepository productRepository;

    public ProductService(ProductRepository productRepository) {
        this.productRepository = productRepository;
    }

    public Product getProductById(Long id) {
        return productRepository.findById(id).orElseThrow(() -> new ProductNotFoundException("Product not found"));
    }
}   

 

Test unitarios

Un test unitario es una prueba automatizada que se enfoca en verificar el comportamiento de una unidad mínima de código de un sistema, generalmente una función o método individual. El objetivo es asegurarse de que la unidad de código funciona correctamente en aislamiento, sin depender de otras partes del sistema.

@ExtendWith(MockitoExtension.class)
public class ProductServiceTest {

    @Mock
    private ProductRepository productRepository;

    @InjectMocks
    private ProductService productService;

    @Test
    public void testGetProductById() {
        Product mockProduct = new Product(1L, "Product A", 100.0);
        when(productRepository. getAllProducts()).thenReturn(Arrays.asList(mockProduct));
        List<Product> foundProducts = productService.getAllProducts();
        assertThat(foundProducts).hasSize(1);
    }

    @Test
    public void testGetProductById_NotFound() {
        when(productRepository.findById(2L)).thenReturn(Optional.empty());
        Exception exception = assertThrows(ProductNotFoundException.class, () -> {
            productService.getProductById(2L);
        });
        assertEquals("Product not found", exception.getMessage());
    }
}

En este ejemplo, el repositorio ProductRepository  es configurado como un Mock con un comportamiento determinado, lo que permite realizar test unitarios de ProductService de forma aislada.

 

Test de integración

Un Test de Integración es una prueba automatizada que verifica la interacción y colaboración entre diferentes módulos o componentes de un sistema. A diferencia de los tests unitarios, los tests de integración se centran en asegurar que los módulos de software funcionen correctamente cuando se integran entre sí, y que se cumplan los requisitos del sistema en su conjunto. Estos tests validan aspectos como la comunicación entre componentes, la coherencia de datos, y el comportamiento en conjunto.

En este ejemplo, el repositorio ProductRepository  es configurado como una BBDD en local y por lo tanto en el test ya no se simula el comportamiento, sino que se testea de forma integrada el comportamiento de ProductService con una BBDD real.

@SpringBootTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@ActiveProfiles("test") // Activar el perfil de test
public class ProductServiceIntegrationTest {
    @Autowired
    private ProductService productService;
    @Autowired
    private ProductRepository productRepository;

    @BeforeEach
    void setUp() {
        productRepository.deleteAll();
    }
    @Test
    void whenSaveProduct_thenProductShouldBeFound() {
        Product mockProduct = new Product(1L, "Product A", 100.0);
        productService.saveProduct(product);
        List<Product> foundProducts = productService.getAllProducts();
        assertThat(foundProducts).hasSize(1);
    }
    @Test
    public void testGetProductById_NotFound() {
        when(productRepository.findById(2L)).thenReturn(Optional.empty());

        Exception exception = assertThrows(ProductNotFoundException.class, () -> {
            productService.getProductById(2L);
        });
        assertEquals("Product not found", exception.getMessage());
    }
}

 

Paso 5. Observabilidad

Antes de desplegar el microservicio en un entorno se recomienda activar la observabilidad centralizada. Para ello en el entorno donde se va a desplegar el microservicio tiene que cumplirse el siguiente requisito:

  • El microservicio, una vez desplegado, debe tener conexión con el componente OTELCollector desplegado en ese entorno. Este componente centraliza el procesamiento de métricas, trazas y logs en todo el sistema. 

Para activar la observabilidad deben configurarse las propiedades:

management.otlp.metrics.export.enabled=true
fwk.otlp.enabled=true

y validar que las url de conexión con el OTELCollector ya sea por http (fwk.otlp.http) o por grpc, si aplica, (fwk.otlp.grpc) son correctas.

Puede encontrarse información más detallada sobre estas propiedades y su uso en la documentación del módulo fwk-otlp y un ejemplo completo de como configurar la observabilidad en el showcase-module-otlp.

 
Paso 6. Configuración personalizada

Antes de desplegar el microservicio en un entorno se recomienda extraer la configuración con la que se ha estado trabajando en local a un repositorio git externo.  Para ello tienen que cumplirse los siguientes requisitos:

  • Debe existir en el proyecto un repositorio git para almacenar la configuración. El repositorio git tiene que tener una estructura similar a la que se muestra.
Main 
 |- sa-oas-fwk-ms  #Se recomienda utilizar el artifactId del microservicio como identificador
   | - application.yml  #Fichero con la configuración común a todos los entornos
   | - application-des.yml #Fichero con la configuración específica de desarrollo
   | - application-pru.yml #Fichero con la configuración específica de entorno de Test
   | - application-pre.yml #Fichero con la configuración específica de entorno de Pre-Producción
   | - application-pro.yml #Fichero con la configuración específica de entorno de Producción

 

  • Debe estar desplegado en el namespace del entorno donde se va a desplegar el microservicio un microservicio específico que actúe como servidor de configuraciones. Si no existe, debe generarse y desplegarse. Para generar este tipo de microservicios el framework ada-fwk-ms ha publicado el arquetipo fwk-config-server-archetype. Se recomienda consultar la documentación de dicho arquetipo para obtener el comando maven a ejecutar y  las características del microservicio generado por el arquetipo. las características del microservicio generado por el arquetipo.

Una vez se va verificado que se cumplen los requisitos deben seguirse los siguientes pasos:

  1. Si no existe, crear en el repositorio git de configuración una carpeta para alojar la configuración del microservicio. Se recomienda usar como identificador el artifactId definido en el fichero pom.xml del microservicio.
  2. Dentro de esa carpeta, siguiendo la estructura indicada, deben depositarse los ficheros de configuración:
    • El fichero application.yml con la configuración común a todos los entornos. En este fichero debe ponerse toda la configuración del fichero application.yml local a excepción del bloque comentado que ha generado el arquetipo. En el fichero application.yml local del microservicio sólo debe quedarse el bloque de código comentado.
    • Los ficheros application-[entorno].yml con la configuración específica de cada entorno. Se incluye también el fichero correspondiente al entorno local.
       
  3. En este punto, en el microservicio solo tiene que existir el fichero de configuración application.yml vacío a excepción del bloque de código comentado. El resto de ficheros deben haberse borrado del microservicio y haberse trasladado al repositorio git.
  4. Por último, se descomenta el contenido del fichero application.yml y se configura correctamente el valor de las siguientes propiedades:
    • spring.cloud.config.uri: Url de conexión al microservicio que actúa como servidor de configuración
    • spring.cloud.config.name: Nombre de la carpeta creada en el paso 1 que almacena los ficheros de configuración. Se recomienda usar como identificador el artifactId definido en el fichero pom.xml del microservicio.
       

Para obtener más información, se recomienda consultar la documentación del módulo fwk-config. Además existe un ejemplo completo de configuración centralizada en showcase-module-config.

 

Implementación usando Spring Boot como framework de desarrollo

Para obtener información detallada de cómo construir un microservicio utilizando Spring Boot se recomienda consultar la documentación oficial y las guías y manuales publicados por Spring.

 

Implementación usando Quarkus como framework de desarrollo

Para obtener información detallada de cómo construir un microservicio utilizando Quarkus se recomienda consultar la documentación oficial y las guías y manuales publicados por Quarkus y Red Hat.

 

Repositorio de código del microservicio

Cuando se desarrolla un Microservicio es obligatorio que el código esté alojado en un repositorio de código remoto que permita el alojamiento de proyectos, la colaboración en equipo, el control de versiones, la automatización de ciertas tareas y la integración con herramientas externas.

Existe un Repositorio de Código corporativo de la Junta de Andalucía de uso obligatorio para todos los proyectos. Además, el correcto uso de este repositorio se encuentra gobernado por una serie de normas que definen la Estrategia de Ramificación del mismo.

 

Calidad del microservicio

La construcción de los microservicios debe de realizarse con un diseño y codificación de calidad. Existen muchos recursos que nos pueden ayudar en ese cometido, pero desde la ADA si se establece unos criterios normalizados de forma que la medición de la calidad del software no sea subjetiva.

Puede consultar más en información en:

 

Anexo. Creación de eventos usando microservicios

A continuación se explica cómo crear microservicios que actúen como productores o consumidores de eventos. Antes de proceder al desarrollo de estos microservicios se recomienda leer la guía de integración de eventos donde se explican conceptos básicos sobre diseño de eventos, seguridad y gestión de errores.

 

Desarrollo de un productor

Implementación usando ada-fwk-ms como framework de desarrollo

Paso 1. Elección y ejecución del arquetipo

ada-fwk-ms dispone de un conjunto de arquetipos especialmente diseñados para la creación de microservicios cuyo principal cometido es actuar como productores de eventos para Kafka.

  • fwk-default-producer-archetype: Arquetipo que incorpora el módulo fwk-kafka-simple y permite crear un microservicio que publica un productor Kafka usando el productor que proporciona ada-fwk-ms. Arquetipo recomendado para casos de uso donde se necesite un productor sencillo
  • fwk-custom-producer-archetype: Arquetipo que incorpora el módulo fwk-kafka-simple y permite crear un microservicio que publica un productor Kafka usando un productor personalizado y que no se basa en el que proporciona ada-fwk-ms. Arquetipo recomendado para casos de uso donde se necesite un productor que requiera de un procesamiento complejo: gestión de errores, reintentos, gestión manual del envío de mensajes.

A continuación, partiendo del supuesto de que el microservicio que se va a construir publicará un productor personalizado, se muestra un ejemplo del comando maven que habría que ejecutar si el arquetipo elegido es fwk-custom-producer-archetype:

mvn archetype:generate -DarchetypeGroupId=es.juntadeandalucia.ada.oda.ada-fwk-ms -DarchetypeArtifactId= fwk-custom-producer-archetype -DarchetypeVersion=X.X.X.RELEASE

Finalizado este proceso el desarrollador dispondrá en su equipo local de un microservicio básico listo para ejecutar con las características indicadas en la documentación del arquetipo seleccionado. 

 

Paso 2. Revisar fichero pom.xml

Debe revisarse el microservicio generado y verificar que en el parent pom está declarada la versión correcta de ada-fwk-ms:

<parent>
<groupId>es.juntadeandalucia.ada.oda.ada-fwk-ms</groupId>
	<artifactId>fwk-ms-parent-pom</artifactId>
	<version>X.X.X-RELEASE</version>
	<relativePath />
</parent>

También que se incluye el módulo fwk-kafka-simple:

<dependency>
	<groupId>es.juntadeandalucia.ada.oda.ada-fwk-ms</groupId>
	<artifactId>fwk-kafka-simple</artifactId>
</dependency>

Si se va a utilizar Apicurio (recomendado) revisar que se incluye el módulo fwk-registry-apicurio:

<dependency>
<groupId>es.juntadeandalucia.ada.oda.ada-fwk-ms</groupId>
	<artifactId>fwk-registry-apicurio</artifactId>
</dependency>

Y en el caso de utilizar Apicurio y mensajes con schema AVRO (recomendado) revisar que se tiene el plugin de maven avro-maven-plugin declarado y correctamente configurado:

<plugin>
<groupId>org.apache.avro</groupId>
	<artifactId>avro-maven-plugin</artifactId>
	<version>1.10.0</version>
	<executions>
		<execution>
			<id>schemas</id>
			<phase>generate-sources</phase>
			<goals>
				<goal>schema</goal>
			</goals>
			<configuration>
				<sourceDirectory>
${project.basedir}/src/main/resources/avro/
</sourceDirectory>
<outputDirectory>
				${project.build.directory}/generated-sources/avro/
</outputDirectory>
				<stringType>String</stringType>
			</configuration>
		</execution>
	</executions>
</plugin>

 

Paso 3. Revisar la configuración

Debe revisarse el fichero application.yaml  generado por el arquetipo y verificar que la configuración para conectarse con Kafka, Apicurio (si se incorpora el módulo fwk-registry-apicurio) y la configuración del propio productor es correcta. Se recomienda consultar la documentación de Spring Boot y revisar todas las propiedades disponibles bajo el prefijo spring.kafka para adaptar la funcionalidad del productor a la que requiere el negocio.

spring:
  kafka:
    bootstrap-servers: 127.0.0.1:9092  
    producer:
      key-serializer: org.apache.kafka.common.serialization.StringSerializer
      value-serializer: io.apicurio.registry.serde.avro.AvroKafkaSerializer
      properties:
        apicurio.registry.url: http://localhost:8990/apis/registry/v2
        apicurio.registry.auto-register: true
        apicurio.registry.artifact-id: io.apicurio.registry.utils.serde.strategy.TopicIdStrategy

 

Paso 4. Incorporar la definición del schema AVRO

Si  se ha definido un formato para el mensaje, es necesario añadir el schema AVRO en el microservicio. La ubicación para depositar el schema AVRO es configurable pero habitualmente se pone en /src/main/resources/avro/ tal y como se ve en el ejemplo para configurar el plugin avro-maven-plugin.

Una vez que el schema AVRO está en la ruta correcta es necesario compilar el proyecto con Maven para que el plugin avro-maven-plugin genere las clases que implementan el schema AVRO.

 

Paso 5. Implementar el productor

Tanto si se usa el arquetipo fwk-custom-producer-archetype como fwk-default-producer-archetype se debe revisar el productor que el arquetipo ha generado y adaptarlo al negocio que se va a implementar. 

Se recomienda consultar la documentación  documentación y  los showcases publicados en ada-fwk-ms que ilustran los aspectos principales del módulo fwk-kafka-simple.

 

Paso 6. Probar el productor

Con independencia de los test unitarios que el desarrollador haga, para verificar que el productor funciona correctamente y se conecta a Kafka y Apicurio sin problema es necesario realizar algún test de integración en local. Para probar el productor deben seguirse los siguientes pasos:

  1. Tener Kafka y Apicurio levantados en local. En el showcase del módulo fwk-kafka-simple se publica un fichero docker-compose.yaml que levanta ambos componentes.
  2. Arrancar el microservicio e invocar al servicio que envía el mensaje.
  3. Si no existe microservicio que actúe como consumidor se puede crear un consumidor Kafka y configurarlo para que consuma los mensajes del topic donde ha escrito el productor. La forma más fácil de crear este consumidor es utilizando el script kafka-console-consumer.sh o kafka-console-consumer.bat en entornos Windows que publica Kafka para este fin y pasarle las propiedades necesarias para que se conecte a Apicurio.

kafka-console-consumer.bat --bootstrap-server 127.0.0.1:9092 --topic [topic] --from-beginning -–property apicurio.registry.url=http://localhost:8990/apis/registry/v2 --property apicurio.registry.use-specific-avro-reader=true --property apicurio.registry.auto-register=true -–property apicurio.registry.artifact-id= io.apicurio.registry.utils.serde.strategy.TopicIdStrategy -- key.deserializer= org.apache.kafka.common.serialization.StringDeserializer -–property value.deserializer= io.apicurio.registry.serde.avro.AvroKafkaDeserializer

 

Implementación usando Spring Boot como framework de desarrollo

Para obtener información detallada de cómo construir un microservicio que actúe como productor utilizando Spring Boot se recomienda consultar la documentación oficial y las guías y manuales publicados por Spring.

 

Implementación usando Quarkus como framework de desarrollo

Para obtener información detallada de cómo construir un microservicio utilizando Quarkus se recomienda consultar la documentación oficial y las guías y manuales publicados por Quarkus y Red Hat.

 

Desarrollo de un consumidor

Implementación usando ada-fwk-ms como framework de desarrollo

Paso 1. Elección y ejecución del arquetipo

ada-fwk-ms dispone de un conjunto de arquetipos especialmente diseñados para la creación de microservicios cuyo principal cometido es actuar como consumidor de eventos para Kafka.

  • fwk-default-consumer-archetype: Arquetipo que incorpora el módulo fwk-kafka-simple y permite crear un microservicio que publica un consumidor Kafka usando el consumidor que proporciona ada-fwk-ms. Arquetipo recomendado para casos de uso donde se necesite un productor sencillo que solo imprima un mensaje en el log.
  • fwk-custom-producer-archetype: Arquetipo que incorpora el módulo fwk-kafka-simple y permite crear un microservicio que publica un consumidor Kafka usando un consumidor personalizado y que no se basa en el que proporciona ada-fwk-ms. Arquetipo recomendado para casos de uso donde se necesite un productor que requiera de un procesamiento complejo: gestión de errores, reintentos, gestión manual del envío de mensajes.

A continuación, partiendo del supuesto de que el microservicio que se va a construir publicará un consumidore personalizado, se muestra un ejemplo del comando maven que habría que ejecutar si el arquetipo elegido es fwk-custom-consumer-archetype:

mvn archetype:generate -DarchetypeGroupId=es.juntadeandalucia.ada.oda.ada-fwk-ms -DarchetypeArtifactId= fwk-custom-consumer-archetype -DarchetypeVersion=X.X.X.RELEASE

Finalizado este proceso el desarrollador dispondrá en su equipo local de un microservicio básico listo para ejecutar con las características indicadas en la documentación del arquetipo seleccionado. 

 
Paso 2. Revisar fichero pom.xml

Debe revisarse el microservicio generado y verificar que en el parent pom está declarada la versión correcta de ada-fwk-ms:

<parent>
<groupId>es.juntadeandalucia.ada.oda.ada-fwk-ms</groupId>
	<artifactId>fwk-ms-parent-pom</artifactId>
	<version>X.X.X-RELEASE</version>
	<relativePath />
</parent>

También que se incluye el módulo fwk-kafka-simple:

<dependency>
	<groupId>es.juntadeandalucia.ada.oda.ada-fwk-ms</groupId>
	<artifactId>fwk-kafka-simple</artifactId>
</dependency>

Si se va a utilizar Apicurio (recomendado) revisar que se incluye el módulo fwk-registry-apicurio:

<dependency>
<groupId>es.juntadeandalucia.ada.oda.ada-fwk-ms</groupId>
	<artifactId>fwk-registry-apicurio</artifactId>
</dependency>

Y en el caso de utilizar Apicurio y mensajes con schema AVRO (recomendado) revisar que se tiene el plugin de maven avro-maven-plugin declarado y correctamente configurado:

<plugin>
<groupId>org.apache.avro</groupId>
	<artifactId>avro-maven-plugin</artifactId>
	<version>1.10.0</version>
	<executions>
		<execution>
			<id>schemas</id>
			<phase>generate-sources</phase>
			<goals>
				<goal>schema</goal>
			</goals>
			<configuration>
				<sourceDirectory>
${project.basedir}/src/main/resources/avro/
</sourceDirectory>
<outputDirectory>
				${project.build.directory}/generated-sources/avro/
</outputDirectory>
				<stringType>String</stringType>
			</configuration>
		</execution>
	</executions>
</plugin>

 

Paso 3. Revisar la configuración

Debe revisarse el fichero application.yaml  generado por el arquetipo y verificar que la configuración para conectarse con Kafka, Apicurio (si se incorpora el módulo fwk-registry-apicurio) y la configuración del propio consumidor es correcta. Se recomienda consultar la documentación de Spring Boot y revisar todas las propiedades disponibles bajo el prefijo spring.kafka para adaptar la funcionalidad del productor a la que requiere el negocio.

spring:
  kafka:
    bootstrap-servers: 127.0.0.1:9092
    consumer:
      group-id: consumer-group
      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      value-deserializer: io.apicurio.registry.serde.avro.AvroKafkaDeserializer
      properties:
        apicurio.registry.use-specific-avro-reader: true
        apicurio.registry.url: http://localhost:8990/apis/registry/v2
        apicurio.registry.artifact-id: io.apicurio.registry.utils.serde.strategy.TopicIdStrategy
        apicurio.registry.auto-register: true

 

Paso 4. Incorporar la definición del schema AVRO

Si  se ha definido un formato para el mensaje, es necesario añadir el schema AVRO en el microservicio. La ubicación para depositar el schema AVRO es configurable pero habitualmente se pone en /src/main/resources/avro/ tal y como se ve en el ejemplo para configurar el plugin avro-maven-plugin.
Una vez que el schema AVRO está en la ruta correcta es necesario compilar el proyecto con Maven para que el plugin avro-maven-plugin genere las clases que implementan el schema AVRO.
 

Paso 5. Implementar el consumidor

Tanto si se usa el arquetipo fwk-custom-consumer-archetype como fwk-default-consumer-archetype se debe revisar el consumidor que el arquetipo ha generado y adaptarlo al negocio que se va a implementar. 

Se recomienda consultar la documentación y  los showcases publicados en ada-fwk-ms que ilustran los aspectos principales del módulo fwk-kafka-simple.

 

Paso 6. Probar el consumidor

Con independencia de los test unitarios que el desarrollador haga, para verificar que el consumidor funciona correctamente y se conecta a Kafka y Apicurio sin problemas es necesario realizar algún test de integración en local. Para probar el consumidor deben seguirse los siguientes pasos:

  1. Tener Kafka y Apicurio levantados en local. En el showcase del módulo fwk-kafka-simple se publica un fichero docker-compose.yaml que levanta ambos componentes.
  2. Arrancar el microservicio y observar que el consumidor se conecta correctamente a Kafka y Apicurio aunque aún no existan mensajes para consumir.
  3. Si el microservicio que actúa como productor existe ya lo más fácil es levantarlo y ejecutar el servicio para mandar un mensaje. Si no existe la forma más fácil de crear este productor es utilizando el script kafka-console-producer.sh o kafka-console-producer.bat en entornos Windows que publica Kafka para este fin y pasarle las propiedades necesarias para que se conecte a Apicurio.
  4. Comprobar que cuando se manda un mensaje desde el productor este llega al consumidor y puede procesarse correctamente

 

Implementación usando Spring Boot como framework de desarrollo

Para obtener información detallada de cómo construir un microservicio que actúe como productor utilizando Spring Boot se recomienda consultar la documentación oficial y las guías y manuales publicados por Spring.

 

Implementación usando Quarkus como framework de desarrollo

Para obtener información detallada de cómo construir un microservicio utilizando Quarkus se recomienda consultar la documentación oficial y las guías y manuales publicados por Quarkus y Red Hat.