D2 图表
从基于文本的 D2 语法渲染架构图、流程图、时序图和 SQL 模型。图表以跟随站点主题的 SVG 形式呈现。
当图表需要嵌套的容器与边界、带主键和外键的数据库模式,或者可以通过切换布局引擎进行调整的版式时,请使用 D2。快速绘制流程图时 Mermaid 仍然适用。当结构变得偏向架构时,请切换到 D2。编写 D2 的方式与 Mermaid 相同,都是在 Markdown 中使用代码围栏。
基本用法
使用带有 d2 语言标识符的代码围栏:
```d2
a -> b -> c
```
图表类型
架构图
架构图展示服务之间的连接方式。使用带标签的形状来展示请求在系统中的传递路径。
```d2
Client: Web Client
API: API Server
Database: { shape: cylinder }
Client -> API: request
API -> Database: query
```
容器
容器用于对相关节点进行分组。在 { } 中嵌套形状,可以对云账户或部署等边界进行建模。然后绘制跨越这些边界的连接。
```d2
cloud: Cloud {
api: API
worker: Worker
}
queue: Message Queue
cloud.api -> queue: publish
queue -> cloud.worker: consume
```
时序图
时序图展示组件之间随时间的交互。在容器上设置 shape: sequence_diagram。按顺序列出消息,以记录 API 或身份验证流程。
```d2
flow: {
shape: sequence_diagram
Client -> Server: request
Server -> Database: query
Database -> Server: results
Server -> Client: response
}
```
类图
类图用于记录面向对象系统的结构。在节点上设置 shape: class,并列出其字段和方法。成员前缀 + 表示公有,- 表示私有,# 表示受保护。连接各个类以展示它们之间的关系。
```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
```
状态图
状态图用于建模对象或流程的生命周期。D2 没有专门的状态图形状。将状态建模为椭圆或圆形,然后在它们之间绘制带标签的转换。
```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
```
SQL 表
SQL 表形状使用列和类型来记录数据库模式。使用 { constraint: primary_key } 或 { constraint: foreign_key } 标记列,即可渲染 PK 和 FK 标记。将外键连接到其引用的表,以展示关系。
```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
```
形状
在任意节点上设置 shape 可以改变其渲染方式:
| 语法 | 形状 | 适用于 |
|---|---|---|
shape: rectangle | 矩形 | 默认节点、流程 |
shape: circle | 圆形 | 状态、简单节点 |
shape: cylinder | 圆柱体 | 数据库、存储 |
shape: cloud | 云 | 外部服务、网络 |
shape: diamond | 菱形 | 决策、条件 |
shape: person | 人形 | 用户、参与者 |
shape: sql_table | SQL 表 | 数据库模式、ER 模型 |
连接
连接用于定义节点之间的方向和关系:
| 语法 | 说明 | 适用于 |
|---|---|---|
a -> b | 有向箭头 | 常规流程 |
a -- b | 无向线 | 关联关系 |
a <-> b | 双向箭头 | 双向交换 |
a <- b | 反向箭头 | 反向流程 |
a -> b: label | 带标签的连接 | 描述关系 |
选择布局引擎
D2 提供多种布局引擎。默认为 dagre。对于连接较密的图,可在图表源码中通过 D2 原生配置块切换到 ELK。本版本中没有组件属性可以设置引擎。
```d2
vars: {
d2-config: {
layout-engine: elk
}
}
ingress -> service -> database
```
宽幅图表会在其容器内水平滚动,不会超出页面范围。
样式提示
Jamdesk 将 D2 图表构建为双主题 SVG。颜色在每种主题下都保持可读,无需任何配置。
- 保持每个图表小巧:将大型系统拆分为聚焦的视图。
- 为每个连接标注其关系。
- 将相关节点分组到容器中,而不是使用一个扁平的图。
- 对于连接众多的密集图,切换到 ELK 布局引擎。
D2 与 Mermaid
D2 和 Mermaid 都在构建时渲染。根据适用性选择:
- 选择 D2:架构与基础设施图、SQL 和 ER 模型、草图风格的视觉效果,以及需要选择布局引擎的场景。
- 选择 Mermaid:流程图、甘特图和 Git 图。Mermaid 的时序语法功能比 D2 更丰富。D2 时序图可以让整个图表保持在同一种语言中。Mermaid 也被广泛采用。
有关 Mermaid 语法和示例,请参阅 Mermaid 图表 页面。
了解更多
完整语法(包括样式、类和动画)请参阅官方 D2 文档。
