Norma para desarrollos Java

Ámbito de aplicación de la norma

Esta norma es de aplicación tanto para nuevos desarrollos como mantenimientos de productos software que se realicen en lenguaje Java.

Las directrices que contiene la norma son independientes de la pila tecnológica utilizada para el desarrollo de la solución software.

Al implementar un sistema utilizando este lenguaje deben tenerse en cuenta:

• Las directrices y estándares referidos en esta norma.
• Otras normas específicas a la arquitectura o arquitecturas que apliquen a los componentes software del sistema.

Puedes conocer en esta sección  cómo se marca la obligatoriedad de cumplimiento de las directrices que componen la norma.

Librerías y versiones

Versión de la JVM

DIR_01 Versión de Java

RECOMENDADO Se recomienda realizar los desarrollos en la versión Java especificada en el stack tecnológico.

Si el contexto en el que se está desarrollando la aplicación no hace posible usar esta versión deberá usarse la versión LTS (Long Term Support) más cercana.

Maven

DIR_02 Versión de maven

OBLIGATORIO Para los nuevos desarrollos, se utilizará Maven, en la versión Java especificada en el stack tecnológico, para la gestión de las dependencias en el desarrollo.

RECOMENDADO Para desarrollos existentes, se recomienda utilizar Maven, en la versión Java especificada en el stack tecnológico, para la gestión de las dependencias en el desarrollo.

Lombok

DIR_03 Uso de Lombok

OBLIGATORIO Para los nuevos desarrollos, se utilizará la librería Lombok para reducir el texto repetitivo en el código.

RECOMENDADO Para desarrollos existentes, se recomienda utilizar la librería Lombok para reducir el texto repetitivo en el código.

Lombok es una librería que a través del uso de etiquetas simplifica la creación de código volviéndolo menos verboso con lo que es más fácil de mantener y establece unas pautas de estandarización que reducen la cantidad de código repetido que se copia y pega en diferentes desarrollos.

DIR_04 Configuración de Lombok

RECOMENDADO  Se creará el fichero lombok.config.

Este fichero prepara el código autogenerado por la librería Lombok para que no sea incluido dentro de los análisis de código que hace Sonar. El fichero debe ubicarse en la raíz del proyecto y contener como mínimo las siguientes propiedades:

config.stopBubbling = true
lombok.addLombokGeneratedAnnotation = true

Uso de maven

Estructura de los proyectos 

DIR_05 Estructura del proyecto

RECOMENDADO El proyecto maven estará construido siguiendo una estructura Standard Directory Layout. El proyecto seguirá la siguiente estructura:

• proyecto-maven
  • pom.xml
  • README.md
  • CHANGELOG.md
  • NOTICE.txt
  • LICENSE.txt
  • /src
    • /main
      • /java
      • /resources
      • /filters
      • /webapp
      • /test
    • /it
    • /site
    • /assembly

El uso de esta estructura no limita el uso de la arquitectura que mejor se adapte al proyecto Java. La estructura de arquitectura interna de un proyecto se ubica dentro de los directorios que cuelgan de /src/main  y el contenido de estos directorios puede organizarse para ajustar la estructura del proyecto a la arquitectura que se quiera utilizar.

DIR_06 Estructura de ficheros pom.xml

RECOMENDADO Se establecerá una jerarquía entre los diferentes ficheros pom.xml que intervienen en un proyecto mediante el uso ficheros pom.xml padre y su referencia en los pom.xml hijos.

DIR_07 Directorio src/main

OBLIGATORIO La estructura del proyecto contendrá el directorio src/main. Este directorio es el más importante del proyecto y en su interior se ubicará todo el código que forme parte de la construcción del artefacto tanto si es un jar como si es un war.

DIR_08 Directorio src/test

OBLIGATORIO La estructura del proyecto contendrá el directorio src/test. En este directorio se ubicarán los ficheros con las pruebas que permiten verificar la calidad del desarrollo. Este directorio no forma parte del empaquetado final del artefacto.

Coordenadas

DIR_09 Coordenadas de los proyectos

OBLIGATORIO Se declararán las coordenadas de repositorio en el fichero pom.xml.

La convención para nomenclatura de las coordenadas del pom.xml serán las siguientes:

• GroupID: es.juntadeandalucia.<proyecto>
• ArtifactID: NombreComponente
• Versión: X.Y.Z / X.Y.Z-SNAPSHOT (para versiones snapshots)

Nota: Snapshots son versiones candidatas a liberar que actualmente no son estables.

El repositorio rechazará las subidas que no cumplan con el patrón en el campo groupId: es/juntadeandalucia/*

Se admitirán por compatibilidad los siguientes formatos en el groupId, no debiendo usarse para nuevos desarrollos:

• es/junta-andalucia/*
• es/jda/*

Dependencias

DIR_10 Gestión de dependencias

OBLIGATORIO Se especificará la versión exacta de una dependencia, no estando permitida  definirlas usando intervalos.

<version>[1.1.15,1.2.0)</version> ##no es una opción válida

DIR_11 Centralización de dependencias

RECOMENDADO En proyectos con una estructura compleja que impliquen varios módulos y una jerarquía de ficheros pom.xml, se definirá un bloque de <dependencyManagement> en el pom padre. Este bloque centralizará en un único lugar la versión que se va a utilizar de una dependencia, garantizando que todo el proyecto utilice la misma versión y evitando problemas de compatibilidad entre librerías.

Plugins

DIR_12 Plugin JaCoCo

OBLIGATORIO Para el análisis de la cobertura de código se utilizará la herramienta JaCoCo.

Como resultado de la ejecución de la herramienta, se generará un fichero jacoco.xml que permitirá cargar la información generada en otras herramientas de visualización. Para utilizar JaCoCo en el proyecto, se incluirá en el pom.xml de los productos en los que se deba realizar el análisis de cobertura el siguiente plugin, con la configuración indicada:

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.7</version>
    <executions>
        <execution>
            <id>jacoco-initialize</id>
            <goals>
                    <goal>prepare-agent</goal>
            </goals>
        </execution>
        <execution>
            <id>jacoco-site</id>
            <phase>test</phase>
            <goals>
                    <goal>report</goal>
            </goals>
            <configuration>
                <formats>
                    <format>XML</format>
                </formats>
            </configuration>
        </execution>
    </executions>
</plugin>

La ubicación del fichero jacoco.xml, como otras configuraciones para la carga automatizada en SonarQube se realizarán sobre el fichero sonar.properties. Por ejemplo:

sonar.projectKey=es.juntadeandalucia.proyecto
sonar.projectName=proyecto
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml
sonar.sources=src
sonar.java.binaries=target/**
sonar.junit.reportsPath=reports/java/surefire-reports
sonar.sourceEncoding=UTF-8
http.proxyHost=proxy.chap.junta-andalucia.es
http.proxyPort=3128

Repositorios

DIR_13 Repositorios de dependencias autorizados

OBLIGATORIO Se tendrán configurados únicamente los repositorios de dependencias autorizados por la Junta de Andalucía. Si se identifica alguna dependencia, necesaria para el proyecto que no esté en este repositorio, se solicitará su inclusión, previo estudio del área de ciberseguridad.

Ficheros específicos

DIR_14 Fichero README.md

RECOMENDADO Se generará en el directorio raíz el fichero README.md.

Este fichero contendrá la información de negocio, técnica o de despliegue que sea de utilidad para los desarrolladores. 

DIR_15 Fichero CHANGELOG.md

RECOMENDADO Se generará en el directorio raíz el fichero CHANGELOG.md.

Este fichero listará los cambios introducidos en la última versión y además guardará un registro de las modificaciones realizadas en versiones anteriores. Se recomienda crear el fichero CHANGELOG.md siguiendo las buenas prácticas de Keep a Changelog".

DIR_16 Fichero LICENSE.md

RECOMENDADO Se generará en el directorio raíz el fichero LICENSE.txt.

Este fichero tendrá la licencia asociada al software. Salvo que para algún proyecto la dirección determine algo distinto, con carácter general, la licencia de todo el software publicado por la Junta de Andalucía es EUPL v1.2.

Diseño de aplicaciones

Patrones de diseño

DIR_17 Aplicación de los patrones de diseño

OBLIGATORIO El diseño de las aplicaciones se basará en la implementación y uso de patrones de diseño.

Las aplicaciones utilizarán patrones de diseño que le ayuden a implementar la funcionalidad que deben ejecutar. 

Se recomienda, siempre que sea posible, no implementar el patrón de diseño manualmente sino ayudarse de etiquetas que lo implementan automáticamente como @Builder, @Singleton, @Data... Se recomienda consultar las etiquetas publicadas por el framework bajo el que se implemente la aplicación para utilizar su equivalente ya que estarán optimizadas para la ejecución de ese framework en particular. 

Desarrollo de aplicaciones

Framework de desarrollo

DIR_18 Uso de framework de desarrollo

OBLIGATORIO La implementación de una aplicación se hará usando un framework de desarrollo. 

El uso de framework de desarrollo ayuda a estandarizar el código, reducir la cantidad de código manual que ha de implementarse durante el desarrollo y evita la implementación de anti patrones como  “Boilerplate” o  “Big Ball of Mud”. 

El uso de anti patrones y la implementación manual de soluciones que el framework de desarrollo proporciona automáticamente, genera aplicaciones más difíciles de mantener y propensas a que se produzcan errores.

DIR_19 Framework de desarrollo recomendados

RECOMENDADO Para la implementación de aplicaciones Java se utilizará el framework de desarrollo Spring Boot como opción preferente, existiendo también la opción de usar Quarkus. Para saber más, consulta la norma de Alineamiento con la pila tecnológica de la ADA y su anexo, en el que se detallan las opciones disponibles y versiones recomendadas.

Así mismo, se recomienda a los equipos que extiendan dichos framework con funcionalidades de uso común implementando librerías para minimizar el código repetido o “boilerplate” en sus microservicios. 

En línea con esta recomendación, la Oficina de Arquitectura mantiene y evoluciona el activo Framework de desarrollo de microservicios (ada-fwk-ms). Este activo es un framework de desarrollo que extiende Spring Boot 3 e implementa funcionalidades de uso común a todos los proyectos. Las funcionalidades que amplía este framework no son de uso obligatorio y no impide que se utilicen las funcionalidades nativas de Spring Boot 3.

Gestión de errores

Excepciones técnicas

DIR_20 Tipos de excepciones técnicas

OBLIGATORIO Las excepciones definidas en una aplicación pertenecerán a una de estas dos categorías: excepciones de ejecución (Runtime exceptions) y excepciones de comprobación (Checked exceptions).

Este tipo de excepciones se producen en tiempo de ejecución de la aplicación. No pueden predecirse en el código y tienen que gestionarse en tiempo de ejecución. Ejemplo de excepciones: NullPointerException, ArrayIndexOutOfBoundsException y ArithmeticException.

Las excepciones de comprobación pueden predecirse y gestionarse directamente en el código. Ejemplo de estas excepciones son: IOException, SQLException y ClassNotFoundException.

DIR_21 Excepciones de ejecución

OBLIGATORIO Las excepciones de ejecución heredarán de la clase RuntimeException.

Estas excepciones no necesitan ser declaradas en un bloque try-catch ni en la cláusula throws de un método.

Se gestionarán según los mecanismos implantados por el framework y las librerías que se usen durante el desarrollo.

DIR_22 Excepciones de comprobación

OBLIGATORIO Las excepciones de comprobación heredarán de la clase Exception.

Estas excepciones se gestionarán mediante bloques de tipo try-catch o propagadas usando la cláusula throws del método.

Se recomienda centralizar, por ejemplo en la capa de servicio, la gestión de todas las excepciones que se produzcan en una petición  y propagar a capas superiores las que se produzcan en las capas inferiores.

Excepciones de negocio

DIR_23 Excepciones de negocio

OBLIGATORIO Las aplicaciones, además de controlar excepciones de tipo técnico, también controlarán y gestionarán las excepciones que puedan producirse a nivel de negocio.

Todos los datos de entrada en la aplicación se someterán a validación para detectar errores de negocio o formato. Toda aplicación es responsable de los datos que recibe y procesa, por lo tanto esta validación debe hacerse con independencia de que ya se haya hecho en el componente que generó la información.

Notificación de excepciones

DIR_24 Notificación de excepciones en los logs

OBLIGATORIO Las excepciones que se produzcan en una aplicación, con independencia del tipo que sean, se registrarán en el log de la aplicación según las directrices establecidas en la norma para la observabilidad.

No debe exponerse información sensible de usuarios en los logs de una aplicación.

Se permite en los logs exponer información referente a máquina o componentes propios de la Junta de Andalucía, intentando minimizar todo lo posible la información sensible de este tipo expuesta.

DIR_25 Notificaciones de excepciones a usuarios

OBLIGATORIO Las excepciones que deban notificarse a los usuarios no pueden mostrar información sensible, ni de usuarios, ni de máquinas o componentes propios de la Junta de Andalucía.