de_DEen_USes_ESfa_IRfr_FRhi_INid_IDjapl_PLpt_PTru_RUvizh_CNzh_TW

Aproximando ao Máximo: Compreendendo Diagramas de Código C4 – O que São, Quando Adicionam Valor e Exemplos Práticos com PlantUML

O que é um Diagrama de Código C4?

O diagrama de código é Nível 4 — o nível mais profundo e detalhado no modelo C4 de Simon Brown.

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

Mostra:

  • Classes, interfaces, enums, registros, ou outros construtos de nível de código que implementam um determinado componente (do Nível 3).

  • Relacionamentos entre essas classes (herança, composição, dependência, realização de interfaces, etc.).

  • Elementos-chave elementos de design como padrões aplicados dentro do componente (por exemplo, repositórios, serviços, DTOs, entidades de domínio, fábricas).

Na prática, este nível é quase sempre um diagrama de classes UML (ou uma variante simplificada) focado em um (ou muito poucos) componentes.

Esclarecimento importante:

  • O Nível 4 é não sobre todo o código-fonte.

  • Ele é nãonecessário para mostrar cada classe.

  • Ele mapeiaapenas a estrutura essencialnecessário para entender como um componente complexo ou crítico é realmente construído.

  • A recomendação oficial do C4:idealmente gerado automaticamentea partir do código-fonte (por meio de ferramentas como Doxygen, Javadoc + plugins UML, yWorks, Structurizr, CodeSee, etc.) em vez de desenhado à mão.

Quando criar um diagrama de código

Crie diagramas de Nível 4 com parcimônia — apenas nessas situações:

  • O componente éaltamente complexo, crucial para a missão, oudifícil de entenderapenas a partir do código-fonte (por exemplo, lógica de domínio complexa, uso intensivo de padrões de design, fluxos criptográficos, máquinas de estado, código legado repleto de dívida técnica).

  • Você está trabalhando em umsetor altamente regulamentado (finanças, saúde, aeroespacial, defesa) em que auditores ou equipes de conformidade exigem mapeamento explícito da arquitetura → design → implementação.

  • Duranterefatoração principal, enfraquecendo um componente legado, ouintroduzindo um novo padrão arquitetônico (hexagonal, limpo, fatia vertical, agregados DDD) — visualizações antes/depois ajudam a comunicar a mudança.

  • Onboardingdesenvolvedores sêniorouarquitetosque precisam compreender rapidamente a estrutura interna não óbvia de um trecho de código de alto risco.

  • Você já investiu em geração automáticaferramentas — então manter o Nível 4 custa quase nada.

  • A equipe concordou que “documentação viva”no nível de classe é valioso para este subsistema específico.

Não crie diagramas de Nível 4 quando:

  • A estrutura dos componentes é óbvia por nomes adequados, pequeno tamanho ou código limpo (a maioria dos microsserviços modernos se encaixa aqui).

  • Você já tem boas testes unitários/integração, interfaces claras, e comentários explicativos.

  • A maioria da equipe consegue navegar pelo código com facilidade.

  • O custo de manutenção supera o benefício (diagramas de classes desenhados à mão ficam desatualizados muito rapidamente).

Simon Brown e a maioria dos profissionais enfatizam: A maioria das equipes nunca precisa do Nível 4. Níveis 1 + 2cobrem 80–90% das necessidades de comunicação; Nível 3lidam com a maioria do restante. O Nível 4 é a exceção, não a regra.

Por que usar diagramas de código? (Quando eles agregam valor)

  • Ponte entre arquitetura ↔ implementação— Mostra como os componentes de alto nível são realmente implementados no código.

  • Esclarecer o design interno complexo— Revela o uso de padrões (Strategy, Factory, Decorator, Repository), violações de camadas, acoplamento forte ou modelagem inteligente do domínio.

  • Apoiar auditorias e conformidade — Demonstra que as decisões arquitetônicas são seguidas até o código.

  • Apoiar discussões de refatoração e migração — Estruturas de classes antes/depois tornam as propostas tangíveis.

  • Reduzir o “conhecimento tribal” — Ajuda novos contratados sênior a entender partes complexas mais rapidamente do que lendo todos os arquivos-fonte.

  • Versões geradas automaticamente tornam-se “documentos vivos” — Se ferramentas estiverem em vigor, permanecem precisas com quase nenhum esforço.

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

  1. Escolha UM componente — Geralmente de um diagrama de Nível 3 onde a complexidade interna justifica o zoom.

  2. Decida: desenhado à mão ou gerado?

    • Desenhado à mão → apenas para workshops, propostas ou áreas muito bagunçadas para ferramentas automáticas.

    • Gerado → preferido (o PlantUML ainda pode ser usado para estilizar/ajustar a saída).

  3. Foque nos essenciais — Mostre:

    • Classes/interfaces principais

    • Relacionamentos importantes (→ dependência, — composição, <| realidade, ^ herança)

    • Agregados, entidades, objetos de valor (estilo DDD)

    • Padrões críticos ou anti-padrões que você deseja destacar

  4. Mantenha-o pequeno — No máximo 8 a 15 classes. Se maior → divida em diagramas focados (por exemplo, “fatia de autenticação”, “entidades de processamento de pedidos”).

  5. Melhores práticas

    • Prefira geração automática sempre que possível (menos obsolescência).

    • Use sintaxe PlantUML classDiagram sintaxe — limpa e versionável.

    • Adicione notas para decisões não óbvias (por exemplo, “Usa Modelo de Domínio Anêmico – refatoração planejada”).

    • Evite mostrar tudo — omita getters/setters triviais, classes utilitárias.

    • Armazene no repositório → trate como código (confirme arquivos .puml próximo ao componente).

    • Use com parcimônia — um por componente complexo, não por microserviço.

    • Combine com visões dinâmicas (seqüência/colaboração) se o fluxo em tempo de execução for mais importante que a estrutura estática.

Exemplo PlantUML – Componente de Autenticação (extensão do estilo Big Bank plc)

Aqui está um exemplo realista do Nível 4, focando no Componente de Segurança / Autenticação dos diagramas anteriores da Aplicação de API.

@startuml
title C4 Nível 4 – Diagrama de Código: Autenticação dentro da Aplicação de API

skinparam monochrome true
skinparam shadowing false
skinparam class {
  BackgroundColor White
  BorderColor Black
  ArrowColor Black
}

abstract class AuthenticationProvider {
  + authenticate(credentials): Authentication
}

class JwtAuthenticationProvider {
  - tokenProvider: JwtTokenProvider
  - userDetailsService: UserDetailsService
  + authenticate(credentials): Authentication
}

class JwtTokenProvider {
  - secretKey: String
  - validityInMilliseconds: long
  + generateToken(userDetails): String
  + validateToken(token): boolean
  + getUsernameFromToken(token): String
}

interface UserDetailsService {
  + loadUserByUsername(username): UserDetails
}

class DatabaseUserDetailsService {
  - userRepository: UserRepository
  + loadUserByUsername(username): UserDetails
}

class UserRepository {
  + findByUsername(username): Optional<User>
}

class User {
  - username: String
  - passwordHash: String
  - roles: Set<Role>
}

class JwtAuthenticationToken << (T,orchid) Authentication >> {
  - principal: UserDetails
  - credentials: Object
  - authorities: Collection<GrantedAuthority>
}

' Relacionamentos
JwtAuthenticationProvider -up-> JwtTokenProvider : usa
JwtAuthenticationProvider -up-> UserDetailsService : usa
DatabaseUserDetailsService .up.|> UserDetailsService
DatabaseUserDetailsService --> UserRepository : usa
UserRepository --> User : retorna

JwtAuthenticationToken .up.|> Authentication

note right of JwtAuthenticationProvider
  Fluxo principal de autenticação para sessões sem estado baseadas em JWT
end note

note bottom of JwtTokenProvider
  Assina e verifica JWTs usando HS512
end note

@enduml

Este pequeno diagrama:

  • Foca apenas nos internos da autenticação

  • Mostra classes principais, interfaces e dependências

  • Destaca padrões (provedor, repositório)

  • Usa notas para contexto

Cole em qualquer renderizador PlantUML — personalize para o seu domínio (por exemplo, substitua JWT por OAuth2, adicione classes de MFA, etc.).

Lembrete de resumo: O Nível 4 é poderoso, mas raro. Use-o intencionalmente, prefira a geração automática e nunca deixe que se torne trabalho rotineiro. A maior parte do valor do C4 vem dos Níveis 1 a 3. Feliz modelagem (seletiva)!

Recurso

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