Quick Start

Build your first diagram in six steps

快速入门

通过六个步骤构建您的第一个经过验证的架构图。每一步都引入了一个新的 Datro 概念。最后，您将拥有一个完整的、样式化的、经过约束检查的图表，可以导出为 SVG。

打开图表制作器

在实时编辑器中进行操作 - 粘贴每个片段并单击“验证”。

第 1 步 - 编写第一个节点和边

每个 .dtro 文件都以一个神奇的标头开头。之后，声明节点（实体）和边（关系）。将其粘贴到编辑器中：

arch.dtro

#!DATRO 1.0

node frontend { type: web      label: "React App" }
node backend  { type: service  label: "NestJS API" }
node db       { type: database label: "PostgreSQL" }

edge frontend -> backend { kind: http }
edge backend  -> db      { kind: query }

ℹ️

需要魔术头

第 1 行的 #!DATRO 1.0 行是强制性的。如果缺少，解析器将返回 E100。

第 2 步 — 添加 `attrs` 以获得更丰富的元数据

attrs 块保存任意键值元数据。值可以是字符串、数字、布尔值或数组。常见属性有 tech、owner、deprecated 和 sla。

DATRO

node backend {
  type:  service
  label: "NestJS API"
  attrs {
    tech:  "nestjs"
    owner: "platform-team"
  }
}

属性传递到 JSON IR 并在渲染的 SVG 中显示为工具提示 - 对于待命和 SLA 元数据非常有用。

第 3 步 - 添加边缘元数据

边有一个种类（语义关系类型）、一个可选的标签、一个权重（相对流量）和一个异步标志。异步边缘呈现为虚线。

DATRO

edge backend -> stripe {
  kind:  http
  label: "charge API"
  async: false
}

Field	Type	Required	Default	Description
`kind`	EdgeKind "http""grpc""query""publish""subscribe""read""write""deploys""monitors""depends""…21 total"	Yes	`unknown`	语义关系类型
`label`	string	No	—	边缘线上显示短文本
`weight`	number	No	`1.0`	相对流量权重——较重的边缘呈现较厚
`async`	boolean	No	`false`	当 true 时，边缘呈现为虚线（即发即弃模式）

第 4 步 — 将节点分组为集群

使用 group 块来集群相关节点。组在 SVG 中呈现为带标签的子图框。一个节点只能属于一个组。

DATRO

group data_tier {
  label:   "Data Layer"
  members: [db, redis_cache]
}

node redis_cache { type: cache label: "Redis" }

edge backend -> redis_cache { kind: read  label: "session" }

💡

组与node.group

您还可以使用 group: data_tier 直接在节点上分配组。两种样式都有效； group 块的 members 列表优先。

第 5 步 — 添加架构约束

约束是机器检查的架构规则。验证器根据 IR 对其进行评估，并在违反规则时返回 E501 错误。

DATRO

constraint {
  id:       "no-db-external"
  rule:     "database !-> external"
  message:  "Databases must not connect to external services"
  severity: error
}

规则database !-> external意味着：database类型的节点不能与external类型的任何节点有有向边。这会阻止意外的直接数据库 → 第三方 API 调用。

第 6 步 — 添加布局提示和主题

使用 layout 块控制图表的排列方式，并使用 theme 块定义调色板。如果任何颜色低于 WCAG AA 对比度，则可访问性检查将触发 W602。

DATRO

layout { direction: LR  algo: dagre  node_sep: 60  rank_sep: 120 }

theme {
  palette {
    service:    "#D0E8FF"
    database:   "#FFE8C0"
    web:        "#E8D0FF"
    cache:      "#C0FFE8"
    background: "#FFFFFF"
  }
  accessibility { min_contrast: AA }
}

💡

WCAG 对比是自动的

DOT 导出器使用 WCAG 2.1 相对亮度公式自动为每个节点填充选择黑色或白色字体颜色 - 需要零配置。

后续步骤

阅读 Language Reference 了解每个块类型的完整语法。
使用 CLI Reference 从命令行进行验证、格式化和导出。
了解如何使用 remark 或 markdown-it 插件 embed diagrams in Markdown 编写文档。

打开图表制作器