Norma para el desarrollo de SPA

Ámbito de aplicación de la norma

Esta norma es de aplicación tanto para nuevos desarrollos como mantenimientos que incluyan la creación de aplicaciones de tipo SPA.

Las directrices que contiene la norma son independientes de la pila tecnológica que se utilice. Los objetivos y características de la arquitectura no están vinculados a la tecnología de implementación. 

Por tanto, al implementar una SPA con una tecnología específica, hay que cumplir con:

• Las normas y estándares referidos en esta página.
• Otras normas particulares establecidas para dicha tecnología.

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

Diseño

Principio de modularidad

Las SPA se diseñarán de manera modular, donde cada componente sea independiente, reutilizable y tenga un propósito específico. Esto asegura que el sistema sea escalable y fácil de mantener.

DIR_01 Modularidad

OBLIGATORIO La SPA estará estructurada de manera modular, con componentes independientes y bien definidos, permitiendo que cada uno pueda ser mantenido y evolucionado sin impactar negativamente al resto de la aplicación:

• Se estructurará en componentes funcionales independientes, cada uno con su responsabilidad específica en la interfaz de usuario o la lógica de negocio; autenticación, navegación, gestión de usuarios, entre otros. Al modularizar el desarrollo, las aplicaciones pueden desarrollar y probar componentes que pueden desplegarse eficientemente debido a su ubicación central.
• Facilitar la reutilización de los componentes a través de diferentes vistas o secciones de la aplicación, lo que significa una coherencia inquebrantable y una pequeña cantidad de código duplicado.
• Definir interfaces claras para cada componente, limitando el acceso directo a sus campos internos. En su lugar, se deben exponer únicamente las propiedades, eventos y servicios necesarios a través de estas interfaces, garantizando la seguridad y permitiendo que los módulos evolucionen, se reemplacen o se intercambien entre bibliotecas compatibles sin afectar otros elementos de la aplicación.
• Es recomendable reutilizar librerías y servicios compartidos para componentes comunes: los elementos de la interfaz de usuario básica como botones, tablas, formularios, esquemas de diseño, estilos, patrones de diseño y servicios comunes como enrutadores y API se pueden usar en múltiples ubicaciones de aplicación. Fomenta la coherencia visual y funcional.
• Es recomendable diseñar los componentes de forma que puedan comprenderse y gestionarse de manera clara y manejable, distribuyendo las grandes funcionalidades en componentes más pequeños, lo que se traduce en mayor facilidad de mantenimiento y resolución de errores.
• Evitar dependencias críticas entre componentes que comprometan su independencia. Cualquier interacción entre componentes debe gestionarse mediante servicios compartidos, patrones de eventos o estado centralizado, si es necesario.

Principio de Responsabilidad Única (SRP)

Cada componente dentro de una SPA estará dedicado a cumplir con una sola función o responsabilidad. Esto no solo reduce la complejidad y mejora la mantenibilidad, sino que también asegura que cada parte pueda evolucionar de manera controlada sin impactar a las demás. Además, limita los cambios y promueve la depuración y el desarrollo eficiente.

DIR_02 Responsabilidad única

OBLIGATORIO Los componentes en una SPA seguirán el Principio de Responsabilidad Única (SRP), limitando su alcance a una única responsabilidad o funcionalidad específica dentro de la aplicación:

• Se diseñarán componentes con una única responsabilidad claramente definida, garantizando que cualquier cambio afecte solo esa área específica. Esto no solo facilita el mantenimiento y la evolución del sistema, sino que también asegura un código cohesivo, fácil de entender y depurar, al evitar la inclusión de funcionalidades no relacionadas.
• Se documentará el propósito de cada componente, especificando su responsabilidad y cómo interactúa con otros componentes o servicios, para que los equipos de desarrollo tengan claridad sobre su rol dentro de la SPA.
• Es recomendable realizar revisiones periódicas para asegurar que los componentes mantengan sus responsabilidades previstas y no acumulen "deuda técnica".

Consistencia de la Interfaz de Usuario

La consistencia en la interfaz de usuario es crucial para asegurar una experiencia de usuario coherente y predecible en toda la aplicación SPA. Esto incluye la utilización de un diseño visual uniforme, patrones de interacción comunes y la reutilización de componentes de UI compartidos.

DIR_03 Sistema de diseño

OBLIGATORIO La SPA seguirá el sistema de diseño de la Junta de Andalucía, publicado en el portal de desarrollo de servicios digitales, para garantizar la consistencia de la interfaz de usuario en toda la aplicación: 

• Utilizar el sistema de diseño compartido, que incluye guías de estilo, componentes visuales y patrones de interacción, asegurando una apariencia y comportamiento uniformes en toda la aplicación.
• Respetar las guías de estilo definidas, como tipografía, colores, espaciado y otros elementos visuales, para mantener la uniformidad en la interfaz de usuario.
• Los cambios en el sistema de diseño o en los componentes compartidos se han de propagar de manera coherente a lo largo de toda la SPA, preservando la coherencia visual y funcional.
• Es recomendable realizar auditorías periódicas de la interfaz de usuario para verificar que la SPA cumpla con las guías de estilo y para identificar desviaciones que necesiten ser corregidas.
• Es recomendable documentar cualquier adaptación o personalización específica del sistema de diseño utilizada en la SPA, justificando y aprobando dichas variaciones a través de un proceso definido por la Oficina de Arquitectura o el equipo responsable.
•  

DIR_04 Reutilización de componentes

OBLIGATORIO Los componentes de la interfaz de usuario serán reutilizados y compartidos dentro de la SPA para garantizar la consistencia y la coherencia visual en toda la aplicación: 

• Utilizar componentes de UI provenientes de una librería común proporcionada y gobernada por la Oficina de Arquitectura (OdA) o el equipo asignado responsable. Esto asegura que los elementos visuales y patrones de interacción sean consistentes en todas las vistas de la SPA, evitando duplicar esfuerzos y manteniendo una experiencia de usuario uniforme.
• Diseñar los componentes de manera que permitan su fácil integración en cualquier parte de la SPA, con opciones de personalización limitadas para garantizar que la coherencia visual se mantenga en toda la aplicación.
• Es recomendable que cualquier nuevo componente necesario para un SPA específico sea evaluado para su inclusión en la librería de componentes compartidos de la OdA. Los equipos de desarrollo pueden proponer nuevos componentes a la OdA, quienes revisarán su viabilidad y coherencia con el sistema.

DIR_05 Coherencia en la experiencia de uso

OBLIGATORIO La interfaz de usuario de la SPA será coherente en todas las plataformas y dispositivos, asegurando una experiencia uniforme para todos los usuarios: 

• Aplicar el diseño responsivo establecido en el sistema de diseño para garantizar que la SPA se adapte correctamente a diferentes tamaños de pantalla y dispositivos, manteniendo la coherencia en la experiencia del usuario.
• Seguir patrones de navegación y disposición consistentes en todas las vistas de la SPA, independientemente del dispositivo o plataforma, para evitar confusión y mejorar la usabilidad.
• Es recomendable realizar pruebas de usabilidad en múltiples dispositivos y navegadores para verificar que la experiencia del usuario sea satisfactoria y consistente en todos los contextos de uso.
• Es recomendable documentar las adaptaciones específicas para diferentes plataformas en el sistema de diseño, asegurando que los desarrolladores comprendan cómo implementar interfaces coherentes en diversas condiciones.

Gestión del estado

La gestión de estado en las SPA garantiza que los datos se manejen de manera consistente y eficiente en toda la aplicación. Una gestión adecuada del estado asegura la sincronización correcta entre la interfaz de usuario y los datos subyacentes, mejorando la experiencia del usuario y facilitando el mantenimiento del sistema.

DIR_06 Gestión eficiente del estado

OBLIGATORIO El estado se gestionará de manera eficiente en las SPA, diferenciando claramente entre el estado local de los componentes y el estado global de la aplicación: 

• Encapsular los estados locales dentro de los componentes individuales para evitar dependencias innecesarias. El estado compartido entre vistas o componentes debe gestionarse mediante patrones de estado centralizado.
• Aplicar patrones de inmutabilidad en el manejo del estado, asegurando que las actualizaciones de datos sean predecibles y fáciles de depurar.
• Es recomendable documentar la gestión del estado de la SPA, incluyendo diagramas de flujo de datos, descripciones de los estados locales y globales, y ejemplos que expliquen su interacción.
• Es recomendable realizar revisiones periódicas de las estrategias de gestión de estado para verificar que sean eficientes y escalables a medida que la aplicación crece.

DIR_07 Sincronización del estado

OBLIGATORIO Sincronizar el estado en las SPA mediante mecanismos desacoplados, garantizando que los datos se actualicen correctamente sin generar dependencias fuertes entre componentes o vistas.: 

• Implementar mecanismos de sincronización utilizando patrones centralizados o eventos desacoplados, como Pub/Sub o Context API, que permitan a los componentes publicar y suscribirse a eventos sin requerir conocimiento directo de otros módulos.
• Gestionar posibles conflictos de sincronización mediante resoluciones claras, como la priorización de la última actualización válida o el uso de versiones controladas del estado.
• Es recomendable revisar y optimizar las estrategias de sincronización periódicamente para identificar cuellos de botella o áreas donde se pueda mejorar la eficiencia del flujo de datos.

DIR_08 Manejo del estado

OBLIGATORIO La persistencia del estado en las SPA se manejará para garantizar una experiencia de usuario fluida, preservar la integridad de los datos y mantener la seguridad:

• Implementarse mecanismos de persistencia del estado que permitan su recuperación tras recargas de página o cambios de contexto, utilizando opciones como almacenamiento local, IndexedDB o mecanismos similares, según las necesidades de la aplicación.
• Desplegar medidas de seguridad y privacidad al manejar la persistencia del estado, aplicando técnicas como cifrado y una gestión segura de los datos almacenados.
• Incorporar mecanismos de limpieza o expiración de datos persistidos para evitar la acumulación de información obsoleta que pueda degradar el rendimiento de la aplicación.

Optimización del rendimiento

La optimización del rendimiento es esencial en las SPAs para garantizar una experiencia de usuario rápida y fluida, minimizando los tiempos de carga inicial y mejorando la eficiencia de las interacciones.

DIR_09 Tiempo de carga y uso de recursos

OBLIGATORIO Minimizar el tiempo de carga inicial y mejorar la eficiencia de los recursos:

• Utilizar técnicas de minimización y compresión de archivos (CSS, JavaScript, imágenes) para reducir el tamaño de los recursos enviados al cliente.
• Implementar la carga diferida (lazy loading) para imágenes, scripts y otros recursos no críticos, asegurando que solo se carguen cuando sean necesarios. Esto reduce la sobrecarga inicial y mejora la percepción de rendimiento.
• Es recomendable emplear particionamiento de código (code splitting) para dividir el JavaScript en fragmentos más pequeños, cargando únicamente lo necesario para la vista actual. Esto mejora la velocidad de carga inicial y optimiza la interactividad.
• Es recomendable optimizar las consultas a la API para reducir la cantidad de datos transferidos y minimizar el tiempo de respuesta, utilizando técnicas como paginación, filtrado y compresión de respuestas.

DIR_10 Rendimiento lado cliente

OBLIGATORIO Implementar estrategias de optimización del rendimiento del lado del cliente para garantizar una experiencia de usuario ágil y eficiente, minimizando los tiempos de carga y mejorando la interacción en la aplicación:

• Implementar almacenamiento en caché de recursos estáticos en el navegador del usuario, estableciendo políticas de caché adecuadas (como control de cache con headers Cache-Control y ETag) para maximizar la reutilización de recursos entre visitas. Esto minimiza la necesidad de recargar recursos inalterados y mejora la velocidad de navegación.
• Utilizar técnicas de prerenderizado o renderizado en el servidor (Server-Side Rendering, SSR) cuando sea necesario, especialmente en aplicaciones con mucho contenido dinámico o que requieren un rendimiento óptimo en el tiempo de carga inicial.
• Es recomendable integrar un Content Delivery Network (CDN) para distribuir recursos estáticos (CSS, JavaScript, imágenes) de manera eficiente y reducir la latencia de carga para usuarios en diferentes ubicaciones geográficas.
• Es recomendable monitorear continuamente el rendimiento en el cliente utilizando herramientas de análisis de rendimiento para identificar y corregir cuellos de botella en el rendimiento.

DIR_11 Mejora continua del rendimiento

OBLIGATORIO Optimizar y monitorizar su rendimiento de manera continua para garantizar eficiencia, escalabilidad y una experiencia de usuario fluida:

• Implementar prácticas de optimización en las interacciones con el servidor, como la compresión de datos, la reducción de la carga útil y el uso de respuestas en caché, para minimizar la latencia y mejorar la eficiencia.
• Integrar las SPAs con el sistema de observabilidad centralizado de la Junta de Andalucía mediante el protocolo OpenTelemetry, asegurando una monitorización constante del rendimiento y alertas en caso de degradación.
• Es recomendable realizar pruebas de carga regulares para evaluar el comportamiento de la aplicación bajo condiciones de alta demanda y garantizar su capacidad de escalar.
• Es recomendable incluir el rendimiento como un criterio clave en revisiones de código y pruebas automatizadas para prevenir posibles degradaciones en nuevas implementaciones.

Accesibilidad

La accesibilidad es un aspecto fundamental en el diseño y desarrollo de SPAs, garantizando que todos los usuarios, incluidas las personas con discapacidades, puedan interactuar eficazmente con la aplicación. Asegurar la accesibilidad no solo es una responsabilidad social y legal en muchos contextos, sino que también mejora la usabilidad general, ampliando el alcance de la aplicación y mejorando la satisfacción del usuario.

Cumplir con las normas de accesibilidad permite que las SPAs sean inclusivas, proporcionando igualdad de acceso y mejorando la experiencia de todos los usuarios, independientemente de sus habilidades o del dispositivo que utilicen.

DIR_12 Accesibilidad

OBLIGATORIO Cumplir con las Directrices de Accesibilidad para el Contenido Web (WCAG) y con las políticas establecidas en el documento de Normativa de Accesibilidad de la Junta:

• Asegurar que todas las funcionalidades y contenidos sean accesibles para todos los usuarios, incluidas las personas con discapacidades, siguiendo los lineamientos definidos en el documento de normas de accesibilidad.

Construcción

Selección de Tecnología

La selección de tecnologías adecuadas es esencial para garantizar que las SPA sean eficientes, escalables y mantenibles. Las decisiones tecnológicas se alinearán con los objetivos del proyecto, las capacidades del equipo y las directrices establecidas por la Oficina de Arquitectura (OdA) y el documento de arquitectura de referencia para SPA.

DIR_13 Tecnología

OBLIGATORIO La selección de tecnología se alineará con el stack tecnológico definido y aprobado por la Oficina de Arquitectura (OdA) en el documento de arquitectura de referencia de SPA:

• Utilizar únicamente tecnologías especificadas en el stack tecnológico aprobado por la OdA, asegurando que cada elección permita una integración fluida y coherente entre los diferentes módulos y servicios de la SPA.
• Emplear versiones respaldadas y actualizadas de las tecnologías incluidas en el stack, garantizando la estabilidad, seguridad y rendimiento tanto en entornos de desarrollo como en producción.
• Es recomendable que los equipos de desarrollo revisen periódicamente las versiones de las tecnologías utilizadas para verificar que cumplen con las últimas actualizaciones autorizadas, asegurando compatibilidad y rendimiento óptimos.
• Es recomendable mantener coherencia tecnológica dentro de la SPA, evitando la introducción de tecnologías adicionales no aprobadas que puedan generar inconsistencias o dificultar la integración y el mantenimiento. 

Calidad del código

Mantener la calidad del código es esencial para garantizar la mantenibilidad, escalabilidad y seguridad del software. Las normas de calidad del código ayudan a reducir errores, mejorar la legibilidad y facilitar la colaboración entre desarrolladores, especialmente en el desarrollo de SPA, donde la modularidad y la coherencia son fundamentales.

DIR_14 Estándares de calidad

OBLIGATORIO El código de la SPA cumplirá los estándares de calidad definidos por la Oficina de Calidad o la Oficina de Arquitectura para garantizar su mantenibilidad y seguridad:

• Seguir un conjunto de estándares de codificación bien definidos y aprobados por la organización, incluyendo el uso de linters, formateadores y otras herramientas para mantener la consistencia en el estilo y la estructura del código.
• Es recomendable realizarse revisiones de código regulares por parte de otros desarrolladores o pares del equipo para identificar problemas, compartir conocimiento y mejorar la calidad general del código.
• Es recomendable documentar el código de manera clara y concisa, incluyendo comentarios que expliquen la lógica y el propósito de secciones complejas, facilitando la comprensión y el mantenimiento del código a largo plazo.
• Es recomendable adoptar prácticas de desarrollo orientadas a pruebas, como Test-Driven Development (TDD), para mejorar la calidad del código desde el inicio del desarrollo.

DIR_15 Análisis de la calidad

OBLIGATORIO El código será analizado continuamente para asegurar su calidad y seguridad: 

• Utilizar herramientas de análisis estático de código que identifiquen vulnerabilidades, malas prácticas y posibles errores antes de que el código sea desplegado. Esto asegura que el código cumpla con los estándares de calidad y seguridad establecidos.
• Integrar pruebas automatizadas que cubran un alto porcentaje del código, incluyendo pruebas unitarias, de integración y de regresión, asegurando que el código sea robusto y libre de errores conocidos.
• Es recomendable realizar revisiones de calidad del código antes de cada despliegue importante, asegurando que no se introduzcan nuevas vulnerabilidades o errores en producción.

Políticas para la gestión de errores

La gestión adecuada de errores en las SPA garantiza la estabilidad, confiabilidad y una experiencia de usuario consistente. Las políticas de gestión de errores deben detectar, manejar y comunicar los problemas de manera efectiva, minimizando su impacto en el sistema y facilitando su resolución rápida.

DIR_16 Manejo de errores

OBLIGATORIO Implementar un manejo de errores consistente y predecible para mantener la estabilidad del sistema y la calidad de la experiencia del usuario:

• Capturar y manejar los errores de manera consistente, utilizando bloques try-catch y mecanismos centralizados de manejo de errores tanto para errores síncronos como asíncronos.
• Registrar todos los errores críticos en un sistema centralizado de logs, facilitando el monitoreo y el análisis en tiempo real. Los logs deben contener el stack trace, el contexto del error y cualquier información adicional significativa para diagnosticar el problema.
• Es recomendable configurar un sistema de alertas que notifique al equipo de desarrollo de forma automática sobre los errores críticos del entorno de producción, posibilitando una pronta reacción.
• Es recomendable aplicar una estrategia de manejo de errores que posibilite la recuperación automática siempre que sea posible, de esta manera se minimiza el impacto en la experiencia del usuario.

DIR_17 Mensajes de error

OBLIGATORIO La SPA proporcionará mensajes de error claros y útiles tanto para los desarrolladores como para los usuarios finales, garantizando una experiencia coherente y efectiva en caso de fallos:

• Proporcionar mensajes de error comprensibles y detallados para los desarrolladores en los logs, incluyendo información suficiente para diagnosticar y resolver el problema rápidamente.
• Mostrar mensajes de error amigables al usuario final que no expongan detalles técnicos innecesarios, pero que informen claramente sobre lo que salió mal y, si es posible, cómo proceder. Esto mejora la experiencia del usuario y reduce la frustración en caso de fallos.
• Es recomendable proporcionar mecanismos de feedback al usuario final en caso de error, como botones para reintentar o enlaces a páginas de ayuda, facilitando la recuperación de la situación.
• Es recomendable documentar los códigos de error utilizados en el sistema para que el equipo de soporte pueda proporcionar asistencia efectiva y rápida cuando sea necesario.

DIR_18 Errores de red

OBLIGATORIO La SPA implementará una gestión robusta de errores de red para garantizar la resiliencia en entornos con conectividad inestable, preservando la experiencia del usuario y la estabilidad del sistema:

• Manejar adecuadamente las desconexiones y reconexiones, mostrando mensajes claros y apropiados al usuario, e intentando recuperar la operación automáticamente cuando la conectividad se restablezca.
• Utilizar un servicio centralizado para la gestión de errores de red, que pueda monitorizar y reportar patrones de fallos, ayudando a identificar problemas sistémicos o intermitentes en la infraestructura.
• Es recomendable probar los SPA en entornos simulados de conectividad limitada para asegurar que se comporten de manera predecible y segura bajo condiciones adversas.

DIR_19 Resiliencia

OBLIGATORIO La SPA contará con mecanismos robustos para la gestión de errores persistentes y la recuperación ante fallos, asegurando la resiliencia del sistema y minimizando el impacto en la experiencia del usuario:

• Implementar un sistema de recuperación ante fallos que permita restaurar el estado previo de la aplicación tras un error crítico, siempre que sea posible. Esto incluye la capacidad de guardar el estado temporal y restaurarlo después de que el problema haya sido resuelto.
• Se diseñará para capturar y reportar errores persistentes que no puedan ser resueltos inmediatamente, facilitando su análisis y corrección en futuras iteraciones del desarrollo.
• Es recomendable que incluya capacidades de auto-diagnóstico, donde se puedan identificar y aislar módulos o componentes problemáticos, minimizando el impacto en el resto del sistema.
• Es recomendable planificar y probar escenarios de recuperación ante fallos durante el ciclo de desarrollo, asegurando que las estrategias de mitigación y recuperación funcionen como se espera.

Pruebas

DIR_20 Pruebas unitarias

OBLIGATORIO La SPA contará con pruebas unitarias exhaustivas que cubran las funcionalidades críticas, asegurando que cada unidad de código funcione correctamente de manera aislada. Se utilizarán frameworks de pruebas unitarias compatibles con el stack tecnológico definido en el proyecto.

DIR_21 Pruebas de integración

OBLIGATORIO La SPA contará con pruebas de integración que validen la correcta interacción entre los diferentes módulos y componentes, garantizando que las dependencias internas funcionen de manera coherente y sin errores.

DIR_22 Pruebas end-to-end

OBLIGATORIO La SPA se someterá a pruebas end-to-end (E2E) que simulen el flujo completo de usuario desde la interfaz hasta la lógica de backend, asegurando que la aplicación funcione correctamente en un entorno de producción realista.

DIR_23 Automatización de pruebas

OBLIGATORIO Las pruebas unitarias, de integración y end-to-end se automatizarán en los procesos de Integración Continua (CI) para garantizar la detección temprana de errores y fallos en el desarrollo:

• Automatización de Pruebas Unitarias y de Integración: se dispondrán pruebas unitarias y de integración automatizadas que se ejecuten como parte del pipeline de CI/CD, permitiendo la detección temprana de errores y garantizando la calidad continua del código.
• Automatización de Pruebas End-to-End: Las pruebas End-to-End se automatizarán en la medida de lo posible, integrándose en el pipeline de CI/CD para validar automáticamente la funcionalidad completa del sistema en cada despliegue.
• Mantenimiento de Scripts de Pruebas Automatizadas: Los scripts de pruebas automatizadas se mantendrán y actualizarán regularmente para reflejar cambios en la funcionalidad de la SPA, asegurando que las pruebas sigan siendo relevantes y efectivas.

Normas relacionadas

La construcción de un microservicio implica el cumplimiento de esta norma y las normas transversales que se apliquen:

• Norma de uso del repositorio de código corporativo
• Norma de uso de la estrategia de ramificación de la plataforma CI/CD corporativa
• Norma de uso del pipeline de integración continua de la Plataforma CI/CD corporativa
• Norma para el alineamiento con la pila tecnológica de la ADA
• Norma para el desarrollo seguro
• Norma para la observabilidad

Estándares

El siguiente listado muestra los estándares que se aplican a la arquitectura de microservicios. Puede consultarse la descripción de cada estándar en la siguiente página

Definición de servicios y eventos

• Open API
• Web Components Standard
• Custom Events
• Web Messaging

Comunicaciones

• API RESTful
• GraphQL
• gRPC
• WebSockets
• Server-Sent Events (SSE)

Seguridad

• Content Security Policy (CSP)
• SOWEB(SAML 2.0)
• HTTPS/SSL
• OAuth2

Diseño y accesibilidad

• Web Content Accessibility Guidelines (WCAG)
• Diseño responsivo