节点与分组

节点是可引用的架构实体，分组是带标签的包含边界。两者共同描述图中可见的组件与作用域。

节点

节点需要全局唯一标识符和可见标签。标识符供连线和布局语句引用，但不会渲染；标签长度为 1 至 60 个 Unicode scalar。

stack 1.0

diagram "Node example" {
  node api "Public API" {
    kind service
    detail "Order orchestration"
  }
}

不同实体可以使用相同可见标签，但最好让标签不依赖位置也能理解。节点块不能重复 kind、icon 或 detail。

节点种类

kind 表示粗粒度架构语义，并选择由主题控制的形状和回退图标。默认值是 service。

Kind	预期含义
actor	人、角色、团队或自主参与者
client	浏览器、移动/桌面应用、设备或其他客户端
service	长期运行的应用、API、网关或通用组件
function	按需或 serverless 计算单元
worker	后台处理器或定时任务
database	持久、可查询的数据存储
cache	内容可丢弃或可重新生成的数据存储
queue	用于异步传递的队列、流、总线或 broker
storage	Blob、对象、文件或归档存储
external	架构控制边界之外的系统

Kind 是语义分类，不是厂商形状。托管 PostgreSQL 仍是 database，技术名称应写入 detail。

标签与详情

detail 是可选的可见第二行，长度为 1 至 80 个 Unicode scalar。可填写一种技术或简短职责，如 "Next.js"、"PostgreSQL 17" 或 "Order orchestration"。它必须在所有渲染图中可见，不能只放在 tooltip 中。

标签和详情是纯文本。显式 icon 只装饰节点，不改变 kind、identity 或无障碍标签。另见主题与图标。

分组

分组需要全局唯一标识符、1 至 60 个 Unicode scalar 的标签，以及至少一个后代节点。它可包含节点、嵌套分组和一个布局块。

stack 1.0

diagram "Boundaries" {
  group platform "Platform" {
    group data "Data layer" {
      node primary "Primary database" {
        kind database
      }
    }
  }
}

分组最多可在图下嵌套三层。节点属于最近的分组，也传递地属于所有祖先分组。声明不能复用，因此一个节点不能同时属于两个独立分组。

连线必须在图作用域声明，且只有节点可作为端点。分组不会产生隐式节点或连线。标签用于说明它代表系统、领域、网络、部署区域、团队或其他边界；包含关系本身不表示运行时隔离、安全性、所有权或部署语义。