de_DEen_USes_ESfa_IRfr_FRhi_INid_IDjapl_PLpt_PTru_RUvizh_CNzh_TW

Profundización en el nivel 3 del modelo C4: dominar los diagramas de componentes para revelar la estructura interna y las responsabilidades

¿Qué es un diagrama de componentes C4?

El diagrama de componentes es Nivel 3 en el modelo C4 de Simon Brown. Se enfoca en un contenedor específico (del diagrama de contenedores del nivel 2) para mostrar:

The Ultimate Guide to C4 Model Visualization with Visual Paradigm's AI Tools - ArchiMetric

  • Los bloques lógicos de construcción (componentes) que conforman ese contenedor.

  • Cómo interactúan esos componentes interactúan entre sí.

  • Responsabilidades y tecnologías de implementación (a un nivel superior al de las clases — piense en Beans de Spring, módulos, servicios, controladores, fachadas, etc.).

  • Interfaz clave interfaces o contratos entre componentes (a menudo implícitos a través de relaciones).

Aclaración importante: Un «componente» en C4 es no una clase. Es un agrupación lógica de clases detrás de una interfaz bien definida — algo que tiene una responsabilidad clara, puede desarrollarse, probarse y desplegarse de forma parcialmente independiente (dentro del contenedor), pero no es no desplegable por separado como un contenedor.

Ejemplos de componentes:

  • Controlador REST / Controlador web

  • Servicio / Caso de uso / Servicio de aplicación

  • Repositorio / Objeto de acceso a datos

  • Modelo de dominio / Entidad

  • Seguridad / Módulo de autenticación

  • Remitente de notificaciones

  • Fachada para sistema externo

  • Motor de reglas de negocio

  • Capa de caché

El diagrama permanecelógico / suficientemente independiente de la implementación— sin atributos de clase, firmas de métodos ni detalles completos de clases UML (eso es código de nivel 4, que es opcional y raro).

Cuándo crear un diagrama de componentes

Crear (y mantener) un diagrama de componentessolo cuando:

  • El contenedor elegido eslo suficientemente complejode manera que su estructura interna no sea evidente solo por su nombre y descripción.

  • Los nuevos miembros del equipo (especialmente desarrolladores de backend) preguntan con frecuencia: «¿Cómo se implementa realmente la característica X dentro de este servicio/API?»

  • Estásrefactorizando, dividiendo, oextrayendológica dentro de un contenedor y necesitas aclarar límites/responsabilidades.

  • Estás realizando discusiones detalladas sobrediscusiones de diseño, revisiones de código, o entregas de turno en llamada para un contenedor específico.

  • Quieres documentar decisiones arquitectónicas clave dentro de un contenedor (por ejemplo, arquitectura hexagonal, corte vertical, separación CQRS, punto de aplicación de seguridad).

  • Has identificado deuda técnica, clases diosas, o acoplamiento fuerte dentro de un contenedor y quieres visualizar la situación antes de la limpieza.

  • Estás incorporando desarrolladores o arquitectos senior que necesitan comprender rápidamente la estructura de módulos.

No hagas crear diagramas de componentes para:

  • Contenedores simples (API CRUD con un controlador + un servicio + un repositorio — estructura obvia).

  • La mayoría de los microservicios (a menudo lo suficientemente pequeños como para que el nivel de contenedor sea suficiente).

  • Contenedores de front-end (aplicaciones React/Vue — generalmente mejor mostrados con árboles de componentes o storybook).

  • Cuando el nivel 2 (contenedor) + una buena estructura/nomenclatura de código ya comunica todo lo necesario.

Simon Brown recomienda: La mayoría de los equipos pueden detenerse en el nivel 1 + 2. Solo pasa al nivel 3 para los complicados / riesgosos / centrales / de alta rotación contenedores.

¿Por qué usar diagramas de componentes? (Principales beneficios)

  • Aclara las responsabilidades internas — Muestra la separación de preocupaciones (por ejemplo, controladores frente a servicios frente a acceso a datos frente a integración externa).

  • Exponen el acoplamiento y las dependencias — Hace visible los componentes dioses, dependencias cíclicas o el exceso de dependencia del código de infraestructura.

  • Facilita una mejor incorporación y transición — Los desarrolladores comprenden los límites de los módulos más rápido que leyendo todos los archivos de origen.

  • Guía la refactorización y evolución — Base visual antes/después de dividir monolitos o introducir patrones (puertas y adaptadores, cortes verticales).

  • Permite revisiones de arquitectura y modelado de amenazas — Identifica dónde ocurren la validación, autorización, registro, etc.

  • Arquitectura como código — Cuando se almacena en PlantUML → versionado con la base de código, comparable, revisable en las solicitudes de pull.

  • Escalabilidad de la comunicación — Los desarrolladores senior se preocupan por las responsabilidades de los componentes; los junior se preocupan por dónde colocar el nuevo código.

Cómo crear un diagrama de componentes excelente (paso a paso + mejores prácticas)

  1. Elige UN contenedor — Comienza con el más complejo o crítico para el negocio (a menudo la API principal o servicio de backend).

  2. Copia el contexto desde el nivel 2 — Incluye actores externos (otros contenedores, personas, sistemas externos) que interactúan con este contenedor.

  3. Dibuja el límite del contenedor — Usa Límite_Contenedor en PlantUML para delimitar claramente “dentro de este contenedor”.

  4. Identifica los componentes — Pregunta:

    • ¿Cuáles son los módulos principales / Spring Beans / paquetes / contextos acotados dentro?

    • ¿Dónde llegan las solicitudes entrantes? (controladores/gestores)

    • ¿Dónde se orquesta la lógica de negocio?

    • ¿Dónde se accede a los datos / se almacenan en caché / se validan?

    • ¿Dónde se gestionan las preocupaciones transversales? (seguridad, registro)

    • ¿Alguna fachada / capa de protección contra corrupción con sistemas heredados/externos?

  5. Añade tecnología y descripción breve — Nombre, tecnología (Servicio Spring, Gestor .NET, Módulo Go, etc.), propósito breve (< 15 palabras).

  6. Definir interacciones — Mostrar dirección e intención (Usa, Llama, Lee desde, Publica eventos a). El protocolo suele omitirse a este nivel.

  7. Mejores prácticas

    • Limitar el alcance — Máximo 6 a 12 componentes por diagrama. Si hay más → crear vistas secundarias enfocadas (por ejemplo, “rebanada de autenticación”).

    • Nombrar de forma significativa — Prefiere “Servicio de colocación de pedidos” frente a “OrderService”.

    • Mostrar responsabilidades, no clases — Evita listar cada clase; agrupa lógicamente.

    • Usar íconos con moderación — Solo si aclaran la tecnología (íconos de Spring, .NET).

    • Habilitar leyenda — Ayuda a los lectores nuevos.

    • Mantener el diseño limpio — LAYOUT_WITH_LEGEND(), LAYOUT_TOP_DOWN().

    • Versión en el repositorio — Archivos .puml junto al código del contenedor.

    • Iterar — Actualizar durante picos de refactorización o revisiones trimestrales de salud arquitectónica.

Ejemplo de PlantUML – Aplicación de API del Sistema de Banca en Línea (estilo clásico de Big Bank plc)

Aquí tienes un ejemplo de producción utilizando la biblioteca oficial C4-PlantUML — la muestra del mundo real más comúnmente citada.

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Component.puml

title Diagrama de componentes: Sistema de banca en línea - Aplicación de API

' Actores / partes externas desde el nivel de contenedor
Container(spa, "Aplicación de página única", "JavaScript & Angular", "Proporciona la interfaz de usuario de banca en línea a través del navegador")
Container(mobile, "Aplicación móvil", "iOS/Android", "Proporciona funcionalidad limitada de banca móvil")
ContainerDb(database, "Base de datos de banca", "PostgreSQL", "Almacena preferencias del usuario, datos en caché y sesiones")
System_Ext(mainframe, "Sistema de banca central", "Mainframe – cuentas y transacciones principales")

' El contenedor al que estamos acercándonos
Container_Boundary(api, "Aplicación de API") {
    Component(signInCtrl, "Controlador de inicio de sesión", "Controlador REST de Spring MVC", "Maneja la autenticación y la creación de sesiones")
    Component(accountsCtrl, "Controlador de resumen de cuentas", "Controlador REST de Spring MVC", "Proporciona saldos y resúmenes de cuentas")
    Component(resetPwdCtrl, "Controlador de restablecimiento de contraseña", "Controlador REST de Spring MVC", "Gestiona el flujo de restablecimiento de contraseña")
    
    Component(security, "Componente de seguridad", "Bean de Spring", "Tokens JWT, hashing de contraseñas, verificación de roles")
    Component(accountService, "Componente de gestión de cuentas", "Bean de Spring / Servicio", "Orquesta consultas de cuentas y reglas de negocio")
    Component(mainframeFacade, "Fachada de banca del mainframe", "Bean de Spring", "Capa anti-corrupción para el mainframe heredado")
    Component(emailNotifier, "Componente de notificación por correo electrónico", "Bean de Spring", "Envía correos de confirmación y restablecimiento")
}

' Relaciones dentro del límite
Rel(signInCtrl, security, "Usa")
Rel(accountsCtrl, accountService, "Usa")
Rel(resetPwdCtrl, security, "Usa")
Rel(resetPwdCtrl, emailNotifier, "Usa")
Rel(accountService, mainframeFacade, "Usa")
Rel(accountService, database, "Lee desde y escribe en", "JDBC")
Rel(mainframeFacade, mainframe, "Usa", "XML/HTTPS")
Rel(emailNotifier, database, "Lee preferencias del usuario", "JDBC")

' Llamadas entrantes desde las interfaces front-end
Rel(spa, signInCtrl, "Usa", "JSON/HTTPS")
Rel(spa, accountsCtrl, "Usa", "JSON/HTTPS")
Rel(spa, resetPwdCtrl, "Usa", "JSON/HTTPS")
Rel(mobile, signInCtrl, "Usa", "JSON/HTTPS")
Rel(mobile, accountsCtrl, "Usa", "JSON/HTTPS")
Rel(mobile, resetPwdCtrl, "Usa", "JSON/HTTPS")

LAYOUT_WITH_LEGEND()
LAYOUT_LEFT_RIGHT()

@enduml

Esto genera:

  • Límite claro alrededor del contenedor de API

  • Agrupación lógica de controladores, servicios y fachadas

  • Responsabilidades precisas

  • Interacciones clave y dependencias

  • Leyenda automática para mejorar la legibilidad

Pegue en el renderizador de PlantUML (en línea o IDE) — personalice nombres/tecnologías para su sistema.

Utilice este patrón como plantilla inicial. El objetivo siempre es comunicación efectiva entre equipos — no la belleza del diagrama. ¡Feliz modelado!

Recurso de diagrama de componentes C4