C4-PlantUML项目中的模型与视图分离实践

背景与需求

在软件架构可视化领域，C4模型是一种广泛使用的分层架构描述方法。C4-PlantUML作为PlantUML的扩展库，允许用户通过简洁的语法快速绘制C4模型图。在实际项目中，我们经常遇到需要复用模型元素（如系统、容器、组件等定义）的场景，但又不希望这些基础定义在每次引用时都被自动渲染出来。

核心问题分析

传统使用!include指令包含模型定义文件时，所有被包含的元素都会在生成的图表中显示。这导致了两个主要问题：

1. 基础模型元素被重复渲染，造成图表冗余
2. 难以实现"定义与使用分离"的工程化实践

解决方案探索

方案一：remove @unlinked指令

PlantUML原生提供了remove @unlinked指令，可以隐藏未被显式引用的元素。但实际测试发现存在以下限制：

• 在某些情况下会抛出内部异常
• 当父元素（如System）包含子元素（如Component）时，需要同时引用父子元素才能正确显示

方案二：JSON结构化定义

社区开发者提出了通过JSON文件集中管理模型元素的方案。这种做法的优势包括：

• 实现真正的模型与视图分离
• 支持更复杂的模型关系管理
• 便于与其他工具链集成

方案三：PlantUML子部分包含

PlantUML的预处理功能支持通过!startsub和!endsub标记代码块，再使用!includesub选择性包含特定部分。这种方法可以实现：

• 模块化的模型定义
• 精确控制包含内容
• 保持单一可信源

最佳实践建议

1. 对于简单项目，可以尝试使用remove @unlinked结合显式引用的方式
2. 中大型项目推荐采用JSON结构化方案，便于长期维护
3. 需要精细控制包含内容时，子部分包含是最灵活的选择

实施示例

' 基础模型定义文件(model.puml)
!startsub SYSTEM_A
System(systemA, "系统A")
!endsub

!startsub COMPONENT_A1
Component(componentA1, "组件A1", "技术A")
!endsub

' 视图文件(view.puml)
!includesub model.puml!SYSTEM_A
Rel(systemA, componentB, "调用")

通过以上方法，开发者可以在C4-PlantUML项目中实现真正的模型与视图分离，提高架构描述的可维护性和一致性。