Loading... # D2 声明式图表语言入门指南 # 一、概述 ## 1. 简介 ### A. 是什么 D2（Declarative Diagramming）是一种声明式图表脚本语言，能够将文本描述转换为可视化图表。用户只需用简洁的语法描述想要展示的内容，D2 会自动处理布局和渲染，生成专业的架构图、流程图等图表。 ### B. 为什么学 - 解决传统绘图工具操作繁琐、版本管理困难的问题 - 代码即图表，便于版本控制和协作 - 内置智能布局引擎，自动优化图表结构 - 支持多种主题和样式，快速生成美观图表 ### C. 学完能做什么 - 使用 D2 语法编写架构图、流程图、序列图等 - 通过 CLI 工具将文本转换为 SVG、PNG 等格式 - 利用 Playground 实时预览和调试图表 - 在文档、博客中嵌入可维护的图表代码 ## 2. 前置知识 ### A. 必备技能 - 基本文本编辑器操作 - 命令行基础操作 ### B. 推荐知识 - 了解软件架构图、流程图等图表概念 - 熟悉 YAML 或 JSON 等配置格式 # 二、环境准备 ## 1. 系统要求 D2 是跨平台工具，支持： - Linux - macOS - Windows ## 2. 安装步骤 使用包管理器安装： macOS（Homebrew）： ```bash brew install d2 ``` Linux： ```bash curl -fsSL https://d2lang.com/install.sh | sh ``` 或从 GitHub Releases 页面下载二进制文件： https://github.com/terrastruct/d2/releases ## 3. 验证安装 ```bash d2 version ``` # 三、核心概念 ## 1. 基本术语 - **声明式（Declarative）**：描述想要什么，而不是如何实现 - **节点（Node）**：图表中的元素，如实体、组件、角色等 - **边（Edge）**：节点之间的关系或连接 - **形状（Shape）**：节点的视觉表现形式，如矩形、圆形、数据库图标等 - **布局引擎（Layout Engine）**：负责自动排列节点和边的算法 ## 2. 工作原理 ```mermaid graph LR A[D2 源码] --> B[D2 CLI] B --> C[布局引擎] C --> D[渲染器] D --> E[输出图片] F[配置文件] --> B G[主题文件] --> D ```  D2 解析用户编写的声明式代码，通过布局引擎计算节点位置，最后渲染成可视化图表。 # 四、快速上手 ## 1. Hello World 示例 创建文件 input.d2： ```d2 # 创建两个节点和一条连接 A -> B: Hello ``` 运行命令： ```bash d2 input.d2 output.svg ``` ## 2. 核心功能演示 ### A. 定义节点 ```d2 user: 用户 server: 服务器 database: 数据库 ``` ### B. 创建连接 ```d2 user -> server: 请求 server -> database: 查询 ``` ### C. 设置样式 ```d2 user: { shape: person style: { fill: #e1f5fe } } ``` ## 3. 代码讲解 D2 语法简洁直观： - 节点名称直接书写，冒号后可添加标签 - 箭头 -> 表示连接关系 - 花括号 {} 用于定义属性和子元素 - 注释使用 # 符号 # 五、进阶内容 ## 1. 常用功能 ### A. 嵌套结构 ```d2 network: { cell tower: 基站 satellites: 卫星 transmitter: 发射器 satellites -> transmitter: send } ``` ### B. 多种形状 D2 支持丰富的形状类型： - rectangle：矩形（默认） - circle：圆形 - diamond：菱形 - cylinder：圆柱体（数据库） - hexagon：六边形 - person：人物图标 - stored_data：存储图标 - page：页面图标 ### C. 样式定制 ```d2 connection -> database: { style.stroke-dash: 3 label: 访问 } ``` ## 2. 最佳实践 - 使用有意义的节点命名 - 合理组织嵌套结构 - 利用主题保持视觉一致性 - 使用注释说明复杂逻辑 - 配合版本管理追踪变更 ## 3. 性能优化 - 大型图表使用 ELK 布局引擎（--layout elk） - 启用 watch 模式实时预览（-w 参数） - 使用变量复用配置（vars 块） # 六、实战案例 ## 1. 场景描述 绘制一个完整的软件系统架构图，包含用户界面、API 服务、数据处理和存储等组件。 ## 2. 实现步骤 编写完整的 D2 代码： ```d2 vars: { d2-config: { layout-engine: elk theme-id: 300 } } network: { cell tower: { satellites: { shape: stored_data style.multiple: true } transmitter satellites -> transmitter: send } online portal: { ui: {shape: hexagon} } data processor: { storage: { shape: cylinder style.multiple: true } } cell tower.transmitter -> data processor.storage: phone logs } user: { shape: person width: 130 } user -> network.cell tower: make call user -> network.online portal.ui: access { style.stroke-dash: 3 } api server -> network.online portal.ui: display api server -> logs: persist logs: {shape: page; style.multiple: true} network.data processor -> api server ``` 生成图表： ```bash d2 --theme=300 --dark-theme=200 -l elk --pad 0 ./input.d2 ./output.svg ``` 使用 watch 模式： ```bash d2 -w input.d2 ``` 这样在编辑 input.d2 时，图表会自动更新。 # 七、常见问题 ## 1. 安装问题 Q: macOS 安装后找不到 d2 命令 A: 确保将 Homebrew 安装路径添加到 PATH： ```bash export PATH="/opt/homebrew/bin:$PATH" ``` ## 2. 配置问题 Q: 如何自定义主题 A: 在代码中使用 vars 块配置： ```d2 vars: { d2-config: { theme-id: 自定义主题ID } } ``` ## 3. 运行问题 Q: 生成的图表布局不理想 A: 尝试不同的布局引擎： - dagre：层次化布局（默认） - elk：层级布局，适合复杂图 - tala：力导向布局 # 八、学习资源 ## 1. 官方资源 - D2 官方文档：https://d2lang.com/tour/intro - 在线 Playground：https://play.d2lang.com - GitHub 仓库：https://github.com/terrastruct/d2 ## 2. 社区资源 - Discord 社区：https://discord.com/invite/pbUXgvmTpU - 示例画廊：https://d2lang.com/examples/overview/ ## 3. 快速参考 文档末尾提供速查表（Cheat Sheet），涵盖常用语法和示例。 *** ## 参考资料 1. [D2 Tour | D2 Documentation](https://d2lang.com/tour/intro) 最后修改：2026 年 01 月 16 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏