DEV Community: Agustín Ventura Carrasco

Configuration Properties con Spring Boot

Agustín Ventura Carrasco — Fri, 23 Feb 2024 17:19:22 +0000

En artículos anteriores usábamos propiedades de configuración para pasar distintos parámetros a nuestra aplicación, haciendo algo de memoria, teníamos un secrets.properties en src/main/resources (junto con application.properties) con este contenido:

song-server.base.url=http://localhost:3000
song-server.api-key=mytoken

Y lo importábamos en application.properties:

spring.config.import=secrets.properties
spring.main.web-application-type=none
logging.level.org.springframework.web=TRACE

Eso nos permitía usar esas propiedades (las que empiezan por song-server) en nuestra aplicación, por ejemplo, a través de la anotación @value:

@Bean
public Map<String, String> headers(@Value("${song-server.api-key}") String apiKey) {
  return Map.of(
      HttpHeaders.CONTENT_TYPE, APPLICATION_JSON,
      HttpHeaders.AUTHORIZATION, "Bearer " + apiKey
  );
}

Esto es muy cómodo y ya hemos visto que nos permite incluso sobreescribir el valor pasándolo como variable de entorno. Además, @Value nos permite especificar valores por defecto y otra serie de funciones avanzadas que son muy útiles.

El problema que podemos tener por tanto, no depende de la funcionalidad en sí, sino del uso que hagamos de la misma, en concreto, este uso puede dar lugar a tener nuestro código trufado de anotaciones @Value en multitud de sitios, con el incordio que resulta para el mantenimiento de la aplicación. Lo idóneo sería tener una especie de diccionario central donde tengamos concentradas todas nuestras propiedades.

Pues esto, como no, existe y se llama ConfigurationProperties y por supuesto, tiene ventajas adicionales.

Usando ConfigurationProperties para centralizar nuestra configuración

Vamos a seguir con el ejemplo y vamos a centralizar todas las propiedades de song-server en un record que se llamará SongServerConfigurationProperties y sería tal que así:

@ConfigurationProperties(prefix = "song-server")
public record SongServerConfigurationProperties (String baseUrl, String apiKey) {

}

Esto significa que va a leer todas las propiedades que empiecen por song-server y las va a cargar en las variables definidas. Spring automáticamente interpola los nombres (esto se llama relaxed binding) y las asigna, es decir, va a leer tanto song-server.baseUrl como song-server.base-url, le sirve cualquiera de estas definiciones.

Una vez creado este record, hay que habilitarlo mediante la anotación @EnableConfigurationProperties justo donde tenemos nuestra anotación @SpringBootApplication (o cualquier otra clase anotada con @Configuration) y podemos quitar las anotaciones @Value:

@SpringBootApplication
@EnableConfigurationProperties(SongServerConfigurationProperties.class)
public class PlayListHistoryApplication {

  ...

  @Bean
  public RestClient restClient(SongServerConfigurationProperties songServerConfigurationProperties) {
    return RestClient.builder()
        .baseUrl(songServerConfigurationProperties.baseUrl())
        .defaultHeader(HttpHeaders.ACCEPT, APPLICATION_JSON)
        .defaultStatusHandler(
            HttpStatusCode::isError,
            (request, response) ->
                logger.error("Response error [code={}, body={}]", response.getStatusCode(), new String(response.getBody().readAllBytes()))
        )
        .build();
  }

  @Bean
  public Map<String, String> headers(SongServerConfigurationProperties songServerConfigurationProperties) {
    return Map.of(
        HttpHeaders.CONTENT_TYPE, APPLICATION_JSON,
        HttpHeaders.AUTHORIZATION, "Bearer " + songServerConfigurationProperties.baseUrl()
    );
  }
  ...
}

Y podemos probar a arrancar para obtener un error feísimo y sin sentido:

java.lang.IllegalArgumentException: URI with undefined scheme

¿Qué está pasando aquí? Que el error sea relativo a la URI nos indica que es algo relacionado con el bean restClient, ¿por qué se queja de la URI? Precisamente hemos modificado la construcción de ese bean para eliminar @Value y usar nuestro record de configuración. Si ponemos un breakpoint y observamos nuestro record, podemos ver el error.

Podemos ver que apiKey tiene valor, pero baseUrl esta a null, lo cual termina produciendo el error que vemos ya que no puede crear una URI con null como baseUrl, pero, ¿por qué pasa esto? Si miramos nuestro secrets.properties, podemos ver que mientras que la propiedad apiKey esta definida en kebab case, baseUrl esta definido separado por un . (es decir, base.url). Esto hace que Spring no pueda reconocer la propiedad porque el . se utiliza para separar jerárquicamente las propiedades, es decir, si quisiéramos, podríamos tener otro ConfigurationProperties con prefix "song-server.base" y ahí si definiríamos la propiedad url y la leería. Como tampoco es lo que queremos sino que es un error, lo cambiamos en secrets.properties:

song-server.base-url=http://localhost:3000
song-server.api-key=mytoken

Si volvemos a lanzar la aplicación, magia, funciona, sin haber tenido que tocar ninguna anotación @Value ni hacer ningún tipo de modificación (y en caso de hacerla hubiera sido solo en nuestro record).

¿Qué os parece? El código, ya sabéis, en GitHub.

Secretos en desarrollo local con Spring Boot

Agustín Ventura Carrasco — Tue, 13 Feb 2024 19:29:25 +0000

Cuando trabajamos con recursos externos a nuestra aplicación (bases de datos, APIs con algún tipo de autenticación, etc...) es bastante habitual tener algún elemento como un nombre de usuario y contraseña o un token que no queremos publicar junto con el código de nuestra aplicación.
Por ejemplo, en el artículo de Headers y HTTP Interface usábamos un API key en la cabecera para acceder al servidor.

Esta API key en nuestro ejemplo esta en el application.properties:

spring.main.web-application-type=none
logging.level.org.springframework.web=TRACE
song-server.base.url=http://localhost:3000
song-server.api-key=mytoken

Y como tal se puede filtrar (y se ha filtrado a GitHub). Aquí dá igual porque es un dato de prueba que no sirve para nada, pero queda claro el riesgo de que filtremos inadvertidamente datos privados como URLs de servidores y tokens, usuarios o contraseñas (secretos en general).

Otro de los problemas es que esos datos serán distintos según el entorno de ejecución, es decir, mytoken será válido para nuestro servidor de desarrollo, pero lógicamente en producción será otro dato (que incluso podemos recuperar en tiempo de ejecución de algo como Vault o AWS Secrets Manager).

Tenemos entonces dos problemas:

Como evitar filtrar secretos.
Como utilizar distintos secretos según el entorno.

Como evitar filtrar secretos

La solución estandarizada en otros lenguajes y frameworks es utilizar archivos .env como en JavaScript y Node.

Desde Spring Boot 2.4 tenemos una utilidad no muy conocida como es Spring Config Import que, hay que admitirlo, no tiene un nombre tan molón como archivos .env pero hace exactamente lo mismo.

Siguiendo con el ejemplo, vamos a llevarnos las propiedades de configuración de song server (song-server.base.url y song-server.api-key) a un archivo aparte llamado secrets.properties.

Creamos secrets.properties en src/main/resources (junto con application.properties):

song-server.base.url=http://localhost:3000
song-server.api-key=mytoken

Y lo importamos en application.properties:

spring.config.import=secrets.properties
spring.main.web-application-type=none
logging.level.org.springframework.web=TRACE

Y ahora, lo más importante, lo añadimos añadimos a .gitignore:

**/secrets.properties

Como utilizar distintos secretos según el entorno

Con esto ya tenemos el archivo secrets.properties únicamente en local por lo que si construimos el jar de la aplicación en un entorno de CI/CD este jar no contendrá el archivo secrets.properties. Podemos simular esto generando nuestro jar con:

./gradlew clean bootJar

Y una vez creado el jar en /build/libs, lo podemos abrir con un gestor de archivos zip y borrar el secrets.properties. Con esto, podemos probar a arrancarlo:

java -jar playlisthistory-0.0.1-SNAPSHOT.jar

Nos encontraremos con un fallo similar a éste:

13:28:54.667 [main] ERROR org.springframework.boot.diagnostics.LoggingFailureAnalysisReporter -- 

***************************
APPLICATION FAILED TO START
***************************

Description:

Config data resource 'class path resource [secrets.properties]' via location 'secrets.properties' does not exist

Esto tiene todo el sentido, Spring entiende que el archivo secrets.properties es obligatorio y por tanto se niega a arrancar si no se lo proporcionamos, así que lo primero es marcarlo como optional en la importación en application.properties:

spring.config.import=optional:secrets.properties
spring.main.web-application-type=none
logging.level.org.springframework.web=TRACE

Una vez marcado como optional, si intentamos arrancar la aplicación, veremos algo así:

2024-02-11T13:40:57.637+01:00  INFO 63006 --- [           main] d.a.p.PlayListHistoryApplication         : Starting PlayListHistoryApplication using Java 21.0.2 with PID 63006 (/home/vagustin/Development/Projects/Personal/playlisthistory/build/libs/playlisthistory-0.0.1-SNAPSHOT.jar started by vagustin in /home/vagustin/Development/Projects/Personal/playlisthistory/build/libs)
2024-02-11T13:40:57.641+01:00  INFO 63006 --- [           main] d.a.p.PlayListHistoryApplication         : No active profile set, falling back to 1 default profile: "default"
2024-02-11T13:40:58.179+01:00  WARN 63006 --- [           main] s.c.a.AnnotationConfigApplicationContext : Exception encountered during context initialization - cancelling refresh attempt: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'restClient' defined in dev.agustinventura.playlisthistory.PlayListHistoryApplication: Unexpected exception during bean creation
2024-02-11T13:40:58.187+01:00  INFO 63006 --- [           main] .s.b.a.l.ConditionEvaluationReportLogger : 

Error starting ApplicationContext. To display the condition evaluation report re-run your application with 'debug' enabled.
2024-02-11T13:40:58.205+01:00 ERROR 63006 --- [           main] o.s.boot.SpringApplication               : Application run failed
...
Caused by: java.lang.IllegalArgumentException: Could not resolve placeholder 'song-server.base.url' in value "${song-server.base.url}"

Es decir, la aplicación arranca pero falla porque no encuentra el valor para song-server.base.url (ni para song-server.api-key, claro). Una de las mejores cosas de Spring es que nos permite especificar propiedades de configuración como parámetros, así que podemos lanzar la aplicación:

java -jar -Dsong-server.base.url=http://localhost:3000 -Dsong-server.api-key playlisthistory-0.0.1-SNAPSHOT.jar

Y ya funcionaría, así que podríamos incluir estos parámetros dentro de nuestro shell script que lanza la aplicación/Docker/Kubernetes o la tecnología que utilicemos. Esto siempre y cuando sean secretos estáticos o que podamos inyectar a través del entorno, si quisiéramos hacer una resolución dinámica, podríamos optar por utilizar perfiles y tener uno de dev que los resuelva estáticamente con el secrets.properties y otro de prod que cree un bean que ya en tiempo de ejecución vea cómo tiene que resolverlo. Algo más complejo, pero entra dentro de lo normal.

Y por supuesto, tienes el código en GitHub.

Headers y Spring Boot HTTP Interface

Agustín Ventura Carrasco — Sun, 11 Feb 2024 11:48:34 +0000

Siguiendo con la serie de clientes REST con Spring, queda por cubrir un caso de uso muy frecuente, ¿cómo envío cabeceras?

Si comparamos las dos soluciones que hemos visto hasta ahora, cuando usábamos RestClient, si que enviábamos la cabecera Accept al hacer peticiones GET y cuando hacíamos la petición POST, enviamos también la cabecera Content-Type. Sin embargo al usar HTTP Interface, no lo hemos utilizado y hemos confiado en que enviamos y recibimos siempre JSON. Eso incluso nos dá cierto problema que ya hemos visto al tratar los errores en el HTTP Interface, siendo necesario eliminar el contenido del buffer de entrada si recibimos una respuesta errónea (como un 404), ya que ahí estaríamos recibiendo texto en vez de JSON y falla el parseador de JSON.

Para hacer un ejemplo algo más interesante, imaginemos que tenemos una API con parte pública (como todos los GET) y parte privada (como los POST), así que queremos hacer dos cosas:

Enviar en todas las peticiones la cabecera ACCEPT con JSON como el tipo aceptado.
Enviar en las peticiones POST únicamente la cabecera Authorization con un determinado Bearer token así como la cabecera Content-type.

Todo ésto usando HTTP Interface, claro, ya que con RestClient sería modificar los métodos oportunos.

Enviando una cabecera en todas las peticiones

Esta precisamente puede ser la parte más sencilla, de la misma manera que al crear el RestClient que da soporte al HTTP Interface definimos un status handler por defecto, podemos asignar una cabecera a todas las peticiones:

private static final String APPLICATION_JSON = MediaType.APPLICATION_JSON.getType() + "/" + MediaType.APPLICATION_JSON.getSubtype();

@Bean
public RestClient restClient(@Value("${song-server.base.url}") String baseUrl) {
  return RestClient.builder()
      .baseUrl(baseUrl)
      .defaultHeader(HttpHeaders.ACCEPT, APPLICATION_JSON)
      .defaultStatusHandler(
          HttpStatusCode::isError,
          (request, response) ->
              logger.error("Response error [code={}, body={}]", response.getStatusCode(), new String(response.getBody().readAllBytes()))
      )
      .build();
}

Listo, por defecto siempre vamos a enviar la cabecera ACCEPT con el tipo application/json (hace falta esa constante porque defaultHeader toma como parámetros dos String).

Enviando cabeceras en las peticiones POST

Adjuntar cabeceras a las peticiones POST es muy sencillo (como vamos a ver ahora), sin embargo tiene su miga arquitecturalmente hablando. Vamos a empezar a la TDD por la solución más sencilla posible y analizaremos problemas y posibles errores.
Para enviar cabeceras con un único método, es tan sencillo como añadir un nuevo parámetro al método que hace el POST, anotándolo con @RequestHeaders:

public interface SongsLocalRepository extends LoadLastPlayedPort, SaveLastPlayedPort {

  @Override
  @GetExchange("/items")
  List<PlayListHistoryItem> loadLastPlayedSongs();

  @Override
  @GetExchange("/items/{id}")
  Optional<PlayListHistoryItem> loadPlayedSong(@PathVariable String id);

  @Override
  @PostExchange("/items")
  PlayListHistoryItem save(@RequestHeader Map<String, String> headers, @RequestBody PlayListHistoryItem item);
}

Esto hace que se nos rompa nuestro puerto de guardado, pero de momento lo podemos modificar rápidamente:

public interface SaveLastPlayedPort {

  PlayListHistoryItem save (Map<String, String> headers, PlayListHistoryItem item);
}

Y ahora desde el sitio de uso del puerto, podemos pasar las cabeceras que queramos:

@Bean
  ApplicationRunner appStarted(LoadLastPlayedPort loadLastPlayedPort, SaveLastPlayedPort saveLastPlayedPort,
      @Value("${song-server.api-key}") String apiKey) {
    return args -> {
      List<PlayListHistoryItem> lastPlayedSongs = loadLastPlayedPort.loadLastPlayedSongs();
      Optional<PlayListHistoryItem> notValidSong = loadLastPlayedPort.loadPlayedSong("foo");
      Optional<PlayListHistoryItem> playedSong = loadLastPlayedPort.loadPlayedSong(lastPlayedSongs.getFirst().id());
      PlayListHistoryItem newPlayedSong = PlayListHistoryItemBuilder.aPlayListHistoryItem().withId("SANsVA4ihQplEQIf0GZea3").withPlayedAt(
          LocalDateTime.now()).withTrack(playedSong.get().track()).build();
      saveLastPlayedPort.save(
          Map.of(HttpHeaders.CONTENT_TYPE, APPLICATION_JSON, HttpHeaders.AUTHORIZATION, "Bearer " + apiKey),
          newPlayedSong);
    };
  }

Aquí, para darle algo de realismo, inyectamos un api token y cuando invocamos al puerto para salvar la reproducción, le pasamos el content-type y el authorization.

Ahora si arrancamos con el log puesto a TRACE veremos algo así:

TRACE 4167793 --- [           main] o.s.w.s.i.RequestHeaderArgumentResolver  : Resolved request header value 'Content-Type:application/json'
TRACE 4167793 --- [           main] o.s.w.s.i.RequestHeaderArgumentResolver  : Resolved request header value 'Authorization:Bearer mytoken'

Pues ya estaría, ¿no? Un momento, ¿no dijimos arriba que había problemas arquitecturales? Efectivamente, aquí estamos introduciendo en nuestro SaveLastPlayedPort una dependencia con el mecanismo concreto de persistencia, el parámetro headers.
Visto de otra manera, nuestro puerto pertenece a la aplicación, expresa la funcionalidad de guardar una reproducción de una canción, sin importar dónde, podría ser una llamada REST como en este caso o insertar en una base de datos o guardar en un archivo. Si estuviéramos guardando en un archivo, ¿añadiríamos un parámetro con la ruta del archivo? Poder, podemos, pero introduce una fragilidad innecesaria además de emborronar los conceptos.

¿Qué podemos hacer entonces? La solución a un acoplamiento suele ser introducir otra capa de indirección. En este caso tenemos dos partes, un puerto que solo establece el contrato de como guardar las reproducciones y una interfaz que establece la comunicación REST, ¿qué necesitamos? Un adaptador que coordine como es esa comunicación.

Vale, ya sabemos que necesitamos introducir una nueva pieza de software, hacemos una lista de las cosas que queremos que haga este adaptador:

Para cargar todas las reproducciones, invocará el método loadLastPlayedSongs de SongsLocalRepository
Para cargar una canción en concreto, invocará el método loadLastPlayedSong de SongsLocalRepository
Para guardar una reproducción, invocará el método save de SongsLocalRepository, pasando las cabeceras oportunas.

Lo podríamos haber definido por comportamiento (es decir, para tal entrada quiero obtener tal salida), pero en este caso no queremos comprobar las entradas/salidas que al fin y al cabo ya sabemos cuales son sino las interacciones con el repositorio.

Podríamos escribir algo así:

@Test
void givenNoIdShouldInvokeLoadLastPlayedSongs() {
  restSongsAdapter.loadLastPlayedSongs();

  verify(songsLocalRepository, times(1)).getAll();
}

@Test
void givenAnIdShouldInvokeLoadLastPlayedSong() {
  String songId = "testSongId";

  restSongsAdapter.loadPlayedSong(songId);

  verify(songsLocalRepository, times(1)).getWithId(songId);
}

@Test
void givenAPlaylistHistoryItemShouldInvokeSaveWithHeaders() {
  PlayListHistoryItem playedSong = PlayListHistoryItemsMother.getRecentlyPlayed();

  restSongsAdapter.save(playedSong);

  verify(songsLocalRepository, times(1)).post(headers, playedSong);
}

Esto nos permite hacer un par de cambios importantes, el primero es que nuestra interfaz SongsLocalRepository ya no tiene por qué extender los puertos, ahora la implementación de los puertos de salida es el adaptador, por lo que la interfaz quedaría así:

public interface SongsLocalRepository {

@GetExchange("/items")
List<PlayListHistoryItem> getAll();

@GetExchange("/items/{id}")
Optional<PlayListHistoryItem> getWithId(@PathVariable String id);

@PostExchange("/items")
PlayListHistoryItem post(@RequestHeader Map<String, String> headers, @RequestBody PlayListHistoryItem item);
}

Hemos cambiado los nombres de los métodos para que estén más relacionados con HTTP y REST ya que ahora será el adaptador el que haga la conversión de conceptos de negocio a llamadas concretas. Creo que así la interfaz queda más expresiva.

La implementación concreta sería así:

public class RestSongsAdapter implements LoadLastPlayedPort, SaveLastPlayedPort {

  private final Map<String, String> headers;

  private final SongsLocalRepository songsLocalRepository;

  public RestSongsAdapter(Map<String, String> headers, SongsLocalRepository songsLocalRepository) {
    this.headers = headers;
    this.songsLocalRepository = songsLocalRepository;
  }

  @Override
  public List<PlayListHistoryItem> loadLastPlayedSongs() {
    return songsLocalRepository.getAll();
  }

  @Override
  public Optional<PlayListHistoryItem> loadPlayedSong(String id) {
    return songsLocalRepository.getWithId(id);
  }

  @Override
  public PlayListHistoryItem save(PlayListHistoryItem item) {
    return songsLocalRepository.post(headers, item);
  }
}

Inyectamos las cabeceras que enviaremos y el repositorio e implementamos los métodos de los puertos llamando al repositorio. En este ejemplo es muy sencillo, pero este adaptador puede llegar a ser importantísimo ya que puede tener varias funciones:

Validar los parámetros que se enviarán al repositorio, como el item del post o el id para el get.
Mapear entre el modelo REST y nuestro modelo de negocio. Si tuviéramos un modelo rico con funcionalidad, este sería el punto en el que convertiríamos de los DTOs usados para comunicarnos con REST (y con anotaciones propias de Jackson, por ejemplo) a nuestro modelo de negocio.
Este mismo mapeo nos indica que es el punto de hacer operaciones más sofisticadas si las necesitamos, por ejemplo, nuestra entidad de dominio puede estar construida a partir de varios DTOs, incluso de DTOs con distintas tecnologías, como pueden ser provenientes de una base de datos y una API REST. Aquí es donde realizar las distintas llamadas para obtener/persistir. Esto también nos permite implementar lo que en términos de DDD se conoce como una capa de anticorrupción para asegurar no solo que los datos que enviamos son correctos, si no que los que recibimos se ajustan a nuestras restricciones de dominio.

Con estos cambios, tendríamos que actualizar también la aplicación y la podríamos ejecutar:

@SpringBootApplication
public class PlayListHistoryApplication {

  private static final Logger logger = LoggerFactory.getLogger(PlayListHistoryApplication.class);

  public static void main(String[] args) {
    SpringApplication.run(PlayListHistoryApplication.class, args);
  }

  private static final String APPLICATION_JSON = MediaType.APPLICATION_JSON.getType() + "/" + MediaType.APPLICATION_JSON.getSubtype();

  @Bean
  public RestClient restClient(@Value("${song-server.base.url}") String baseUrl) {
    return RestClient.builder()
        .baseUrl(baseUrl)
        .defaultHeader(HttpHeaders.ACCEPT, APPLICATION_JSON)
        .defaultStatusHandler(
            HttpStatusCode::isError,
            (request, response) ->
                logger.error("Response error [code={}, body={}]", response.getStatusCode(), new String(response.getBody().readAllBytes()))
        )
        .build();
  }

  @Bean
  public Map<String, String> headers(@Value("${song-server.api-key}") String apiKey) {
    return Map.of(
        HttpHeaders.CONTENT_TYPE, APPLICATION_JSON,
        HttpHeaders.AUTHORIZATION, "Bearer " + apiKey
    );
  }

  @Bean
  public SongsLocalRepository songsLocalRepository(RestClient restClient) {
    RestClientAdapter adapter = RestClientAdapter.create(restClient);
    HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(adapter).build();
    return factory.createClient(SongsLocalRepository.class);
  }

  @Bean
  public LoadLastPlayedPort loadLastPlayedPort(Map<String, String> headers, SongsLocalRepository songsLocalRepository) {
    return new RestSongsAdapter(headers, songsLocalRepository);
  }

  @Bean
  public SaveLastPlayedPort saveLastPlayedPort(Map<String, String> headers, SongsLocalRepository songsLocalRepository) {
    return new RestSongsAdapter(headers, songsLocalRepository);
  }

  @Bean
  ApplicationRunner appStarted(LoadLastPlayedPort loadLastPlayedPort, SaveLastPlayedPort saveLastPlayedPort) {
    return args -> {
      List<PlayListHistoryItem> lastPlayedSongs = loadLastPlayedPort.loadLastPlayedSongs();
      Optional<PlayListHistoryItem> notValidSong = loadLastPlayedPort.loadPlayedSong("foo");
      Optional<PlayListHistoryItem> playedSong = loadLastPlayedPort.loadPlayedSong(lastPlayedSongs.getFirst().id());
      PlayListHistoryItem newPlayedSong = PlayListHistoryItemBuilder.aPlayListHistoryItem().withId("SANsVA4ihQplEQIf0GZea3").withPlayedAt(
          LocalDateTime.now()).withTrack(playedSong.get().track()).build();
      saveLastPlayedPort.save(newPlayedSong);
    };
  }
}

Hemos pasado de tener un cliente REST y dos HTTP interface (necesarias por las dos implementaciones de los puertos) a tener un cliente REST, un HTTP interface y dos instancias del adaptador. También creamos el mapa con las cabeceras para inyectar en los adaptadores las cabeceras y es en ese mapa donde inyectamos nuestra API key.

De esta manera conseguimos aislar conceptos, nuestro dominio (representado por los puertos) no conoce nada de la tecnología subyacente (como eran las cabeceras que necesitábamos antes) y es el adaptador el que se encarga de unir (adaptar entre sí) los dos conceptos: nuestro modelo de dominio (en lo tocante a los puertos) y REST.

Sigues teniendo el código en GitHub

Usando Spring Boot HTTP Interface

Agustín Ventura Carrasco — Mon, 05 Feb 2024 09:42:56 +0000

Este artículo es una continuación del anterior, en el que usábamos RestClient para acceder a una API REST. Si no lo has leído, repásalo porque vamos a usar la misma API de reproducción de canciones para nuestro ejemplo.

Como resumen rápido, en el artículo anterior teníamos esta API de canciones que hemos reproducido recientemente y usábamos el nuevo RestClient para acceder a ella y hacer algunas operaciones básicas, como traerlas todas, buscar una por su id o crear una nueva reproducción.

Hasta aquí, todo bien, ¿cuál es el problema? Pues que en realidad, para hacer una operación relativamente sencilla, tenemos mucho código, ¿no? Si repasamos el código final del repositorio:

public class SongsLocalRepository implements LoadLastPlayedPort, SaveLastPlayedPort {

  private static final String LAST_PLAYED_SONGS_COLLECTION = "/items";

  private final RestClient restClient;

  public SongsLocalRepository(RestClient restClient) {
    this.restClient = restClient;
  }

  @Override
  public List<PlayListHistoryItem> loadLastPlayedSongs() {
    return restClient
        .get()
        .uri(LAST_PLAYED_SONGS_COLLECTION)
        .accept(MediaType.APPLICATION_JSON)
        .retrieve()
        .body(new ParameterizedTypeReference<List<PlayListHistoryItem>>() {});
  }

  @Override
  public Optional<PlayListHistoryItem> loadPlayedSong(String id) {
    try {
      PlayListHistoryItem playedSong = restClient
          .get()
          .uri(LAST_PLAYED_SONGS_COLLECTION + "/{id}", id)
          .accept(MediaType.APPLICATION_JSON)
          .retrieve()
          .onStatus(HttpStatusCode::is4xxClientError, (request, response) -> {
            throw new IllegalArgumentException();
          })
          .body(PlayListHistoryItem.class);
        return Optional.ofNullable(playedSong);
    } catch (IllegalArgumentException iae) {
      return Optional.empty();
    }
  }

  @Override
  public PlayListHistoryItem save(PlayListHistoryItem item) {
    if (item == null) {
      throw new IllegalArgumentException("Stored song can't be null");
    }
    return restClient
        .post()
        .uri(LAST_PLAYED_SONGS_COLLECTION)
        .contentType(MediaType.APPLICATION_JSON)
        .accept(MediaType.APPLICATION_JSON)
        .body(item)
        .retrieve()
        .body(PlayListHistoryItem.class);
  }
}

Vemos que el uso que hacemos es bastante similar en todos los casos, cambiando alguna particularidad como el tratamiento de errores en el load o la doble llamada a body en el caso del save.

Cabe preguntar entonces, ¿no hay una manera más sencilla de implementar ésto? Pues sí y existe de hace años, Feign. Básicamente, Feign nos permite definir una interfaz que contendrá nuestros puntos de llamada HTTP y en tiempo de ejecución inyectar la implementación que hará estas llamadas, esto no solo tiene la ventaja de simplificar el código sino que además nos permite poder cambiar fácilmente el cliente que usamos.

En nuestro ejemplo, con Spring, podríamos cambiar de RestTemplate a RestClient sin tocar otro punto que la construcción del cliente de Feign. Además de ésto Feign tiene muchas más funcionalidades, pero si queremos solamente un uso básico, aquí vienen las buenas noticias... desde Spring 6 no necesitamos añadir Feign si no que podemos utilizar HTTP Interfaces.

Usando HTTP Interface

Como dice el nombre, usar HTTP Interface es tan sencillo como crear una interfaz y añadirle unas anotaciones (como las que usamos en Spring MVC para definir los resources), vamos a migrar nuestro repositorio a esta interfaz:

public interface SongsLocalRepository extends LoadLastPlayedPort, SaveLastPlayedPort {

  @Override
  @GetExchange("/items")
  List<PlayListHistoryItem> loadLastPlayedSongs();

  @Override
  @GetExchange("/items/{id}")
  Optional<PlayListHistoryItem> loadPlayedSong(@PathVariable String id);

  @Override
  @PostExchange("/items")
  PlayListHistoryItem save(@RequestBody PlayListHistoryItem item);
}

Y listo, con apenas 11 líneas tenemos lo mismo que teníamos antes, pero es que además, al estar utilizando un componente propio de Spring, nos podemos evitar las pruebas unitarias (es más, no podemos hacer pruebas unitarias porque realmente no tenemos implementación). Si podría tener sentido en un contexto más amplio tener pruebas de integración, pero en nuestra prueba no es necesario.

Como podemos ver, todas las anotaciones son muy parecidas a las que usaríamos si estuviéramos haciendo un servidor con Spring MVC y no un cliente. En concreto el uso de @PathVariable (o @RequestParam) y @RequestBody son exactamente iguales.

Como último paso, tenemos que proveer el cliente concreto, esto lo hacemos en la clase de la aplicación, donde creamos los beans de Spring oportunos:

@SpringBootApplication
public class PlayListHistoryApplication {

  private static final Logger logger = LoggerFactory.getLogger(PlayListHistoryApplication.class);

  public static void main(String[] args) {
    SpringApplication.run(PlayListHistoryApplication.class, args);
  }

  @Bean
  public RestClient restClient(@Value("${song-server.base.url}") String baseUrl) {
    return RestClient.builder()
        .baseUrl(baseUrl)
        .defaultStatusHandler(
            HttpStatusCode::isError,
            (request, response) ->
              logger.error("Response error [code={}, body={}]", response.getStatusCode(), new String(response.getBody().readAllBytes()))
            )
        .build();
  }

  @Bean
  public LoadLastPlayedPort loadLastPlayedPort(RestClient restClient) {
    RestClientAdapter adapter = RestClientAdapter.create(restClient);
    HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(adapter).build();
    return factory.createClient(SongsLocalRepository.class);
  }

  @Bean
  public SaveLastPlayedPort saveLastPlayedPort(RestClient restClient) {
    RestClientAdapter adapter = RestClientAdapter.create(restClient);
    HttpServiceProxyFactory factory = HttpServiceProxyFactory.builderFor(adapter).build();
    return factory.createClient(SongsLocalRepository.class);
  }

  @Bean
  ApplicationRunner appStarted(LoadLastPlayedPort loadLastPlayedPort, SaveLastPlayedPort saveLastPlayedPort) {
    return args -> {
      List<PlayListHistoryItem> lastPlayedSongs = loadLastPlayedPort.loadLastPlayedSongs();
      Optional<PlayListHistoryItem> notValidSong = loadLastPlayedPort.loadPlayedSong("foo");
      Optional<PlayListHistoryItem> playedSong = loadLastPlayedPort.loadPlayedSong(lastPlayedSongs.getFirst().id());
      PlayListHistoryItem newPlayedSong = PlayListHistoryItemBuilder.aPlayListHistoryItem().withId("SANsVA4ihQplEQIf0GZea3").withPlayedAt(
          LocalDateTime.now()).withTrack(playedSong.get().track()).build();
      saveLastPlayedPort.save(newPlayedSong);
    };
  }
}

Aquí si tenemos algo más de complicación. Para crear los puertos ya no instanciamos directamente el repositorio (no podemos, ya que es una interfaz), sino que utilizando un adaptador para nuestro RestClient (podríamos estar usando también WebClient o RestTemplate) y una factoría devolvemos el cliente.

La configuración de RestClient si es más interesante. Ahora podemos hacer un tratamiento de errores genérico, en vez de tenerlo que hacer en todos los métoodos que lo usan. Por ejemplo, aquí se ha optado simplemente por logar el error en la consola y seguir ejecutando, pero tendría sentido dividirlo en dos:

Si es un error de cliente, devolver Optional.empty
Si es un error de servidor, lanzar una excepción propia

Esto lo podemos conseguir si en el defaultStatusHandler utilizamos is4xxClientError y is5xxServerError, pero para el ejemplo nos quedamos con ésto.

Importante: Si queremos que devuelva correctamente Optional.empty en caso de un 404, tenemos que invocar necesariamente response.getBody().readAllBytes(), ya que esto consume el contenido del response, dejándolo vacío. Si no hacemos ésto, tratará de mapear el contenido de response a un objeto (PlayListHistoryItem en este caso), pero el contenido será de tipo text/plain en vez de JSON y fallará.

Como en el anterior, tienes el código en GitHub

Usando Spring Boot RestClient

Agustín Ventura Carrasco — Tue, 30 Jan 2024 10:22:49 +0000

El consumo de una API REST es un caso muy habitual cuando trabajamos en una arquitectura de microservicios, y es casi que la opción por defecto para el tráfico entre los distintos microservicios (aunque si es por eficiencia, deberíamos usarlo solo para tráfico norte-sur y optar por otras opciones más eficientes como gRPC para el tráfico este-oeste).
Normalmente, en el mundo de Spring usamos por defecto dos opciones:

Si estamos usando el stack bloqueante (web) RestTemplate.
Si usamos el stack reactivo (webflux) WebClient.

Los años de RestTemplate (13) se notan si hemos usado WebClient, ya que tiene una API mucho más concisa y fluida, más elegante. La contraprestación es que está diseñado para trabajar con Spring WebFlux y por tanto usa los tipos de datos reactivos Flux y Mono, por lo que si tu aplicación sigue un modelo bloqueante, vas a trufar todos los usos de WebClient con bloqueos para obtener los resultados y conversiones de Mono a tipos concretos o de Flux a colecciones.

Sin embargo, ninguna de las dos opciones es la más moderna a la hora de trabajar con APIs REST. En Spring 6.0 y Spring 6.1 se han introducido nuevos clientes que podemos utilizar.
Si estamos usando el stack bloqueante, podemos usar desde Spring 6.1 el nuevo RestClient, que no es más que la API de WebClient sobre RestTemplate, por lo que tenemos todas las ventajas de esta API sin los inconvenientes derivados del stack reactivo que comentábamos arriba.

Pero además, desde Spring 6 podemos usar una interfaz HTTP tanto sobre RestTemplate, RestClient y WebClient que nos permite anotar interfaces con métodos @HttpExchange y derivar en Spring toda la gestión del cliente concreto. Para entendernos, haríamos algo parecido a lo que hacemos cuando definimos un RestController pero para un cliente.

En este artículo vamos a ver como usar RestClient y en uno posterior veremos como podemos cambiar el código para usar el HTTP Interface.

La API

Vamos a montar una API de ejemplo que nos va a permitir acceder y guardar las últimas canciones que hemos reproducido en nuestro cliente multimedia favorito:



{
    "items": [
        {
            "id": "RBnhX0DJw5HGmYIwjriPMu",
        "track": {
                "album": {
                    "id": "6tKQyT3LHSMOsObqfk264N",
                    "name": "Femme Fatale"
                },
                "artists": [
                    {
                        "id": "2wJ4vsxWd7df7dRU4KcoDe",
                        "name": "Sharon Van Etten"
                    }
                ],
                "id": "2HDycU1sqxlfYQloriXcK1",
                "name": "Femme Fatale"
            },
            "played_at": "2024-01-23T13:07:21.657Z"
        },
        {
        "id": "LS0vdfbKzKwWFXhlS3SsDu",
            "track": {
                "album": {
                    "id": "3QoFSi0dH7mXm3ajgX51Si",
                    "name": "Cosy Karaoke, Vol. 1"
                },
                "artists": [
                    {
                        "id": "0Ak6DLKHtpR6TEEnmcorKA",
                        "name": "The Vaccines"
                    }
                ],
                "id": "6JOlPrtFaVK7TYmtgi93GC",
                "name": "No One Knows"
            },
            "played_at": "2024-01-23T12:59:45.307Z"
        }
    ]
}

Podemos montar un servidor local con JSON Server siguiendo tres pasos:

Instalamos JSON Server
Creamos un archivo db.json
Copiamos los items en este archivo
Arrancamos JSON Server

Y con esto, en http://localhost:3000/items tendríamos la API CRUD completa de nuestras canciones.

El Proyecto de Ejemplo

Vamos a ir a Spring Initializr (o usar el wizard de IntelliJ) y vamos a crear un proyecto con los siguientes datos:

Solo añado la dependencia web porque es donde se encuentra el RestClient.
Si seguimos un diseño de arquitectura hexagonal, la raíz de nuestro agregado es PlayListHistoryItem, ya que en un principio queremos traer simplemente las últimas canciones reproducidas. El dominio completo lo podemos representar mediante una serie de records ya que no tiene comportamiento (es una mala práctica, siendo un modelo de dominio anémico, pero para el ejemplo sirve).



public record PlayListHistoryItem(String id, Track track, @JsonProperty("played_at") LocalDateTime playedAt) {}

public record Track(String id, String name, Album album, Set<Artist> artists) {}

public record Album(String id, String name) {}

public record Artist(String id, String name) {}

Otra mala práctica aquí es que hemos metido la anotación JsonProperty en un objeto de dominio. Todo ésto nos indica claramente que estamos creando DTOs y que nuestro modelo de dominio debería ser otro. Pero de nuevo lo hacemos así para mantener el ejemplo contenido.

El comportamiento de carga de estas canciones desde un sistema externo al sistema lo definimos en un puerto secundario (o de salida):



public interface LoadLastPlayedPort {

  List<PlayListHistoryItem> loadLastPlayedSongs();
}

Y la responsabilidad de conectar concretamente con nuestro servidor local la podemos implementar en una clase SpongRepository que implementa el LoadLastPlayedPort:



public class SongsLocalRepository implements LoadLastPlayedPort {

  @Override
  public List<PlayListHistoryItem> loadLastPlayedSongs() {
    return List.of();
  }
}

Usando RestClient

Ahora hay que modelar SongsLocalRepository que será donde usemos el RestClient, siguiendo un enfoque TDD podemos escribir esta lista de comportamiento que deseamos del repositorio:

Si no hay canciones reproducidas recientemente, devolverá una lista vacía. ¿Por qué una lista? Pues porque tendremos duplicados (al menos de la canción, ya que puedo reproducir varias veces la misma) y además el orden es importante (viene dado cronológicamente). También se podría optar para este caso por un SortedSet.
Si hay canciones, las devolverá en una lista ordenadas por orden de reproducción, es decir, decrecientemente de lastPlayedAt. Nuestra clase de tests será algo así: ```java

class SongsLocalRepositoryTest {

private SongsLocalRepository songsLocalRepository;

@BeforeEach
void setUp() {
songsLocalRepository = new SongsLocalRepository();
}

@test
void givenNoLastPlayedSongsShouldReturnEmptyList() {
List lastPlayedSongs = songsLocalRepository.loadLastPlayedSongs();

assertThat(lastPlayedSongs).isEmpty();

}

@test
void givenMoreThanOneLastPlayedSongShouldReturnSongsInDecreasingLastPlayedAtOrder() {
List lastPlayedSongs = songsLocalRepository.loadLastPlayedSongs();

assertThat(lastPlayedSongs).isNotEmpty();
assertThat(lastPlayedSongs.getFirst().playedAt()).isAfter(lastPlayedSongs.getLast().playedAt());

}
}

La nomenclatura no es muy consistente porque quiero obtener las canciones, pero claro, realmente lo que obtengo son PlayListHistoryItems, pero bueno... con esto, por fín podemos ir a una primera implementación:
```java


public class SongsLocalRepository implements LoadLastPlayedPort {

  @Override
  public List<PlayListHistoryItem> loadLastPlayedSongs() {
    RestClient restClient = RestClient.builder()
        .baseUrl("http://localhost:3000")
        .build();
    return restClient
        .get()
        .uri("/items")
        .accept(MediaType.APPLICATION_JSON)
        .retrieve()
        .body(new ParameterizedTypeReference<List<PlayListHistoryItem>>() {});
  }
}

Vale, aquí hacemos dos cosas (lo cual ya nos indica que estamos haciendo algo mal):

Crear el RestClient como tal que es tan sencillo como indicarle la URL base de nuestras peticiones (con lo cual la relación RestClient a URL es 1:1, es decir, si quiero atacar otra URL, necesitaré otro cliente).
Hacer la petición como tal.

Entrando al detalle de la petición podemos ver que es bastante autodescriptiva:

Indicamos que vamos a hacer una petición GET
Decimos contra que URI vamos a ir, que se concatenará a la baseUrl del builder
Añadimos la cabecera que indica el tipo de contenido que aceptamos como respuesta
Hacemos la invocación en sí con retrieve
Convertimos el contenido de body al tipo de respuesta (el ParameterizedTypeReference es la manera que tenemos de evitar el borrado de tipos en genéricos)

Si arrancamos nuestro JSON Server y lanzamos las pruebas, nos encontramos con que pasa la que espera dos canciones, pero falla la que no espera ninguna. Esto es así porque lo que estamos haciendo es una prueba de integración y no unitaria, cuando debiera ser así. Para que sea una prueba unitaria, tenemos que aislar nuestro código creando un sustituto para RestClient, podemos por ejemplo, mockearlo y nuestras pruebas quedarían así:



class SongsLocalRepositoryTest {

  private SongsLocalRepository songsLocalRepository;

  @BeforeEach
  void setUp() {
    songsLocalRepository = new SongsLocalRepository();
  }

  @Test
  void givenNoLastPlayedSongsShouldReturnEmptyList() {
    List<PlayListHistoryItem> playListHistoryItems = PlayListHistoryItemsMother.getEmptyRecentlyPlayed();
    RestClient restClient = mockRestClient(playListHistoryItems);
    RestClient.Builder restClientBuilder = mock(RestClient.Builder.class);
    try (MockedStatic<RestClient> mockedBuilder = mockStatic(RestClient.class)) {
      mockRestClientBuilder(mockedBuilder, restClientBuilder, restClient);

      List<PlayListHistoryItem> lastPlayedSongs = songsLocalRepository.loadLastPlayedSongs();

      assertThat(lastPlayedSongs).isEmpty();
    }
  }

  @Test
  void givenMoreThanOneLastPlayedSongShouldReturnSongsInDecreasingLastPlayedAtOrder() {
    List<PlayListHistoryItem> playListHistoryItems = PlayListHistoryItemsMother.getTwoRecentlyPlayed();
    RestClient restClient = mockRestClient(playListHistoryItems);
    RestClient.Builder restClientBuilder = mock(RestClient.Builder.class);
    try (MockedStatic<RestClient> mockedBuilder = mockStatic(RestClient.class)) {
      mockRestClientBuilder(mockedBuilder, restClientBuilder, restClient);

      List<PlayListHistoryItem> lastPlayedSongs = songsLocalRepository.loadLastPlayedSongs();

      assertThat(lastPlayedSongs).isNotEmpty();
      assertThat(lastPlayedSongs.getFirst().playedAt()).isAfter(lastPlayedSongs.getLast().playedAt());
    }
  }

  private RestClient mockRestClient(List<PlayListHistoryItem> items) {
    RestClient restClient = mock(RestClient.class);
    RequestHeadersUriSpec getRequest = mock(RequestHeadersUriSpec.class);
    ResponseSpec response = mock(ResponseSpec.class);
    when(restClient.get()).thenReturn(getRequest);
    when(getRequest.uri(anyString())).thenReturn(getRequest);
    when(getRequest.accept(any())).thenReturn(getRequest);
    when(getRequest.retrieve()).thenReturn(response);
    when(response.body(any(ParameterizedTypeReference.class))).thenReturn(items);
    return restClient;
  }

  private void mockRestClientBuilder(MockedStatic<RestClient> mockedBuilder, Builder restClientBuilder, RestClient restClient) {
    mockedBuilder.when(RestClient::builder).thenReturn(restClientBuilder);
    when(restClientBuilder.build()).thenReturn(restClient);
    when(restClientBuilder.baseUrl(anyString())).thenReturn(restClientBuilder);
    when(restClientBuilder.defaultHeader(anyString(), anyString())).thenReturn(restClientBuilder);
  }
}

El código es bastante feo: el motivo es que tenemos que mockear la llamada estática al builder de RestClient y no tenemos más remedio que usar el MockedStatic.
Lo que hacemos es utilizar un Object Mother para crear en el primer test una lista vacía y en el segundo una lista con dos elementos y que cuando se invoca al retrieve() se devuelva la lista oportuna, todo este follón es para eso, sin más.

Ahora hay una refactorización que es obvia, RestClient debería estar inyectado en nuestro repositorio (la responsabilidad del repositorio no es crear RestClient, sino usarlo para acceder a los recursos):



public class SongsLocalRepository implements LoadLastPlayedPort {

  private static final String LAST_PLAYED_SONGS_COLLECTION = "/items";

  private final RestClient restClient;

  public SongsLocalRepository(RestClient restClient) {
    this.restClient = restClient;
  }

  @Override
  public List<PlayListHistoryItem> loadLastPlayedSongs() {
    return restClient
        .get()
        .uri(LAST_PLAYED_SONGS_COLLECTION)
        .accept(MediaType.APPLICATION_JSON)
        .retrieve()
        .body(new ParameterizedTypeReference<List<PlayListHistoryItem>>() {});
  }
}

Esto nos permite evitar la llamada estática al builder de RestClient y por tanto dejar las pruebas más concisas:



class SongsLocalRepositoryTest {

  private RestClient restClient;
  private SongsLocalRepository songsLocalRepository;

  @BeforeEach
  void setUp() {
    restClient = mock(RestClient.class);
    songsLocalRepository = new SongsLocalRepository(restClient);
  }

  @Test
  void givenNoLastPlayedSongsShouldReturnEmptyList() {
    List<PlayListHistoryItem> playListHistoryItems = PlayListHistoryItemsMother.getEmptyRecentlyPlayed();
    setUpMockGetAllRequest(playListHistoryItems);

    List<PlayListHistoryItem> lastPlayedSongs = songsLocalRepository.loadLastPlayedSongs();

    assertThat(lastPlayedSongs).isEmpty();
  }

  @Test
  void givenMoreThanOneLastPlayedSongShouldReturnSongsInDecreasingLastPlayedAtOrder() {
    List<PlayListHistoryItem> playListHistoryItems = PlayListHistoryItemsMother.getTwoRecentlyPlayed();
    setUpMockGetAllRequest(playListHistoryItems);

    List<PlayListHistoryItem> lastPlayedSongs = songsLocalRepository.loadLastPlayedSongs();

    assertThat(lastPlayedSongs).isNotEmpty();
    assertThat(lastPlayedSongs.getFirst().playedAt()).isAfter(lastPlayedSongs.getLast().playedAt());
  }

  private void setUpMockRestClient(List<PlayListHistoryItem> items) {
    RequestHeadersUriSpec getRequest = mock(RequestHeadersUriSpec.class);
    ResponseSpec response = mock(ResponseSpec.class);
    when(restClient.get()).thenReturn(getRequest);
    when(getRequest.uri(anyString())).thenReturn(getRequest);
    when(getRequest.accept(any())).thenReturn(getRequest);
    when(getRequest.retrieve()).thenReturn(response);
    when(response.body(any(ParameterizedTypeReference.class))).thenReturn(items);
  }
}

Para cargar una canción por su id, tenemos unos pasos muy similares. Podemos especificarlo así:



@Test
void givenNonExistingPlayedSongShouldReturnEmpty() {
  Optional<PlayListHistoryItem> playedSong = songsLocalRepository.loadPlayedSong("foo");

  assertThat(playedSong).isNotPresent();
}

@Test
void givenAnExistingPlayedSongShouldReturnIt() {
  PlayListHistoryItem playListHistoryItem = PlayListHistoryItemsMother.getPlayListHistoryItem();
  Optional<PlayListHistoryItem> playedSong = songsLocalRepository.loadPlayedSong(playListHistoryItem.id());

  assertThat(playedSong).isPresent();
  assertThat(playedSong.get()).isEqualTo(playListHistoryItem);
}

Modificamos el puerto de lectura para añadir el método que nos permite cargar una reproducción por su id:



public interface LoadLastPlayedPort {

  List<PlayListHistoryItem> loadLastPlayedSongs();

  PlayListHistoryItem loadPlayListHistoryItem();
}

E implementamos de manera parecida a la anterior:



@Override
public Optional<PlayListHistoryItem> loadPlayedSong(String id) {
  try {
    PlayListHistoryItem playedSong = restClient
        .get()
        .uri(LAST_PLAYED_SONGS_COLLECTION + "/{id}", id)
        .accept(MediaType.APPLICATION_JSON)
        .retrieve()
        .onStatus(HttpStatusCode::is4xxClientError, (request, response) -> {
          throw new IllegalArgumentException();
        })
        .body(PlayListHistoryItem.class);
      return Optional.ofNullable(playedSong);
  } catch (IllegalArgumentException iae) {
    return Optional.empty();
  }
}

Esto es más interesante porque dejando de lado la sobrecarga del método uri() que nos permite pasar un path param de manera limpia, podemos ver como gestionar errores.

Si no definimos ningún onStatus(), las respuestas con un código HTTP mayor que 400, lanzarán un RestClientResponseException, pero si definimos el método podemos personalizarlo.

Por ejemplo, aquí optamos por lanzar una IllegalArgumentException si recibimos un error del rango 400.

Aprovechamos para capturar este error y devolver un Optional.empty(), con lo cual tenemos el caso de que se solicite una canción no existente. Si queremos ser exhaustivos, tendríamos que añadir otra para el caso de que sea un error del servidor (usando is5xxServerError).

Y podemos terminar los tests:



@Test
void givenNonExistingPlayedSongShouldReturnEmpty() {
  String notFoundId = "foo";
  setUpMockGetNotFoundRequest(notFoundId);

  Optional<PlayListHistoryItem> playedSong = songsLocalRepository.loadPlayedSong(notFoundId);

  assertThat(playedSong).isNotPresent();
}
@Test
void givenAnExistingPlayedSongShouldReturnIt() {
  PlayListHistoryItem playListHistoryItem = PlayListHistoryItemsMother.getPlayListHistoryItem();
  setUpMockGetByIdRequest(playListHistoryItem);

  Optional<PlayListHistoryItem> playedSong = songsLocalRepository.loadPlayedSong(playListHistoryItem.id());

  assertThat(playedSong).isPresent().contains(playListHistoryItem);
}

private void setUpMockGetNotFoundRequest(String notFoundId) {
  RequestHeadersUriSpec getRequest = mock(RequestHeadersUriSpec.class);
  ResponseSpec response = mock(ResponseSpec.class);
  when(restClient.get()).thenReturn(getRequest);
  when(getRequest.uri("/items/{id}", notFoundId)).thenReturn(getRequest);
  when(getRequest.accept(any())).thenReturn(getRequest);
  when(getRequest.retrieve()).thenReturn(response);
  when(response.onStatus(any(), any())).thenThrow(IllegalArgumentException.class);
}
private void setUpMockGetByIdRequest(PlayListHistoryItem item) {
  RequestHeadersUriSpec getRequest = mock(RequestHeadersUriSpec.class);
  ResponseSpec response = mock(ResponseSpec.class);
  when(restClient.get()).thenReturn(getRequest);
  when(getRequest.uri("/items/{id}", item.id())).thenReturn(getRequest);
  when(getRequest.accept(any())).thenReturn(getRequest);
  when(getRequest.retrieve()).thenReturn(response);
  when(response.onStatus(any(), any())).thenReturn(response);
  when(response.body(PlayListHistoryItem.class)).thenReturn(item);
}

Por último, vamos a crear una nueva reproducción de una canción si es válida. La especificación sería algo así:



@Test
void givenANullPlayedSongShouldThrowIllegalArgumentExceptionWhenStoringIt() {
  Throwable thrown = catchThrowable(() -> songsLocalRepository.save(null));

  assertThat(thrown).isInstanceOf(IllegalArgumentException.class);
}

@Test
void givenAPlayedSongShouldStoreIt() {
  PlayListHistoryItem playListHistoryItem = PlayListHistoryItemsMother.getPlayListHistoryItem();

  PlayListHistoryItem savedPlayListHistoryItem = songsLocalRepository.save(playListHistoryItem);

  assertThat(savedPlayListHistoryItem).isEqualTo(playListHistoryItem);
}

Lo primero es crear un nuevo puerto para especificar la operación. ¿Por qué un nuevo puerto? Pues mientras que antes teníamos dos casos distintos pero con una misma funcionalidad, la carga de datos, aquí tenemos una funcionalidad completamente distinta y que podría estar implementada de otra manera:



public interface SaveLastPlayedPort {

  PlayListHistoryItem save (PlayListHistoryItem item);
}

Pero en nuestro caso usaremos el mismo mecanismo de implementación (RestClient), así que lo implementamos en nuestro repositorio:



public class SongsLocalRepository implements LoadLastPlayedPort, SaveLastPlayedPort {

  private static final String LAST_PLAYED_SONGS_COLLECTION = "/items";

  private final RestClient restClient;

  public SongsLocalRepository(RestClient restClient) {
    this.restClient = restClient;
  }

  @Override
  public List<PlayListHistoryItem> loadLastPlayedSongs() {
    return restClient
        .get()
        .uri(LAST_PLAYED_SONGS_COLLECTION)
        .accept(MediaType.APPLICATION_JSON)
        .retrieve()
        .body(new ParameterizedTypeReference<List<PlayListHistoryItem>>() {});
  }

  @Override
  public Optional<PlayListHistoryItem> loadPlayedSong(String id) {
    try {
      PlayListHistoryItem playedSong = restClient
          .get()
          .uri(LAST_PLAYED_SONGS_COLLECTION + "/{id}", id)
          .accept(MediaType.APPLICATION_JSON)
          .retrieve()
          .onStatus(HttpStatusCode::is4xxClientError, (request, response) -> {
            throw new IllegalArgumentException();
          })
          .body(PlayListHistoryItem.class);
        return Optional.ofNullable(playedSong);
    } catch (IllegalArgumentException iae) {
      return Optional.empty();
    }
  }

  @Override
  public PlayListHistoryItem save(PlayListHistoryItem item) {
    if (item == null) {
      throw new IllegalArgumentException("Stored song can't be null");
    }
    return restClient
        .post()
        .uri(LAST_PLAYED_SONGS_COLLECTION)
        .contentType(MediaType.APPLICATION_JSON)
        .accept(MediaType.APPLICATION_JSON)
        .body(item)
        .retrieve()
        .body(PlayListHistoryItem.class);
  }
}

Vamos a revisar el uso de RestClient, aunque es bastante directo:

Decimos que vamos a hacer un post en vez de un get
La uri sería la misma porque vamos a crearlo en la misma colección
Como es un post, llevamos contenido, le tenemos que indicar que es de tipo JSON
Y le indicamos en el body cuál es el contenido que vamos a enviar
Por último, indicamos que queremos de vuelta JSON
Lo enviamos
Recuperamos la respuesta

Lo único que puede resultar confuso aquí es que tenemos dos veces la llamada a body(), pero tiene sentido, en una para el cuerpo de la petición y en la última para parsear el cuerpo de la respuesta. Si no quisiéramos devolver nada, podríamos ignorar este último.

Ahora vamos a dejar las pruebas pasando:



@Test
void givenANullPlayedSongShouldThrowIllegalArgumentExceptionWhenStoringIt() {
  Throwable thrown = catchThrowable(() -> songsLocalRepository.save(null));

  assertThat(thrown).isInstanceOf(IllegalArgumentException.class);
}

@Test
void givenAPlayedSongShouldStoreIt() {
  PlayListHistoryItem playListHistoryItem = PlayListHistoryItemsMother.getPlayListHistoryItem();
  setUpMockPostRequest(playListHistoryItem);

  PlayListHistoryItem savedPlayListHistoryItem = songsLocalRepository.save(playListHistoryItem);

  assertThat(savedPlayListHistoryItem).isEqualTo(playListHistoryItem);
}

private void setUpMockPostRequest(PlayListHistoryItem item) {
  RequestBodyUriSpec postRequest = mock(RequestBodyUriSpec.class);
  ResponseSpec response = mock(ResponseSpec.class);
  when(restClient.post()).thenReturn(postRequest);
  when(postRequest.uri(anyString())).thenReturn(postRequest);
  when(postRequest.contentType(any())).thenReturn(postRequest);
  when(postRequest.body(any(PlayListHistoryItem.class))).thenReturn(postRequest);
  when(postRequest.accept(any())).thenReturn(postRequest);
  when(postRequest.retrieve()).thenReturn(response);
  when(response.body(PlayListHistoryItem.class)).thenReturn(item);
}

Con esto tendríamos una cobertura completa de tests de nuestro proyecto. Si quisiéramos ser exhaustivos, ahora tendríamos que hacer pruebas de integración, usando WireMock para mockear las respuestas del servidor, pero para no extender mucho más el artículo, vamos a ver como podríamos lanzarlo al arrancar la aplicación.



@SpringBootApplication
public class PlayListHistoryApplication {

  public static void main(String[] args) {
    SpringApplication.run(PlayListHistoryApplication.class, args);
  }

  @Bean
  public RestClient restClient(@Value("${song-server.base.url}") String baseUrl) {
    return RestClient.builder()
        .baseUrl(baseUrl)
        .build();
  }

  @Bean
  public LoadLastPlayedPort loadLastPlayedPort(RestClient restClient) {
    return new SongsLocalRepository(restClient);
  }

  @Bean
  public SaveLastPlayedPort saveLastPlayedPort(RestClient restClient) {
    return new SongsLocalRepository(restClient);
  }

  @Bean
  ApplicationRunner appStarted(LoadLastPlayedPort loadLastPlayedPort, SaveLastPlayedPort saveLastPlayedPort) {
    return args -> {
      List<PlayListHistoryItem> lastPlayedSongs = loadLastPlayedPort.loadLastPlayedSongs();
      Optional<PlayListHistoryItem> notValidSong = loadLastPlayedPort.loadPlayedSong("foo");
      Optional<PlayListHistoryItem> playedSong = loadLastPlayedPort.loadPlayedSong(lastPlayedSongs.getFirst().id());
      PlayListHistoryItem newPlayedSong = PlayListHistoryItemBuilder.aPlayListHistoryItem().withId("SANsVA4ihQplEQIf0GZea3").withPlayedAt(
          LocalDateTime.now()).withTrack(playedSong.get().track()).build();
      saveLastPlayedPort.save(newPlayedSong);
    };
  }
}

Aquí podemos ver como se define el RestClient como un bean de Spring (leyendo su URL base de una propiedad definida en el application.properties), como instanciamos los puertos, aunque sea la misma clase de implementación, así nos mantenemos independizados de que esta implementación cambie en un futuro y como los inyectamos en un bean de tipo ApplicationRunner que se ejecutará al arrancar la aplicación.

Realmente la lógica de creación de la nueva canción debería ir en un puerto primario (o de entrada) de la aplicación, pero se va un poco del objetivo de mostrar como usar RestClient.

Si arrancamos JSON server y lanzamos la aplicación podemos ver que ejecuta sin más (¿qué esperabas? Al fín y al cabo no hemos puesto ningún mensaje de salida :P).

Tienes el código completo en GitHub