PlantUML + C4 模型完整权威指南

来源：本站编辑

23小时前

# PlantUML + C4 模型完整权威指南（水利数字孪生场景版）

本指南为**纯净无报错、离线可用、可直接交付架构文档**的 PlantUML + C4 模型手册。所有案例、业务场景、中间件落地全部统一替换为**水利数字孪生场景**（水库防汛、水文监测、数据汇聚、仿真调度、预警大屏）。

核心说明：官方 C4 模型仅四层，无 C4_Code，代码粒度采用标准 PlantUML 类图补充。

内容包含：

1. **PlantUML 通用离线基础语法**

2. **C4 四层完整模型（适配水利数字孪生业务）**

3. **每层专属水利行业组件/中间件实例说明**

4. **可直接运行的全套水利场景示例代码**

5. **代码层类图补充（水利业务模块）**
本指南可以使用在线[plantUml服务器](https://daf.jmhui.com.cn/ "plantUml服务器")在线绘制。
---

# 一、PlantUML 通用基础语法（全局通用）

## 1. 文档标准结构

```markdown
@startuml 图表名称
' 单行注释
title 主标题
caption 图表说明
' 元素、连线、样式
@enduml
```

## 2. 箭头关系规范

```markdown
A -> B      实线：同步调用、实时交互、直接依赖
A --> B     虚线：异步通知、数据推送、间接依赖
```

## 3. 离线引入规则

```markdown
!include <C4/xxx>      ' PlantUML 内置官方C4标准库（纯离线）
!include xxx.puml       ' 本地离线图标资源
```

---

# 二、C4 模型核心规则（官方标准）

C4 模型仅包含 **四层标准架构视图**，无 Code 层：

1. **Context 上下文层**：业务宏观视图

2. **Container 容器层**：技术服务与中间件视图

3. **Component 组件层**：服务内部模块视图

4. **Deployment 部署层**：物理集群节点视图

## C4 元素统一语法模板

```markdown
元素类型(唯一别名, 展示名称, 技术/业务描述, $sprite="图标名")
```

- **唯一别名**：内部连线引用，不展示

- **展示名称**：图表可视化名称（支持中文）

- **描述信息**：技术栈、业务用途、功能说明

- **$sprite**：可选离线图标

## 官方合法库引入（零报错、纯离线）

```markdown
!include <C4/C4_Context>
!include <C4/C4_Container>
!include <C4/C4_Component>
!include <C4/C4_Deployment>
```

---

# 三、C4 四层水利数字孪生场景完整示例

## 层级1：Context 系统上下文图（业务宏观层）

**作用**：面向领导、业务、甲方汇报，只展示「用户、本系统、外部水利生态系统」宏观业务关系，无任何技术细节。

**本层水利场景惯用实例**：

- 角色人员：水利运维人员、防汛值班人员、管理员、应急指挥人员

- 核心主体：水利数字孪生平台（本系统）

- 外部系统：水文监测采集系统、气象预报系统、防汛指挥系统、视频监控平台、水资源调度系统
![上下文图](/u/cms/www/202606/01175024jfc4.png)

```markdown
@startuml C4_01_水利数字孪生_上下文图
title C4层级1：水利数字孪生系统上下文图
caption 水利场景 | 业务宏观视图 | 纯离线渲染

!include <C4/C4_Context>
!include font-awesome-5/users.puml

' 人员角色
Person(waterOperator, "水利运维人员", "日常监测、设备运维、数据核查", $sprite="users")
Person(floodManager, "防汛值班人员", "汛期预警核查、应急调度指挥", $sprite="users")

' 核心自研系统
System(waterTwinSys, "水利数字孪生平台", "水库/河道/灌区全要素仿真、监测、预警、调度一体化平台")

' 外部水利生态系统
System_Ext(hydrologySys, "水文监测采集系统", "实时水位、雨量、流量数据上报")
System_Ext(weatherSys, "气象预报系统", "降雨、台风、气象预警数据推送")
System_Ext(videoSys, "水利视频监控平台", "河道、水库实时视频流")
System_Ext(floodCmdSys, "市级防汛指挥系统", "上级应急调度指令下发、上报")

' 业务交互关系
Rel(waterOperator, waterTwinSys, "日常运维、数据查看、设备管理")
Rel(floodManager, waterTwinSys, "汛期监控、预警处置、仿真推演")

Rel(waterTwinSys, hydrologySys, "实时拉取水文监测数据")
Rel(waterTwinSys, weatherSys, "接入气象预报数据辅助研判")
Rel(waterTwinSys, videoSys, "调取现场实时视频画面")
Rel(waterTwinSys, floodCmdSys, "上报险情、接收调度指令")

@enduml
```

---

## 层级2：Container 容器图（技术服务+中间件层）

**作用**：架构核心视图，展示水利孪生平台所有**可独立部署的服务、中间件、存储、仿真引擎**，用于微服务架构设计、技术评审。

**本层水利场景惯用中间件/容器全覆盖**：

- 接入层：孪生可视化网关、数据接入网关、负载均衡

- 业务服务：水文数据服务、仿真推演服务、预警调度服务、大屏展示服务、设备管理服务

- **缓存中间件**：Redis（实时监测数据缓存、大屏秒级刷新）

- **消息中间件**：RocketMQ/Kafka（水文数据异步解耦、海量测点数据削峰）

- **调度中间件**：XXL-Job（定时数据补采、报表生成、模型重置）

- **时序数据库**：InfluxDB/TimescaleDB（存储海量时序水文数据）

- **搜索引擎**：Elasticsearch（日志检索、险情记录、运维记录查询）

- **仿真引擎**：水利数值仿真引擎（水动力学模型、洪水演进模型）

- 存储：MySQL业务库、时序数据库、文件对象存储
![容器图](/u/cms/www/202606/01175106nob8.png)

```markdown
@startuml C4_02_水利数字孪生_容器图
title C4层级2：水利数字孪生系统容器图（含全品类中间件）
caption 水利场景 | 微服务+中间件完整架构 | 纯离线渲染

!include <C4/C4_Context>
!include <C4/C4_Container>
!include font-awesome-5/users.puml
!include devicons/nginx.puml
!include devicons/java.puml
!include devicons/mysql.puml
!include devicons/redis.puml

' 外层角色与外部系统
Person(waterOperator, "水利运维人员", $sprite="users")
System_Ext(hydrologySys, "水文监测采集系统", "外部测点数据上报")
System_Ext(weatherSys, "气象预报系统", "外部气象数据推送")

' 水利数字孪生系统边界
System_Boundary(waterTwinBoundary, "水利数字孪生平台系统") {
    ' 接入层容器
    Container(gateway, "统一接入网关", "SpringCloud Gateway", "数据转发、权限拦截、流量管控", $sprite="nginx")

' 核心业务微服务
    Container(dataCollectService, "水文汇聚服务", "Java SpringBoot", "测点数据接收、解析、清洗、入库", $sprite="java")
    Container(simulateService, "仿真推演服务", "Java + 数值模型", "洪水演进、库容演算、态势仿真", $sprite="java")
    Container(earlyWarnService, "预警调度服务", "Java SpringBoot", "阈值研判、分级预警、调度方案生成", $sprite="java")
    Container(screenService, "孪生大屏服务", "Java + Web", "三维场景渲染、实时态势展示", $sprite="java")

' 缓存中间件
    Container(redisCache, "Redis缓存集群", "Redis 7.x", "实时监测数据缓存、大屏秒级刷新、热点数据加速", $sprite="redis")

' 消息中间件
    Container(mqCluster, "消息队列集群", "RocketMQ", "海量测点数据异步解耦、流量削峰、事件分发")

' 调度中间件
    Container(jobCenter, "定时调度中心", "XXL-Job", "定时数据补采、模型周期计算、日报生成")

' 搜索引擎
    Container(esSearch, "Elasticsearch检索引擎", "全文检索", "运维日志、险情记录、操作记录检索")

' 数据库存储
    ContainerDb(businessDb, "水利业务数据库", "MySQL 8.0", "用户、设备、预案、预警配置数据", $sprite="mysql")
    ContainerDb(timeSeriesDb, "水文时序数据库", "InfluxDB", "海量水位/雨量/流量时序监测数据")
}

' 业务交互关系
Rel(waterOperator, gateway, "访问孪生平台、运维操作")
Rel(gateway, dataCollectService, "转发数据接入请求")
Rel(gateway, simulateService, "转发仿真推演请求")
Rel(gateway, earlyWarnService, "转发预警调度请求")
Rel(gateway, screenService, "转发大屏展示请求")

Rel(hydrologySys, dataCollectService, "上报实时水文测点数据")
Rel(weatherSys, dataCollectService, "推送气象预报数据")

Rel(dataCollectService, mqCluster, "海量监测数据异步投递")
Rel(mqCluster, simulateService, "消费数据驱动仿真计算")
Rel(mqCluster, earlyWarnService, "消费数据触发预警研判")

Rel(dataCollectService, redisCache, "缓存最新监测数据")
Rel(simulateService, redisCache, "缓存仿真结果数据")
Rel(screenService, redisCache, "读取缓存实现大屏秒级刷新")

Rel(jobCenter, dataCollectService, "定时补采历史缺失数据")
Rel(jobCenter, simulateService, "定时执行周期仿真演算")

Rel(dataCollectService, businessDb, "存储设备、测点配置信息")
Rel(dataCollectService, timeSeriesDb, "入库海量时序监测数据")
Rel(earlyWarnService, businessDb, "存储预警记录、调度预案")
Rel(simulateService, esSearch, "归档仿真日志、险情推演记录")

@enduml
```

---

## 层级3：Component 组件图（服务内部模块层）

**作用**：面向开发设计，拆解单个微服务内部的功能模块、中间件适配模块、数据处理模块，用于代码拆分、模块设计、接口开发。

**本层水利场景惯用组件类别**：

- 基础组件：权限校验、登录认证、日志记录、参数校验组件

- 水利核心业务组件：数据解析组件、异常研判组件、洪水演算组件、预警分级组件

- 中间件适配组件：时序库读写组件、缓存操作组件、消息生产消费组件、定时任务组件

- 数据层组件：业务数据持久、时序数据入库、日志归档组件
![组件图](/u/cms/www/202606/01175143izpp.png)

```markdown
@startuml C4_03_水利数字孪生_组件图
title C4层级3：水文汇聚服务内部组件结构图
caption 水利场景 | 单服务模块拆解 | 开发设计视图

!include <C4/C4_Container>
!include <C4/C4_Component>
!include devicons/java.puml
!include devicons/mysql.puml
!include devicons/redis.puml

' 外层容器依赖
Container(dataCollectService, "水文汇聚服务", "Java SpringBoot", "水利测点数据汇聚处理服务", $sprite="java")
ContainerDb(businessDb, "水利业务数据库", "MySQL 8.0", $sprite="mysql")
ContainerDb(timeSeriesDb, "水文时序数据库", "InfluxDB")
Container(redisCache, "Redis缓存集群", "Redis 7.x", $sprite="redis")
Container(mqCluster, "RocketMQ消息队列集群", "消息中间件")

' 服务内部组件边界
Container_Boundary(collectBoundary, "水文汇聚服务内部功能模块") {
    ' 通用基础组件
    Component(authComponent, "权限认证组件", "安全模块", "接口访问拦截、用户权限校验")
    Component(logComponent, "运维日志组件", "通用模块", "数据接入日志、异常日志记录归档")

' 水利核心业务组件
    Component(dataParseComponent, "测点数据解析组件", "核心业务", "解析水文、雨量、流量原始报文")
    Component(dataFilterComponent, "数据清洗过滤组件", "核心业务", "剔除异常值、补全缺失数据、数据校验")
    Component(abnormalJudgeComponent, "异常研判组件", "核心业务", "水位超限、雨量暴增异常初步判定")

' 中间件适配组件
    Component(redisOperateComponent, "缓存适配组件", "中间件层", "更新最新测点缓存、刷新大屏数据")
    Component(mqProduceComponent, "消息生产组件", "中间件层", "推送标准化水文数据至消息队列")

' 数据持久组件
    Component(businessDaoComponent, "业务数据组件", "数据层", "设备信息、测点配置读写")
    Component(timeSeriesDaoComponent, "时序数据组件", "数据层", "海量监测时序数据批量入库")
}

' 组件交互关系
Rel(authComponent, dataParseComponent, "权限校验通过放行请求")
Rel(logComponent, dataParseComponent, "记录数据接入日志")
Rel(logComponent, dataFilterComponent, "记录数据清洗异常日志")

Rel(dataParseComponent, dataFilterComponent, "原始数据清洗标准化")
Rel(dataFilterComponent, abnormalJudgeComponent, "标准化数据异常研判")

Rel(abnormalJudgeComponent, redisOperateComponent, "更新异常监测数据至缓存")
Rel(dataFilterComponent, redisOperateComponent, "更新正常监测数据至缓存")
Rel(dataFilterComponent, mqProduceComponent, "推送标准化数据供下游服务消费")

Rel(redisOperateComponent, redisCache, "操作分布式缓存集群")
Rel(mqProduceComponent, mqCluster, "投递水文事件消息")

Rel(dataParseComponent, businessDaoComponent, "校验测点设备配置信息")
Rel(dataFilterComponent, timeSeriesDaoComponent, "时序数据批量入库")
Rel(businessDaoComponent, businessDb, "读写业务配置数据")
Rel(timeSeriesDaoComponent, timeSeriesDb, "写入时序监测数据")

@enduml
```

---

## 层级4：Deployment 部署图（物理集群部署层）

**作用**：面向运维、交付、部署，展示水利孪生平台所有服务、中间件、数据库的服务器集群、物理节点部署结构。

**本层水利场景惯用部署节点**：

- 接入节点：网关负载节点、外网接入节点

- 业务节点：微服务应用集群、仿真计算节点

- 中间件节点：缓存集群、消息队列集群、调度节点、检索集群

- 存储节点：业务数据库主从、时序数据库集群、文件存储节点

- 运维节点：日志监控、系统告警节点
![部署图](/u/cms/www/202606/01175208iorl.png)

```markdown
@startuml C4_04_水利数字孪生_部署图
title C4层级4：水利数字孪生系统物理部署架构图
caption 水利场景 | 集群部署视图 | 运维交付专用

!include <C4/C4_Deployment>
!include <C4/C4_Container>
!include devicons/nginx.puml
!include devicons/java.puml
!include devicons/mysql.puml
!include devicons/redis.puml

' 终端用户
Person(waterUser, "水利运维/值班人员")

' 1. 网关接入节点
Deployment_Node(gatewayNode, "网关接入集群", "Linux / Nginx+Gateway") {
    Container(gateway, "统一接入网关", "微服务网关", $sprite="nginx")
}

' 2. 业务微服务节点
Deployment_Node(serviceCluster, "水利业务服务集群", "Linux / JDK17 / 多实例") {
    Container(dataCollectService, "水文汇聚服务", "SpringBoot微服务", $sprite="java")
    Container(simulateService, "仿真推演服务", "水利模型服务", $sprite="java")
    Container(earlyWarnService, "预警调度服务", "业务微服务", $sprite="java")
    Container(screenService, "孪生大屏服务", "可视化服务", $sprite="java")
}

' 3. 中间件专属集群节点
Deployment_Node(redisNode, "缓存中间件集群", "Redis Cluster") {
    Container(redisCache, "分布式缓存集群", "实时数据缓存", $sprite="redis")
}

Deployment_Node(mqNode, "消息中间件集群", "RocketMQ主从集群") {
    Container(mqCluster, "水文消息队列", "异步数据分发")
}

Deployment_Node(jobNode, "调度中间件节点", "XXL-Job集群") {
    Container(jobCenter, "定时调度中心", "周期任务管理")
}

Deployment_Node(esNode, "日志检索集群", "Elasticsearch集群") {
    Container(esSearch, "日志与记录检索引擎")
}

' 4. 数据存储节点
Deployment_Node(dbNode, "业务数据库集群", "MySQL主从架构") {
    ContainerDb(businessDb, "水利业务库", "配置、预案、用户数据", $sprite="mysql")
}

Deployment_Node(timeDbNode, "时序数据库集群", "InfluxDB集群") {
    ContainerDb(timeSeriesDb, "水文时序数据库", "海量监测时序数据")
}

' 节点交互关系
Rel(waterUser, gatewayNode, "外网访问孪生平台")
Rel(gatewayNode, serviceCluster, "内网路由分发请求")

Rel(serviceCluster, redisNode, "读写实时缓存数据")
Rel(serviceCluster, mqNode, "生产/消费水文业务消息")
Rel(jobNode, serviceCluster, "定时触发补采、推演任务")
Rel(serviceCluster, esNode, "归档日志、检索记录")

Rel(serviceCluster, dbNode, "读写水利业务配置数据")
Rel(serviceCluster, timeDbNode, "入库海量时序监测数据")

@enduml
```

---

# 四、代码层绘制方案（非C4标准，水利业务类图）

C4 官方无代码层，最细粒度代码结构采用**标准 PlantUML 类图** 绘制，以下为**水利水文数据模块**完整代码层级示例。

![类图](/u/cms/www/202606/01175232za8i.png)

```markdown
@startuml 水利水文数据_代码层类图
title 代码层级：水利水文数据汇聚模块类结构
caption 补充C4模型最细粒度 | 业务代码设计视图

' 业务接口
interface HydrologyDataService {
  + parseOriginalData(): DataResult
  + filterAbnormalData(): StandardData
  + cacheRealTimeData()
}

' 接口实现类
class HydrologyDataServiceImpl {
  - dataParser: DataParser
  - dataFilter: DataFilter
  - redisTemplate: RedisTemplate
  + parseOriginalData(): DataResult
  + filterAbnormalData(): StandardData
  + cacheRealTimeData()
}

' 数据实体类
class HydrologyDataEntity {
  - siteId: String
  - waterLevel: Double
  - rainfall: Double
  - flowRate: Double
  - collectTime: Date
  - deviceStatus: Integer
}

' 数据持久接口
interface HydrologyDataMapper {
  + insertTimeSeriesData()
  + selectLatestData(siteId)
}

' 类关系绑定
HydrologyDataService <|.. HydrologyDataServiceImpl
HydrologyDataServiceImpl --> HydrologyDataMapper : 数据持久调用
HydrologyDataServiceImpl --> HydrologyDataEntity : 操作水文监测实体
HydrologyDataMapper --> HydrologyDataEntity : 数据库实体映射

@enduml
```

---

# 五、总结（水利数字孪生C4模型核心规范）

1. **C4 官方四层完整适配水利场景**：业务上下文→服务容器→模块组件→物理部署，全覆盖水利孪生业务架构

2. **无 C4_Code.puml**，代码粒度统一使用 PlantUML 原生类图绘制

3. 每层严格对应水利行业专属组件：水文采集、仿真推演、预警调度、时序数据、大屏可视化

4. 所有中间件（缓存/消息/调度/检索/时序库）均贴合水利海量时序数据、异步推演、定时运维的行业特性

5. 所有脚本纯离线可用，无网络依赖，可直接用于架构文档、汇报、评审、交付

PlantUML + C4 模型完整权威指南

热门评论最新评论

相关推荐

PlantUML + C4 模型完整权威指南

热门评论 最新评论

相关推荐

热门评论最新评论