Diagrammes D2

Optez pour D2 lorsqu'un diagramme nécessite des conteneurs imbriqués et des délimitations, un schéma de base de données avec clés primaires et étrangères, ou une mise en page ajustable en changeant de moteur. Il vient s'ajouter au support Mermaid déjà présent dans Jamdesk : continuez à utiliser Mermaid pour des organigrammes rapides, et passez à D2 lorsque la structure devient architecturale. Les deux partagent le même emplacement de rédaction, un bloc de code délimité dans votre Markdown, donc le choix de l'un ou l'autre est une question d'adéquation, pas de workflow.

Utilisation de base

Utilisez un bloc de code délimité avec l'identifiant de langage d2 :

```d2
a -> b -> c
```

Types de diagrammes

Architecture

Les diagrammes d'architecture cartographient les connexions entre services. Utilisez des formes étiquetées pour montrer le chemin des requêtes dans votre système.

```d2
Client: Web Client
API: API Server
Database: { shape: cylinder }

Client -> API: request
API -> Database: query
```

Conteneurs

Les conteneurs regroupent des nœuds liés. Imbriquez des formes dans { } pour modéliser des délimitations comme un compte cloud ou un déploiement, puis tracez des connexions qui traversent ces délimitations.

```d2
cloud: Cloud {
  api: API
  worker: Worker
}

queue: Message Queue

cloud.api -> queue: publish
queue -> cloud.worker: consume
```

Diagrammes de séquence

Les diagrammes de séquence montrent comment les composants communiquent dans le temps. Définissez shape: sequence_diagram sur un conteneur et listez les messages dans l'ordre pour documenter une API ou un flux d'authentification.

```d2
flow: {
  shape: sequence_diagram

  Client -> Server: request
  Server -> Database: query
  Database -> Server: results
  Server -> Client: response
}
```

Diagrammes de classes

Les diagrammes de classes documentent la structure des systèmes orientés objet. Définissez shape: class sur un nœud et listez ses champs et méthodes. Préfixez les membres avec + pour public, - pour privé, ou # pour protégé, et connectez les classes pour montrer leurs relations.

```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
```

Diagrammes d'états

Les diagrammes d'états modélisent le cycle de vie d'un objet ou d'un processus. D2 n'a pas de forme dédiée pour les diagrammes d'états. Modélisez les états sous forme d'ovales ou de cercles, puis tracez des transitions étiquetées entre eux.

```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
```

Tables SQL

Les formes de table SQL documentent un schéma de base de données avec colonnes et types. Marquez une colonne avec { constraint: primary_key } ou { constraint: foreign_key } pour afficher les badges PK et FK, puis connectez une clé étrangère à sa table référencée pour montrer la relation.

```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
```

Formes

Définissez une shape sur n'importe quel nœud pour changer son rendu :

Connexions

Les connexions définissent la direction et les relations entre les nœuds :

Choisir un moteur de mise en page

D2 est livré avec plusieurs moteurs de mise en page. Le moteur par défaut est dagre. Pour passer à ELK pour des graphes plus denses, définissez-le dans la source du diagramme à l'aide du bloc de configuration natif de D2. Il n'existe aucune prop de composant pour cela dans cette version ; le moteur se sélectionne dans le diagramme lui-même.

```d2
vars: {
  d2-config: {
    layout-engine: elk
  }
}

ingress -> service -> database
```

Les diagrammes larges défilent horizontalement dans leur conteneur, de sorte qu'un graphe dense reste lisible sans déborder de la page.

Conseils de style

Pour des diagrammes efficaces :

• Gardez chaque diagramme petit : divisez un grand système en vues ciblées.
• Étiquetez les connexions pour que la relation soit claire en un coup d'œil.
• Regroupez les nœuds liés dans des conteneurs plutôt qu'un seul graphe plat.
• Passez au moteur de mise en page ELK pour les graphes denses avec de nombreuses connexions.

D2 vs Mermaid

Les deux langages effectuent le rendu au moment du build, donc le choix dépend de l'adéquation :

• Choisissez D2 pour les diagrammes d'architecture et d'infrastructure, les modèles SQL et ER, les visuels de type croquis, et lorsque vous souhaitez un choix de moteurs de mise en page.
• Choisissez Mermaid pour les organigrammes, les diagrammes de Gantt et les graphes Git. Les deux effectuent le rendu de diagrammes de séquence ; la syntaxe de séquence de Mermaid est plus riche en fonctionnalités, tandis que celle de D2 garde le reste de votre diagramme dans un seul langage. Mermaid est largement adopté et dispose d'un vaste écosystème.

Consultez la page Diagrammes Mermaid pour la syntaxe et des exemples Mermaid.

En savoir plus

Pour la référence complète de la syntaxe D2, y compris le style, les classes et l'animation, consultez la documentation officielle de D2.

Et ensuite ?