go-用代码画架构图：D2 语言深度解析与实战指南，告别手动拖拽，让你的文档随代码同步更新

icy 昨天 17 抢沙发

默认

摘要： 告别手动拖拽：走进 D2 声明式绘图语言在软件开发过程中，架构图、流程图和时序图是不可或缺的沟通工具。然而，传统的绘图工具（如 Visio, Lucidchart, Draw.i...

告别手动拖拽：走进 D2 声明式绘图语言

在软件开发过程中，架构图、流程图和时序图是不可或缺的沟通工具。然而，传统的绘图工具（如 Visio, Lucidchart, Draw.io）存在一个巨大的痛点：维护成本极高。每当系统架构发生微小变动，你都需要手动拖拽方块、重新对齐线条，这不仅低效，且容易导致文档与实际代码脱节。

D2 (Declarative Diagramming) 正是为了解决这一问题而生的现代声明式绘图语言。它允许你用简单的文本描述逻辑关系，由 D2 引擎自动计算布局并渲染成精美的图表。

1. 为什么选择 D2 而不是 Mermaid 或 PlantUML？

虽然市场上已有 Mermaid 和 PlantUML 等工具，但 D2 在设计哲学上进行了升级：

更强大的布局引擎：D2 支持多种布局引擎（包括内置引擎和第三方如 Dagre, ELK），能够更智能地处理复杂节点的交叉，减少“面条线”现象。
现代化的语法：语法极其精简，支持嵌套容器（Containers），可以轻松表达“服务 A 在集群 B 中，集群 B 在 VPC C 中”这种层级关系。- 高度可定制化：支持通过简单的属性定义颜色、形状、图标（如 AWS/GCP/Azure 图标），而无需编写复杂的样式表。
交互性与扩展性：支持将图表导出为 SVG、PNG，甚至可以通过 D2 编译器集成到 CI/CD 流水线中。

2. D2 核心语法快速上手

D2 的核心逻辑非常简单：节点名称: 属性 或 源节点 -> 目标节点。

2.1 基础连接

最简单的定义方式就是定义两个点及其关系：

text

用户 -> 登录页面: 访问
登录页面 -> 认证服务: 提交凭据
认证服务 -> 数据库: 查询用户

2.2 嵌套容器（Containers）

这是 D2 最强大的功能之一。你可以使用花括号 {} 来定义作用域，实现逻辑分组。

text

云端环境: {
  API网关 {
    认证模块
    限流模块
  }
  
  后端服务: {
    用户服务
    订单服务
  }
  
  数据库集群 {
    MySQL
    Redis
  }
}

用户 -> 云端环境.API网关: 请求
云端环境.API网关 -> 云端环境.后端服务.用户服务: 转发
云端环境.后端服务.用户服务 -> 云端环境.数据库集群.MySQL: 读写

2.3 样式与图标

D2 允许你快速为节点添加视觉属性。

text

AWS服务: {
  shape: cloud
  style: {
    fill: "#fdfdfd"
    stroke: "#ff9900"
  }
}

数据库: {
  shape: cylinder
  icon: postgres
}

AWS服务 -> 数据库: 存储数据

3. 实战实例：构建一个微服务架构图

假设我们要描述一个典型的电商下单流程，包含前端、网关、订单服务、库存服务和消息队列。

text

direction: right

# 定义全局样式
vars: {
  d2-config: {
    layout-engine: elk
  }
}

# 客户端层
Client: {
  shape: person
  label: "终端用户"
}

# 基础设施层
Cloud: {
  label: "AWS 生产环境"
  
  Gateway: {
    label: "API Gateway"
    shape: rectangle
  }

  # 业务服务组
  Services: {
    OrderService: {
      label: "订单服务"
      icon: go
    }
    InventoryService: {
      label: "库存服务"
      icon: rust
    }
  }

  # 数据持久层
  Persistence: {
    DB: {
      shape: cylinder
      label: "PostgreSQL"
    }
    Cache: {
      shape: cylinder
      label: "Redis"
    }
  }

  # 异步通信
  MQ: {
    shape: queue
    label: "RabbitMQ"
  }
}

# 定义交互关系
Client -> Cloud.Gateway: HTTPS Request
Cloud.Gateway -> Cloud.Services.OrderService: 路由请求
Cloud.Services.OrderService -> Cloud.Persistence.DB: 写入订单
Cloud.Services.OrderService -> Cloud.MQ: 发送订单创建事件
Cloud.MQ -> Cloud.Services.InventoryService: 消费事件
Cloud.Services.InventoryService -> Cloud.Persistence.Cache: 更新库存缓存

4. 如何安装与使用 D2

4.1 安装

你可以通过多种方式安装 D2 编译器： - macOS (Homebrew): brew install d2 - Linux: 使用官方提供的安装脚本。 - Docker: docker pull terrastruct/d2

4.2 运行

创建一个文件 diagram.d2，写入上述代码，然后在终端运行：

text

d2 diagram.d2 diagram.svg

这将生成一个矢量图文件，可以直接在浏览器中打开。

4.3 在线尝试

如果你不想安装，可以直接访问 D2 Playground，在左侧编写代码，右侧实时预览。

5. D2 的最佳实践建议

利用 direction 关键字：通过 direction: right 或 direction: down 快速调整整体布局流向。
使用变量（Vars）：对于重复的样式（如所有数据库都用蓝色），可以定义变量来统一管理。
版本控制：将 .d2 文件直接提交到 Git 仓库。这样，当架构变更时，你只需要提交一个文本 Diff，而不是上传一张无法搜索且无法对比的 PNG 图片。
结合 CI/CD：在 GitHub Actions 中配置 D2，每当 .d2 文件更新时，自动重新生成图片并更新到 README 中。