序列图是可视化系统中对象或组件随时间交互的基本工具。它们描绘了消息、数据和控制信号的流动，提供了系统行为的时间视图。正确使用这些图表可以减少歧义，统一团队理解，并以技术与非技术人员均可理解的格式记录复杂逻辑。然而，杂乱或结构不良的图表反而会导致困惑而非清晰。本指南概述了构建能够有效传达意图的序列图的基本标准。
🧩 理解核心组件
在深入布局和流程之前，必须使用标准元素建立坚实的基础。每个序列图都依赖于特定的构建模块。一致地使用这些元素，可确保任何审阅文档的人都能理解逻辑，而无需依赖图例。
- 生命线：表示交互中的参与者。通常以从图顶部延伸到底部的垂直虚线表示。每条生命线代表一个对象、角色或子系统。
- 参与者：表示流程的发起者。通常以左侧的简笔人像或简单图标表示，用以表明外部用户或系统触发了该序列。
- 消息：连接生命线的水平箭头。它们表示从一个参与者发送到另一个参与者的请求、调用或信号。
- 激活条：放置在生命线上的矩形条。它们表示参与者正在积极执行操作的时间段。
- 返回消息：指向发送者的虚线箭头。它们表示请求已完成或数据已返回。
确保所有参与者名称清晰明确。避免使用“Object1”或“System”等通用名称。应使用“UserSession”、“PaymentProcessor”或“OrderRepository”等描述性名称。这种上下文命名有助于读者无需查阅其他文档即可立即理解每个组件的角色。
📩 规划消息流
序列图的核心是消息流。你绘制和标注这些箭头的方式决定了读者对交互时间与性质的理解。遵循标准符号可避免误解。
1. 同步与异步调用
区分阻塞与非阻塞操作。实心箭头头通常表示同步消息，发送方在继续之前会等待响应。空心箭头头（杆状箭头）通常表示异步消息，发送方在发送信号后立即继续执行。
- 同步：在后续逻辑依赖于调用结果时使用。
- 异步：用于“发送即忘”操作，例如日志记录或通知，其流程不依赖于立即返回。
2. 处理返回值
不要用每一个返回值来使图表杂乱。仅返回对逻辑或数据流具有重要意义的返回消息。如果方法返回布尔状态，可在标签中注明（例如“返回：true”）。如果返回大型对象，可进行概念性描述（例如“返回：OrderData”）。
确保返回箭头以虚线绘制。这种视觉区分可将请求与响应分开，使时间线更易阅读。除非为调试流程所必需，否则避免为不跨越组件边界的内部操作绘制返回消息。
🔄 使用控制框管理复杂性
随着系统规模扩大，交互顺序变得非线性。你会遇到涉及条件、循环和可选行为的场景。控制框可让你封装这些行为，而不会破坏图表的线性阅读流程。
1. 选择（Alt）框
使用Alt用于表示条件逻辑（if-else 情况）。根据条件将框架拆分为多个片段。
- 主片段： 主要条件（例如：“用户已认证”）。
- 否则片段： 备用条件（例如：“用户未认证”）。
清晰地标记每个片段。避免嵌套过多层级的 Alt 框架，因为这会造成难以理解的“意大利面式”效果。如果逻辑分支过深，建议将序列图拆分为多个独立的图，每个图对应一个主要场景。
2. 可选（Opt）框架
使用Opt用于表示可能根据特定条件出现或不出现的行为。这与 Alt 不同，Alt 表示路径之间必须做出选择。例如，“忘记密码”链接可能仅在登录页面显示。使用 Opt 框架来表示这种逻辑，以表明它是标准流程的例外。
3. 循环框架
当一个过程重复时，使用Loop 框架。无需绘制每一次迭代，只需绘制一个具有代表性的交互，并将其包含在带有条件的循环框架中（例如：“对购物车中的每个项目”）。
- 在框架标题中明确说明迭代条件。
- 确保循环体准确地表示一次迭代。
- 避免使用循环来表示每次迭代行为都会变化的复杂逻辑；相反，应使用循环并添加注释说明变化情况。
🎨 视觉清晰度与布局
序列图是一种视觉化产物。其有效性在很大程度上取决于其外观。杂乱的图表暗示着代码混乱或设计过程混乱。应严格遵守格式规则，以保持专业性。
1. 对齐与间距
将所有生命线垂直对齐。确保消息的水平位置与时间的逻辑流程一致。参与者应根据交互频率或逻辑层级从左到右排列。发起者通常应位于最左侧。
在消息之间使用一致的垂直间距。不要将交互紧密堆叠在一起。空白空间是降低认知负荷的工具。如果两个交互迅速连续发生，应稍作间隔以区分事件。
2. 激活条管理
激活条表示正在处理。如果处理时间可以忽略不计，则无需为每个消息都绘制激活条。应重点关注跨越多个消息或跨系统边界的激活条。这能突出计算工作量集中的位置。
3. 颜色使用
尽管文档中的图表通常为单色，但适度使用颜色可以提高可读性。然而，确保颜色不是意义的唯一指示器。使用颜色来分组相关的参与者或突出显示特定的错误路径。始终确保图表在灰度下也清晰可读，以适应打印友好的文档。
👥 针对不同受众的定制
并非每位读者都需要相同程度的细节。面向资深架构师的图表与面向初级开发者的图表有所不同。应根据受众调整细节程度。
| 受众 | 关注领域 | 详细程度 | 排除 |
|---|---|---|---|
| 业务利益相关者 | 高层级工作流程 | 低 | 数据库调用，API 头部 |
| 系统架构师 | 组件集成 | 中 | 变量名，特定逻辑 |
| 开发者 | 逻辑实现 | 高 | 无（关注流程） |
对于业务利益相关者，应抽象技术步骤。不要使用“POST /api/v1/orders”这样的表述，而应将交互标记为“创建订单请求”。这能确保关注点集中在业务价值上，而非端点语法。
对于开发者，应在有帮助的地方包含方法签名。明确指出错误处理路径。如果事务回滚，应显示回滚消息并返回给调用者。
⚠️ 常见错误与修正
避免常见陷阱与遵循最佳实践同样重要。在最终确定文档前，请对照此清单审查您的工作。
- 抽象层次混杂：不要在同一张图中混合使用高层级业务操作与低层级数据库查询。这会混淆时间线。应将数据库持久化逻辑与编排逻辑分开。
- 缺少返回消息： 如果发送了一条消息，通常返回消息意味着操作完成。省略返回消息会使流程显得不完整。
- 生命线过于拥挤： 如果生命线包含过多交互，就会变成“一团乱麻”。应将图表拆分为子流程，或使用注释引用外部逻辑。
- 时间推进不清晰： 确保时间严格从上到下流动。除非是返回消息，否则不要画向上方的箭头。不表示消息的对角线箭头会造成混淆。
- 命名不一致： 确保不要用不同名称指代同一参与者（例如，“User”与“Client”）。一致性有助于建立文档的可信度。
🔄 维护与演进
软件很少是静态的。需求会变化，功能也会被弃用。如果一个序列图没有得到维护，就会成为一种负担，可能导致开发人员误以为图表与代码一致，从而引发错误。
1. 版本控制
将图表视为代码。将它们与应用程序一起存储在同一个版本控制系统中。使用有意义的提交信息，说明图表为何发生变化。如果图表被更新，请在标题中注明版本号。
2. 与代码关联
尽可能将图表元素链接到实际的实现文件。这使开发人员能够从可视化表示导航到源代码。这减少了文档与现实之间的摩擦。
3. 定期审查
安排定期审查你的图表。在代码重构或冲刺规划期间，确认图表仍然反映系统的当前状态。如果某个功能已被移除，应立即更新图表，以避免新团队成员产生混淆。
📝 关键指南摘要
总而言之，有效的序列图需要在设计和维护上都保持纪律性。它们不仅仅是绘图，而是系统与构建或维护它的人之间的契约。遵循以下原则，可以确保你的文档增加价值，而非产生噪音。
- 从参与者开始：始终明确谁启动了该过程。
- 保持线性：时间应垂直流动，不应倒流，除非是返回。
- 限制深度：避免Alt和Loop框的深层嵌套。将复杂的逻辑拆分为多个图表。
- 清晰标注：每个箭头和框都应有描述性标签。
- 审查清晰度：请同事在没有上下文的情况下阅读图表。如果他们无法理解流程，请简化它。
投入时间创建高质量的序列图，将在减少调试时间、加快新开发人员入职速度以及减少架构误解方面带来回报。一张清晰的图表，是一种无声的共识，表明每个人都以相同的方式理解系统。
