de_DEen_USes_ESfa_IRfr_FRhi_INid_IDjapl_PLpt_PTru_RUvizh_CNzh_TW

Aprofundamento no Nível 3 do Modelo C4: Dominando Diagramas de Componentes para Revelar Estrutura Interna e Responsabilidades

O que é um Diagrama de Componentes C4?

O diagrama de componentes éNível 3no modelo C4 de Simon Brown. Ele se aproxima deum contêiner específico (do diagrama de contêiner do Nível 2) para mostrar:

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

  • Osbloco lógicos (componentes) que compõem esse contêiner.

  • Como esses componentesinteragem entre si.

  • Responsabilidades etecnologias de implementação (em um nível mais alto que classes — pense em Beans do Spring, módulos, serviços, controladores, fachadas, etc.).

  • Interfaceschave oucontratos entre componentes (muitas vezes implícitos por meio de relacionamentos).

Esclarecimento importante: Um “componente” no C4 énão uma classe. É umagrupamento lógico de classes atrás de uma interface bem definida — algo com uma responsabilidade clara, que pode ser desenvolvido/testado/implantado de forma parcialmente independente (dentro do contêiner), mas não énão separadamente implantável como um contêiner.

Exemplos de componentes:

  • Controlador REST / Controlador Web

  • Serviço / Caso de Uso / Serviço de Aplicação

  • Repositório / Objeto de Acesso a Dados

  • Modelo de Domínio / Entidade

  • Segurança / Módulo de Autenticação

  • Remetente de Notificações

  • Facade para sistema externo

  • Motor de Regras de Negócio

  • Camada de Cache

O diagrama permanece lógico / suficientemente independente da implementação — sem atributos de classe, assinaturas de métodos ou detalhes completos de classe UML (isso é Código Nível 4, que é opcional e raro).

Quando criar um diagrama de componente

Criar (e manter) um diagrama de componente apenas quando:

  • O container escolhido é complexo o suficiente de forma que sua estrutura interna não seja óbvia apenas pelo nome e descrição.

  • Novos membros da equipe (especialmente desenvolvedores de back-end) frequentemente perguntam: “Como a funcionalidade X é realmente implementada dentro deste serviço/API?”

  • Você está refatorando, dividindo, ou extraíndo lógica dentro de um container e precisa esclarecer limites/responsabilidades.

  • Você está fazendo discussões detalhadas de discussões de design, revisões de código, ou entregas de plantão para um contêiner específico.

  • Você deseja documentar decisões arquitetônicas principais dentro de um contêiner (por exemplo, arquitetura hexagonal, fatia vertical, separação CQRS, ponto de aplicação de segurança).

  • Você identificou dívida técnica, classes de deus, ou acoplamento rígido dentro de um contêiner e deseja visualizar o estado atual antes da limpeza.

  • Você está onboarding desenvolvedores/sócios sênior que precisam entender a estrutura de módulos rapidamente.

Não faça criar diagramas de componente para:

  • Contêineres simples (API CRUD com um controlador + um serviço + um repositório — estrutura óbvia).

  • A maioria dos microserviços (geralmente pequenos o suficiente para que o nível de contêiner seja suficiente).

  • Contêineres de front-end (aplicativos React/Vue — geralmente melhor mostrados com árvores de componentes ou storybook).

  • Quando o Nível 2 (Contêiner) + estrutura de código/nomeação adequada já comunica tudo o que é necessário.

Simon Brown recomenda: A maioria das equipes pode parar no Nível 1 + 2. Apenas vá para o Nível 3 para os complexos / arriscados / principais / de alta rotatividade contêineres.

Por que usar diagramas de componente? (Principais benefícios)

  • Clareia as responsabilidades internas — Mostra a separação de preocupações (por exemplo, controladores vs serviços vs acesso a dados vs integração externa).

  • Exibe acoplamento e dependências — Torna visíveis componentes de deus, dependências cíclicas ou excessiva dependência de código de infraestrutura.

  • Apoia uma melhor integração e transferência de conhecimento — Desenvolvedores compreendem os limites dos módulos mais rapidamente do que lendo todos os arquivos de origem.

  • Guiam a refatoração e a evolução — Base visual antes/depois da divisão de monolitos ou introdução de padrões (portas e adaptadores, fatias verticais).

  • Permite revisões de arquitetura e modelagem de ameaças — Identifica onde ocorrem validação, autorização, registro de logs, etc.

  • Arquitetura como código — Quando armazenado em PlantUML → versionado com o código-fonte, comparável, revisável em PRs.

  • Escalona a comunicação — Desenvolvedores sênior se importam com as responsabilidades dos componentes; júnior se importam com onde colocar o novo código.

Como criar um ótimo diagrama de componentes (Passo a passo + Melhores práticas)

  1. Escolha UM container — Comece com o mais complexo ou crítico para o negócio (geralmente a API principal / serviço de back-end).

  2. Copie o contexto do Nível 2 — Inclua atores externos (outros containers, pessoas, sistemas externos) que interagem com este container.

  3. Desenhe o limite do container — Use Limite_Container no PlantUML para delimitar claramente “dentro deste container”.

  4. Identifique os componentes — Pergunte:

    • Quais são os principais módulos / Spring Beans / pacotes / contextos delimitados dentro?

    • Onde os pedidos recebidos chegam? (controladores/manipuladores)

    • Onde a lógica de negócios é orquestrada?

    • Onde os dados são acessados / armazenados em cache / validados?

    • Onde são tratadas as preocupações transversais? (segurança, registro de logs)

    • Há fachadas / camadas anti-corrupção para sistemas legados/externos?

  5. Adicione Tecnologia e Descrição Breve — Nome, tecnologia (Serviço Spring, Manipulador .NET, Módulo Go, etc.), propósito breve (< 15 palavras).

  6. Definir Interações — Mostrar direção + intenção (Usa, Chama, Lê de, Publica eventos para). O protocolo geralmente é omitido neste nível.

  7. Melhores Práticas

    • Limitar escopo — Máximo de 6 a 12 componentes por diagrama. Se houver mais → crie visualizações focadas (por exemplo, “fatia de Autenticação”).

    • Nomear de forma significativa — Prefira “Serviço de Colocação de Pedidos” em vez de “OrderService”.

    • Mostrar responsabilidade, não classes — Evite listar todas as classes; agrupe logicamente.

    • Use ícones com parcimônia — Apenas se ajudarem a esclarecer a tecnologia (ícones do Spring, .NET).

    • Habilitar legenda — Ajuda leitores novos.

    • Mantenha o layout limpo — LAYOUT_COM_LEGENDA(), LAYOUT_DE_CIMA_PARA_BAIXO().

    • Versão no repositório — Arquivos .puml ao lado do código do container.

    • Iterar — Atualize durante picos de refatoração ou verificações trimestrais da saúde da arquitetura.

Exemplo do PlantUML – Aplicação de API do Sistema de Banco na Internet (estilo clássico da Big Bank plc)

Aqui está um exemplo de produção usando a biblioteca oficial C4-PlantUML — a amostra do mundo real mais frequentemente referenciada.

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

title Diagrama de Componentes: Sistema de Banco na Internet - Aplicação de API

' Atores / partes externas do nível de Container
Container(spa, "Aplicação de Página Única", "JavaScript & Angular", "Fornece a interface de banco na internet via navegador")
Container(mobile, "Aplicativo Móvel", "iOS/Android", "Fornece funcionalidades limitadas de banco móvel")
ContainerDb(database, "Banco de Dados Bancário", "PostgreSQL", "Armazena preferências do usuário, dados em cache e sessões")
System_Ext(mainframe, "Sistema Bancário Central", "Mainframe – contas e transações principais")

' O container ao qual estamos nos aproximando
Container_Boundary(api, "Aplicação de API") {
    Component(signInCtrl, "Controlador de Entrada de Login", "Controlador REST do Spring MVC", "Gerencia autenticação e criação de sessão")
    Component(accountsCtrl, "Controlador de Resumo de Contas", "Controlador REST do Spring MVC", "Fornece saldos e resumos de contas")
    Component(resetPwdCtrl, "Controlador de Redefinição de Senha", "Controlador REST do Spring MVC", "Gerencia o fluxo de redefinição de senha")
    
    Component(security, "Componente de Segurança", "Bean do Spring", "Tokens JWT, hash de senhas, verificações de papel")
    Component(accountService, "Componente de Gestão de Contas", "Bean do Spring / Serviço", "Orquestra consultas de contas e regras de negócios")
    Component(mainframeFacade, "Facade de Banco do Mainframe", "Bean do Spring", "Camada anti-corrupção para o mainframe legado")
    Component(emailNotifier, "Componente de Notificação por E-mail", "Bean do Spring", "Envia e-mails de confirmação e redefinição")
}

' Relacionamentos dentro da fronteira
Rel(signInCtrl, security, "Usa")
Rel(accountsCtrl, accountService, "Usa")
Rel(resetPwdCtrl, security, "Usa")
Rel(resetPwdCtrl, emailNotifier, "Usa")
Rel(accountService, mainframeFacade, "Usa")
Rel(accountService, database, "Lê de e escreve para", "JDBC")
Rel(mainframeFacade, mainframe, "Usa", "XML/HTTPS")
Rel(emailNotifier, database, "Lê preferências do usuário", "JDBC")

' Chamadas entrantes dos front-ends
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_COM_LEGENDA()
LAYOUT_ESQUERDA_DIREITA()

@enduml

Isso gera:

  • Fronteira clara ao redor do container da API

  • Agrupamento lógico de controladores, serviços e facades

  • Responsabilidades precisas

  • Interações e dependências principais

  • Legenda automática para legibilidade

Cole no renderizador PlantUML (online ou IDE) — personalize nomes/tecnologias para o seu sistema.

Use este padrão como seu modelo inicial. O objetivo é semprecomunicação eficaz entre equipes— não a beleza do diagrama. Boa modelagem!

Recursos do Diagrama de Componentes C4

This post is also available in Deutsch, English, Español, فارسی, Français, English, Bahasa Indonesia, 日本語, Polski, Ру́сский, Việt Nam, 简体中文 and 繁體中文.