不会过时的架构图：活文档工作流

每个工程团队都有这样一张图：Wiki 里的那张架构图，多年前曾经准确过几个星期。新同事认真研究它，然后从同事那里得知，一半的框已经改了名，中间那个队列去年春天就被替换掉了。大多数架构文档最佳实践关注的是“画什么”。本文讨论更难的部分：在初稿之后如何让架构图保持准确，并建立一套把架构图当作活文档、而不是一次性产物的工作流。

架构文档为什么会过时

架构图过时，很少是因为大家偷懒，而是因为围绕它的流程让过时成了常态。

• 它们是一次性产物。 架构图通常为一次设计评审、一次迁移启动会或一次审计而画。会议结束后，就没人有理由再打开它。
• 截图被贴得到处都是。 源文件躺在某个人的笔记本电脑里，而一张 PNG 被贴进 Wiki、入职文档、三份幻灯片和一个 README。现在有五份副本，却没有一份可以编辑。
• 没有负责人。 “平台团队”不是负责人。当没有具体的人负责时，每个人都以为别人会去更新。
• 没有触发更新的机制。 代码变更要经过 pull request、评审和 CI。架构图只有在有人想起来时才会更新，而这很少恰好是系统发生变化的时候。
• 信息太多。 一张包含每个 Pod、每个队列、每个 IAM 角色和每条用户旅程的图，完成当天就已过时，因为任何地方的任何变化都会让它出错。

这些首先都不是工具问题；再好的绘图工具也弥补不了缺失的负责人。但工具可以让正确的工作流变得省力，或者变得费劲。

面向活架构图的架构文档最佳实践

下面是我们推荐的工作流，观点鲜明是有意为之。

1. 每张图只有一个事实来源

每张架构图只存在于一个可编辑的位置，其他地方都只是指向它的链接或嵌入。如果你正要导出一张 PNG 贴到别处，先问问自己：一个链接是否就够了？通常是够的。

2. 用链接，不要复制

Wiki、文档站点和 README 应该指向活的架构图，而不是放一张它的图片。实时嵌入的架构图会随源头变化而变化；贴上去的截图在下一次变更后就永远是错的。如果确实需要静态图片，比如给审计人员的 PDF，请把它当作带日期的导出件，不要放进大家日常依赖的文档里。

3. 指定负责人

每张图都要有负责人：一个人，或者一个有明确联系人的团队。负责人不必亲自画每一处改动，但要能发现图什么时候不对了，也是大家提问的对象。把负责人写在图上，也写进你的架构图索引。

4. 把更新触发点挂在已有的事件上

不要依赖记忆。把架构图的更新绑定到本来就会发生的事件上：

• Pull request。 在 PR 模板中加入一个“架构影响”复选框。
• ADR。 每条被接受的架构决策记录（ADR）都链接到它所改变的架构图，并在接受决策时同步更新这张图。
• 事故复盘。 如果事故暴露出架构图有误或遗漏了某个依赖，就把修正它列为一项待办行动。
• 季度评审。 负责人为每张图花几分钟确认它是否仍与现实一致，然后更新“最近评审”日期。

一个 PR 模板片段：

## Architecture impact
- [ ] This change does not affect any architecture diagram
- [ ] I updated the affected diagram(s) and linked them below
- [ ] This needs an ADR (link):

5. 选择合适的细节层级

用分层的视图代替一张巨大的图。C4 model 提供了一套通用词汇：System Context 视图（人和系统）、Container 视图（应用和数据存储），以及某个 container 内部的 Component 视图。高层级很少变化，维护成本低；低层级变化频繁，所以只在确实需要的地方画，更底层的部分就以代码为准。

一条实用的经验：如果一张图每个迭代都要改，它很可能画得深了一层。

6. 让日期和版本一目了然

在每张图的一角写上负责人和“最近评审”日期。读者一眼就能判断可信程度：上个月评审过的图和两年前评审过的图，值得的信任程度不同。没有日期时，每张图看起来都同样权威，这比显示一个旧日期更糟糕。

7. 维护一份架构图索引

用一个页面列出所有重要的架构图：

索引能让缺口一目了然（没有负责人、日期太旧），也是季度评审最自然的起点。

8. 把架构图和 ADR 配对

架构图展示架构 是什么，却无法说明 为什么。架构决策记录正好补上这一空白。Michael Nygard 的 原始 ADR 格式 足够简短，大家真的愿意写：标题、状态、背景、决策、后果。在图中链接 ADR，在 ADR 中链接图：

# ADR-019: Move payment events to a dedicated queue

## Status
Accepted

## Context
Payment events share a queue with notifications.

## Decision
Give payment events their own queue.

## Consequences
One more queue to operate. Diagram "Payments: containers" updated.

半年后有人问“为什么是这样？”，答案只需点一下就能找到。

Archboard 如何支持活文档工作流

Archboard 是一个托管式（云端 SaaS）架构工作区，上面的工作流大部分都能对应到它已有的功能。下面说明它覆盖了哪些部分，以及哪些地方仍需要你自己的流程。

• 单一事实来源。 每张图都是工作区中的一个文档，支持自动保存和修订快照。Free 保留最近 5 个修订版本；Pro 保留一年的修订历史，Enterprise 不设上限。
• 用链接，不要复制。 所有套餐都有公开分享链接（Free 带品牌标识）。在 Pro 和 Enterprise 上，你可以通过 iframe 把架构图嵌入文档站点，页面显示的就是当前版本，而不是逐渐过时的截图。
• 在代码仓库中保留历史。 把架构图导出为结构化 JSON，提交到代码或 ADR 旁边。这样除了应用内的修订版本，你还能获得 Git 历史和针对架构图变更的评审步骤。导出是手动操作，所以要把它变成 PR 习惯的一部分。
• 画布上的笔记。 Markdown 节点直接放在画布上，负责人、最近评审日期、ADR 链接和简短图例都可以写在图里，而不是另起一个文档。
• 合适的细节层级。 C4 Model 包提供 Person、Software System、Container、Component 和 Database 节点以及 boundary。节点是带端口的一等节点，通过连接端口来建立关系。把 context 视图和 container 视图保存为两张独立的图。

针对单个系统的具体做法：

1. 创建两张图：“Payments: Context”和“Payments: Containers”。
2. 在左上角添加一个 Markdown 节点，写上负责人、最近评审日期和相关 ADR 的链接。
3. 在 Pro 上，把 container 视图嵌入该服务的文档页面；在 Free 上，使用分享链接。
4. 当某个 PR 改变了架构时，更新架构图（或者让处理该 PR 的编程智能体通过 Archboard 的 MCP 服务器来完成），导出 JSON，并在同一个 PR 中提交到 docs/architecture/。
5. 把两张图都加入索引页面。

完整功能请参见产品概览，C4 专用配置请参见 C4 使用场景，各计划包含的内容请参见价格页面。Free 提供 3 张图，每张图可容纳 15 个图表节点和 150 个便签、文本、贴纸和思维导图主题，足以为一个系统试画上下文视图；当你要为整个平台编写文档时，Pro 可解锁无限的图和节点。

活文档检查清单

• 每张图都只有一个可编辑的来源
• 文档嵌入或链接活的架构图，没有粘贴的截图
• 每张图都有明确的负责人，并标注在图上
• PR 模板中有“架构影响”复选框
• 被接受的 ADR 链接到它所改变的架构图
• 事故复盘会问“架构图还准确吗？”
• 负责人每季度评审自己的图并更新日期
• 架构图按 C4 层级拆分，而不是一张巨大的图
• 架构图索引列出层级、负责人、最近评审日期和 ADR
• 架构图的源文件（例如 JSON 导出）提交在代码旁边

常见问题

一个系统应该有多少张架构图？ 先从一张 context 视图和一张 container 视图开始。只为大家经常询问的部分补充 component 视图。少量准确的图胜过大量过时的图。

架构图应该放在代码仓库里还是工具里？ 在一个地方编辑，并把历史保存在团队已经评审变更的地方。使用 Archboard 时，你在画布上编辑，再把 JSON 导出提交到 Git。

免费开始 — 1 个席位，无需信用卡