实际场景架构图实例详解：逻辑分层、部署与时序图

我见过太多团队把架构图画成了壁纸：贴在文档首页、塞进评审 PPT 第三页，然后整整一年没人再看第二眼。等到新人入职问“这个系统长什么样”，老同事翻出那张两年前的图，指着已经下线的模块说“这块现在不用了”，剩下半张图全是误导。问题不在画图这件事本身，而在于大部分架构图是“为了完成任务而画”，不是“为了让某个人做出某个判断而画”。这篇内容我想聊的是实际场景下的架构图实例及其详细说明——不是教科书上的分层示意图，而是能直接放进项目文档、能让运维照着排查、能让新人半小时看懂的图，配上它背后那套“为什么这么画”的说明文字。适合三类人看：刚接手存量系统的开发者、需要向非技术同事解释系统的技术负责人、以及被要求“画个架构图”但不确定从哪下笔的同学。全文会给出三套完整的实例拆解（逻辑分层、物理部署、关键链路时序），附带参数估算过程、常见翻车点和一套让图不过期的维护机制。

1. 先想清楚：架构图到底画给谁看

1.1 一张图的价值等于它降低的决策成本

我判断一张架构图合不合格，只有一个标准：目标读者看完之后，能不能少问三个问题。如果读者看完还得追问“这个服务跟那个服务是什么关系”“挂了会怎样”“数据从哪来到哪去”，那这张图的信息密度就不够，或者信息放错了位置。反过来，如果一张图把读者不需要的细节也塞进去，比如给产品经理画一张带连接池参数和 JVM 参数的部署图，那它的价值同样是负的——读者被无关信息干扰，反而抓不住重点。

这个判断标准会直接决定画图的第一步不是打开工具，而是写清楚三行字：读者是谁、他要做什么决策、这张图的有效期到什么时候。我习惯把这三行写在图的标题下方，作为元信息。比如“读者：值班运维；决策：故障时先看哪个组件；有效期：下次大版本发布前”。听起来有点小题大做，但实测下来，写这三行能让画图时间缩短至少三分之一，因为你会主动砍掉大量“好像应该画上”的东西。

顺带说个反直觉的观察：信息越全的架构图，被使用的频率往往越低。一张画了四十个方框、六十条箭头的全景图，读者的第一反应是“算了，我还是直接问人吧”。真正被反复打开的，通常是三到五张各讲一件事的小图，加上一段说人话的说明文字。所以我在实际项目里倾向于“一图一议题”，宁可拆成五张，也不合并成一张大杂烩。

1.2 三类读者的信息密度完全不同

同一个系统，面对不同读者，图的抽象层级差别可能有三四层。我一般把读者分成三类，对应三种画法。

第一类是业务方与非技术同事，他们关心的是“系统边界在哪、我提的需求落在哪个环节、为什么这个改动要排期两周”。给他们看的图，方框数量控制在十个以内，不出现任何中间件名字，用“订单中心”“库存中心”这种业务语言，箭头只表示业务动作，不表示协议。图下方配一段两百字左右的说明，把“用户提交→系统校验→资源锁定→结果通知”这条主线讲清楚。

第二类是同团队或跨团队的开发者，他们关心的是模块职责、依赖方向、接口契约、数据归属。这张图可以出现服务名、数据库、缓存、消息队列，方框数量二三十个属于正常，但必须标清楚分层和依赖方向，并且明确“谁调用谁、谁是同步、谁是异步”。这张图的信息量最大，也最容易被画坏，后文会重点拆。

第三类是运维与稳定性负责人，他们关心的是物理部署、网络分区、单点、容量水位、故障域。这张图上应该出现机房或可用区的划分、负载均衡、实例数量、主从关系、备份链路。业务语义可以弱化，但每一条跨区域的连线都必须标注流量类型和带宽量级。

把这三类读者混在一张图上，是实际项目里最常见的错误，没有之一。混出来的结果是：业务方看不懂中间件，开发者被机房划分干扰，运维找不到实例数量。拆开画反而省事，因为每张图只需要讲一条逻辑。

1.3 我的分层原则：一张图只回答一个问题

具体执行时，我会给每张图配一个“问题句”，写在图的元信息里，格式是“这张图回答：______”。比如“这张图回答：一次下单请求会经过哪些组件、在哪些点可能失败”。有了这个句子，画图过程中每次犹豫“这个要不要画”，都可以拿它来裁决——跟这个问题无关的，一律不画。

这个习惯带来的另一个好处是图的命名变得规范。我的命名格式是“系统名-视图类型-版本日期”，例如“订单系统-逻辑分层-20240612”。光看文件名就知道这是什么图、什么时候画的，比“架构图最终版-改3”这种命名靠谱太多。

最后说一个容易被忽略的点：图例。很多人觉得图例是形式主义，实际上它是降低阅读成本最划算的投入。我固定用四类视觉编码：实线箭头表示同步调用、虚线箭头表示异步消息、粗边框表示有状态组件、加锁图标（用文字标注“单点”即可，不用图标）表示单点。颜色只用来区分归属团队或部署区域，绝不用来表达“重要程度”，因为重要程度是主观的，而读者需要的是客观信息。

2. 架构图分类与选型：什么场景画什么图

2.1 五类常用图的适用边界

在没有明确规范的情况下，大部分人画出来的其实是“四不像”：既有一点分层，又有一点部署，还夹着几条业务流。我的做法是先选类型再动笔，把常见的五类图各自的职责划清楚。下表是我在项目里常用的对照，可以直接拿去当团队约定。

这张表最有用的一列是“不该出现的东西”。实际画图时，破坏图面清晰度的往往不是缺了什么，而是多了什么。比如逻辑分层图里一旦出现“3 台实例”，读者的注意力就会被容量问题带走，反而忽略模块边界这个主线。

2.2 C4 模型的取舍：我通常只画两层

C4 模型（Context、Container、Component、Code）是业界比较成熟的架构描述方法，四层从宏观到微观逐级下钻。它的价值在于给出了统一的抽象层级，但它也有个现实问题：四层全画完，工作量抵得上半个需求文档，而且下层图老化得极快。

我的实际取舍是只画前两层，再按需补一张时序图。第一层（系统上下文）用来对齐边界：把系统当成一个黑盒，画出它和外部角色、外部系统之间的交互，方框数量控制在八个以内。这一层的寿命最长，一年不动很正常，适合放在文档最前面。第二层（容器/服务）用来讲清内部构成：有哪些可独立部署的单元、各自用什么存储、之间怎么通信。这一层的寿命以季度计，需要跟着发布节奏更新。

第三、四层我基本不画成图，改用两种替代方案：一是接口清单表格，把组件间的契约用表列清楚，比图更精确也更好维护；二是关键链路时序图，只对最容易出问题的那两三条链路画，覆盖正常路径和一两条异常分支。理由很实在——组件内部的类图、代码结构图，IDE 一秒钟就能生成，手画一遍除了浪费时间没有额外收益。

2.3 图例与命名约定：让符号自己说话

统一约定这件事，在小团队里看起来没必要，人员一到七八个就会开始疼。我们踩过的坑是：同一条虚线，A 同学用来表示异步消息，B 同学用来表示“已废弃”，C 同学用来表示跨团队边界。评审会上三个人对着同一张图理解出三种意思，讨论半小时才发现说的不是一回事。

后来我们定了一份一页纸的《图面约定》，核心就六条，贴在这里供参考：

• 箭头方向统一为“调用方 → 被调用方”，消息流向也是“发送方 → 接收方”，不允许反向，避免歧义。
• 实线代表同步阻塞调用，虚线代表异步或最终一致，粗线仅用于标注核心链路（一张图最多两条）。
• 方框内第一行写中文职责名，第二行小字写技术标识（服务名或组件类型），两行都要有。
• 有状态组件（数据库、缓存、队列、对象存储）统一画成圆柱或带“存储”标注的方框，与无状态服务在视觉上区分开。
• 所有跨信任边界的连线必须加文字标注，写清楚协议和用途，比如“HTTP 内部调用 / 查询库存”。
• 图的右下角固定写元信息：作者、日期、适用版本、下次校验时间。

这六条落地成本很低，收益却很明显。最直接的体现是新人上手时间：有约定的团队，新同事看图的提问量大概能少一半，因为符号不需要靠猜。

3. 工具选型：从手绘到代码化绘图

3.1 三类工具的适用场景与真实成本

工具这块我不太喜欢给绝对推荐，因为选型强依赖于“图要不要跟着代码一起演进”。按我的实际使用经验，可以分成三类。

第一类是轻量手绘风工具，包括白板和手绘风格的绘图软件。优点是零门槛、画得快、天然带着“这是草图不是最终稿”的心理暗示，特别适合需求评审早期的头脑风暴。缺点是排版靠手调，改动一个方框可能牵动整张图的位置，图一复杂就容易崩。

第二类是图形化拖拽工具，模板和形状库齐全，输出规整，适合做对外汇报和正式文档。这类工具的隐形成本是协作：多人同时改一张图容易冲突，而且图文件通常是二进制或私有格式，放进代码仓库没法 diff，评审时只能截图，改了什么全靠嘴说。

第三类是代码化绘图工具，用文本描述图形，由渲染引擎出图。它的最大价值不是好看，而是可版本化：图源文件是纯文本，能提交、能 diff、能出现在代码评审里。缺点是排版控制力弱，复杂布局需要反复调，学习曲线大概需要半天到一天。

我的实际组合是这样：早期讨论用第一类，正式文档用第二类做精修，而需要长期维护、频繁变更的核心架构图用第三类，源文件直接放在代码仓库的 docs 目录下。这个组合的本质是按“图的半衰期”分配工具——活得久的图，值得用可维护的方式存。

3.2 代码化绘图的实际收益与代价

代码化绘图的收益，最直观的是改动成本。举个真实场景：系统从单机房扩展到双机房，图形化工具里要手动挪几十个方框、重连十几条线，半小时起步；文本描述里可能只是把几个节点包进一个新的分组块，改五行，渲染出来布局自动调整。

代价也说清楚，避免踩坑。第一，字体和中文支持需要提前配好，否则渲染出来是方块，我第一次用的时候就栽在这上面，排查了快一小时。第二，自动布局不可控，元素一多容易出现连线交叉、标签重叠，需要手动指定方向或分组顺序，这部分调优时间往往比画图本身还长。第三，评审体验下降，非技术同事看不懂文本描述，所以代码化产出的图必须同步导出一份图片放进文档，不能只给源文件链接。

还有一个实践细节值得提：代码化绘图的源文件，我建议一个文件对应一张图，不要把所有图塞进一个大文件。原因是 diff 的可读性——一次改动只影响一个文件，评审时一眼能看出动的是哪张图。文件名与图的标题保持一致，靠命名而不是靠目录层级来组织。

下面是一段我常用的时序图描述示例，用来表达“下单主链路 + 库存预占失败分支”，供参考格式：

@startuml participant "客户端" as C participant "接入层" as G participant "订单服务" as O participant "库存服务" as S participant "消息队列" as M C -> G : 提交下单请求（幂等键） G -> O : 转发（超时 3s） O -> S : 预占库存（超时 800ms） alt 预占成功 S --> O : 锁定成功（有效期 15min） O -> O : 落订单（待支付） O --> C : 返回订单号 O -> M : 发支付超时延时消息 else 预占失败 S --> O : 库存不足 O --> C : 返回可售罄提示 end @enduml

这段描述里，我特意标注了超时时间和幂等键，因为这两项是线上问题的高发点。图的价值不在于画出“谁调用谁”，而在于把约束条件写在图上，让读图的人不用翻代码就知道边界在哪。

3.3 版本管理：把图当代码一样对待

图存在哪里，决定了它会不会过期。我的做法是三条硬规矩。

第一，图源文件和代码同仓库，路径固定为docs/architecture/，跟代码一起提交、一起评审。架构变更的提交里如果只有代码没有图，评审时直接打回，这条规矩比任何口头强调都管用。

第二，每张图带元信息头，至少包含四项：最后校验日期、适用版本或里程碑、负责人、失效条件（比如“引入分库分表后本图作废”）。失效条件这一项特别有用，它把“什么时候该重画”从主观判断变成了可检查的条件。

第三，过期图不删除，移入archive/目录并在文件名后加-deprecated。删除历史图看起来干净，实际上断掉了追溯链——半年后有人问“当时为什么这么设计”，唯一能回答的就是那张旧图。

这三条落地之后，我观察到的变化是：架构图的平均“新鲜度”从大半年缩短到一两个月，而且新人提问里“图跟代码对不上”这类问题基本消失。

4. 实例拆解一：内部业务系统的逻辑分层图

4.1 背景与画图目标

假设我们手上有一个内部订单处理系统，日订单量二十万级，对外提供下单、查询、取消三个核心能力，内部依赖库存、支付、通知三个下游。团队六个人，系统跑了两年，代码里堆了不少历史包袱。现在要做的是：给这张图定一个明确目标——回答“新增一个业务规则应该改哪一层、会不会影响其他模块”。

目标定下来之后，画法就清楚了：不需要画实例数量，不需要画机房，不需要画数据库表结构。需要画的是分层、每层的职责边界、层与层之间的调用方向，以及跨模块的依赖是否被允许。读者是同团队和相邻团队的开发者，他们看图的目的是判断改动影响面。

这里插一句我的经验：画之前先跑一遍代码里的依赖关系，靠记忆画出来的分层图，八成跟实际不符。我一般会花二十分钟把服务间的调用日志或依赖配置捞一遍，把“以为没有的依赖”找出来。这一步经常有惊喜，比如发现某个数据访问层直接调了另一个模块的服务，这种越层依赖恰恰是图上最该暴露的问题。

4.2 分层划分与边界判定的思考过程

图的结构我采用五层，从外到内依次是接入层、应用层、领域服务层、数据访问层、基础设施层。这个分法不新鲜，关键在于每层的准入规则要写清楚，否则分层就只是画着好看。

接入层负责协议转换、鉴权、限流、参数校验，规则是“不做任何业务判断”。这条规则的实际意义是：新增一个业务规则时，如果改动落在接入层，就说明规则被放错了位置。应用层负责用例编排和事务边界，规则是“只编排不实现”，也就是调用领域服务完成一个完整用例，自己不含核心业务计算。领域服务层是业务规则的唯一归属地，规则是“不直接访问数据库以外的东西”，也不允许跨领域直接调用，跨领域必须经过应用层编排。数据访问层负责持久化，规则是“不含业务判断”，只有增删改查和必要的查询组合。基础设施层放缓存、消息、对象存储、外部接口适配。

这套规则的实操价值在于它把“该改哪里”变成了可执行的判断。举个例子：需求是“下单时如果用户有未支付订单，需要提示”。这条规则属于业务判断，应该落在领域服务层，而不是接入层的参数校验里。有了分层图加规则说明，评审时可以直接指着图问“这个改动落在哪一层”，比讨论半小时更有效。

边界判定上，我特别标注了两类容易被破坏的约束。一是领域服务之间禁止横向调用，如果需要组合两个领域的能力，必须上移到应用层编排，避免领域之间形成网状依赖。二是数据访问层禁止跨领域访问他人数据表，跨领域数据必须通过对方的服务接口获取。这两条在图上的表达方式很简单：用不同底色区分领域，并在图下方用一段文字说明约束。实测下来，这种“图 + 约束说明”的组合比单纯一张图有效得多，因为图只能表达现状，说明文字才能表达规则。

4.3 关键标注：容量、数据量怎么估

逻辑分层图本身不强调容量，但在实际场景里，标注几个关键量级能极大提升图的可信度，因为读者立刻能判断“这个设计撑不撑得住”。我一般标注三类数字，而且都是估算，不追求精确，只求数量级正确。

第一类是请求量。日订单二十万，假设 80% 集中在四小时内，那就是 160000 ÷ 14400 ≈ 11 QPS 的平均值。峰值按平均值的 4 倍估算，约 45 QPS。这个数字决定了应用层需要多少实例、连接池开多大。我在图上标注为“峰值约 50 QPS（下单接口）”。

第二类是数据量。订单主表单行按 1KB 估，日增 20 万行就是 200MB/天，一年约 70GB。加上索引和从库，主库存储预留 300GB 比较稳妥。这个数字直接决定了是否需要在一年内考虑分表——单表超过千万行之后，即使索引做得再好，某些范围查询也会开始变慢，所以图上标注“预计 14 个月后触发分表评估”。这句话的价值在于，它把未来的技术债变成了一个有时间点的待办，而不是等出问题再说。

第三类是缓存量级。经验上热数据大约占总量的 20%，七天内的订单约 140 万条，但真正被频繁访问的是“待支付 + 近三小时”的部分，估算在 30 万条以内，单条 2KB，约 600MB。所以缓存实例选 2GB 规格，留三倍余量。这个计算过程我建议直接写在图的说明里，因为它是“为什么是这个规格”的唯一依据，比写“按经验配置”有说服力得多。

4.4 说明文字模板：图只是索引，文字才是正文

一张图配一段说明，这段说明的写法有讲究。我的模板固定四段，每段两到四句话，加起来三百字左右，读者三十秒能扫完。

第一段写这张图回答什么问题、读者是谁。第二段写分层与边界的关键约束，也就是那些“图上看不出来但必须遵守”的规则。第三段写关键量级与容量结论，包含估算过程的一句话概括。第四段写已知的例外与待改进项，比如“通知模块目前直接读订单库，属于已知越层，计划下季度改为订阅消息”。

第四段是我认为最有价值的部分。绝大多数架构图只画“应该是什么样”，不写“实际是什么样”，结果图越漂亮，跟现实差距越大，最后没人信。把已知的例外老老实实写出来，图才立得住。我在实际项目里甚至会标注“此处为临时方案，标记为技术债 #37”，让读图的人知道哪里是坑。

5. 实例拆解二：部署架构图与网络分区

5.1 从逻辑到物理的映射方式

逻辑分层图讲的是“有哪些模块”，部署架构图讲的是“这些模块跑在哪儿”。两者的映射关系不是一一对应，一个服务可能部署多个实例，多个模块可能合并成一个进程。画部署图时，我习惯先在纸上列一张映射表，再动手画，避免画到一半发现漏了组件。

映射表至少包含四列：逻辑组件、部署形态（独立服务/合并进程/托管服务）、实例数量、所在区域。这张表填完，图的结构基本就出来了。实际项目里最容易漏的是“定时任务”和“后台消费者”这两个角色——它们不在请求链路上，画图时很容易被忘掉，但它们同样占用资源、同样会产生故障，必须出现在部署图上。

下面是我们那个订单系统的映射结果，作为实例参考：

表格填完，画图时只要把区域画成大方框、把节点画进对应方框、把实例数写在方框里就行，逻辑会非常清楚。

5.2 区域划分与流量走向的标注规范

部署图的核心视觉结构是区域嵌套：最外层是地域，往里是可用区，再往里是子网或机架。每一层用不同的边框粗细区分，不要用颜色区分层级（颜色留给“是否跨区”这种判断信息）。区域之间的连线是这张图的重点，我要求每条跨区连线都标注三件事：方向、流量类型、量级。

方向写“单向”还是“双向”，流量类型写“同步调用/异步复制/备份传输”，量级写带宽或 QPS 的数量级。比如“主区 → 备区：数据库半同步复制，峰值约 2MB/s”“备区 → 主区：只读请求回源，峰值约 10 QPS”。这三项写全之后，这张图就能直接拿去支撑容量评审和故障演练，因为读者能立刻判断哪条链路的压力最大。

还有一个细节：健康检查与负载均衡的位置必须画出来。很多部署图只画服务不画流量入口，读者看不出请求是从哪进来的，也就无法判断入口层是不是单点。我的画法是把负载均衡画成一个横跨多个可用区的长条，用箭头指向后端实例组，并在旁边标注“健康检查间隔 5s，摘除阈值 3 次”。这个信息在排查“为什么流量没切过去”的时候非常关键。

5.3 单点与故障域的显式标注

部署图上最有价值的信息，往往是那些“看起来正常但其实是单点”的地方。我的做法是给每个单点组件加一个醒目的标注框，写上“单点”两个字，并在说明文字里列出缓解措施。比如上表里的定时任务，只有一个实例，机器挂了任务就停。缓解措施可能是“任务幂等 + 补跑脚本”，也可能是“两个实例加分布式锁抢主”，具体看任务性质。

故障域要沿着“一个组件挂掉会影响谁”这条线去梳理。常见的故障域有四个层级：单实例、单可用区、单地域、单依赖。部署图上，我用不同的底色块表示故障域，同一色块内的组件共享同一个故障域。这么做的直接好处是：做容灾演练时，可以按色块设计演练场景，比如“停掉主区全部实例，观察备区接管时间”，而不是拍脑袋随便停一个服务。

这里有个实际踩过的坑值得说：跨区复制的延迟经常被低估。我们最初假设同城两区之间延迟在 1ms 以内，实际压测发现高峰期能到 5ms 以上，导致半同步复制偶尔超时，切换到异步模式。所以部署图上标注链路时，我建议把实测延迟也写上，而不是写理论值。理论值和实测值之间的差距，往往就是故障的藏身之处。

5.4 容量参数的估算过程

部署图上的数字不能拍脑袋，我一般按“入口流量 → 单实例吞吐 → 实例数 → 冗余”这条链推算，每一步都留出处。

下单接口峰值 50 QPS，单请求平均处理耗时 30ms，一个实例配 8 个工作线程，理论吞吐是 8 ÷ 0.03 ≈ 260 QPS。但实际不能按满负荷跑，按 50% 水位算，单实例约 130 QPS。50 QPS 只需要 1 个实例就够，但考虑高可用，至少 3 个实例分布在两个区，这样挂一个区还剩 1 个实例能承接全部流量。

数据库连接数按“实例数 × 单实例连接数”估：3 个应用实例 × 20 连接 = 60，加上定时任务和后台消费者的 20，总共 80 左右。数据库最大连接数一般 500 起步，留足余量没问题，但如果后面应用实例扩到 10 个，连接数就会逼近 250，需要引入连接池中间件。这个结论我也会写在图上，作为扩容的前置条件。

存储容量前面算过，一年 70GB，考虑索引和从库，主库预留 300GB，从库同规格。缓存 2GB 规格，用量约 600MB，水位 30%，属于健康区间。带宽方面，接口响应体平均 2KB，50 QPS 对应 100KB/s，属于很低的水位，可以忽略，但对象存储的写入是另一回事——如果对账单文件日增 5GB，那就要单独评估出口带宽。

这些数字写在图的说明里，价值在于它们是可复核的。任何人觉得“实例数不对”，可以顺着推算过程重新算一遍，讨论就有了共同基础。

6. 实例拆解三：关键业务链路的时序图

6.1 时序图最容易画错的地方

我审过的时序图里，八成以上只画了正常路径。参与者排成一排，箭头从左到右走一遍，最后返回成功，图面干干净净。这种图基本没有实用价值，因为线上故障从来不发生在正常路径上。时序图真正的价值是把异常分支和约束条件暴露出来，让读图的人知道“哪一步可能慢、哪一步可能重复、哪一步失败之后数据会不一致”。

所以我现在画时序图有个硬性要求：至少画两条异常分支，并且标注超时、重试、幂等三要素。这三样东西是链路稳定性的核心，缺一样这张图就不完整。

具体到订单链路，主路径是：客户端提交 → 接入层鉴权限流 → 订单服务生成幂等键 → 库存服务预占 → 落订单 → 返回订单号 → 发延时消息等支付。异常分支至少要考虑：库存预占失败、预占成功但落订单失败、支付回调重复、延时消息重复消费。后两个属于“重复”类问题，是资损的高发区。

6.2 只画异常分支才有价值

我拿“预占成功但落订单失败”这条分支举例，看看图上应该怎么表达。

库存服务返回锁定成功后，如果订单服务在写库时挂掉或者超时，就会留下一个“库存被锁但订单不存在”的脏状态。库存锁的有效期是 15 分钟，15 分钟内没有订单关联，锁会被自动释放。这条信息必须画在图上，用一条从库存服务指向自己的虚线箭头，标注“15 分钟后自动释放未关联的锁定”。

同时，订单服务这边需要一个补偿机制：写库失败时立即发起一次解锁请求，解锁失败则落一条补偿记录交给定时任务重试。补偿记录重试三次仍失败，进人工处理队列。这条链路在图上表现为：订单服务 → 库存服务（解锁请求），失败则 → 补偿表（落库）。

把这些画出来之后，图的信息量就完全不一样了。读者能看到“脏数据的产生条件”和“脏数据的清理路径”，而不是只知道“这里有个调用”。我在实际项目里发现，很多资损事故的根因，就是某条异常分支在设计阶段压根没被画出来，也就没人去想它。

还有一条经验：时序图上的参与者超过七个，就该拆图。参与者一多，箭头交叉严重，读者要来回找对应关系，阅读成本陡增。拆的原则是按“信任边界”拆，跨边界的一段一张图，图与图之间用编号串联，比如“图 3-1 下单主链路”“图 3-2 支付回调与补偿”。

6.3 超时、重试、幂等的标注写法

这三项的标注我有固定写法，直接写在箭头旁边，格式统一，方便横向对比。

超时写成“超时 Nms”，取值为下游 P99 延迟的 2 到 3 倍。比如库存服务 P99 是 250ms，超时设 800ms 比较合理。设太短会导致大量误超时，触发无谓的重试；设太长会拖垮上游线程池，一个慢调用可能把整个服务拖住。

重试写成“重试 N 次，间隔 Xms”，并且必须说明“仅对幂等操作重试”。我见过最典型的翻车是：支付回调处理超时后无条件重试，结果重复扣款。正确做法是回调接口带幂等键，服务端先查幂等表，已处理过就直接返回成功。

幂等的标注位置在参与者方框下方，写“幂等键：订单号 + 业务类型”。同时要在图上体现幂等表的写入时机——是落订单之前写，还是之后写。这里的顺序很关键：先写幂等表再处理业务，能防重复；先处理业务再写幂等表，中间崩溃就会漏防。这个细节很多图都不画，但它恰恰是“能不能防住”的分水岭。

顺便提一下延时时长的估算。订单待支付超时时间设 15 分钟，是基于业务侧的转化数据：绝大多数支付在 3 分钟内完成，超过 15 分钟再支付的占比极低，而锁库存的成本随时间增加。这个 15 分钟不是技术拍出来的，是业务和成本共同决定的，所以图上的说明要写清楚依据，否则后面有人会问“为什么不是 30 分钟”。

7. 常见问题与排查实录

7.1 常见问题速查表

下面这张表来自我这些年审图、改图积累下来的高频问题，按“症状 → 根因 → 处理办法”组织，遇到类似情况可以直接对照。

这张表里，我认为最值得警惕的是第一行和第三行。图没人看，通常不是画得丑，而是画得太全；符号不一致，通常不是能力问题，而是没人定规矩。这两个问题都属于“一开始多花二十分钟就能避免，后面省下几十小时”的类型。

7.2 让图不过期的维护机制

图画完那一刻就开始过期，这不是悲观，是事实。所以要靠机制，不能靠自觉。我实际用过的机制有三个，成本从低到高。

第一个是元信息 + 季度巡检。每张图带最后校验日期，每季度末花半小时，把docs/architecture目录下的图过一遍，改过代码没改图的补上，确认没变的更新日期。这个动作看起来很形式，但它保证了图上的日期可信——读者看到“三个月内校验过”，心里就有底。

第二个是与发布流程挂钩。凡是涉及接口变更、新增外部依赖、部署形态调整的发布，必须附带架构图改动，评审清单里加一条“架构图是否已更新”。这条规矩刚开始会有人抵触，觉得增加流程负担，但两三次之后大家就习惯了，因为改动通常只是改几行文本的事。

第三个是故障复盘反向校验。每次线上故障复盘时，对照架构图看：故障链路上的组件在图上有吗？单点标注了吗？故障域画对了吗？如果图上没有，说明图的缺失本身就是故障的间接原因，补图列为复盘行动项。这个机制我觉得最有效，因为它让图的价值和真实事故挂上了钩，比任何规范都更有约束力。

7.3 评审与讲图的实际技巧

图画得好，还得讲得好。我的经验是十五分钟规则：讲图不超过十五分钟，超过就说明图的信息组织有问题。具体讲法是先给全景（三十秒），再下钻一条最关键的链路（五分钟），最后停在两三个待决策点上（剩余时间留给讨论）。

讲的时候有几个小技巧挺管用。第一，先讲约束再讲结构——先说“这个系统有三个硬约束：数据不能出主区、库存必须强一致、支付回调必须幂等”，听众带着约束看图，理解速度快很多。第二，主动指出图上的已知缺陷，比如“这块是单点，目前靠告警兜底”，这比等别人挑出来要主动得多，也更容易建立信任。第三，把待决策点写成问句，比如“定时任务是双实例抢主还是单实例加补跑脚本，需要今天定”，会议就有了明确的产出。

还有一个反直觉的建议：别在评审会上现场改图。我试过几次，一边讨论一边改，结果图越改越乱，讨论焦点也跟着跑偏。后来改成“会上只记录，会后统一改，改完发群里确认”，效率反而高不少。

7.4 一个容易被忽略的细节：图的归档与检索

系统跑久了，架构图会攒下几十张。如果没有检索方式，找一张“去年双十一之前的部署图”得翻半天。我的做法是维护一个docs/architecture/INDEX.md，用表格列出所有图的名称、类型、创建日期、最后校验日期、状态（现行/归档）、一句话摘要。这个索引文件维护成本极低，每次新增图时加一行，但它在“追溯历史设计决策”这个场景下的价值极高。

索引表的一个实用字段是“一句话摘要”，写法要具体，比如“描述双机房部署与主备切换路径，含单点清单”，而不是“部署架构图”这种等于没写的描述。检索的时候，人靠的就是这句话。

最后分享一个我坚持了几年的个人习惯：每张图在归档时，我会在文件末尾追加一段“当时的取舍”，三到五句话，写清楚为什么没选另一个方案。半年后回头看，这段文字往往比图本身更有价值，因为图和文字记录的是“结论”，而那段话记录的是“推理过程”。新人问“为什么当时不用分库分表”，翻出这段话就能得到答案，不用去打扰已经调岗的老同事。这个习惯的成本是一张图多写五分钟，收益是整个团队少走一遍弯路。