Jamdesk Documentation logo

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_tableSQL 表数据库模式、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 文档。

接下来做什么?

Mermaid 图表

使用 Mermaid 渲染流程图和时序图

组件概览

浏览所有可用组件