Subdirección de las Tecnologías de la Información y Comunicaciones
Área de Gobernanza y Calidad
Versión
Tabla de Contenido
Cumplimiento Normativo
Las normas expuestas son de obligado cumplimiento. La STIC podrá estudiar los casos excepcionales los cuales serán gestionados a través de los responsables del proyecto correspondiente y autorizados por el Área de Gobernanza de la STIC. Asimismo cualquier aspecto no recogido en estas normas deberá regirse en primera instancia por las guías técnicas correspondientes al esquema nacional de seguridad y esquema nacional de interoperabilidad según correspondencia y en su defecto a los marcos normativos y de desarrollo software establecidos por la Junta de Andalucía, debiendo ser puesto de manifiesto ante la STIC.
La STIC se reserva el derecho a la modificación de la norma sin previo aviso, tras lo cual, notificará del cambio a los actores implicados para su adopción inmediata según la planificación de cada proyecto.
En el caso de que algún actor considere conveniente y/o necesario el incumplimiento de alguna de las normas y/o recomendaciones, deberá aportar previamente la correspondiente justificación fehaciente documentada de la solución alternativa propuesta, así como toda aquella documentación que le sea requerida por la STIC para proceder a su validación técnica.
Contacto Arquitectura: l-arquitectura.stic@juntadeandalucia.es
Histórico de cambios
Los cambios en la normativa vendrán acompañados de un registro de las modificaciones. De este modo se podrá realizar un seguimiento y consultar su evolución. Ordenándose de mas recientes a menos recientes, prestando especial cuidado a las cabeceras de la tablas dónde se indican las fechas de entrada en vigor y versión.
2. Introducción
El objetivo de este documento es documentar pormenorizadamente las responsabilidades, mecanismos y detalles para integrar un host con un MicroFrontend.
2.1 Definiciones
- HOST: Aplicación contenedora, que hospeda y que requiere de la funcionalidad de otro contexto.
- MICROFRONTEND: Encapsulación lógica de negocio, que contiene una funcionalidad concreta en su dominio y que está diseñada para incorporarse en un host.
- FRAGMENT: un componente del microfrontend que representa una parte específica de una aplicación que tiene una funcionalidad concreta y es capaz de operar de forma independiente. Son una forma de dividir una aplicación en partes más pequeñas y manejables que se pueden desarrollar y mantener de forma independiente.
- CAPABILITY: es una funcionalidad específica que un fragmento puede proporcionar a otras partes de la aplicación. Se refiere a una interfaz o un contrato que un fragmento puede ofrecer para ser utilizado por otros fragmentos o microfrontends. Permiten la interoperabilidad entre diferentes partes de la aplicación al definir claramente qué funcionalidades están disponibles y cómo se pueden acceder
Un host es la aplicación contenedora, que tiene la necesidad de incluir una funcionalidad provista desde otro contexto funcional a través de un microfrontend.
3. Instalación
Se deberá consultar la documentación del microfrontend para conocer las posibilidades de instalación que ofrecen.
Los bundelizados con librerías externas aumentan la garantía de que no haya conflictos entre librerías pero hace una gestión ineficiente del uso de dependencias haciendo que el peso del entregable aumente y que el código bundelizado de esa librería se descargue tantas veces como el numero de bundles donde se encuentre.
En caso de que el host quiera proporcionar las librerías externas (bundlelización sin librerías externas, importmaps) el host deberá consultar y garantizar la compatibilidad con la versión establecida por el microfrontend
3.1 Run Time
La instalación se hace al ejecutar el host
- Embebida: la documentación del microfrontend especificará la url de integración por entorno. Este tipo de instalación será siempre con integración Aislada
- Script
- full: con librerías externas
- kernel: sin librerías externas
- RECOMENDADAimport maps
| EMBEBIDA | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| PE-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| PE-02 | El host deberá usar el componente @sas/wc-stic-isolated-microfrontend | Revisión de dependencias y Revisión de código |
| PE-03 | El host no deberá crear un iframe | Revisión de código |
| SCRIPT | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| PS-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| PS-02 | Se deberán utilizar ÚNICAMENTE scripts del CDN del SAS | Revisión de código |
| PS-03 | Si se usa la versión full del microfrontend, se debe tener cuidado por posibles conflictos con las librerías propias del host | Revisión de la consola de desarrollador del navegador que no hay errores y del funcionamiento correcto del microfrontend |
| PS-04 | Si se usa la versión kernel del microfrontend, el host debe proporcionar las dependencias necesarias del microfrontend | Revisión de la consola de desarrollador del navegador que no hay errores y del funcionamiento correcto del microfrontend |
| PS-05 | Se debe usar importación dinámica de módulos para una optima descarga y carga de módulos dentro del host | Revisión de código |
| Importmap | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| PIM-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| PIM-02 | Se deberán utilizar ÚNICAMENTE scripts del CDN del SAS | Revisión de código |
| PIM-03 | Se deberán incluir la configuración de importmap establecida por el microfrontend | Revisión de código |
| PIM-04 | Se debe usar importación dinámica de módulos para una optima descarga y carga de módulos dentro del host | Revisión de código |
3.2 Build Time
La instalación se hace durante la construcción del host
- A través de un gestor de paquetes (npm, yarn, pnpm etc...).
| Gestor de paquetes | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| GP-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| GP-02 | Se deberán utilizar ÚNICAMENTE paquetes obtenidos a través de la DML del SAS | Construcción correcta a través del Jenkins del SAS |
| GP-03 | Se deberán incluir en la sección dependencies del package.json de la aplicación | Revisión de código y construcción correcta a través del Jenkins del SAS |
| GP-04 | En caso de ser un aplicación legacy, server render, se deberá incluir un mecanismo (Maven, Ant, Nuget) en tiempo de construcción compatible con proyectos npm que descargue las dependencias de la DML y las copie a la carpeta de script de la aplicación legacy. | Construcción correcta a través del Jenkins del SAS |
4. Integración
Se deberá consultar la documentación del microfrontend para conocer las posibilidades de integración que ofrecen. Estas pueden ser de dos tipos:
- Aislada (Isolated): Esta opción tiene la ventaja de que ofrece un contexto tecnológico que evita conflictos tanto de librerías como de estilos. Tiene la desventaja de que, al construir un contexto de ejecución propio e independiente, debe obtener las librerías para su propio contexto, impidiendo la posibilidad de compartir módulos entre microfrontends, o entre el host y el microfrontend.
- RECOMENDADA Directa : Siempre que sea posible y se ofrezca la posibilidad esta es la opción más eficiente y la recomendada por parte de las STIC. Permite una gestión más eficiente de los recursos.
A nivel de uso, el objetivo es que para el host no exista diferencia a la hora de usar una integración aislada de una no aislada. Los contratos y la interacción deben ser exactamente la misma.
| Aislada | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| AIS-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| AIS-02 | El host debe usar el componente @sas/wc-stic-isolated-microfrontend o alguna extensión de negocio del componente | Revisión de dependencias y Revisión de código |
| AIS-03 | Este tipo de integración debe ser previamente aprobada por el departamento de arquitectura de la STIC | Ticket Jira de decisión técnica en el proyecto Host |
| AIS-04 | Si se desea una integración completa, el host debe seguir las pautas de creación de theming definidas en el apartado Theming | Revisión visual del estilo aplicado para el microfrontend |
| AIS-05 | Para interactuar con un host se deben hacer uso de los mecanismos definidos en la sección de comunicación | Revisión de código |
| AIS-06 | El host es el responsable de determinar la correcta estrategia de carga del microfrontend:
| Uso de herramientas como lighthouse que miden los tiempos de carga de los módulos |
| Directa | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| DIR-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| DIR-02 | Si se desea una integración completa, el host debe seguir las pautas de creación de theming definidas en el apartado Theming | Revisión visual del estilo aplicado para el microfrontend |
| DIR-03 | Para interactuar con un host se deben hacer uso de los mecanismos definidos en la sección de comunicación | Revisión de código |
| DIR-04 | El host es el responsable de determinar la correcta estrategia de carga del microfrontend:
| Uso de herramientas como lighthouse que miden los tiempos de carga de los módulos |
5. Theming
Se deberá consultar la documentación del microfrontend para conocer las posibilidades de theming y personalización de estilos que se ofrecen:
- Aislado: El host y el theming no comparten estilos y cada uno conservará los suyos al integrarse. Si se quieren compartir, el host debe extender o estar desarrollado con el theming de la stic @sas/wc-stic-theme
- RECOMENDADADirecta: El host le comparte su theming (@sas/wc-stic-theme ) y el microfrontend lo carga y se adapta tanto al theming base del host como a las características definidas por el usuario en la configuración de la interfaz del host (densidad, contrastes, accesibilidad etc)
| Aislado | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| TAIS-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| TAIS-02 | El host debe tener cargado el theme de la stic. En caso contrario se instanciará el theme por defecto de la stic | Revisión de dependencias, revisión de código y revisión visual del estilo aplicado para el microfrontend |
| Directa | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| TDIR-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| TDIR-02 | El host debe tener cargado el theme de la stic. En caso contrario no se visualizarán con corrección los componentes del microfrontend | Revisión de dependencias, revisión de código y revisión visual del estilo aplicado para el microfrontend |
6. Comunicación
La comunicación con el microfrontend deberá ser siempre la estándar. Se deberá consultar la documentación de la api definida del microfrontend para conocer las posibilidades de comunicación.
6.1 Información
- Host -> Microfrontend: lo host hará uso de las propiedades del microfrontend siempre que quiera realizar un cambio en el estado del mismo.
- Microfrontend → Host: el microfrontend hará uso de los eventos para notificar al host cualquier cambio de estado interno o acción que se haya realizado internamente que el negocio del microfrontend considere interesante compartir con el host
| Información | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CINFO-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| CINFO-02 | El host comunicar los datos a través de propiedades definidas en el api del microfrontend | Test de integración |
| CINFO-03 | El host recibirá respuesta o notificaciones del microfrontend a través de los eventos definidos en el api del microfrontend | Test de integración |
| CINFO-03 | Los errores ocurridos dentro del microfrontend se comunicarán al host a través de un evento de error | Test de integración |
6.2. Routing
Se deberá consultar la documentación del microfrontend para conocer las posibilidades de enrutado que se ofrecen. El enrutado del microfrontend será siempre interno virtual, es decir, que no se hará a través de la url del navegador, permitiendo así navegar de forma independiente y a través de múltiples microfrontends dentro de la misma ruta externa del host. El microfrontend ofrecerá en su documentación:
- El listado de rutas y parámetros en caso de ser necesario
- Una propiedad a través de la cual el host le puede comunicar al microfrontend a que ruta necesita navegar.
| Routing | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CROU-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| CROU-02 | El host indicará a que ruta, de la lista definida, desea navegar a través de la propiedad definida para ello. | Test de integración |
| CROU-03 | En caso de que el host indique alguna ruta errónea, a través de eventos, se le notificará | Test de integración |
6.3. Seguridad
Se deberá consultar la documentación del microfrontend para conocer las posibilidades de seguridad concreta que se ofrecen.
- El host deberá proveer un jwt al microfrontend a través de la propiedad correspondiente.
- El jwt deberá estar firmado
- El jwt deberá tener el scope adecuado del microfrontend asignado LUIS MARTINEZ FONTIVEROS como ves este punto?
- El host deberá exponer y compartir una url con el jks que ofrezca la clave publica de firmado para poder validarlo
- En caso de que el microfrontend requiera una claim con MACO se deberá consultar la normativa al respecto
| Seguridad | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CSEC-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| CSEC-02 | El host compartirá su jwt token con el microfrontend que lo requiera, a través, de la propiedad definida para ello | Test de integración |
| CSEC-03 | En caso de que el host no tenga permisos o alguna otra situación errónea de seguridad, el microfrontend notificará un error a través del evento definido para ello. | Test de integración |
6.4. Configuración
- Externa: Se deberá consultar la documentación del microfrontend para conocer las posibilidades de configuración externa concreta que se ofrecen. Dicha configuración se compartirá, como indica el estándar de comunicación, a través de la propiedad que esté definida en la api para dicho propósito.
| Configuración | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CCNF-01 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
| CCNF-02 | El host NO es responsable de la configuración interna del microfrontend | Test de integración |
| CCNF-03 | El host podrá configurar el microfrontend a través de las propiedades definidas en la documentación par tal objetivo | Test de integración |
| CCNF-04 | El host NO transmitirá información sensible a través de las propiedades del microfrontend sin que estén debidamente codificada o cifrada por un servidor. | Test de integración |
| CCNF-05 | En caso de que haya algún error en la información de configuración transmitida se notificará el error a través del evento definido para ello | Test de integración |
6.5. Estado Compartido
Se entiende por estado compartido, cualquier información de estado del host relevante para el microfrontend, o cualquier información de estado del microfrontend relevante para el host.| Estado Compartido | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CEC-01 | El host será el único responsable de mantener, en caso de que lo considere necesario, el estado del microfrontend. | Revisión de código |
| CEC-02 | El microfrontend mantendrá de manera interna y aislada su propio estado. | Revisión de código |
| CEC-03 | En caso de que se considere relevante a nivel del negocio, microfrontend notificará, como indica el estándar de comunicación, a través de eventos el cambio de su estado interno | Test de integración |
| CEC-04 | En ningún caso se asumirá que el microfrontend tiene la capacidad de acceder al estado del host de manera directa | Revisión de código |
| CEC-05 | Cualquier comunicación sobre el estado que el host necesite notificar al microfrontend será , como indica el estándar de comunicación, a través de propiedades expuestas por el propio microfrontend | Test de integración |
7. Versionado
El versionado de los microfrontend se llevará a cabo respetando el estándar de Semantic Version.
| Versionado | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CEC-01 | El host tendrá asegurada la retrocompatibilidad de los desarrollos realizados para un microfrontend dentro de una misma mayor. | Test de integración |
| CEC-02 | En una integración en runtime, el host recibirá las actualizaciones dentro de una misma mayor de manera automática | Smoke test |
| CEC-03 | En una integración en buildtime, el host será el responsable de mantenerse actualizado | Test de integración |
| CEC-04 | En caso de que haya algún error en la integración se notificará el error a través del evento definido para ello | Test de integración |
8. Conflictos
Se identifican 4 tipos de conflictos que pueden surgir a la hora de llevar a cabo una integración con microfrontend:
- Librerías externas
- Misma librería diferentes versiones incompatibles dentro del mismo contexto de carga de módulos (no aislado)
- Variables Globales
- Que dos librerías (externas o internas) hagan uso de una variable global con el mismo nombre
- Para aplicaciones basadas en la nueva arquitectura de referencia (WC) no está permitido el uso de variables globales al contexto
- Para aplicaciones legacy y que no estén sujetos a la normativa de la nueva arquitectura de referencia, se debe limitar el uso de variables globales a las ya existentes sin poder añadir nuevas variables, e intentando en la medida de lo posible ir eliminando la existencia de las mismas, dando prioridad aquellas que al realizar una integración estén generando conflicto
- Estilos
- Todos los microfrontend estarán desarrollando haciendo uso de la nueva arquitectura de referencia, es decir, estarán desarrollados con Web Component. Esto implica que la propia tecnología ofrece un contexto aislado sobre los estilos evitando así que de forma general el host pueda entrar en conflicto con los estilos del microfrontend.
- El único escenario donde pudiera haber un conflicto de estilos sería si el host hace uso de variables css y estas tienen el mismo nombre que el proporcionado en el componente de la stic (stic-theme) y definidas en el Sistema de diseño . No está permitido el uso de dichas variables css fuera del componente del stic-theme
- Registro de componentes (CustomElements): El registro de un mismo componente (mismo tag html) puede generar un conflicto y por tanto un error en la consola relacionado con el CustomRegistry.
| Librerías externas | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CLE-01 | El host debe evaluar los posibles conflictos con las librerías externas documentadas en el api del microfrontend | Revisión del manual del package.json |
| CLE-02 | El host debe decidir si puede alinear la versión de la librería conflictiva identificada. En caso de no ser posible debe aislar el uso del microfrontend. | Test unitarios y Test de integración |
| Variables Globales | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CVG-01 | El host no debe crear ni hacer uso de variable globales. | Revisión del manual del package.json |
| CVG-02 | El host debe evaluar si algún conflicto no puede ser resuelto desde el host. En caso de no ser posible debe aislar el uso del microfrontend. | Test unitarios y Test de integración |
| Estilos | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CE-01 | El host debe evaluar los posibles conflictos de variables CSS con el theme de la stic(@sas/wc-stic-theme). microfrontend | Revisión del manual de los ficheros CSS o consola del desarrollador del navegador |
| CE-02 | El host debe renombrar las variables css conflictivas y añadiéndole el contexto del host. En caso de no ser posible debe aislar el uso del microfrontend. | Test unitarios y Test de integración |
| CE-03 | El host, salvo autorización expresa del departamento de arquitectura a través de un ticket Jira de decisión técnica en el proyecto Host, no podrá redefinir el valor de dichas variables | Revisión de código |
| Registro de componentes: Build Time | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CRCBT-01 | El host debe garantizar la unicidad de las versiones de los componentes compartidos con el microfrontend utilizado. | Revisión del manual del package.json |
| CRCBT-02 | El host deberá bundelizar el proyecto al completo para garantizar la unicidad de los componentes. | Test de integración |
| CRCBT-03 | En caso de recurrir a opciones como el peerdependency y/o el override para determinar las versiones a utilizar, el host asumirá la responsabilidad de un posible funcionamiento inesperado por parte del microfrontend | Test de integración |
| Registro de componentes: RunTime | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CRCRT-01 | El host debe verificar que los componentes se encuentran en la misma mayor, que aseguran retrocompatibilidad, que los que usa el microfrontend | Revisión del manual del package.json |
| CRCRT-02 | La bundlelización del host debe obviar las dependencias externas y estas deben ser proporcionadas a través de los importmaps | Test de integración |
| CRCRT-03 | El host debe mergear los importmaps suyos con los definidos por el microfrontend | Revisión del manual de los importmaps |
9. Documentación
Deberá dejar cumplimentada la plantilla de integración con cada uno de los microfrontend
Normativas de la arquitectura de referencia tecnológica para el desarrollo frontal de software
| Normativa | Descripción | Versión Activa | Fecha de activa | Versión Pre-Release | Fecha de Pre-release |
|---|---|---|---|---|---|
Clientes JAXRS - FHIR RESTFULL | Normas y recomendaciones sobre como crear servicios y clientes REST orientados a protocolo. | N/A | N/A | 1.0 |
|
Guías de desarrollo frontal
| Normativa | Descripción | Versión Activa | Fecha de activa | Versión Pre-Release | Fecha de Pre-release |
|---|---|---|---|---|---|
| Desarrollo de instaladores en entornos k8s con helm | Esta guía cubre las necesidades de generación de plantillas helm, necesarias para articular las operaciones de instalación de las soluciones basadas en contenedores. | 1.0 |
| - | - |
| Directrices de implementación enfocadas en la calidad. | Está guía proporciona una serie de pautas para el diseño y el desarrollo que facilitan la mantenibilidad, la legibilidad y el cambio del código. | 1.0 |
| ||
| Implementación para arquitecturas limpias | Esta guía pretende impulsar los diseños de las aplicaciones que están basadas en Arquitecturas Limpias y Domain Centric que permitirán un diseño orientado al negocio y un desarrollo que facilite el cambio. | 1.0 |
|
Terminología
| Concepto | Definición |
|---|---|
| Microfrontend | Encapsulación lógica de negocio, que contiene una funcionalidad concreta en su dominio y que está diseñada para incorporarse en un host. |
| Isolated-Microfrontend | Microfrontend que dispone de un contexto de ejecución aislado |
Referencias
Vista general
Herramientas de contenido
- Impreso por Atlassian Confluence 8.7.2