Build C4 System Context Diagrams with PlantUML

在设计软件系统时，向技术利益相关者和非技术利益相关者清晰地传达高层边界至关重要。在本大师班教程中，我们将逐步演示如何在免费的 VPasCode编辑器中从零开始构建专业的 C4 系统上下文图。

为什么为 C4 模型采用“图表即代码”方法？

传统的拖放绘图工具往往会导致框线错位、样式不一致，并且在架构演进时需要进行繁琐的手动更新。通过利用图表即代码工具（例如免费的 PlantUML 编辑器），您的文档将始终与代码保持同步、支持版本控制且整洁清晰。使用 VPasCode，您可以获得实时渲染和自动格式检测功能，使软件架构的可视化变得轻松自如。

大师班案例研究：在线杂货店架构

为了展示如何构建一个健壮的系统上下文图，让我们来看一个在线杂货店平台。该架构需要涵盖最终用户、外部配送司机、核心杂货系统以及第三方服务（如支付网关和物流提供商）。

以下是我们将逐步分解的完整 PlantUML 源代码：

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
skinparam vpDiagramType C4modelSystemContextDiagram

LAYOUT_TOP_DOWN()
LAYOUT_WITH_LEGEND()

title 在线杂货店系统上下文图

Person(customer, "客户", "浏览商店、订购杂货并安排配送")
Person_Ext(driver, "配送司机", "向客户配送订单")

Enterprise_Boundary(grocery_co, "在线杂货店") {
  System(grocery_system, "在线杂货店系统", "允许客户在线订购杂货并管理履约")
}

System_Ext(payment, "支付网关", "处理银行卡和数字钱包支付")
System_Ext(shipping, "物流提供商", "规划配送路线并安排司机)

Rel(customer, grocery_system, "浏览商品并下单", "HTTPS")
Rel(grocery_system, payment, "通过", "HTTPS/API" 处理支付)
Rel(grocery_system, shipping, "通过", "HTTPS/API" 创建配送任务)
Rel(driver, grocery_system, "查看配送任务", "HTTPS")

@enduml

代码逐步详解

1. 设置基础环境

我首先使用标准的 PlantUML 标签初始化脚本，并导入官方的 C4-PlantUML 标准库宏。通过引用 C4_Context.puml，我们解锁了专为系统上下文图设计的语义元素。

库包含： !include .../C4_Context.puml加载了用于人员、系统和边界的标准形状、颜色和样式规则。
图表类型与布局：设置 skinparam vpDiagramType C4modelSystemContextDiagram可确保在 VPasCode中正确集成，而 LAYOUT_TOP_DOWN()将视觉层次结构从顶部到底部清晰地组织起来。我还启用了 LAYOUT_WITH_LEGEND()以在画布右下角自动生成一份有用的参考指南。

2. 定义参与者和用户

接下来，我需要定义与我们的生态系统交互的人类参与者。我使用特定的 C4 宏来区分标准系统用户和外部实体：

核心用户：我使用以下代码创建主要用户：Person(customer, "Customer", ...)该用户负责发起订单并浏览库存。
外部参与者：我使用以下代码定义配送司机：Person_Ext(driver, "Delivery Driver", ...)以强调尽管他们与我们的履约流程进行交互，但他们位于我们核心内部安全边界之外。

3. 建立组织边界和核心系统

架构清晰度需要明确的边界。为了区分公司自有部分与依赖外部供应商的部分，我建立了一个企业边界：

企业边界：使用以下代码：Enterprise_Boundary(grocery_co, "Online Grocery Store")会创建一个虚线容器框，在视觉上对内部基础设施进行分组。
内部系统：在此边界内，我使用以下代码放置我们的主要软件资产：System(grocery_system, "Online Grocery Store System", ...).