Ya hemos visto en otro post mi propuesta para tener una documentación ligera del proyecto que se mantenga actualizada y sea realmente útil (spoiler: reduciéndola al máximo), sin embargo era documentación más bien técnica, dirigida al equipo o a posibles colaboradores. Es cierto que tenemos un README en el que especificamos que hace la aplicación (o servicio o como queramos decirle), pero… ¿cómo podemos mantener viva la documentación sobre QUÉ es lo que hace el proyecto detalladamente? ¿No sería genial si esta documentación fuera ejecutable y verificable? De esa manera nos podríamos asegurar siempre de que no rompemos nada y que la funcionalidad más importante de la aplicación sigue funcionando. De la misma manera que para la documentación técnica trato de mantener un enfoque práctico y minimalista, creo que para esta documentación de funcionalidad (o comportamiento) debemos hacer lo mismo. Cuántos más artefactos superfluos tengamos (larguísimos documentos de requisitos, especificaciones de usuarios…) peor, mayor sería la entropía acumulada. Entonces, ¿cómo podemos recoger esta información? Una aproximación son las historias de usuario.

1. ¿Qué es (realmente) la Arquitectura Hexagonal? 🔗La arquitectura hexagonal está de moda, pero cuando te pones a investigar, te das cuenta de que el nombre es lo de menos. ¿Es hexagonal? ¿Ports & Adapters? ¿Arquitectura cebolla? ¿O incluso Clean Architecture? 🤔 La idiosincrasia es que realmente no es una arquitectura rígida, sino más bien un patrón, una serie de guías para construir tu aplicación. En todas sus variantes, el flujo de la información es, a grandes rasgos, el siguiente:

La tentación de empezar a programar (y por qué deberías esperar) 🔗Como desarrolladores, nuestro primer impulso al empezar un proyecto es casi siempre el mismo: abrir el IDE y ponernos a picar código. 🚀 Ya sea eligiendo dependencias, escribiendo tests o definiendo el modelo de dominio, esa es la parte divertida, ¿verdad? Este enfoque funciona para pruebas de concepto rápidas. Pero si estás construyendo un producto a largo plazo, sobre todo en equipo, necesitas un plan. Hasta la idea más simple puede significar algo diferente para cada persona.

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.

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: