Mermaid.js C4 图表语法与架构指南

C4 图表是一种标准化的架构可视化方法，旨在以多个结构抽象层次来建模软件系统。Mermaid.js 原生内置了该功能，c4引擎遵循 C4 模型的四个核心层级：上下文（宏观生态系统），容器（应用程序、服务和数据库），组件（内部结构模块），以及动态交互。该工具通过根据您的文本声明应用一致且可直接展示的架构模块，消除了自定义 CSS 样式带来的麻烦。

理解 C4 图表抽象与关键词

Mermaid 支持四种专用的图表初始化标题，具体取决于您的系统布局所需的详细程度：

  • C4Context：专注于整体视图，展示用户、核心软件生态系统以及高层级的外部依赖关系。
  • C4Container：向下深入一级，分解独立应用程序、前端界面、微服务、数据库存储系统和队列。
  • C4Component：深入容器内部，展示代码级别的内部模块，例如控制器（Controllers）、服务（Services）和存储库（Repositories）。
  • C4Dynamic：专注于追踪运行时数据交互或基础设施模块之间的分步事务序列。

基本语法结构

每个 C4 图表都以特定层级的标题开头，后接可选的标题语句和用逗号分隔的宏组件。参数包含在括号中，字符串用双引号包围。

Mermaid 在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
C4Context
  title "互联网核心系统上下文蓝图"
  Person(customer, "银行客户", "拥有个人账户的银行客户。")
  System(banking_system, "网上银行系统", "允许客户查看账户信息。")
  Rel(customer, banking_system, "使用", "HTTPS")
Edit Mermaid in VPasCode
在 VPasCode 中编辑 Mermaid

完整的 C4 元素宏分类体系

Mermaid C4 库提供了一套广泛的专用宏，可清晰地区分所有抽象层级中的内部组件、外部系统和数据库层。

1. 人员与用户宏

  • Person(别名, 标签, [描述], [角色图像], [标签]): 表示组织内部的人类用户或利益相关者。
  • Person_Ext(别名, 标签, [描述], [角色图像], [标签]): 表示位于您核心组织边界之外的外部用户（例如第三方供应商或审计员）。

2. 系统与软件生态系统宏

  • System(别名, 标签, [描述], [角色图像], [标签]): 表示在您直接管理下的内部、在范围内的软件系统集群。
  • System_Ext(别名, 标签, [描述], [角色图像], [标签]): 表示由第三方管理的关键外部软件系统（例如身份提供商、核心银行账本）。
  • SystemDb(别名, 标签, [描述], [角色图像], [标签]): 渲染一个呈圆柱形的系统级数据存储库框。
  • SystemDb_Ext(别名, 标签, [描述], [角色图像], [标签]): 渲染一个外部的第三方数据库层级。

3. 容器层宏（C4容器层）

  • Container(别名, 标签, 技术, [描述], [角色图像], [标签]): 表示一个独立的可运行应用程序、API服务器或前端界面。
  • ContainerDb(别名, 标签, 技术, [描述], [角色图像], [标签]): 渲染一个容器级别的关系型或非关系型数据库引擎包装器。
  • Container_Ext(别名, 标签, 技术, [描述], [角色图像], [标签]): 表示外部云容器或应用服务。
  • ContainerDb_Ext(别名, 标签, 技术, [描述], [角色图像], [标签]): 表示外部的、由第三方管理的云数据库存储层级。

4. 组件层宏（C4组件层）

  • Component(别名, 标签, 技术, [描述], [角色图像], [标签]): 映射内部代码级别的模块、层或类控制器。
  • ComponentDb(别名, 标签, 技术, [描述], [角色图像], [标签]): 表示内部的微组件存储或底层文件缓存系统。

边界容器与结构封装

为了表示安全边界、企业防火墙或逻辑应用边界，Mermaid 提供了三种专用的括号包围的容器封装。嵌套在其中的元素会以视觉方式被分组在一起。

  • 企业边界（别名，标签）{ ... }: 将高层系统包裹在一个宽广的视觉边界内，表示整个企业或公司基础设施的外围。
  • 系统边界（别名，标签）{ ... }: 将紧密相关的应用容器或微服务分组在一个统一的软件生态系统框内。
  • 容器边界（别名，标签）{ ... }: 在单一应用模块上下文层内隔离代码级别的组件。

高级关系方向操作符

C4图中连接模块依赖于Rel宏或其显式方向变体。与其传递原始流程图线条，不如在逻辑块内部直接声明技术向量，以语义方式跟踪连接。

关系语法标记 视觉箭头方向 使用对齐上下文
Rel（来源，目标，标签，[技术]） 动态/自动 默认关系。让布局算法决定最佳连线路径。
BiRel（来源，目标，标签，[技术]） 双向（<–>） 表示双向交互握手、全双工协议或同步过程。
Rel_Back（来源，目标，标签，[技术]） 反向箭头顶部（<–） 在代码逻辑中向前绘制关系，但将可见的视觉箭头反向翻转。
Rel_Neighbor（来源，目标，标签，[技术]） 水平布局优先 强制目标节点与源节点保持在同一水平行上并紧邻。
Rel_Down（来源，目标，标签，[技术]） / Rel_D（...） 直线向下（v） 强制垂直数据流向下流向数据库层或后续后台进程。
Rel_Up(起点, 终点, 标签, [技术]) / Rel_U(...) 垂直向上 (^) 强制关系轨迹直接向上连接到客户端UI组件。
Rel_Left(起点, 终点, 标签, [技术]) / Rel_L(...) 水平向左 (<-) 将路径水平路由到画布元素的左侧。
Rel_Right(起点, 终点, 标签, [技术]) / Rel_R(...) 水平向右 (->) 将路径水平路由到画布元素的右侧。

自定义动态样式与标记（C4形状覆盖）

为了标识遗留应用程序、突出显示高级系统或强调安全数据流，您可以使用元素标签引擎创建自定义样式。在文档顶部定义标签属性矩阵，然后将该标签名称附加到您的元素定义中。

样式修改关键字：

  • UpdateElementStyle(元素名称, 背景色, 字体颜色, [边框颜色], [阴影效果]): 直接覆盖显式元素框的默认背景调色板。
  • UpdateRelStyle(起点, 终点, 线条颜色, 文本颜色): 显式指定连接路径以重新着色线条路径或连接描述。
Mermaid 在VPasCode中编辑Mermaid
Mermaid Edit Mermaid in VPasCode 
C4Context
  标题 "自定义颜色编码的全局架构图"
  
  System(legacy_api, "遗留计费核心", "处理订阅续订。")
  System(modern_portal, "客户仪表板门户", "现代用户网页视图引擎。")
  
  %% 直接颜色自定义
  UpdateElementStyle(legacy_api, "#d9534f", "#ffffff", "#c9302c")
  UpdateElementStyle(modern_portal, "#5cb85c", "#ffffff", "#4cae4c")
Edit Mermaid in VPasCode
在VPasCode中编辑Mermaid

现实世界蓝图：企业电子商务系统边界容器图

这个全面的、多层级的容器蓝图追踪一个在线电子商务生态系统。它使用一个System_Boundary块容器来隔离内部核心服务器，并通过外部系统，映射内部关系型数据库存储以及外部追踪微服务，并使用明确的技术栈参数固定通信管道。

Mermaid 在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
C4Container
  标题 "企业级电子商务平台的容器蓝图"

  人物(客户, "在线购物者", "浏览商品目录并将产品添加到其数字购物车。")
  外部系统(支付网关, "Stripe API 服务", "第三方信用卡保险库与处理引擎。")

  系统边界(电商范围, "电子商务核心边界") {
    容器(前端应用, "店面 Web 应用", "Next.js, React", "提供静态资源并处理用户购物车会话。")
    容器(结账微服务, "结账微服务", "Node.js, Express", "处理购物车工作流并计算税额。")
    数据库容器(订单账本数据库, "订单账本数据库", "PostgreSQL", "存储历史交易记录和安全账本数据。")
  }

  %% 架构交互路径
  关系(客户, 前端应用, "使用", "HTTPS/浏览器")
  关系_下(前端应用, 结账微服务, "通过", "JSON/REST API")
  
  关系_右(结账微服务, 订单账本数据库, "在内部持久化事务状态，使用", "SQL/JDBC 连接")
  关系_左(结账微服务, 支付网关, "使用", "安全 TLS/HTTPS API")
Edit Mermaid in VPasCode
在 VPasCode 中编辑 Mermaid

常见语法陷阱与系统约束

在为软件框架编译干净的 C4 图表时，请注意以下执行参数，以防止图表损坏：

  • 逗号分隔格式： 与几乎所有的其他 Mermaid 模式不同，C4 宏要求参数之间使用严格的逗号：人物(标识符, "标签", "描述")。忘记添加分隔逗号将导致布局生成器完全崩溃。
  • 保留的标签引号：宏内部的显示字段、技术标签和描述块必须用清晰的双引号包裹。在未使用引号包裹的情况下直接插入原始文本，会导致解析错误并破坏图表。
  • 边界嵌套顺序： 当将元素包裹在 系统边界 或 企业边界 块中时，必须使用标准的大括号显式清除其工作区内容。{ } 如果边界括号未正确闭合或匹配错误，将导致渲染布局失败。
  • 动态别名实例化： 你无法绘制关系（关系）到一个未被其上方元素宏块显式初始化的别名标识符。请确保你的声明流程从上到下逐步进行。
滚动至顶部