Loading... # 架构图绘制进阶指南：避免七大常见错误 # 一、概述 ## 1. 简介 ### A. 是什么 架构图是记录复杂系统的核心工具，用于展示系统组件之间的关系和交互。本文是对《架构图七大常见错误》的续篇，进一步深入探讨架构图绘制中的典型问题。 ### B. 为什么学 - 避免常见错误，提升图表可读性 - 掌握正确的图表设计原则 - 提高团队沟通效率 ### C. 学完能做什么 - 识别并修正架构图中的常见错误 - 选择合适的图表类型表达系统架构 - 创建清晰、准确的技术文档 ## 2. 前置知识 ### A. 必备技能 - 基本了解系统架构概念 - 熟悉常见图表类型（流程图、时序图等） ### B. 推荐知识 - 阅读过前作《架构图七大常见错误》 - 了解 UML 图表基础 # 二、核心概念 ## 1. 基本术语 - **资源（Resource）**：图表中的实体，位于线条之间的节点 - **类型（Type）**：描述资源的种类，如数据库表、虚拟机实例、服务等 - **名称（Name）**：区分同类资源的标识符 - **关系图（Relational Diagram）**：展示资源之间关系的静态图表 - **行为图（Behavioral Diagram）**：展示资源间具体交互的动态图表 - **扇形陷阱（Fan Trap）**：当关系信息在中间资源中丢失时产生的问题 ## 2. 工作原理 架构图的目的是清晰地传达系统结构和组件关系。好的架构图应该让观众快速理解系统组成，而不需要额外的解释。 ```mermaid graph LR A[系统理解] --> B{图表类型} B --> C[关系图] B --> D[行为图] C --> E[静态关系] D --> F[动态交互] E --> G[清晰传达] F --> G ```  # 三、七大常见错误详解 ## 1. 错误一：未包含资源名称 ### A. 问题描述 许多图表中的资源只标注了类型，而没有标注名称。虽然资源类型有价值，但不能替代名称。 ### B. 类型与名称的区别 - **类型**：描述资源是什么（what kind of thing），可以是具体项目（如数据库表、虚拟机实例）或抽象项目（如服务） - **名称**：区分同类资源，描述性名称还能揭示资源的角色或用途 ### C. 正确做法 当空间允许时，应同时显示资源的名称和类型。简单的方法是在资源名称后添加类型后缀，例如订单表、结果桶。当图表使用图标表示类型时，标注名称尤为重要。 ## 2. 错误二：未连接的资源 ### A. 问题描述 图表中的资源应该以某种方式与其他资源相连。包含完全断开的资源是一个常见错误。 ### B. 问题根源 这个问题通常出现在图表作者知道某个资源属于系统，但找不到清晰的方式来表达它。往往是试图在单一图表中包含过多信息的结果。 ### C. 正确做法 确保每个资源都有明确的连接关系。如果某个资源的作用不明确，应该重新评估是否需要包含它，或者创建一个单独的视图来展示该资源的上下文。 ## 3. 错误三：制作"主图" ### A. 问题描述 "主图"试图在单一图表中展示整个系统。这种做法源于一种错误的想法，即想要在一张图中"看到一切"。 ### B. 问题分析 主图几乎总是错误的。试图在一个图表中包含太多信息会压倒观众，导致图表失去沟通价值。 ```mermaid graph LR subgraph 单一主图 M[主图] M --> A[运行时依赖] M --> B[DNS配置] M --> C[CDN配置] M --> D[源代码] M --> E[部署依赖] end subgraph 分解为多视角 A2[运行时视角] B2[网络视角] C2[部署视角] D2[数据流视角] end ```  ### C. 正确做法 将复杂的系统图分解为多个视角（点 of view）。每个视角讲述一个完整的故事，互不干扰。大多数系统都足够复杂，值得将图表分解处理。如果使用基于模型的图表工具，不同视角可以明确共享资源，以保持它们的连接关系。 ## 4. 错误四：传送带综合征 ### A. 问题描述 传送带综合征发生在过度简化行为图时，忽略了系统中实际存在的往返交互和编排。结果是一个严重误导观众的图表。 ### B. 问题分析 许多架构图将系统描绘成装配线：数据整齐地从一个资源流向下一个资源，好像每个资源从其前驱接收输入，增强该输入，然后将其传递给后续资源。但现实情况是，资源之间存在大量来回交互。 ```mermaid graph LR subgraph 传送带式错误图 A[服务A] --> B[服务B] B --> C[服务C] end subgraph 正确的时序图 A2[客户端] -->|请求| B2[服务A] B2 -->|调用| C2[服务B] C2 -->|返回| B2 B2 -->|响应| A2 end ```  ### C. 正确做法 对于详细的交互，使用时序图（Sequence Diagram）。时序图是专门为展示资源间详细的来回交互而设计的，能够提供更高的细节保真度。 ## 5. 错误五：无意义的动画 ### A. 问题描述 带有无意义、分散注意力和令人烦恼的动画的图表在 LinkedIn 等社交网络上泛滥。 ### B. 问题分析 这类图表几乎完全是为了营销目的而存在。它们擅长吸引注意力，但作为技术资源几乎没有价值。除了分散注意力外，动画箭头完全多余，它们所指示的内容不过是箭头原本的方向。 ### C. 正确做法 除非创建图表主要是为了营销，否则应避免不必要的动画。技术图表应该专注于信息传递，而不是视觉花哨。 ## 6. 错误六：扇形陷阱 ### A. 问题描述 扇形陷阱发生在关系信息在中间资源中丢失时。例如，在事件驱动系统图中，如果边缘资源之间的通信在共享消息代理中被折叠，具体的关系就会丢失。 ### B. 问题分析 当多个资源通过一个中间资源连接时，原始的端到端关系变得模糊。这在事件驱动架构中尤其常见，多个生产者和消费者通过单个消息代理连接。 ```mermaid graph TD subgraph 扇形陷阱问题 A[生产者1] --> X[消息代理] B[生产者2] --> X X --> Y[消费者] end subgraph 正确解决方案 A2[生产者1] --> T1[主题1] B2[生产者2] --> T2[主题2] T1 --> C[消费者] T2 --> C end ```  ### C. 正确做法 通过在中间资源内部添加更具体的资源（在此示例中为主题），并重新路由通过这些新资源的关系，来修复扇形陷阱。这将恢复边缘节点之间的通信路径。当无法添加中间资源时，还有其他方法可以解决扇形陷阱。 ## 7. 错误七：假设 AI 可以从源代码生成高质量图表 ### A. 问题描述 虽然人工智能在绘图时可以发挥作用，但假设 AI 能够直接从源代码自动生成高质量系统图是一个错误的期望。 ### B. 问题分析 AI 生成的图表通常模糊不清、包含幻觉，并表现出上述许多问题。这些问题源于 AI 从源代码创建真实世界系统图时面临的挑战： - 几乎完全缺乏训练数据 - 难以分析密集的源代码 - 通常无法战略性地选择包含和省略什么 ### C. 正确做法 AI 在"白板"场景下最有用，即交互式地指定系统，可以在人类进行迭代改进和尝试想法时提供辅助。详细的系统图绘制仍然主要是一项人类活动。随着 AI 的改进，这种情况未来可能会改变，但目前人工设计仍然是最佳选择。 # 四、最佳实践 ## 1. 图表设计原则 ### A. 清晰优先 - 每个图表应该传达一个明确的信息 - 避免在一个图表中包含过多信息 - 使用适当的抽象级别 ### B. 观众导向 - 考虑观众的技术背景 - 调整细节级别以适应观众需求 - 提供必要的上下文和说明 ### C. 一致性 - 在整个图表集合中使用一致的符号 - 保持颜色、形状和线条样式的统一性 - 建立并遵循图表风格指南 ## 2. 图表类型选择 根据要传达的信息选择合适的图表类型： | 图表类型 | 适用场景 | 不适用场景 | |---------|---------|-----------| | 关系图 | 展示静态组件关系 | 展示详细交互流程 | | 时序图 | 展示详细交互流程 | 展示整体系统架构 | | 部署图 | 展示物理部署结构 | 展示逻辑组件关系 | | 状态图 | 展示状态转换逻辑 | 展示多组件交互 | ## 3. 图表管理 ### A. 版本控制 - 将图表纳入版本控制系统 - 记录图表的变更历史 - 保持图表与代码同步更新 ### B. 多视角分解 - 按关注点分解复杂系统 - 为不同的受众创建不同的视图 - 在视图之间保持一致的元素标识 ### C. 文档配套 - 为图表提供必要的文字说明 - 解释图表中的关键决策 - 记录图表的假设和约束 # 五、工具推荐 ## 1. 基于模型的图表工具 使用支持模型和视角分离的工具，如 Ilograph，可以更好地管理复杂系统的图表。 ## 2. 标准图表工具 - Mermaid：基于文本的图表语言 - PlantUML：UML 图表生成工具 - Draw.io：免费在线图表工具 ## 3. 专业架构工具 - Archi：开放源码架构建模工具 - Structurizr：以代码为中心的架构文档工具 # 六、总结 架构图是沟通系统设计的重要工具，但常见的错误会削弱其效果。通过避免这七大错误，你可以创建更清晰、更有用的架构图： 1. 始终标注资源名称，而不仅仅是类型 2. 确保所有资源都有适当的连接 3. 避免创建过于复杂的"主图"，使用多视角分解 4. 不要过度简化行为图，使用时序图展示详细交互 5. 避免无意义的动画，专注于信息传递 6. 注意并修复扇形陷阱 7. 理解 AI 的局限性，人工设计仍然是最佳选择 记住，好的架构图不是艺术品，而是沟通工具。它的价值在于帮助他人理解你的系统设计。 *** ## 参考资料 1. [7 More Common Mistakes in Architecture Diagrams](https://www.ilograph.com/blog/posts/more-common-diagram-mistakes/) 2. [7 Common Mistakes in Architecture Diagrams](https://www.ilograph.com/blog/posts/diagram-mistakes/) 3. [Breaking Up the Master Diagram](https://www.ilograph.com/blog/posts/breaking-up-the-master-diagram/) 4. [Avoid Fan Traps in System Diagrams](https://www.ilograph.com/blog/posts/avoid-fan-traps-in-system-diagrams/) 最后修改：2026 年 03 月 23 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏