Diagramas D2
Renderize diagramas de arquitetura, fluxogramas, sequências e modelos SQL a partir de sintaxe de texto D2. Os diagramas são renderizados como SVG que segue o tema do site.
Use D2 quando um diagrama precisar de contêineres aninhados e limites, um esquema de banco de dados com chaves primárias e estrangeiras, ou um layout que você possa ajustar trocando de motor. O Mermaid ainda serve para fluxogramas rápidos. Mude para D2 quando a estrutura ficar arquitetural. Você escreve D2 da mesma forma que Mermaid, em um bloco de código delimitado no seu Markdown.
Uso básico
Use um bloco de código delimitado com o identificador de linguagem d2:
```d2
a -> b -> c
```
Tipos de diagramas
Arquitetura
Diagramas de arquitetura mostram como os serviços se conectam. Use formas rotuladas para mostrar o caminho da requisição pelo seu sistema.
```d2
Client: Web Client
API: API Server
Database: { shape: cylinder }
Client -> API: request
API -> Database: query
```
Contêineres
Contêineres agrupam nós relacionados. Aninhe formas dentro de { } para modelar limites como uma conta em nuvem ou uma implantação. Depois desenhe conexões que cruzem esses limites.
```d2
cloud: Cloud {
api: API
worker: Worker
}
queue: Message Queue
cloud.api -> queue: publish
queue -> cloud.worker: consume
```
Diagramas de sequência
Diagramas de sequência mostram como os componentes se comunicam ao longo do tempo. Defina shape: sequence_diagram em um contêiner. Liste as mensagens em ordem para documentar um fluxo de API ou de autenticação.
```d2
flow: {
shape: sequence_diagram
Client -> Server: request
Server -> Database: query
Database -> Server: results
Server -> Client: response
}
```
Diagramas de classes
Diagramas de classes documentam a estrutura de sistemas orientados a objetos. Defina shape: class em um nó e liste seus campos e métodos. Prefixe os membros com + para público, - para privado ou # para protegido. Conecte as classes para mostrar seus relacionamentos.
```d2
User: {
shape: class
+name: string
+email: string
+login(): void
+logout(): void
}
Order: {
shape: class
+id: int
+created: date
+addItem(): void
+checkout(): void
}
Item: {
shape: class
+name: string
+price: float
}
User -> Order: places
Order -> Item: contains
```
Diagramas de estado
Diagramas de estado modelam o ciclo de vida de um objeto ou processo. O D2 não possui uma forma dedicada para diagramas de estado. Modele os estados como ovais ou círculos e depois desenhe transições rotuladas entre eles.
```d2
Draft: { shape: oval }
Review: { shape: oval }
Published: { shape: oval }
Archived: { shape: oval }
Draft -> Review: submit
Review -> Published: approve
Review -> Draft: request changes
Published -> Archived: archive
```
Tabelas SQL
Formas de tabela SQL documentam um esquema de banco de dados com colunas e tipos. Marque uma coluna com { constraint: primary_key } ou { constraint: foreign_key } para renderizar os selos PK e FK. Conecte uma chave estrangeira à tabela referenciada para mostrar o relacionamento.
```d2
users: {
shape: sql_table
id: int { constraint: primary_key }
email: varchar
}
orders: {
shape: sql_table
id: int { constraint: primary_key }
user_id: int { constraint: foreign_key }
total: decimal
}
orders.user_id -> users.id
```
Formas
Defina um shape em qualquer nó para mudar como ele é renderizado:
| Sintaxe | Forma | Uso |
|---|---|---|
shape: rectangle | Retângulo | Nós padrão, processos |
shape: circle | Círculo | Estados, nós simples |
shape: cylinder | Cilindro | Bancos de dados, armazenamento |
shape: cloud | Nuvem | Serviços externos, redes |
shape: diamond | Losango | Decisões, condições |
shape: person | Pessoa | Usuários, atores |
shape: sql_table | Tabela SQL | Esquemas de banco de dados, modelos ER |
Conexões
Conexões definem a direção e os relacionamentos entre nós:
| Sintaxe | Descrição | Uso |
|---|---|---|
a -> b | Seta direcionada | Fluxo normal |
a -- b | Linha não direcionada | Associações |
a <-> b | Seta bidirecional | Troca em dois sentidos |
a <- b | Seta reversa | Fluxo reverso |
a -> b: label | Conexão rotulada | Descrever o relacionamento |
Escolha de um mecanismo de layout
O D2 vem com vários motores de layout. O padrão é dagre. Mude para ELK para grafos mais densos usando o bloco de configuração nativo do D2 na fonte do diagrama. Nenhuma prop de componente define o motor nesta versão.
```d2
vars: {
d2-config: {
layout-engine: elk
}
}
ingress -> service -> database
```
Diagramas largos rolam horizontalmente dentro do seu contêiner. Eles nunca ultrapassam os limites da página.
Dicas de estilo
O Jamdesk gera diagramas D2 como SVGs com dois temas. As cores permanecem legíveis em todos os temas sem nenhuma configuração.
- Mantenha cada diagrama pequeno: divida um sistema grande em visões focadas.
- Rotule cada conexão com o seu relacionamento.
- Agrupe nós relacionados em contêineres em vez de um grafo plano único.
- Mude para o motor de layout ELK para grafos densos com muitas conexões.
D2 versus Mermaid
D2 e Mermaid são renderizados em tempo de build. Escolha conforme o caso:
- Escolha D2 para diagramas de arquitetura e infraestrutura, modelos SQL e ER, visuais em estilo esboço e quando quiser escolher entre motores de layout.
- Escolha Mermaid para fluxogramas, gráficos de Gantt e grafos de Git. A sintaxe de sequência do Mermaid tem mais recursos que a do D2. As sequências em D2 mantêm o restante do seu diagrama em uma única linguagem. O Mermaid é amplamente adotado.
Consulte a página Diagramas Mermaid para a sintaxe e os exemplos do Mermaid.
Saiba mais
Consulte a documentação oficial do D2 para a sintaxe completa, incluindo estilos, classes e animação.
