DEV Community: Ciro

El otro Java + Script, o cómo hacer scripting con Java

Ciro — Tue, 04 Nov 2025 23:00:00 +0000

Real Java script, the only good JavaScript - Josh Long

Java ha evolucionado mucho más allá de ser solo un lenguaje para grandes aplicaciones empresariales. Con las versiones modernas, ahora podemos crear scripts simples y ejecutables de forma rápida, similar a lenguajes como Python o Bash.

La nueva sintaxis de main

Una de las mejoras más significativas es la sintaxis simplificada del método main. Adiós a la verbosidad tradicional:

script.java

void main() {
  IO.println("Hola");
}

Así de simple. No más public static void main(String[] args), no más clases obligatorias. Solo el código que necesitas.

Convirtiendo tu código en un script ejecutable

Para hacer tu archivo Java directamente ejecutable desde la terminal, sigue estos pasos:

1. Elimina la extensión del archivo

Renombra script.java a simplemente script.

2. Agrega el shebang

Al inicio del archivo, añade esta línea especial:

script

#!/usr/bin/env -S java --source 25
void main() {
  IO.println("Hola");
}

El shebang (#!) le indica al sistema operativo que use Java para ejecutar este archivo. El parámetro --source 25 especifica la versión de Java a utilizar.

3. Dale permisos de ejecución

En tu terminal, ejecuta:

chmod a+x script

Este comando hace que el archivo sea ejecutable por todos los usuarios.

4. Ejecuta tu script

Ahora puedes correr tu script directamente:

./script

Y verás tu salida:

Hola

¿Por qué es útil?

Esta funcionalidad es perfecta para:

Automatización: Tareas repetitivas sin necesidad de compilar
Prototipado rápido: Probar ideas sin estructura de proyecto
Utilidades: Pequeñas herramientas de línea de comandos
Aprendizaje: Enseñar Java sin la complejidad inicial

Java ya no es solo para aplicaciones grandes. Ahora también puedes usarlo para scripts rápidos y prácticos, combinando la simplicidad de lenguajes de scripting con el poder y la robustez de Java.

Configurar un CDN gratuito con GitHub y jsDelivr

Ciro — Tue, 21 Oct 2025 22:00:00 +0000

¿Necesitas servir archivos CSS o JavaScript desde un CDN pero no quieres pagar por servicios de terceros? Existe una solución simple y gratuita que aprovecha GitHub y jsDelivr.

El problema

Cuando desarrollas aplicaciones web, es común necesitar:

Compartir hojas de estilo CSS entre múltiples proyectos
Servir archivos estáticos con baja latencia global
Cachear recursos de forma eficiente
Versionar tus assets de manera confiable

Los CDN tradicionales pueden ser costosos o requerir configuración compleja. Pero hay una alternativa mejor.

La solución: GitHub + jsDelivr

jsDelivr es un CDN gratuito que puede servir archivos directamente desde repositorios de GitHub. No requiere registro, configuración ni costo alguno.

Ventajas

Gratis y sin límites para proyectos open source
Red global de servidores con baja latencia
Caché automático para mejorar el rendimiento
Control de versiones mediante tags de Git
Minificación automática disponible

Implementación paso a paso

Vamos a crear un CDN para servir archivos CSS, similar a este ejemplo real.

1. Crea un repositorio en GitHub

mkdir stylesheet-cdn
cd stylesheet-cdn
git init

2. Agrega tus archivos CSS

Crea una carpeta styles/ y añade tu archivo CSS:

mkdir styles

Por ejemplo, styles/mis-estilos.css:

/* Tu CSS aquí */
body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen,
    Ubuntu, Cantarell, sans-serif;
  line-height: 1.6;
  color: #333;
}

h1,
h2,
h3 {
  color: #2c3e50;
  margin-top: 1.5em;
}

code {
  background: #f4f4f4;
  padding: 2px 6px;
  border-radius: 3px;
}

3. Sube el repositorio a GitHub

git add .
git commit -m "Add stylesheet"
git push origin main

4. Usa tu archivo desde el CDN

Ahora puedes incluir tu CSS en cualquier página web:

<!DOCTYPE html>
<html>
  <head>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/gh/TuUsuario/stylesheet-cdn@main/styles/mahonnaise.vs-code-markdown-theme.css"
    />
  </head>
  <body>
    <h1>¡Hola mundo!</h1>
    <p>Este CSS se sirve desde un CDN global gratuito.</p>
  </body>
</html>

Patrón de URL

El formato de URL de jsDelivr es:

https://cdn.jsdelivr.net/gh/{usuario}/{repositorio}@{branch}/ruta/al/archivo

Mejores prácticas

Usa versiones en producción

Para proyectos en producción, es recomendable usar tags de Git en lugar de @main:

# Crea un tag
git tag v1.0.0
git push origin v1.0.0

<!-- URL con versión específica -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/gh/TuUsuario/stylesheet-cdn@v1.0.0/styles/mahonnaise.vs-code-markdown-theme.css"
/>

Esto asegura que tu aplicación no se rompa si actualizas el archivo en el futuro.

Minificación automática

jsDelivr puede minificar tus archivos automáticamente añadiendo .min antes de la extensión:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/gh/TuUsuario/stylesheet-cdn@v1.0.0/styles/mahonnaise.vs-code-markdown-theme.min.css"
/>

Considera el caché

Los archivos se cachean en el CDN, por lo que los cambios pueden tardar 5-10 minutos en propagarse. Para desarrollo, usa @main. Para producción, usa tags versionados.

Casos de uso

Esta técnica es perfecta para:

Librerías CSS compartidas entre múltiples proyectos
Themes y plantillas de código abierto
Archivos JavaScript de utilidades comunes
Recursos estáticos como fuentes o iconos
Prototipos rápidos sin necesidad de configurar hosting

Limitaciones

El repositorio debe ser público
No es ideal para archivos muy grandes (>50MB)
El caché puede dificultar el desarrollo activo (usa @main para desarrollo)

Conclusión

Con GitHub y jsDelivr puedes tener un CDN global de nivel empresarial completamente gratis. Esta solución es ideal para proyectos open source, bibliotecas compartidas, y cualquier recurso estático que quieras distribuir eficientemente.

El código completo de ejemplo está disponible en github.com/Gekyzo/stylesheet-cdn.

Guía rápida SDKMAN!

Ciro — Wed, 08 Oct 2025 20:59:05 +0000

Guía de SDKMAN, gestionar versiones de Java fácilmente

Si trabajas con Java, seguramente has tenido que lidiar con diferentes versiones según el proyecto. SDKMAN es una herramienta que hace esta tarea mucho más sencilla, permitiéndote instalar y cambiar entre versiones de Java con un simple comando.

En este artículo te muestro cómo instalarlo y usar sus funciones principales.

Instalación

Para instalar SDKMAN en tu sistema (Linux, macOS o WSL), ejecuta:

curl -s "https://get.sdkman.io" | bash

Una vez completada la instalación, verificamos que todo funcionó correctamente:

sdk version

Si vemos la versión de sdkman, la instalación se habrá completado.

Listar distribuciones de Java

SDKMAN soporta múltiples distribuciones de Java (Oracle, Temurin, GraalVM, etc.). Para ver todas las versiones disponibles:

sdk list java

Este comando nos mostrará una lista completa con todas las distribuciones y versiones. Si buscamos algo específico, por ejemplo solo versiones de Java 21, puedes filtrar los resultados:

sdk list java | grep " 21\."

Esto nos mostrará únicamente las distribuciones de Java 21, haciendo más fácil encontrar la que necesitemos.

Instalar una versión de Java

Una vez que hemos identificado la versión que queremos, utilizaremos su identificador para instalarlo:

sdk install java 21.0.2-open

SDKMAN descargará e instalará esa versión automáticamente.

Establecer la versión de Java

Aquí es donde SDKMAN realmente brilla. Puedes configurar qué versión usar de dos formas:

Configuración global

Para cambiar la versión de Java que usaremos en todo tu sistema:

sdk use java 21.0.2-open

Configuración por directorio

Si trabajamos en varios proyectos que requieren diferentes versiones de Java, podemos configurar una versión específica para cada directorio:

sdk env init
sdk use java 21.0.2-open

Estos comandos generan un archivo .sdkmanrc en el directorio actual. Este archivo refleja la versión de Java que utilizaremos en ese directorio en específico, sin alterar la configuración global.

Cada vez que entremos a ese directorio, SDKMAN detectará el archivo y usará automáticamente la versión correcta.

Anotación @JsonUnwrapped

Ciro — Mon, 20 Mar 2023 08:00:00 +0000

La anotación @JsonUnwrapped es una anotación de la biblioteca Jackson para Java que se utiliza para indicar una propiedad no debe estar anidada en la estructura JSON resultante, sino que debe estar a nivel superior.

Por ejemplo, supongamos que tenemos una clase Person que tiene una propiedad Address que también es una clase con sus propias propiedades. Si queremos serializar un objeto Person en JSON, la estructura resultante sería algo así como:

{
    "name": "Juan",
    "address": {
        "street": "Calle 123",
        "city": "Ciudad de México",
        "state": "CDMX"
    }
}

Sin embargo, si queremos que las propiedades de Address estén en el mismo nivel que las propiedades de Person, podemos utilizar la anotación @JsonUnwrapped en la propiedad Address. La clase Person se vería así:

public class Person {

    private String name;

    @JsonUnwrapped
    private Address address;
}

public class Address {

    private String street;

    private String city;

    private String state;
}

Al serializar un objeto Person utilizando esta clase, la estructura resultante sería:

{
    "name": "Juan",
    "street": "Calle 123",
    "city": "Ciudad de México",
    "state": "CDMX"
}

Como podemos ver, las propiedades de Address se desempaquetaron y se incluyeron en el mismo nivel que las propiedades de Person.

En resumen, la anotación @JsonUnwrapped es una herramienta que puede ser útil en situaciones en las que queremos una estructura JSON más simple o para facilitar la integración con otros sistemas que esperan una estructura JSON específica.

Anotación @Transient

Ciro — Tue, 24 Jan 2023 23:00:00 +0000

Mediante la anotación @Transient (o transitorio en español) podemos crear atributos en clases de tipo entidad (anotadas con @Entity) que no van a persistir en la base de datos. Igualmente, los atributos anotados con @Transient no se mapean con ninguna columna de la entidad.

Gracias a esta funcionalidad, podemos crear comportamientos como el siguiente:

@Entity
class User {

    @Id
    private Long id;

    @Column(name = "name")
    private String name;

    @Column(name = "group")
    private UserGroup group;

    @Column(name = "type")
    private UserType type;

    @Transient
    private PermissionLevel permissionLevel; // <- Este atributo NO se almacenará en la base de datos

    public int setPermissionLevel(...) {
        //
    }

}

Podemos ver que el atributo PermissionLevel no se almacenará en la base de datos, ya que puede que queramos actualizar su valor en tiempo de ejecución, utilizando en primer lugar unos valores o criterios, y según el usuario interactúa con la aplicación que estos valores cambien.

JUnit Cómo repetir un test con parámetros

Ciro — Wed, 16 Nov 2022 23:00:00 +0000

En publicaciones anteriores hemos visto de qué maneras se podía repetir la ejecución de un test, así como la manera de parametrizar un test.
En esta ocasión vamos a ver cómo unir ambas ideas para repetir un test parametrizado.

Utilizaremos para ello el mismo ejemplo de la publicación repetir la ejecución de un test, recuerdo que se trata de un método que genera un número aleatorio de N dígitos.

Inicialmente, puede que pensamos que es suficiente con combinar las anotaciones mencionadas en las otras publicaciones, @RepeatedTest + @ParameterizedTest, pero lamentablemente JUnit no soporta esta funcionalidad actualmente. Por fortuna la solución alternativa es muy simple.

Supongamos que partimos de un test parametrizado:

/**
 * Parameters:
 * 1. int - The lower bound.
 * 2. int - The upper bound.
 * 3. int - The number of digits of the random generated value.
 */
private static Stream<Arguments> randomNumberGeneratorParams() {
    return Stream.of(
        Arguments.of(1, 9, 1),
        Arguments.of(10, 99, 2),
        Arguments.of(100, 999, 3),
        Arguments.of(1000, 9999, 4),
        Arguments.of(10000, 99999, 5)
    );
}

@ParameterizedTest
@MethodSource(value = "randomNumberGeneratorParams")
@DisplayName(value = "Random numbers generator")
void random_numbers_generator(int low, int high, int numOfDigits) {    
    var actual = RandomUtil.generateNumber(numOfDigits);
    assertTrue(high >= actual, "Error, random is too high");
    assertTrue(low <= actual, "Error, actual is too low");
}

// Test passed: 5 of 5 ✅
// [1] low = 1, high = 9, numOfDigits = 1 -> numero generado 6
// [2] low = 10, high = 99, numOfDigits = 2 -> número generado 56
// [3] low = 100, high = 999, numOfDigits = 3 -> ...
// [4] low = 1000, high = 9999, numOfDigits = 4
// [5] low = 10000, high = 99999, numOfDigits = 5

Podemos imaginar que este test no es muy fiable, ya que sólo hemos generado 1 número aleatorio para cada uno de nuestros casos de uso (generar un número de 1, 2, 3, 4 y 5 dígitos).

Para confirmar con seguridad que la función aleatoria es correcta, sería mejor si pudiéramos generar N números en cada rango o caso de uso, y comprobar que todos ellos cumplen con el test.

Veamos cómo hacerlo:

private static final int NUMBER_REPETITIONS = 1_000;

/**
 * Parameters:
 * 1. int - The lower bound.
 * 2. int - The upper bound.
 * 3. int - The number of digits of the random generated value.
 */
private static Stream<Arguments> randomNumberGeneratorParams() {
    return Stream.of(
        Arguments.of(1, 9, 1),
        Arguments.of(10, 99, 2),
        Arguments.of(100, 999, 3),
        Arguments.of(1000, 9999, 4),
        Arguments.of(10000, 99999, 5)
    );
}

@ParameterizedTest
@MethodSource(value = "randomNumberGeneratorParams")
@DisplayName(value = "Random numbers generator")
void random_numbers_generator(int low, int high, int numOfDigits) {
 int iterationCount = 1;
 do {   // <- Mediante el uso del loop do-while, podemos iterar la generación de los números aleatorios
     var actual = RandomUtil.generateNumber(numOfDigits);
     assertTrue(high >= actual, "Error, random is too high");
     assertTrue(low <= actual, "Error, actual is too low");
     iterationCount++;
 } while (iterationCount <= NUMBER_REPETITIONS);
}

// Test passed: 5 of 5 ✅
// [1] low = 1, high = 9, numOfDigits = 1 -> números generados: 6, 3, 1, 3, 4, 2, 6, 8, 9...1_000_000 de números generados
// [2] low = 10, high = 99, numOfDigits = 2 -> ...
// [3] low = 100, high = 999, numOfDigits = 3
// [4] low = 1000, high = 9999, numOfDigits = 4
// [5] low = 10000, high = 99999, numOfDigits = 5

De esta manera, el test generará tantos números como indiquemos en NUMBER_REPETITIONS, y confirmará que todos ellos cumplen con las afirmaciones del test.

JUnit Cómo parametrizar un test

Ciro — Mon, 14 Nov 2022 08:00:00 +0000

JUnit cuenta con una serie de funcionalidades orientadas a ejecutar tests en nuestra aplicación.
Una de estas funcionalidades son los tests parametrizados, que nos permiten poder declarar los valores que necesitemos fuera del propio test.

Para entender su funcionamiento supongamos que nuestra aplicación cuenta con un validador de códigos bancarios IBAN, que comprueba si un valor determinado cumple el patrón esperado en dichos códigos.

Los códigos IBAN utilizados en esta publicación han sido generados mediante la web http://randomiban.com/?country=Spain

class IbanValidator {
    // Regex pattern that an Iban must match
    static final String PATTERN = "^ES[0-9]{2}[0-9]{20}$";

    boolean isValid(String iban) {
        return iban.matches(PATTERN);
    }    
}

Ahora supongamos que tenemos un test sobre esta clase con la siguiente forma:

@Test
@DisplayName(value = "Check validity of IBAN")
void check_validity_iban() {
    IbanValidator validator = new IbanValidator();
    assertTrue(validator.isValid("ES7921000813610123456789"));
}

// Test passed: 1 of 1 ✅

Como podemos ver, en este ejemplo estamos comprobando únicamente un valor concreto para el código IBAN, por lo que el test estaría sesgado.
Podríamos enfrentarnos a un falso positivo, ya que si desconocemos la implementación del método isValid() podría ser que siempre devuelva true.

Para resolver este problema, sería mejor probar la validación con diferentes valores de IBAN. Nuestro primer instinto podría ser copiar el test N veces, tantas como códigos IBAN diferentes queramos probar, pero JUnit nos facilita este trabajo mediante el uso de la anotación @ParameterizedTest.

@ParameterizedTest

Para indicar el origen de los parámetros de un test parametrizado, debemos hacer uso de otras anotaciones como:

@ValueSource: permite indicar los valores directamente en la anotación.
@MethodSource: permite hacer referencia a un método proveedor que contiene los parámetros.

@ValueSource

Utilizando esta anotación, podemos declarar los valores del parámetro de nuestro test:

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;

@ParameterizedTest  // <- Utilizamos la anotación @ParameterizedTest en lugar de @Test
@ValueSource(strings = {"ES7921000813610123456789", "ES1600755981885574867892"}) // <- Indicamos en la anotación @ValueSource el tipo de parámetro (en este caso String) seguido de los valores que queremos probar
@DisplayName(value = "Check validity of IBAN")
void check_validity_iban(String iban) { // <- Indicamos en el test el tipo y nombre del nuestro parámetro
    IbanValidator validator = new IbanValidator();
    assertTrue(validator.isValid(iban));
}

// Test passed: 2 of 2 ✅

Una de las limitaciones que tiene @ValueSource es que únicamente podemos hacer uso de un parámetro para el test, y en ocasiones esto puede ser insuficiente.
Para resolver este problema debemos hacer uso de la anotación alternativa @MethodSource.

@MethodSource

Aplicando esta anotación al mismo ejemplo, el test quedaría de la siguiente forma:

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.Arguments;
import org.junit.jupiter.params.provider.MethodSource;

private static Stream<Arguments> testIbanValidityParams() { // <- Creamos un método proveedor donde indicamos 
    return Stream.of(
        Arguments.of("ES7921000813610123456789"),
        Arguments.of("ES1600755981885574867892")
    )
}

@ParameterizedTest
@MethodSource(value = "testIbanValidityParams") // <- Indicamos en la anotación @MethodSource el nombre del método que contiene los parámetros
@DisplayName(value = "Check validity of IBAN")
void check_validity_iban(String iban) {
    IbanValidator validator = new IbanValidator();
    assertTrue(validator.isValid(iban));
}

// Test passed: 2 of 2 ✅

Como podemos ver, lo único que necesitamos es crear un método estático que devuelva un Stream<Arguments>, y estos serán utilizados por el test parametrizado.
Algunas de las ventajas de esta anotación frente a @ValueSource son:

Al extraer los parámetros a un método, podemos documentar mejor el test, ya que podemos comentar en el método proveedor información sobre cada parámetro.
El método Arguments.of() espera que indiquemos 1 o N parámetros, por lo que podemos aumentar los casos de uso de nuestro test realizando una simple modificación:

/**
 * Parameters:
 * 1. String - An example of an IBAN code to be validated.
 * 2. boolean - The expected validation
 */
private static Stream<Arguments> testIbanValidityParams() {
    return Stream.of(
        Arguments.of("ES7921000813610123456789", true), // <- Creamos un nuevo parámetro booleano con la respuesta esperada
        Arguments.of("ES1600755981885574867892", true),
        Arguments.of("ESX921000813610123456789", false),
        Arguments.of("E81600755981885574867892", false)
    )
}

@ParameterizedTest
@MethodSource(value = "testIbanValidityParams")
@DisplayName(value = "Check validity of IBAN")
void check_validity_iban(String iban, boolean expected) {   // <- Indicamos el nuevo parámetro 'expected'
    IbanValidator validator = new IbanValidator();
    assertEquals(actual, expected); // <- Modificamos la afirmación de 'assertTrue' a 'assertEquals'
}

// Test passed: 4 of 4 ✅

En esta última versión del test se puede apreciar lo fácil que sería incluir un nuevo caso de uso para la validación, así como nuevos parámetros para comprobar en el test.

JUnit: Cómo ejecutar un test N iteraciones

Ciro — Thu, 10 Nov 2022 08:00:00 +0000

En ciertas ocasiones puede que necesitemos ejecutar un test N veces para poder asegurar su correcto funcionamiento.

Para ello, contamos con varias fórmulas. En primer lugar, vamos a considerar el siguiente escenario:

Queremos testear un método que nos genera un número aleatorio de N dígitos. El valora de N se pasa como parámetro a dicho método.
Creamos una clase de test de jUnit en la que declaramos el número de repeticiones o iteraciones que queremos ejecutar un determinado test.

private static final int NUMBER_REPETITIONS = 1_000_000;

Creamos los tests para validar la funcionalidad del método. En este ejemplo, he creado un test mediante la anotación de jUnit @RepeatedTest y otro test simple en el que realizamos toda la lógica dentro de un bucle do-while.

Test A: utilizando la anotación @RepeatedTest.

import org.junit.jupiter.api.RepeatedTest;

@RepeatedTest(value = NUMBER_REPETITIONS)
void random_number_with_four_digits() {

    var low = 1000;
    var high = 9999;
    var numOfDigits = 4;
    var actual = RandomUtil.generateNumber(numOfDigits);
    assertTrue(high >= actual, "Error, random is too high");
    assertTrue(low <= actual, "Error, actual is too low");
}

Test B: utilizando el bucle do-while.

@Test
void random_numbers_generator() {

    int iterationCount = 1;
    do {
        var low = 1000;
        var high = 9999;
        var numOfDigits = 4;
        var actual = RandomUtil.generateNumber(numOfDigits);
        assertTrue(high >= actual, "Error, random is too high");
        assertTrue(low <= actual, "Error, actual is too low");
        iterationCount++;
    } while (iterationCount <= NUMBER_REPETITIONS);
}

Como podemos ver ambos tests afirman lo mismo, que el método generador de números aleatorios va a devolver un valor que se encuentra entre low y high.
En ambos casos el test se va a ejecutar tantas veces como indiquemos en la constante NUMBER_REPETITIONS.

Una vez contamos con este escenario, podemos realizar distintas pruebas alterando el valor de low, high, numOfDigits y NUMBER_REPETITIONS.

En esta ocasión quería calcular la diferencia de los tiempos de ejecución de cada tipos de test, y estas son las pruebas que he realizado:

Nº Iteraciones	Test A (@RepeatedTest)	Test B (do-while)
1_000	130 ms	13 ms
100_000	2600 ms	20 ms
1_000_000	Indeterminado	55 ms

En este ejemplo, los tests ejecutados mediante el bucle do-while han sido aproximadamente un 90% más rápidos que los ejecutados mediante la anotación @RepeatedTest, además de que para el caso de 1_000_000 iteraciones, no he podido obtener un resultado final ya que la aplicación se quedaba colgada.

Conversores personalizados para @RequestParam

Ciro — Mon, 07 Nov 2022 08:00:00 +0000

En la publicación anterior vimos cómo crear conversores personalizados para propiedades dentro de una clase anotada con @RequestBody.

En esta ocasión veremos cómo hacer la misma lógica para parámetros anotados como @RequestParam.

Refactorizando el ejemplo de la publicación anterior, supongamos que tenemos el siguiente controlador:

@RestController
@AllArgsConstructor
@RequestMapping("transactions")
public class CreateTransactionController {

  @PostMapping
  public ResponseEntity<CreateTransactionOutputDto> createTransaction(
      @RequestParam Double amount,
  ) {
    //
  }

}

Y enviamos una petición a este endpoint con los siguientes parámetros:

POST '{{apiUrl}}/transactions?amount=45.13'

Por defecto Spring será capaz de enlazar cada elemento de la petición con su correspondiente parámetro de nuestro controlador, siempre y cuando encuentre el conversor adecuado para ello.

No tendremos problemas si declaramos parámetros de tipo primitivo o sus wrappers, pero en caso de querer enlazarlos a una clase, debemos crear un conversor.

Cómo mapear Value Objects

Supongamos ahora que actualizamos el tipo de clase del parámetro de la siguiente manera:

// file: Money
public record Money(Double value) {...} // <- Creamos un record para encapsular un elemento de tipo Money

// file: CreateTransactionController
@PostMapping
  public ResponseEntity<CreateTransactionOutputDto> createTransaction(
      @RequestParam Money amount,   // <- Actualizamos el tipo parámetro
  ) {
    //
  }

Para que Spring sea capaz de convertir estos datos correctamente, creamos el conversor extendiendo de org.springframework.core.convert.converter.Converter:

import org.springframework.core.convert.converter.Converter;

public class MoneyConverter implements Converter<String, Money> {   // <- Implementamos la interfaz Converter

  @Override
  public Money convert(String source) {

    return new Money(Double.parseDouble(source));   // <- Implementamos la conversión con la lógica que deseemos
  }

}

Una vez más, se trata de un código muy simple. Únicamente es necesario implementar la infertaz Converter indicando como tipo de parámetros la clase de entrada y la de salida, en este caso indicamos que se va a convertir una String en la clase Money.

Por último, debemos indicar a Spring que se utilice este conversor para mapear las instancias de la clase Money, incluyendo el nuevo conversor dentro del registro de formateadores:

import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

  @Override
  public void addFormatters(FormatterRegistry registry) {

    registry.addConverter(new MoneyConverter());    // <- Instanciamos e incluimos nuestro conversor
  }

}

Una vez hecho esto, Spring será capaz de utilizar nuestro conversor cuando intente mapear propiedades de tipos distintos a los primitivos/wrappers o las clases para las que ya cuenta con conversores.

Conversores personalizados para @RequestBody

Ciro — Thu, 03 Nov 2022 08:00:00 +0000

Normalmente, cuando declaramos un parámetro de un controlador con la anotación @RequestBody, solemos indicar la clase que contiene todos los posibles atributos del cuerpo de la petición.

En la mayoría de casos, Spring es capaz de bindear o enlazar el valor de cada elemento de la petición con su correspondiente atributo en nuestra clase, pero en ciertas ocasiones no podrá hacerlo de forma automática o puede que nosotros mismos queramos alterar este comportamiento.

Para hacer esto, existen los Converter.

Supongamos el siguiente ejemplo, tenemos un controlador que cuenta con un método de tipo POST que espera una serie de elementos en el cuerpo de la petición.

@RestController
@AllArgsConstructor
@RequestMapping("transactions")
public class CreateTransactionController {

  @PostMapping
  public ResponseEntity<CreateTransactionOutputDto> createTransaction(
      @RequestBody CreateTransactionRequest request
  ) {
    //
  }

}

Y enviamos una petición a este endpoint con el siguiente cuerpo:

{
    "reference": "AB-1234",
    "iban": "ES 1234 5678 901234",
    "amount": 45.67,
    "description": "lorem ipsum"
}

Por defecto Spring será capaz de enlazar cada elemento con su correspondiente atributo de nuestra clase, siempre y cuando ésta tenga la siguiente forma:

public record CreateTransactionRequest(
    String reference,
    String iban,  
    Double amount,
    String description
) {
    //
}

Cómo mapear Value Objects

El problema aparece cuando queremos aplicar ciertos principios de DDD como los Value Objects, y representar así mejor cada tipo de dato encapsulándolo en clases como estas:

public record Reference(String value) {...}
public record Iban(String value) {...}
public record Amount(Double value) {...}
public record Description(String value) {...}

public record CreateTransactionRequest(
    Reference reference,
    Iban iban,  
    Amount amount,
    Description description
) {
    //
}

Ahora, Spring no encontrará la forma de mapear cada elemento con la clase correspondiente, por lo que tendremos que indicarle cómo hacerlo creando clases Converter.

En primer lugar, debemos crear el conversor para cada tipo de value object extendiendo de la clase com.fasterxml.jackson.databind.util.StdConverter

(Debemos crear un conversor por cada tipo de value object)

import com.fasterxml.jackson.databind.util.StdConverter;

public class ReferenceConverter extends StdConverter<String, Reference> { // <- Extendemos StdConverter e implementamos sus métodos

  @Override
  public Reference convert(String source) {

    return new Reference(source);   // <- Implementamos la conversión con la lógica que deseemos
  }

  @Override
  public JavaType getInputType(TypeFactory typeFactory) {

    return typeFactory.constructType(String.class); // <- Indicamos el tipo de clase de entrada
  }

  @Override
  public JavaType getOutputType(TypeFactory typeFactory) {

    return typeFactory.constructType(Reference.class);  // <- Indicamos el tipo de clase de salida
  }

}

Podemos ver que se trata de un código muy simple. Únicamente es necesario extender de la clase StdConverter indicando como tipo de parámetros la clase de entrada y la de salida, en este caso indicamos que se va a convertir una String en la clase Reference.

Por último, debemos indicar a Spring que se utilice este conversor para mapear las instancias de la clase Reference, incluyendo en la propia clase la correspondiente anotación:

import com.fasterxml.jackson.databind.annotation.JsonDeserialize;

@JsonDeserialize(converter = ReferenceConverter.class) // <- Indicamos a Spring que use el converter correspondiente
public record Reference(String value) {...}

Ahora Spring será capaz de utilizar nuestro conversor cuando intente mapear propiedades de tipos distintos a los primitivos/wrappers o las clases para las que ya cuenta con conversores.

Utilizar varios archivos de configuración en Spring

Ciro — Mon, 31 Oct 2022 08:00:00 +0000

En anteriores publicaciones vimos cómo agrupar parámetros de configuración mediante el uso de la anotación @ConfigurationProperties con el elemento prefix, así como definir la ruta hasta un archivo de configuración, pero en ocasiones un único archivo de propiedades puede extenderse demasiado por lo que es más conveniente separarlo en varios ficheros.

Podemos por ejemplo organizar los archivos de configuración de la siguiente manera:

// file: resources/admin_cfg.yml
name: "John"

// file: resources/user_cfg.yml
user.firstname: "Ben"
user.lastname: "Stuart"

Ahora podemos crear sus clases de configuración, e indicar la ruta de los archivos utilizando la anotación @PropertySource

@Configuration
@ConfigurationProperties
@PropertySource("classpath:admin_cfg.yml") // <- Indicamos la ruta
data class AdminConfig(
    var name: String = "",
)

@Configuration
@ConfigurationProperties(prefix = "user") // <- Indicamos el prefijo (si fuera necesario)
@PropertySource("classpath:user_cfg.yml") // <- Indicamos la ruta
data class UserConfig(
    var firstname: String = "",
    var lastname: String = "",
)

El acceso a estas propiedades se realiza instanciando la clase de configuración que deseemos, y llamando a la propiedad que nos interese:

@Service
class UsersService(
    val config: UserConfig,
) {
    fun getFullName(): String = "${config.lastname}, ${config.firstname}"
}

Fuente: 24.8 Type-safe Configuration Properties @ Spring Boot Reference Guide

Cómo definir la ruta de un archivo de configuración en Spring

Ciro — Thu, 27 Oct 2022 07:00:00 +0000

Por defecto, Spring busca en la carpeta de resources los archivos de configuración application.properties o application.yml, pero en caso de que queramos indicar la ruta a otros archivos de configuración podemos utilizar la anotación @PropertySource.

En la publicación anterior creamos clases que contenían propiedades de configuración, pero estas propiedades estaban declaradas en el archivo por defecto application.yml

Si queremos definir la ruta hasta un archivo de configuración .yml como el de este ejemplo:

// file: example_cfg.yml
example:
    path: "example path value"
    enabled: true
    port: 1234

Debemos incluir la anotación @PropertySource de la siguiente manera:

@Configuration
@ConfigurationProperties(prefix = "example")
@PropertySource("classpath:example_cfg.yml) // <- Indicamos la ruta hasta el archivo
data class ExampleConfig(
    val path: String,
    val enabled: Boolean,
    val port: Integer,
)

De esta manera Spring nos permite acceder a propiedades declaradas en ficheros .yml

Fuente: 24.7.4 YAML Shortcomings @ Spring Boot Reference Guide