跳至主要內容

Structurizr DSL 建模、校验与发布治理手册

高谷深陵大约 4 分钟约 1286 字
Structurizr workspace 校验与视图投影
Structurizr workspace 校验与视图投影DSL 建立模型和视图，CLI 与 Local 提供验证、预览和导出，Git 保存事实与变更证据。高清原图

Structurizr 把 C4 模型落到 workspace 和 DSL：模型描述人、系统、容器、组件与关系，视图选择受众需要的投影，样式控制表达，CLI 与 Local 负责校验、预览和导出。它解决的是模型即代码的执行链，不等于 C4 方法本身；不了解边界和层级，换成 DSL 仍然会得到错误架构。

选择当前支持的运行入口

安装或启用前先查官方文档中的当前 CLI、Local 和云服务边界，不沿用已经停止演进的旧桌面入口。团队若只需要离线预览，可使用 Local；需要 CI 校验和导出则使用 CLI；需要多人布局与共享时，再评估托管服务的身份、权限和成本。

Java、容器镜像或 CLI 包的版本必须固定。Local 的工作目录只挂载 workspace 和必要资源，不能顺手挂载整个用户目录。云 workspace 使用专门身份和最小权限，API 凭证不写入 DSL。

创建一个可运行 workspace

最小 DSL 同时包含 model 和 views。标识符要稳定，名称面向读者，关系写清意图与技术。视图 key 属于发布接口，一旦被文档链接或导出流程使用，就不应随意重命名。

workspace "Checkout" "结算系统架构" {
  model {
    customer = person "客户"
    checkout = softwareSystem "结算系统"
    customer -> checkout "提交结算请求" "HTTPS"
  }
  views {
    systemContext checkout "CheckoutContext" { include *; autolayout lr }
  }
}

配置影响包括标识符作用域、include、视图过滤、自动布局、主题和属性。布局信息与模型事实分开评审：自动布局变化不应掩盖关系变化，手工布局也不能成为唯一可读结果。

校验、预览与导出

正向验证从 CLI validate 开始，再由 Local 打开 workspace，最后导出关键视图。命令、退出码、工具版本和输出摘要进入 CI 日志。项目接入后，模型变更与相关代码、ADR 同一个 PR 评审。

structurizr-cli validate -workspace architecture/workspace.dsl
structurizr-cli export -workspace architecture/workspace.dsl -format mermaid -output architecture/generated

导出成功只证明语法和引用可以处理，不证明模型符合系统。评审者需要检查边界、方向、责任和技术标签；生产依赖还应与代码、部署清单或可观测数据互证。

反向实验和故障分型

反例可以引用不存在的元素或重复视图 key，确认 CLI 明确失败。另一个实验故意删除一条真实依赖：校验可能仍成功，但架构评审或自动对照应发现事实缺失。这区分了结构校验与语义校验，避免把绿色流水线误认为架构正确。

Local 打不开时先看挂载路径、文件编码和 DSL 解析；保存布局失败再看只读挂载与权限；导出不一致则核对 CLI 与 Local 版本、主题和导出格式。升级后大面积重排属于布局变化，不应与模型对象增删混在同一评审。

大 workspace 的边界、权限与成本

所有系统塞进一个 workspace 会带来加载变慢、owner 模糊和发布权限过宽。按域拆分后，通过稳定 URL、外部系统和明确契约连接。共享词汇和样式可以复用，但每个 workspace 保持独立验证和恢复能力。

模型源可能暴露内部系统、网络与供应商关系。公开视图应单独过滤和脱敏，不能直接公开内部 workspace。托管服务的成员、分享链接和 API Token 定期复查；Local 与 CI 限制文件和网络访问。容量治理记录模型规模、视图数量、导出耗时和人工布局成本。

清理、回滚与迁移恢复

清理元素前先查所有关系、视图和文档链接，关联替代 ADR 后再删除。CLI 升级若引入新告警或导出漂移，回滚版本锁定，并把失败 workspace 缩成兼容夹具。缓存和生成目录可以重建，模型源、视图 key 与布局证据不能随意丢弃。

退出 Structurizr 时保存 DSL、导出图、版本和关系清单，再用目标工具验证关键对象与关系。由于 C4 语义独立于产品，迁移重点是模型与视图，不是复制 UI。恢复演练要在干净环境中完成校验和至少一种导出，证明架构资产不依赖个人机器或云账户。

跳到正文