Información general

Descripción
Código: NOR_SPA
Versión actual: v01r00
Norma para el desarrollo de Single Page Application (SPA), páginas web que cargan dinámicamente contenido sin recargar toda la página, como parte de una solución, de acuerdo a la arquitectura de referencia de SPA.
Incluye un anexo con información básica sobre los estándares a los que hacen referencia las directrices de esta norma.
Á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.
Observabilidad
Monitorización
La monitorización es esencial para asegurar que los SPA estén operando de manera eficiente y para detectar problemas antes de que afecten a los usuarios finales.
DIR_20 Monitoreo
OBLIGATORIO Implementar un sistema de monitoreo robusto de la SPA que permita la observación continua de su estado, rendimiento y disponibilidad:
- Integrar en un sistema centralizado que recopile métricas clave sobre el rendimiento de la aplicación, la tasa de errores y el uso de recursos. Estas métricas deben ser accesibles en tiempo real para los equipos de desarrollo y operaciones, facilitando la detección temprana de problemas y su resolución.
- Configurar alertas basadas en umbrales críticos, como tiempos de respuesta elevados, fallos recurrentes o uso excesivo de recursos. Estas alertas son necesarias para identificar y gestionar incidentes antes de que impacten negativamente en los usuarios finales.
- Es recomendable monitorear métricas específicas de la experiencia del usuario, como el tiempo de carga de la página y el tiempo hasta la interactividad, para garantizar que la aplicación ofrezca un rendimiento óptimo y una experiencia fluida.
- Es recomendable realizar revisiones periódicas de las métricas recopiladas con el objetivo de analizar patrones, detectar tendencias y aplicar mejoras en las áreas críticas de rendimiento y estabilidad de la aplicación.
DIR_21 Disponibilidad y resiliencia
OBLIGATORIO El monitoreo de la SPA medirá su disponibilidad y resiliencia, garantizando que el sistema pueda detectar problemas y responder de manera eficiente:
- Implementar comprobaciones de salud (health checks) que permitan monitorear continuamente el estado y la disponibilidad de la aplicación. Estas comprobaciones deben ser utilizadas para verificar que la SPA esté en condiciones óptimas antes de interactuar con servicios externos o usuarios.
- Implementar dashboards centralizados que presenten información en tiempo real sobre la disponibilidad, los errores y el rendimiento de la aplicación. La visualización centralizada facilita la supervisión continua y la toma de decisiones rápidas en caso de incidentes.
- Es recomendable realizar simulaciones de fallos en entornos de prueba para validar la eficacia de los mecanismos de monitoreo y asegurar que la aplicación pueda recuperarse bajo condiciones adversas. Estas pruebas permiten identificar vulnerabilidades y fortalecer la resiliencia del sistema.
- Es recomendable compartir la información relevante del monitoreo con los equipos involucrados en el desarrollo y mantenimiento de la SPA. Esto garantiza una respuesta coordinada y eficiente frente a incidentes críticos, facilitando la colaboración entre los equipos.
Logging
El logging es una herramienta fundamental para entender el comportamiento de la SPA, facilitar la depuración de problemas y proporcionar un historial detallado de eventos y errores que permite el análisis posterior y la resolución eficiente de incidencias.
DIR_22 Registro de eventos y errores
OBLIGATORIO Registrar eventos y errores de la SPA de manera consistente y centralizada, para facilitar su análisis, diagnóstico y resolución de problemas:
- Registrar eventos clave y errores en un sistema de logging centralizado que permita la correlación y el análisis posterior. Los logs deben incluir información detallada como el timestamp, el contexto del error, y el stack trace.
- Implementar políticas de retención de logs que equilibren la necesidad de almacenamiento con la necesidad de mantener un historial adecuado para análisis forenses y auditorías.
- Es recomendable utilizar un formato estructurado para los logs (por ejemplo, JSON) que facilite la búsqueda, el filtrado y el análisis automatizado de la información registrada.
- Es recomendable integrar el logging con herramientas de análisis de logs que permitan la detección de patrones y la generación de alertas basadas en la ocurrencia de eventos específicos.
DIR_23 Logs compartidos
OBLIGATORIO Los logs de la SPA serán accesibles y utilizables por los diferentes equipos involucrados en su mantenimiento y operación, garantizando una gestión segura y efectiva de la información registrada:
- Almacenar los logs en una plataforma accesible y segura, donde los equipos de desarrollo, operaciones y seguridad puedan acceder para realizar análisis y depuración.
- Implementar políticas de control de acceso que aseguren que solo las personas autorizadas puedan ver y manipular los logs, protegiendo la información sensible y cumpliendo con las regulaciones de privacidad.
- Configurar los niveles de logging adecuados a cada entorno, prohibiendo el uso de niveles DEBUG o TRACE en producción, salvo en casos puntuales y temporalmente acotados para la depuración de errores.
- Usar herramientas de visualización de logs que faciliten la comprensión de los datos y la identificación rápida de problemas, como Open Telemetry .
- Es recomendable que los logs sean revisados regularmente para identificar posibles áreas de mejora en la arquitectura o en los procesos operativos.
Trazabilidad
La trazabilidad del SPA ayuda a entender el flujo de datos y las interacciones dentro del sistema, permitiendo identificar problemas en la comunicación, optimizar el rendimiento y mejorar la experiencia del usuario.
DIR_24 Trazabilidad
OBLIGATORIO Implementar mecanismos de trazabilidad de la SPA que permitan rastrear el flujo de datos y solicitudes a lo largo de todo el sistema:
- Utilizar identificadores únicos de trazabilidad (trace IDs) que acompañen cada solicitud a lo largo de su ciclo de vida, desde su inicio hasta la respuesta final. Esto facilita el seguimiento detallado del recorrido de cada solicitud y permite la correlación de eventos.
- Integrar con sistemas que permitan visualizar el flujo completo de las solicitudes y eventos dentro de la SPA, identificando posibles cuellos de botella, tiempos de respuesta elevados y errores en la comunicación entre módulos o servicios.
- Es recomendable que los mecanismos de trazabilidad capturen información adicional, como tiempos de respuesta, interacciones entre componentes y posibles puntos de fallo. Esto proporciona una visión completa del rendimiento y la eficiencia del sistema.
- Es recomendable revisar periódicamente los datos de trazabilidad con el objetivo de identificar patrones o tendencias que puedan señalar problemas recurrentes, áreas de mejora en la arquitectura o ineficiencias en el flujo de datos
DIR_25 Traza compartida
OBLIGATORIO La trazabilidad de la SPA será accesible y útil para los diferentes equipos responsables de la operación y el mantenimiento, facilitando la comprensión del flujo de datos y la rápida resolución de problemas:
- Almacenar los datos de trazabilidad en un sistema centralizado y accesible que permita realizar consultas ad-hoc por parte de los equipos de desarrollo, operaciones y seguridad. Esto garantiza que la información relevante esté disponible para su análisis en tiempo real y para diagnósticos detallados
- Documentar los patrones de trazabilidad y las pautas para su interpretación, proporcionando a los equipos información clara sobre cómo entender el flujo de datos, las interacciones entre módulos y la relación entre los diferentes componentes del sistema.
- Es recomendable integrar los datos de trazabilidad con los sistemas de monitoreo y logging existentes, ofreciendo una vista unificada del funcionamiento del sistema. Esto facilita la correlación entre métricas, logs y trazas, permitiendo una identificación más eficiente de problemas.
- Es recomendable capacitar a los equipos responsables en el uso de las herramientas de trazabilidad y en la interpretación de los datos recopilados, asegurando que puedan responder de manera rápida y efectiva a cualquier incidente o comportamiento inesperado en la aplicación.
Seguridad
DIR_26 Sesiones
OBLIGATORIO La gestión de sesiones basadas en cookies seguirán las prácticas de seguridad establecidas en la norma para el desarrollo seguro, incluyendo la configuración de las cookies con las banderas HttpOnly y Secure para protegerlas contra accesos indebidos y garantizar que solo se transmitan a través de conexiones HTTPS.
Además, se debe aplicar la política SameSite para mitigar ataques CSRF, configurándola como Lax o Strict. El ciclo de vida de la sesión será gestionado de manera segura, asegurando la validación constante del identificador de sesión por parte del servidor (ASVS V3.4).
DIR_27 Protección de directorios
OBLIGATORIO La deshabilitación de la exploración de directorios en servidores Node.js se implementará utilizando un middleware adecuado, como el proporcionado en Express.js, para garantizar que las solicitudes de directorios sean rechazadas con un error 403 Forbidden. Esto es esencial para prevenir el acceso no autorizado a archivos y directorios sensibles. Esta práctica está alineada con los requisitos de seguridad establecidos en la norma para el desarrollo seguro (ASVS V4.1, V4.3).
DIR_28 Evitar ataques CSRF
OBLIGATORIO Implementar mecanismos anti-CSRF para prevenir ataques de falsificación de solicitudes entre sitios. Se generará un token único anti-CSRF en el servidor, el cual se asociará con la sesión del usuario y se enviará con cada solicitud que pueda modificar el estado del servidor. El servidor validará este token con cada petición para garantizar su legitimidad. Esta norma está alineada con la norma para el desarrollo seguro para mitigar ataques CSRF (ASVS V4.2).
Se exceptúan de esta medida aquellos escenarios en los que no se requiera control de accesos ni autenticación de usuarios, y en los que el impacto de un ataque CSRF sea insignificante. Esta norma está alineada con la norma para el desarrollo seguro para mitigar ataques CSRF (ASVS V4.2).
DIR_29 Validación de los datos de entrada
OBLIGATORIO Se validarán las entradas para garantizar que los datos proporcionados por los usuarios cumplan con los criterios de formato, tipo y longitud. La validación rigurosa previene ataques como la inyección de código y manipulación de datos, protegiendo así la integridad de la aplicación. Esta norma sigue las directrices la norma para el desarrollo seguro (ASVS V5.1).
DIR_30 Validación de parámetros de entrada
OBLIGATORIO Se validarán los parámetros de entrada para garantizar que los datos proporcionados cumplan con reglas predefinidas, incluyendo la restricción a caracteres permitidos. Esta validación se realizará en el servidor para evitar su omisión. La sanitización de datos también es obligatoria para eliminar caracteres peligrosos que puedan ser usados en ataques como inyección de SQL o XSS, según las directrices de la norma para el desarrollo seguro (ASVS V5.1).
DIR_31 Control de tipado
OBLIGATORIO Establecer límites de longitud en las entradas y utilizar tipos de datos fuertemente tipados para garantizar la seguridad y estabilidad de la aplicación. Definir una longitud máxima previene ataques como desbordamiento de búfer, y usar tipos de datos adecuados asegura una manipulación segura y consistente. Se validará que los datos recibidos corresponden al tipo esperado y se manejarán adecuadamente los errores de conversión conforme a la norma para el desarrollo seguro (ASVS V5.1).
DIR_32 Sanitización de datos de entrada
OBLIGATORIO Se depurarán los datos de entrada para garantizar que no contengan contenido malicioso. La eliminación o escape de caracteres especiales y la validación de la estructura de los datos evita ataques como la inyección de código. Esta medida es obligatoria para proteger la integridad del sistema, de acuerdo con la norma para el desarrollo seguro (ASVS V5.2).
DIR_33 Sanitización de entradas de código
OBLIGATORIO Se depurarán entradas de código para eliminar cualquier código potencialmente peligroso, como scripts o etiquetas HTML, que los usuarios intenten introducir. Esto previene ataques de inyección de código y protege la integridad de la aplicación, siguiendo las directrices de la norma para el desarrollo seguro (ASVS V5.2).
DIR_34 Codificación de salidas
OBLIGATORIO Codificar las salidas para asegurar que los datos devueltos al usuario estén correctamente escapados y formateados, evitando ataques de inyección de código como el cross-site scripting (XSS). Esta medida implica el uso de técnicas como la codificación HTML. Es obligatorio implementar la codificación de salidas para proteger la integridad del sistema conforme a las directrices de la norma para el desarrollo seguro (ASVS V5.3).
DIR_35 Prevención de ataques XSS
OBLIGATORIO Prevenir ataques XSS para la seguridad de las aplicaciones web. Si los datos maliciosos se almacenan en la base de datos, es obligatorio usar técnicas de codificación segura como Encode.forHtml() antes de presentar los datos al usuario. También se recomienda utilizar encabezados de seguridad HTTP como Content-Security-Policy (CSP) para limitar la ejecución de scripts no confiables. Estas medidas seguirán las directrices de la norma para el desarrollo seguro (ASVS V5.3).
DIR_36 Cifrado
OBLIGATORIO Se utilizarán algoritmos criptográficos robustos, como AES y RSA, para garantizar la protección efectiva de los datos almacenados. Estos algoritmos ofrecen un alto nivel de seguridad y resistencia frente a ataques criptoanalíticos. Es obligatorio seguir estas prácticas para asegurar la confidencialidad de los datos, según las directrices de la norma para el desarrollo seguro (ASVS V6.2).
DIR_37 Aleatoriedad segura
OBLIGATORIO Generar valores aleatorios de alta entropía para garantizar la seguridad de las claves criptográficas. Estos valores, utilizados como semillas, deben ser seguros y difíciles de predecir, reforzando así la robustez del sistema criptográfico. Esta práctica es obligatoria conforme a las directrices de la norma para el desarrollo seguro (ASVS V6.3).
DIR_38 Manejo de errores
OBLIGATORIO Establecer mecanismos de manejo seguro de errores y excepciones para evitar la exposición de detalles técnicos que puedan ser explotados por atacantes. Se debe registrar los errores internamente y proporcionar mensajes de error genéricos a los usuarios, sin revelar información sensible. Estos controles se implementarán siguiendo las directrices de la norma para el desarrollo seguro.
DIR_39 Carga de archivos
OBLIGATORIO Establecer mecanismos de manejo seguro de la carga de archivos para prevenir vulnerabilidades que comprometan la seguridad de la aplicación. Es obligatorio implementar medidas de seguridad robustas, como la validación del tipo, tamaño de archivo, el uso de directorios seguros y la restricción de tipos de archivos permitidos. Estas prácticas siguen las directrices de la norma para el desarrollo seguro (ASVS V12.1).
DIR_40 Archivos maliciosos
OBLIGATORIO Para prevenir ataques relacionados con la carga de archivos maliciosos, se implementarán medidas de seguridad rigurosas, como la validación y filtrado de los archivos cargados. Esto incluye la verificación del tipo, tamaño y extensión de los archivos, asegurando que solo se acepten archivos seguros y legítimos. Estas medidas deben seguirse según las directrices de la norma para el desarrollo seguro (ASVS V12.1).
Pruebas
DIR_41 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_42 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_43 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_44 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.
Anexo: estándares
Componentización e interoperabilidad
Los estándares de componentes web son esenciales para garantizar que las SPA sean modulares y reutilizables. Estos estándares incluyen características como la encapsulación de estilos y funcionalidades, la personalización mediante atributos y propiedades, y el aislamiento de dependencias, facilitando la interoperabilidad entre módulos
Los componentes web permiten definir elementos personalizados que se integran directamente en el DOM, sin necesidad de dependencias específicas de un framework. Esto asegura que los módulos de una SPA puedan operar de manera autónoma, respetando los principios de independencia y separación de responsabilidades, al tiempo que mantienen una comunicación estandarizada entre módulos desarrollados con diferentes tecnologías.
El uso de componentes web en SPA seguirá estas directrices:
- Utilizar Custom Elements para definir elementos personalizados con funcionalidad específica que puedan ser reutilizados en toda la aplicación.
- Implementar Shadow DOM para encapsular estilos y comportamientos, asegurando que los componentes sean independientes y no afecten otros elementos del DOM.
- Diseñar con HTML Templates para reutilizar estructuras y estilos, optimizando la consistencia y la mantenibilidad del sistema.
Referencias:
Diseño de APIs RESTful
El diseño RESTful establece principios y mejores prácticas para la interacción entre las SPAs y los servicios backend mediante HTTP. Este enfoque asegura una comunicación consistente, eficiente y fácil de usar, facilitando la integración entre módulos y reduciendo errores.
El estándar RESTful define operaciones sobre recursos a través de verbos HTTP como GET, POST, PUT y DELETE, utilizando rutas claras y semánticas. La interacción se basa en códigos de estado estándar (por ejemplo, 200 OK, 404 Not Found) y formatos de datos como JSON para garantizar respuestas ligeras, predecibles y fácilmente consumibles por las SPA.
Las SPA seguirán las siguientes prácticas en el consumo de APIs RESTful:
- Separación de responsabilidades: Cada endpoint debe representar un recurso específico y realizar una única tarea, alineándose con los principios de diseño modular.
- Idempotencia: Asegurar que las operaciones como PUT y DELETE puedan repetirse sin cambiar el estado del recurso más de lo necesario.
- Consistencia en la estructura: Mantener rutas y formatos de datos consistentes en toda la API para simplificar su consumo y reducir errores.
- Uso de códigos de estado: Emplear códigos HTTP estándar para indicar el resultado de las operaciones y facilitar la depuración.
Referencias:
Custom Events
Los Custom Events permiten la creación de eventos personalizados dentro del modelo de eventos del DOM, facilitando la comunicación eficiente y desacoplada entre componentes de una Single Page Application (SPA).
Los Custom Events son un estándar oficial definido por el W3C que habilita la emisión y propagación de eventos personalizados en el DOM. Esta funcionalidad permite que diferentes componentes dentro de una SPA interactúen de manera independiente, utilizando el modelo de burbujeo y captura. Los eventos personalizados incluyen datos estructurados mediante el objeto detail, lo que facilita el intercambio de información clara y específica entre módulos.
Los componentes en una SPA pueden emitir Custom Events utilizando dispatchEvent para notificar cambios o acciones relevantes. Otros componentes o el contenedor principal pueden suscribirse a estos eventos mediante addEventListener para reaccionar a las notificaciones. Los eventos deben tener nombres descriptivos y datos bien estructurados en su objeto detail para garantizar una comunicación clara y predecible entre módulos.
Referencias:
Web Messaging
El estándar Web Messaging del W3C permite la comunicación asincrónica entre distintos contextos de ejecución en el navegador, como iframes, ventanas o aplicaciones cargadas dinámicamente. Este mecanismo facilita el intercambio seguro de información entre componentes que se ejecutan en contextos aislados.
Un componente de la SPA puede enviar mensajes a otro contexto o al contenedor utilizando el método postMessage. El receptor debe implementar un listener con el evento message para capturar los mensajes entrantes y validarlos, comprobando tanto el contenido como el origen del mensaje. Los mensajes deben seguir un formato estructurado y predecible, utilizando identificadores claros que permitan clasificar el tipo de mensaje y su propósito.
Referencias:
Seguridad
Content Security Policy (CSP)
La Política de Seguridad de Contenidos (CSP) es un estándar que protege las aplicaciones SPAs contra amenazas como inyecciones de código y ataques Cross-Site Scripting (XSS), asegurando un entorno de ejecución controlado y seguro.
La CSP permite definir reglas estrictas sobre qué recursos pueden ser cargados o ejecutados por el navegador, limitando la exposición a fuentes externas no confiables. Esto es especialmente importante en aplicaciones SPA, donde múltiples recursos y scripts son utilizados, ya que previene la ejecución de código malicioso, incluso cuando los módulos son desarrollados y gestionados por equipos separados.
Cada SPA definirá políticas de seguridad CSP estrictas, especificando orígenes permitidos para scripts, hojas de estilo, imágenes y otros recursos. Las políticas deben configurarse para:
- Permitir únicamente orígenes explícitamente aprobados para cada tipo de recurso (por ejemplo, script-src, style-src, img-src).
- Bloquear el uso de scripts en línea y eval() cuando sea posible, utilizando hashes o nonces para garantizar la seguridad del código ejecutado.
- Monitorizar y ajustar las políticas CSP en entornos de desarrollo y producción para evitar falsos positivos que puedan afectar el rendimiento o la funcionalidad de la SPA.
Referencias:
HTTPS/SSL
HTTPS utiliza SSL/TLS para cifrar las comunicaciones y autenticar la identidad del servidor mediante certificados digitales válidos. Esto garantiza que los datos intercambiados sean privados, íntegros y que el servidor con el que interactúa la SPA sea legítimo. En contextos donde la seguridad es crítica, se puede implementar autenticación mutua utilizando certificados tanto del servidor como del cliente.
La SPA será servida mediante HTTPS para proteger la confidencialidad e integridad de la información:
- Cifrado de Comunicaciones: Todas las solicitudes y respuestas deben transmitirse a través de HTTPS para evitar ataques de tipo Man-in-the-Middle (MITM) y garantizar la privacidad de los datos.
- Autenticación del Servidor: Los servidores que alojan la SPA deben presentar certificados digitales válidos emitidos por una autoridad de confianza, asegurando su identidad ante los clientes.
- Comunicación entre dominios: En escenarios donde la SPA interactúa con servicios o APIs en otros dominios, todos los endpoints deben implementar HTTPS.
- Autenticación mutua (opcional): En entornos de alta seguridad, se puede implementar un sistema donde tanto el servidor como el cliente presenten certificados válidos para autenticar mutuamente su identidad.
Referencias:
OAuth2
En OAuth2, los tokens de acceso permiten que las SPAs interactúen con recursos protegidos, limitando el acceso únicamente a lo autorizado por el usuario. El protocolo facilita la delegación de autorización, evitando la necesidad de compartir contraseñas. También incluye capacidades para renovar tokens y revocar accesos, lo que mejora la seguridad frente a riesgos como el robo de tokens o accesos no autorizados.
Las SPA que implementen OAuth2 cumplirán con las siguientes directrices:
- Autorización Delegada: Cada SPA debe obtener un access token de un servidor de autorización antes de acceder a servicios o APIs protegidas.
- Control de Acceso: El access token debe ser incluido en las solicitudes para garantizar que el acceso se limite a los recursos y acciones autorizados.
- Renovación de Tokens: Los tokens deben configurarse con una duración limitada y renovarse periódicamente mediante refresh tokens, reduciendo riesgos en caso de compromisos de seguridad.
- Revocación de Acceso: Los usuarios deben tener la capacidad de revocar el acceso otorgado a la SPA, lo que invalida los tokens y asegura el control sobre los datos personales.
Referencias:
JSON Web Token (JWT)
Un JWT está compuesto por tres partes: encabezado, payload (información codificada) y firma digital. Esto garantiza que la información no ha sido alterada durante su transmisión. El uso de JWT permite a las SPAs autenticar usuarios y definir permisos específicos, facilitando un control de acceso granular y seguro. Además, su diseño compacto lo hace ideal para escenarios en los que el rendimiento es crítico.
La SPA implementará el uso de JWT bajo estas directrices:
- Autenticación: Cada solicitud realizada a APIs protegidas debe incluir un JWT en el encabezado de autorización (Authorization: Bearer <token>), validando así la identidad del usuario.
- Validación de Integridad: Los tokens deben ser validados utilizando una clave secreta compartida o un par de claves pública/privada, asegurando que no han sido manipulados.
- Scope y Roles: El payload del token debe contener información relevante como los permisos (scope) y roles del usuario, limitando el acceso a recursos según el contexto de la solicitud.
- Expiración: Los tokens deben configurarse con un tiempo de expiración corto (exp) para minimizar el riesgo en caso de compromiso. Es recomendable utilizar tokens de actualización (refresh tokens) para mantener sesiones activas de manera segura.
Referencias:
Diseño y accesibilidad
Web Content Accessibility Guidelines (WCAG)
Las Pautas de Accesibilidad para el Contenido Web (WCAG) son un estándar internacional diseñado para garantizar que las aplicaciones, incluidas las SPAs, sean accesibles para personas con discapacidades. Estas pautas promueven la creación de interfaces inclusivas y usables por todos los usuarios.
Las WCAG establecen principios fundamentales para el diseño accesible: perceptibilidad, operabilidad, comprensibilidad y robustez. Estas pautas aseguran que las interfaces sean navegables y funcionales para usuarios con discapacidades visuales, auditivas, motoras o cognitivas. En el contexto de las SPAs, cumplir con WCAG implica garantizar que los elementos interactivos sean accesibles y que las interfaces respondan correctamente a tecnologías de asistencia como lectores de pantalla.
La SPA cumplirá con niveles de accesibilidad definidos (A, AA o AAA), aplicando las siguientes buenas prácticas:
- Soporte para lectores de pantalla: Garantizar que los elementos de la interfaz sean identificables y descriptivos mediante atributos como aria-label y role.
- Navegación mediante teclado: Asegurar que todas las funciones sean accesibles sin un ratón, utilizando una navegación intuitiva por teclado.
- Contraste adecuado de colores: Cumplir con las pautas de contraste de colores para garantizar que el contenido sea perceptible por usuarios con discapacidades visuales.
- Alternativas textuales: Proporcionar descripciones para elementos no textuales como imágenes y gráficos.
Referencias:
Gestión de Estado
La gestión del estado en SPAs debe adherirse a principios de desacoplamiento, garantizando que cada módulo administre su propio estado y solo comparta información estrictamente necesaria. Este enfoque asegura modularidad, escalabilidad y flexibilidad en la arquitectura.
El desacoplamiento del estado permite que los módulos dentro de una SPA funcionen de manera autónoma, evitando dependencias innecesarias entre ellos. Esto reduce el riesgo de conflictos en la sincronización, facilita el mantenimiento y mejora la capacidad del sistema para escalar a medida que crecen los requisitos de la aplicación.
El estado debe estructurarse en ámbitos locales, donde cada componente administre su propio estado internamente. La sincronización de datos compartidos debe realizarse mediante eventos desacoplados o servicios centralizados únicamente cuando sea indispensable. Este enfoque asegura que los módulos interactúen de manera consistente sin comprometer la independencia de cada uno.
Diseño responsivo
El Responsive Web Design (RWD) es un estándar que asegura que las interfaces de usuario de las SPAs se adapten a diferentes tamaños y resoluciones de pantalla, proporcionando una experiencia consistente y optimizada en cualquier dispositivo.
El RWD establece principios que permiten que las interfaces ajusten automáticamente su diseño y funcionalidad según las características del dispositivo utilizado. Esto incluye el uso de técnicas como unidades flexibles, consultas de medios y diseño fluido, garantizando que las SPAs sean accesibles y funcionales en teléfonos móviles, tabletas y pantallas grandes.
Las SPA se implementarán siguiendo las mejores prácticas de RWD:
- Utilizar unidades flexibles como porcentajes o unidades relativas (em, rem) en lugar de valores fijos para definir tamaños y espaciados.
- Aplicar media queries para personalizar el diseño y comportamiento en función de las dimensiones y capacidades del dispositivo.
- Incorporar layouts fluidos y técnicas de diseño modular que permitan que los elementos se reorganicen o escalen según el espacio disponible.
Referencias: