如何写出漂亮容易理解的软件设计文档

好的设计文档不是把脑子里的东西倒出来，而是帮下一个打开文件的人，在最短时间里建立同一幅图：要解决什么、为什么这样选、系统怎么拆、风险在哪、下一步做什么。

「漂亮」在这里不是排版花哨，而是层次一眼能看见、重点不用翻三页、图文对得上。「容易理解」则是：读者不用猜你的省略，也不用先读完整个仓库才能读懂这一篇。

1. 先问三个问题

动手写之前，先能口头答完这三句。答不清，文档一定会散。

常见读者不是同一种人，一篇文档里要标明主读者：

• 评审者：关心取舍、边界、风险，不关心函数名。
• 实现者：关心模块怎么拆、接口长什么样、失败怎么处理。
• 后来的维护者：关心「当时为什么不选更简单的路」。
• 协作方（产品、测试、运维）：关心影响面、发布顺序、回滚。

主读者超过两种时，宁可拆成「一页决策 + 一篇实现说明」，也不要揉成七十页百科。

2. 先选对文档类型

很多「难看」的文档，病根是类型错了：把会议纪要写成架构，把接口清单写成愿景。

一条经验：决策用 ADR，结构用 HLD，细节用 LLD，对外契约用接口文档。 混在一处，读者会在「为什么」和「怎么写代码」之间反复迷路。

ADR 可以短到这种程度：

# ADR-0012：订单状态存在独立状态机服务

- 状态：已采纳
- 日期：2026-09-01
- 背景：订单状态原先散落在三个服务的 if/else 里，对账经常不一致。
- 决策：抽成独立状态机，其它服务只发命令、订事件。
- 备选：继续分散；或塞进现有订单服务。
- 后果：多一次网络调用；换来状态可审计、可回放。

短，但后人能看见当时的约束。这比空喊「微服务更好」有用得多。

3. 一份设计文档的推荐骨架

下面这套目录适合大多数中等复杂度的后端 / 平台设计。可以删节，不建议打乱顺序：读者习惯先背景后方案。

# 标题：一句话说清「给谁做什么」

1. 摘要（半页，可单独转发）
2. 背景与问题
3. 目标与非目标
4. 名词与范围
5. 方案概述（先给图）
6. 关键设计（数据、接口、状态、失败）
7. 取舍与备选
8. 风险、观测与发布
9. 开放问题
10. 附录（长表、错误码、会议链接）

3.1 标题和摘要

差标题：订单模块优化
好标题：订单履约：把状态机从三个服务收拢到一处，并保证对账可回放

摘要用五句话就够，建议固定句式：

1. 现在怎样，痛在哪。
2. 我们打算怎样改。
3. 明确不做什么。
4. 最大的风险是什么。
5. 需要谁在何时拍板。

读者若只读摘要就能决定「要不要往下看」，这篇文档就已经赢了一半。

3.2 背景与问题：写事实，不写情绪

把问题写成可检验的句子。

差：现在订单很乱，经常出 bug。
好：近 30 天对账失败 47 次，其中 31 次是「支付成功、履约仍为待支付」，根因是支付回调与库存扣减没有同一套状态源。

配一个「当前链路」简图，比再写三段文字更省事。背景里只放迫使你现在做决定的信息，公司创业史请删。

3.3 目标与非目标：最能让文档变薄的两栏

非目标不是偷懒，是防止评审时被拖进无边需求。写下来，比会上说「那个以后再说」有效。

3.4 名词表：消灭同词异义

团队里最贵的误解，常常是同一个词。花半页列清楚：

后文凡是用这些词，都按表走。比在段落里反复括号解释更干净。

4. 先画图，再写字

人脑对结构的理解，图快于字。漂亮的文档几乎都是图在前、字解释图，而不是字写完再补一张装饰图。

4.1 选对图，不要为了「看起来专业」堆图

分层架构图回答的是谁可以调用谁，不是机房拓扑。四层横条叠起来，箭头只朝下；哪一层放规则、哪一层碰 SQL，一眼能看出来。

部署图回答的是跑在哪、几份、连哪台，不是包名怎么分层。机房或 VPC 画成框，进程写实例数，边上标端口和主从。

一张图只回答一个问题。一张图上既有机房、又有类、又有产品路线图，一定难看。每种图的框和线各自有习惯，底稿见 4.5。

4.2 时序图要写出失败，而不仅是成功

成功路径人人会画。真正让实现者和测试省事的，是超时、重复、乱序：

用户 -> 网关: 提交订单
网关 -> 订单: CreateOrder
订单 -> 库存: Freeze
库存 --x 订单: 超时
订单 -> 订单: 标记 pending_freeze，进入补偿
订单 --> 网关: 202 + 查询号

旁注三行即可：超时阈值、是否可重入、补偿谁来触发。比再写一页「我们会考虑异常情况」实在。

4.3 状态机把事件写在箭头上

状态是圆圈，事件是箭头上的字。只写「待支付 → 已支付」而不写「收到 PaymentSucceeded」，实现时一定会各写各的 if。

同时写明：

• 哪些转移非法（要返回明确错误，而不是默默忽略）。
• 是否允许乱序事件（先到履约、后到支付）。
• 终态能不能再出来（已取消能否复活）。

4.4 图的可读性细则

• 同一概念同一名字，图里叫 FreezeStock，正文不要改成「锁库存」。
• 箭头有方向、有含义；不要用无标签细线把所有框连起来。
• 颜色最多两三种：例如「已有 / 新增 / 废弃」。四色以上像节日贺卡。
• 图放在被解释的那一节正上方，不要全部堆到文末。
• 能用 mermaid / PlantUML 进仓库的，就不要只贴一张过期截图。

4.5 形状与连线：每种图一张底稿

选对图之后，还要约定框是什么、线是什么。下面七张是底稿：形状本身带语义，线上写含义。每张图下方有图例，和正文里的形状一一对应。写正文时只替换名字，不要改形状用法——圆圈忽然变成「服务器」，读者就得重新猜。

5. 把「关键设计」写成别人能实现的规格

概述解决「长什么样」，关键设计解决「碰到硬问题时怎么走」。下面四块几乎每篇中等设计都用得上。

5.1 数据：谁是源，谁是副本

写清：

• 主键与唯一约束（业务幂等键往往比自增 id 重要）。
• 写路径：谁先落库，谁后更新缓存。
• 读路径：能脏读多久，要不要读自己的写。
• 删除是软删还是硬删，审计留多久。

差：订单和支付记录存在数据库里，用 Redis 加速。
好：订单主状态以orders表为准；Redis 只缓存只读展示，TTL 30s，缓存失败直接回表。支付回调以payment_id幂等，重复回调返回 200 且不推进状态。

5.2 接口：给例子，不要只给形容词

每一个对外接口至少具备：路径、调用方、成功示例、失败码、超时与重试、兼容策略。

POST /v1/orders/{id}/freeze-stock
Idempotency-Key: 8f2a...

# 成功
{ "status": "frozen", "expire_at": "2026-09-09T12:00:00+08:00" }

# 失败：库存不足
{ "error": "STOCK_INSUFFICIENT", "sku": "A01", "want": 2, "left": 0 }

「接口要优雅」「错误要友好」这类句子可以删。读者需要的是字段和码。

版本策略也要写死一句，例如：/v1 只追加字段，不改语义；破坏性变更走 /v2，旧版至少保留两个发布周期。

5.3 一致性：说人话，并落到机制

「我们保证最终一致」太空。改写成机制：

• 以哪张表 / 哪个主题为权威。
• 失败如何补偿（定时扫、发件箱、人工工单）。
• 用户看到中间态时，页面怎么写（「支付确认中」而不是假成功）。
• 对账任务的周期、差异阈值、谁值守。

5.4 安全与权限：点名，不空喊

写清：谁能调、凭什么、敏感字段怎么脱敏、审计日志记什么。涉及钱、库存、隐私的设计，缺这一节就不该过审。

6. 语言：清楚比华丽重要

漂亮的中文技术文档，通常有这些习惯。

短句，主动语态。
差：库存的扣减将会在支付完成之后被进行。
好：支付成功后，订单服务调用库存冻结。

先结论后解释。 每节第一句就是答案，细节放后面。评审者时间少，实现者才会往下翻。

一次只引入一个新名字。 同一段里同时冒出「编排器、协调者、网关、门面」，没有人分得清。

数字要有单位和对比。 QPS 会很高 不如 高峰 1.2k QPS，现网峰值的 3 倍。

少用程度副词。 「非常」「尽可能」「妥善」在设计里等于没写。改成阈值、超时、重试次数。

术语第一次出现给定义，之后保持稳定。 不要前一节 SLA、后一节 服务承诺、附录又变 可用性指标。

删除正确的废话。 例如「随着业务发展，系统复杂度提升，我们需要更好的架构」。读者已经在读设计文档了，不用再被说服「设计有意义」。

可用的自检：把一节读给没参加讨论的同事听，他若不断问「这是什么意思」，那一节就还没写完。

7. 正反例：同一件事的两种写法

反例（常见病）

为了提升用户体验并赋能业务高质量发展，我们将对订单中台进行全面升级。新架构采用领域驱动与微服务理念，充分解耦，灵活扩展，后续可支撑各类创新场景。具体实现由各小组根据实际情况推进，遇事沟通。

读完不知道：改什么、不改什么、谁先上、失败怎么办。形容词很多，动词没有。

正例（同一主题）

决策： 把订单状态从支付、履约、库存三处，收拢到订单服务内的状态机；其它服务只发命令、订 order.events。
不做什么： 不拆分结算，不换支付渠道。
成功标准： 支付成功后 5 秒内状态一致；对账差异周均 ≤ 1。
发布： 先双写一周，对账无差异再切读。回滚开关：order.state_machine.enabled。

字数更少，能评审、能实现、能验收。

再看一处接口描述的对比。

差：前端调用后端获取数据，注意性能和安全。

好：

8. 版式：少装饰，多对齐

「漂亮」多半来自克制。

1. 标题是大纲。 读者只扫 h2 / h3 应能复述结构。不要出现「其它」「补充说明」这种垃圾桶标题。
2. 一段一个意思。 超过八行就考虑拆，或改成列表。
3. 能用表就不要用散文。 对比、字段、错误码、发布步骤，表比段落干净。
4. 代码和配置用等宽块。 不要把 JSON 塞进一句话的引号里。
5. 强调不超过一种。 加粗或引用，选一个。满屏加粗等于没有重点。
6. 留白。 节与节之间空一行；图下写一句图注：图 2 支付成功后的补偿路径。
7. 链接写人话。 用「见 ADR-0012」而不是「点击这里」。

Markdown 足够写绝大多数设计文档。先把结构写对，再考虑 Wiki 皮肤和封面。

9. 评审：文档是用来被反对的

写完先自己当反对者，再发给别人。评审不是找错别字，是找没写出来的决定。

请评审者只回答这几个问题：

1. 问题是否真的存在？有没有更小的改法？
2. 非目标是否被偷偷做大了？
3. 失败路径有没有空洞？
4. 数据以谁为准？冲突时听谁的？
5. 发布和回滚能否在半夜独立做完？
6. 三个月后，一个新人只读这一篇，能不能动手？

收集意见时，把「已采纳 / 不采纳 + 理由」写回文档或 ADR，不要只留在聊天记录。反对被记录下来，文档才算闭环。

评审前把文档冻一版（日期 + 链接）。边评边改到面目全非，参会的人会对着不同文本说话。

10. 维护：过期的漂亮文档比没有更危险

设计文档的寿命往往短于系统。要让它继续「容易理解」，得约定谁改、何时改。

• 代码行为变了，先改文档再合入，或在 PR 里附文档 diff。
• 每个 HLD 顶部加一行：最后核对：2026-09-09，与 main@a1b2c3 一致。
• 废弃的方案写 已废弃 并指向新文档，不要直接删——后人会搜到旧链接。
• 季修一次：删掉已落地的「开放问题」，把临时决策收成 ADR。

文档和代码冲突时，以代码为准、并记一笔债。假装文档永远正确，是最常见的信任破产。

11. 样例：一份带分层架构的设计文档

下面整节就是一篇可以拿去评审的设计，主题是内部设备借用系统 DeviceLoan。核心不是堆接口，而是把软件拆成四层：接入、应用、领域、基础设施。依赖只允许从上往下。

deviceloan/
  interface/http/          # L1
  application/             # L2  用例
  domain/
    model/                 # L3  聚合、值对象
    service/               # L3  跨聚合规则（如库存占用）
    port/                  # L3  Repository / Notifier 接口
  infrastructure/
    persistence/           # L4
    notify/                # L4
    directory/             # L4

对照本文前面的标准：读者能画出四层、能指出规则在领域、能按用例写第一行代码。图负责结构，表负责失败码，禁令负责防止分层塌回大泥球。

12. 动笔前的检查清单

写完或评审前，按表勾一遍。未勾的项，就是读者会卡住的地方。

• [ ] 标题能单独转发，不依赖文件夹名字
• [ ] 摘要五句话：现状、方案、非目标、风险、谁来拍板
• [ ] 主读者写明了，深度配得上
• [ ] 目标可验收，非目标能挡住加塞
• [ ] 名词表覆盖易混词
• [ ] 至少一张结构图、一张关键路径图（含失败）
• [ ] 图与正文用同一套名字
• [ ] 数据源、幂等、超时、重试、回滚都有数字
• [ ] 对外接口有成功 / 失败例子
• [ ] 取舍写了「为什么不选更简单的」
• [ ] 观测指标和告警阈值具体
• [ ] 开放问题有负责人，不是修辞
• [ ] 长表和历史讨论进附录，正文能一口气读完
• [ ] 自己出声读一遍，没有接不上的代词

13. 常见跑偏，以及对一下

收束

写出漂亮、好懂的设计文档，靠的不是文采，而是对读者的体贴：先告诉他要做什么决定，再给他刚好够用的结构、图和数字；把形容词换成机制，把情绪换成取舍，把「以后再说」写成非目标或开放问题。

你可以记住一句更短的标准：

一个没参加讨论的同事，只读这一篇，能画出系统、能指出风险、能开始写第一行代码——这才叫写完了。

从下一篇起，先写摘要和非目标，再画一张失败路径图。文档多半会立刻好看一截。