简介这份基于 4In1 System 的软件架构文档样例面向软件设计初学者、架构入门者与需要撰写架构说明的开发团队提供一份可直接参照的完整文档范本帮助理清架构文档应包含哪些章节、每部分如何落笔。包内仅 1 个 doc 文件约 247KB体量轻巧适合通读与二次改写。目录从简介、架构表示方式、架构目标和约束展开用例视图覆盖申请注册、用户注册审核、用户角色管理、角色权限管理、车型信息管理、配件信息管理等业务场景逻辑视图按 Application 层、Business Service 层Service 包、Model 包与 Middleware 层分层描述并延伸至部署视图还附有版本修订历史记录。已有 770 人学习下载可对照其组织结构快速搭建自己的架构文档框架体会分层设计与视图划分的表达方式。1. 一份能直接改的软件架构文档(样例).doc比十张架构全景图更省评审时间启动会开完两周架构评审约在周四下午。评审席上坐着后端、客户端、测试和运维主讲人放了十二页架构全景图讲了四十分钟。提问环节问题集中在三处跨线程的数据谁负责拷贝、对外接口改字段谁通知下游、峰值按什么算出来的。图上都答不了因为图只表达了有什么没表达为什么、多少、变了怎么办。真正能止住这类追问的是一份带样例数据的软件架构文档章节固定、每个数字有推导、每个决策有记录评审从听讲变成对着章节打勾。这份样例文档不是让你重写一套方法论而是给一个可以直接复制、把内容换成自己项目就能交出去的骨架目录怎么排C4 视图怎么落到章节里接口清单用什么字段Markdown 源怎么用 Pandoc 一键生成 docx/doc以及对方说无法预览doc时怎么三步定位。适合架构师、技术负责人以及要写设计说明的后端、Qt 上位机软件架构、智驾软件架构方向的工程师。2. 软件架构文档(样例)的章节骨架从 C4 视图到可裁剪的 doc 目录2.1 样例文档必须写死的 8 个章节样例的价值在于稳定章节名每换一个项目就重编一次评审就没法形成肌肉记忆。我一般按下面 8 个章节固定顺序也固定内容按项目裁剪。章节只回答一个问题缺失后的典型返工建议篇幅目标与范围系统为谁解决什么问题边界在哪评审争论这个模块算不算我们管1 页约束与假设哪些条件不是我们能选的选型结论被一句话推翻1 页上下文视图系统与外部谁交互、走什么协议联调时发现漏了第三方12 页 1 图容器与部署视图进程、节点、中间件怎么摆上线前发现少一个消息队列23 页 2 图组件与职责每个模块负责什么、不负责什么模块边界长期扯皮35 页运行时视图关键用例的调用链与线程模型压测才发现线程池串行23 页 时序图接口清单字段、方向、版本、超时对接时字段名对不上表格随版本滚动质量属性与决策记录为什么这么选目标是多少半年后没人敢改35 页约束与假设这一章最容易被省也最容易出事。假设要写成可验证的句子比如上游推送延迟不超过 3 秒、单条不超过 64KB而不能写上游基本实时。前者出问题能追责、能改设计后者出了事只能开会。2.2 把 C4 四层视图映射到 doc 的章节里C4 模型讲 Context、Container、Component、Code 四层落到文档时不必四层全画。常见做法是画到 Component 为止Code 层交给接口清单和关键类图——因为代码本身才是 Code 层的真相文档抄一遍必然过期。映射关系是这样的Context 图直接对应第 3 章一张图加一张外部接口表外部系统标注协议与责任人Container 图对应第 4 章每个容器要标进程名、部署节点、技术栈、持久化方式尤其是临时文件放哪、日志写哪这类运维会追问的细节Component 图对应第 5 章每个组件三行字职责、对外能力、明确不做什么运行时视图不来自 C4而来自关键用例每个用例一张时序图图旁边标线程与队列。图别贪大。一张图超过 15 个元素读的人就开始找不着主次。超过就按业务域拆成两张宁可多一张图也不要一张挤到看不清。2.3 Qt 上位机与智驾软件架构在样例文档里的裁剪差异同样一份骨架不同形态的系统重心完全不同。做通用后台服务时运行时视图关心线程池、连接池、缓存一致性做 Qt 上位机软件架构关心的是主线程与 QThread 的分工、信号槽跨线程是哪种连接方式、UI 刷新频率和串口/网口读写的阻塞点做智驾软件架构关心周期任务、实时线程优先级、通信中间件的 QoS、端到端时延和失效降级。关注点通用后台服务Qt 上位机软件架构智驾软件架构运行时视图重点线程池、连接池、缓存主线程/工作线程、信号槽连接类型周期任务、实时线程、通信中间件 QoS关键约束吞吐、P99 延迟帧率、设备读写实时性、重连端到端时延、时延抖动、降级策略接口清单重点HTTP/RPC 字段与版本设备协议、SDK 回调、超时信号矩阵、Topic 字段、QoS 配置部署视图重点容器、副本数、配置中心工控机型号、驱动版本、运行账户域控制器、分区、升级方式质量属性目标QPS、可用性帧率、丢包率、恢复时间时延分位、失效模式覆盖这份对照表放在文档附录里很有用评审时能直接回答你们和上一个项目差在哪。但正文里不要贴这张通用表正文要写你自己项目的取值比如串口单帧读取周期 20ms超时 100ms 触发重连重连退避 200ms/500ms/1s。2.4 判定一份样例要不要继续加章节的三条标准新增章节前先问三句这一章能不能被一个具体角色用上比如测试拿它写用例、运维拿它配环境这一章的内容是不是半年内不会因为一次重构就全废这一章有没有可判定的完成标准比如接口清单中的每个接口都有版本号和超时值。三条都不满足就别加把内容塞进已有章节的表格里。文档的敌人从来不是写少了而是写了没人看第二遍。3. 用 Markdown Pandoc 把软件架构文档生成 docx/doc最小可复现链路3.1 源文件目录约定与 YAML 元数据单源多出是这套链路的核心正文只维护一份 Markdowndocx、pdf、doc 都是产物。这样评审意见可以直接用 git diff 看谁改了哪句一目了然。arch-doc/ ├─ docs/ │ ├─ 01-scope.md │ ├─ 02-constraints.md │ ├─ 10-context.md │ ├─ 20-container.md │ ├─ 30-runtime.md │ ├─ 40-interface.md │ ├─ 50-adr.md │ ├─ iface.csv # 接口清单原始数据 │ ├─ puml/ # 图源 │ └─ figures/ # 渲染产物 ├─ templates/ref-arch.docx # 样式模板 ├─ filters/plantuml.lua └─ build/元数据写在docs/00-meta.yaml和各章拼接时放在最前面--- title: 订单中心软件架构文档(样例) author: 架构组 date: 2025-06-01 version: v1.2.0-draft lang: zh-CN toc: true numbersections: true ---字段说明title会进封面version建议跟代码分支号对齐这样文档和代码能互相回溯toc生成目录域numbersections让章节自动编号避免手改序号改漏。3.2 pandoc 生成 docx 的最小命令与 6 个参数pandoc docs/00-meta.yaml docs/0*.md docs/1*.md docs/2*.md docs/3*.md docs/4*.md docs/5*.md \ -o build/软件架构文档(样例).docx \ --reference-doctemplates/ref-arch.docx \ --from gfmpipe_tablesfootnotes \ --toc --toc-depth3 \ --number-sections \ --resource-pathdocs/figures:docs \ --lua-filterfilters/plantuml.lua \ --verbose参数作用改错的后果--reference-doc用模板文件里的样式标题字体、表格线、页边距不加则用默认样式表格挤成一坨--from gfmpipe_tables声明输入方言支持表格与脚注表格原样输出成竖线文本--toc --toc-depth3生成目录域取到三级标题docx 里目录不刷新需手动 F9--number-sections自动编号 1.1、1.1.1手写编号插入一章后全乱--resource-path图片相对路径的搜索目录图片全部丢失只剩文件名--lua-filter在转换过程中处理自定义语法图源没渲染插图位置出现占位符模板文件的做法很简单先用 pandoc 导出一份默认 docxpandoc -o ref-arch.docx --print-default-data-file reference.docx在 Word 或 WPS 里把标题 1/标题 2/正文/表格样式改成公司规范存回templates/。以后所有项目复用同一个模板出稿样式统一。3.3 架构图与接口清单怎么自动进文档图源统一放docs/puml/*.puml正文里只写图片引用渲染交给命令plantuml -tpng -charset UTF-8 -o ../figures docs/puml/*.puml # 渲染完成后正文中的  才会被 pandoc 找到接口清单不要手写 Markdown 表格字段一多必然对不齐。用脚本从 CSV 生成评审只需要改 CSVimport csv FIELDS [接口名, 方向, 协议, 版本, 关键字段, 超时(ms), 重试] with open(docs/iface.csv, encodingutf-8) as fin, \ open(docs/40-interface.md, w, encodingutf-8) as fout: reader csv.DictReader(fin) fout.write(| | .join(FIELDS) |\n) # 表头 fout.write(| ---| * len(FIELDS) \n) # 分隔行pandoc 靠它识别表格 for row in reader: cells [row[k].strip() or - for k in FIELDS] # 空值统一成短横线避免表格塌陷 fout.write(| | .join(cells) |\n)逻辑说明FIELDS决定列顺序改这里等于改文档版式不用动正文or -保证空单元格不出现| |这种在 Word 里会错位的写法生成的文件是完整的一章直接拼进 pandoc 的输入列表。参数上唯一要留意的是编码CSV 必须 UTF-8从 Excel 另存时选CSV UTF-8否则中文列名会变成乱码带进 docx。3.4 从 docx 回到 .doc / PDF 的转换与兼容处理有的交付流程硬性要求.doc这时候再转别把.doc当工作格式soffice --headless --convert-to doc:MS Word 97 \ build/软件架构文档(样例).docx --outdir build soffice --headless --convert-to pdf \ build/软件架构文档(样例).docx --outdir build.doc是二进制复合文档格式转换后目录域、自动编号、图形锚点都可能变样转完必须重新校对一遍目录和表格边框。PDF 用来当只读稿发给评审席.docx留作可编辑版doc只在对方明确要求时给。4. 让样例文档不写成 PPTADR、质量属性场景与接口清单的落地写法4.1 ADR 的最小字段与在 doc 中的排布架构决策记录ADR是文档里唯一越写越值钱的部分。字段不用多八个够用字段写法要求编号ADR-001只增不改标题一句话说清决策如采用本地缓存而非分布式缓存状态提议 / 已接受 / 已废弃 / 被 ADR-00X 取代背景当时的约束和数据含日期决策做了什么用我们决定……备选方案至少两个写清被否原因后果正面、负面都写负面要写触发条件关联需求对应质量属性编号或上游需求号排布上按编号倒序放在文档最后最新的在最上面。状态变更时不要改正文只在状态行追加一句2025-08-01 被 ADR-014 取代。这样半年后回看能看出决策演进路径而不是只看到一份被悄悄改过的结论。4.2 质量属性场景的六要素表写高性能高可用这类词等于没写。按六要素展开刺激源、刺激、环境、制品、响应、响应度量。编号刺激源刺激环境制品响应响应度量QA-01客户端每秒 3 倍峰值查询正常负载查询服务返回结果P99 ≤ 200ms错误率 0.1%QA-02设备串口断开运行中上位机采集模块自动重连并补齐断连数据重连 2s数据缺失 0 帧QA-03传感器单路输入失效正常行驶感知模块降级并上报降级决策 100ms每张场景表下面配一句话说明如果做不到会怎样比如 QA-02 做不到就意味着断连期间的批次数据要靠人工补录。评审时这句话比任何指标都有说服力。4.3 接口清单表格的字段与版本策略接口清单是文档里更新最频繁的一章字段必须一次定死接口名、方向谁调谁、协议、版本、关键字段与类型、超时、重试、幂等性、错误码、兼容性。其中兼容性列写三档向后兼容、需灰度、破坏性变更。版本策略照搬语义化版本的思路新增可选字段升次版本改字段含义或删字段升主版本且必须灰度。文档里每个接口后面标注当前线上版本和计划变更让下游一眼看到自己要不要改。4.4 样例数据怎么造让评审能验算数字要能被复算。比如日均订单 200 万、峰值集中在 4 小时内、峰值系数取 3那么峰值 TPS 2000000 ÷ (4 × 3600) × 3 ≈ 417。这个式子写进文档评审席上有人拿计算器一按就对得上信任感立刻建立。会话数按并发用户 × 1.2 估算存储按单条记录 1.5KB × 日增量 × 保留天数估再留 30% 余量。概算表里给三列参数、取值、来源。来源写监控实测上游承诺行业经验值让读者知道哪个数字是硬的、哪个是猜的。猜的数字后面补一句上线后按实际监控校正比假装精确要专业得多。5. 软件架构文档(样例) doc 的交付验证无法预览、版本漂移与评审清单5.1 拿到 .doc 无法预览时的三步定位对方反馈打不开或无法预览doc先别怀疑文件坏了按三步查。第一步看真实格式file 软件架构文档(样例).doc xxd -l 8 软件架构文档(样例).doc # d0cf11e0 → 真正的旧版二进制 .doc # 504b0304 → 其实是 docx/zip只是后缀叫 doc第二步看兼容性.doc在老版本 WPS 里可能只读、样式错乱在手机端预览器里常常直接拒绝渲染。第三步才是转换用soffice --headless --convert-to docx转成 OOXML 再发一版同时附一份 PDF 只读稿。顺带说一句WPS 的新建菜单里默认只有 docx 模板项没有 doc 项这本身就说明 doc 已经不是首选格式交付时尽量以 docx 为主、doc 为辅。5.2 用 git 管文本源docx 只当产物把docs/下的 Markdown、CSV、PUML 纳入 gitbuild/加进.gitignore只在打 tag 时由流水线生成 docx 并作为发布附件。这样做的直接好处是评审意见是 PR改的是文本冲突好合二进制产物不参与 diff仓库不会越滚越大。注意统一行尾为 LF、文件编码为 UTF-8 无 BOMBOM 会让 pandoc 把第一行标题吞掉。5.3 评审前十分钟的自检清单翻开文档做四件事目录按 F9 刷新过没有每个数字是否有推导或来源每个 ADR 的状态是否最新接口清单里的版本号是否和线上一致。再随手抽一个运行时视图的时序图看图上标注的线程名和超时值在正文里有没有对应说明。如果只能记住一条让样例文档里的每个数字都带上推导过程评审时对方能自己算出同一个值这份 doc 就立住了。本文还有配套的精品资源点击获取
简介这份基于 4In1 System 的软件架构文档样例面向软件设计初学者、架构入门者与需要撰写架构说明的开发团队提供一份可直接参照的完整文档范本帮助理清架构文档应包含哪些章节、每部分如何落笔。包内仅 1 个 doc 文件约 247KB体量轻巧适合通读与二次改写。目录从简介、架构表示方式、架构目标和约束展开用例视图覆盖申请注册、用户注册审核、用户角色管理、角色权限管理、车型信息管理、配件信息管理等业务场景逻辑视图按 Application 层、Business Service 层Service 包、Model 包与 Middleware 层分层描述并延伸至部署视图还附有版本修订历史记录。已有 770 人学习下载可对照其组织结构快速搭建自己的架构文档框架体会分层设计与视图划分的表达方式。1. 一份能直接改的软件架构文档(样例).doc比十张架构全景图更省评审时间启动会开完两周架构评审约在周四下午。评审席上坐着后端、客户端、测试和运维主讲人放了十二页架构全景图讲了四十分钟。提问环节问题集中在三处跨线程的数据谁负责拷贝、对外接口改字段谁通知下游、峰值按什么算出来的。图上都答不了因为图只表达了有什么没表达为什么、多少、变了怎么办。真正能止住这类追问的是一份带样例数据的软件架构文档章节固定、每个数字有推导、每个决策有记录评审从听讲变成对着章节打勾。这份样例文档不是让你重写一套方法论而是给一个可以直接复制、把内容换成自己项目就能交出去的骨架目录怎么排C4 视图怎么落到章节里接口清单用什么字段Markdown 源怎么用 Pandoc 一键生成 docx/doc以及对方说无法预览doc时怎么三步定位。适合架构师、技术负责人以及要写设计说明的后端、Qt 上位机软件架构、智驾软件架构方向的工程师。2. 软件架构文档(样例)的章节骨架从 C4 视图到可裁剪的 doc 目录2.1 样例文档必须写死的 8 个章节样例的价值在于稳定章节名每换一个项目就重编一次评审就没法形成肌肉记忆。我一般按下面 8 个章节固定顺序也固定内容按项目裁剪。章节只回答一个问题缺失后的典型返工建议篇幅目标与范围系统为谁解决什么问题边界在哪评审争论这个模块算不算我们管1 页约束与假设哪些条件不是我们能选的选型结论被一句话推翻1 页上下文视图系统与外部谁交互、走什么协议联调时发现漏了第三方12 页 1 图容器与部署视图进程、节点、中间件怎么摆上线前发现少一个消息队列23 页 2 图组件与职责每个模块负责什么、不负责什么模块边界长期扯皮35 页运行时视图关键用例的调用链与线程模型压测才发现线程池串行23 页 时序图接口清单字段、方向、版本、超时对接时字段名对不上表格随版本滚动质量属性与决策记录为什么这么选目标是多少半年后没人敢改35 页约束与假设这一章最容易被省也最容易出事。假设要写成可验证的句子比如上游推送延迟不超过 3 秒、单条不超过 64KB而不能写上游基本实时。前者出问题能追责、能改设计后者出了事只能开会。2.2 把 C4 四层视图映射到 doc 的章节里C4 模型讲 Context、Container、Component、Code 四层落到文档时不必四层全画。常见做法是画到 Component 为止Code 层交给接口清单和关键类图——因为代码本身才是 Code 层的真相文档抄一遍必然过期。映射关系是这样的Context 图直接对应第 3 章一张图加一张外部接口表外部系统标注协议与责任人Container 图对应第 4 章每个容器要标进程名、部署节点、技术栈、持久化方式尤其是临时文件放哪、日志写哪这类运维会追问的细节Component 图对应第 5 章每个组件三行字职责、对外能力、明确不做什么运行时视图不来自 C4而来自关键用例每个用例一张时序图图旁边标线程与队列。图别贪大。一张图超过 15 个元素读的人就开始找不着主次。超过就按业务域拆成两张宁可多一张图也不要一张挤到看不清。2.3 Qt 上位机与智驾软件架构在样例文档里的裁剪差异同样一份骨架不同形态的系统重心完全不同。做通用后台服务时运行时视图关心线程池、连接池、缓存一致性做 Qt 上位机软件架构关心的是主线程与 QThread 的分工、信号槽跨线程是哪种连接方式、UI 刷新频率和串口/网口读写的阻塞点做智驾软件架构关心周期任务、实时线程优先级、通信中间件的 QoS、端到端时延和失效降级。关注点通用后台服务Qt 上位机软件架构智驾软件架构运行时视图重点线程池、连接池、缓存主线程/工作线程、信号槽连接类型周期任务、实时线程、通信中间件 QoS关键约束吞吐、P99 延迟帧率、设备读写实时性、重连端到端时延、时延抖动、降级策略接口清单重点HTTP/RPC 字段与版本设备协议、SDK 回调、超时信号矩阵、Topic 字段、QoS 配置部署视图重点容器、副本数、配置中心工控机型号、驱动版本、运行账户域控制器、分区、升级方式质量属性目标QPS、可用性帧率、丢包率、恢复时间时延分位、失效模式覆盖这份对照表放在文档附录里很有用评审时能直接回答你们和上一个项目差在哪。但正文里不要贴这张通用表正文要写你自己项目的取值比如串口单帧读取周期 20ms超时 100ms 触发重连重连退避 200ms/500ms/1s。2.4 判定一份样例要不要继续加章节的三条标准新增章节前先问三句这一章能不能被一个具体角色用上比如测试拿它写用例、运维拿它配环境这一章的内容是不是半年内不会因为一次重构就全废这一章有没有可判定的完成标准比如接口清单中的每个接口都有版本号和超时值。三条都不满足就别加把内容塞进已有章节的表格里。文档的敌人从来不是写少了而是写了没人看第二遍。3. 用 Markdown Pandoc 把软件架构文档生成 docx/doc最小可复现链路3.1 源文件目录约定与 YAML 元数据单源多出是这套链路的核心正文只维护一份 Markdowndocx、pdf、doc 都是产物。这样评审意见可以直接用 git diff 看谁改了哪句一目了然。arch-doc/ ├─ docs/ │ ├─ 01-scope.md │ ├─ 02-constraints.md │ ├─ 10-context.md │ ├─ 20-container.md │ ├─ 30-runtime.md │ ├─ 40-interface.md │ ├─ 50-adr.md │ ├─ iface.csv # 接口清单原始数据 │ ├─ puml/ # 图源 │ └─ figures/ # 渲染产物 ├─ templates/ref-arch.docx # 样式模板 ├─ filters/plantuml.lua └─ build/元数据写在docs/00-meta.yaml和各章拼接时放在最前面--- title: 订单中心软件架构文档(样例) author: 架构组 date: 2025-06-01 version: v1.2.0-draft lang: zh-CN toc: true numbersections: true ---字段说明title会进封面version建议跟代码分支号对齐这样文档和代码能互相回溯toc生成目录域numbersections让章节自动编号避免手改序号改漏。3.2 pandoc 生成 docx 的最小命令与 6 个参数pandoc docs/00-meta.yaml docs/0*.md docs/1*.md docs/2*.md docs/3*.md docs/4*.md docs/5*.md \ -o build/软件架构文档(样例).docx \ --reference-doctemplates/ref-arch.docx \ --from gfmpipe_tablesfootnotes \ --toc --toc-depth3 \ --number-sections \ --resource-pathdocs/figures:docs \ --lua-filterfilters/plantuml.lua \ --verbose参数作用改错的后果--reference-doc用模板文件里的样式标题字体、表格线、页边距不加则用默认样式表格挤成一坨--from gfmpipe_tables声明输入方言支持表格与脚注表格原样输出成竖线文本--toc --toc-depth3生成目录域取到三级标题docx 里目录不刷新需手动 F9--number-sections自动编号 1.1、1.1.1手写编号插入一章后全乱--resource-path图片相对路径的搜索目录图片全部丢失只剩文件名--lua-filter在转换过程中处理自定义语法图源没渲染插图位置出现占位符模板文件的做法很简单先用 pandoc 导出一份默认 docxpandoc -o ref-arch.docx --print-default-data-file reference.docx在 Word 或 WPS 里把标题 1/标题 2/正文/表格样式改成公司规范存回templates/。以后所有项目复用同一个模板出稿样式统一。3.3 架构图与接口清单怎么自动进文档图源统一放docs/puml/*.puml正文里只写图片引用渲染交给命令plantuml -tpng -charset UTF-8 -o ../figures docs/puml/*.puml # 渲染完成后正文中的  才会被 pandoc 找到接口清单不要手写 Markdown 表格字段一多必然对不齐。用脚本从 CSV 生成评审只需要改 CSVimport csv FIELDS [接口名, 方向, 协议, 版本, 关键字段, 超时(ms), 重试] with open(docs/iface.csv, encodingutf-8) as fin, \ open(docs/40-interface.md, w, encodingutf-8) as fout: reader csv.DictReader(fin) fout.write(| | .join(FIELDS) |\n) # 表头 fout.write(| ---| * len(FIELDS) \n) # 分隔行pandoc 靠它识别表格 for row in reader: cells [row[k].strip() or - for k in FIELDS] # 空值统一成短横线避免表格塌陷 fout.write(| | .join(cells) |\n)逻辑说明FIELDS决定列顺序改这里等于改文档版式不用动正文or -保证空单元格不出现| |这种在 Word 里会错位的写法生成的文件是完整的一章直接拼进 pandoc 的输入列表。参数上唯一要留意的是编码CSV 必须 UTF-8从 Excel 另存时选CSV UTF-8否则中文列名会变成乱码带进 docx。3.4 从 docx 回到 .doc / PDF 的转换与兼容处理有的交付流程硬性要求.doc这时候再转别把.doc当工作格式soffice --headless --convert-to doc:MS Word 97 \ build/软件架构文档(样例).docx --outdir build soffice --headless --convert-to pdf \ build/软件架构文档(样例).docx --outdir build.doc是二进制复合文档格式转换后目录域、自动编号、图形锚点都可能变样转完必须重新校对一遍目录和表格边框。PDF 用来当只读稿发给评审席.docx留作可编辑版doc只在对方明确要求时给。4. 让样例文档不写成 PPTADR、质量属性场景与接口清单的落地写法4.1 ADR 的最小字段与在 doc 中的排布架构决策记录ADR是文档里唯一越写越值钱的部分。字段不用多八个够用字段写法要求编号ADR-001只增不改标题一句话说清决策如采用本地缓存而非分布式缓存状态提议 / 已接受 / 已废弃 / 被 ADR-00X 取代背景当时的约束和数据含日期决策做了什么用我们决定……备选方案至少两个写清被否原因后果正面、负面都写负面要写触发条件关联需求对应质量属性编号或上游需求号排布上按编号倒序放在文档最后最新的在最上面。状态变更时不要改正文只在状态行追加一句2025-08-01 被 ADR-014 取代。这样半年后回看能看出决策演进路径而不是只看到一份被悄悄改过的结论。4.2 质量属性场景的六要素表写高性能高可用这类词等于没写。按六要素展开刺激源、刺激、环境、制品、响应、响应度量。编号刺激源刺激环境制品响应响应度量QA-01客户端每秒 3 倍峰值查询正常负载查询服务返回结果P99 ≤ 200ms错误率 0.1%QA-02设备串口断开运行中上位机采集模块自动重连并补齐断连数据重连 2s数据缺失 0 帧QA-03传感器单路输入失效正常行驶感知模块降级并上报降级决策 100ms每张场景表下面配一句话说明如果做不到会怎样比如 QA-02 做不到就意味着断连期间的批次数据要靠人工补录。评审时这句话比任何指标都有说服力。4.3 接口清单表格的字段与版本策略接口清单是文档里更新最频繁的一章字段必须一次定死接口名、方向谁调谁、协议、版本、关键字段与类型、超时、重试、幂等性、错误码、兼容性。其中兼容性列写三档向后兼容、需灰度、破坏性变更。版本策略照搬语义化版本的思路新增可选字段升次版本改字段含义或删字段升主版本且必须灰度。文档里每个接口后面标注当前线上版本和计划变更让下游一眼看到自己要不要改。4.4 样例数据怎么造让评审能验算数字要能被复算。比如日均订单 200 万、峰值集中在 4 小时内、峰值系数取 3那么峰值 TPS 2000000 ÷ (4 × 3600) × 3 ≈ 417。这个式子写进文档评审席上有人拿计算器一按就对得上信任感立刻建立。会话数按并发用户 × 1.2 估算存储按单条记录 1.5KB × 日增量 × 保留天数估再留 30% 余量。概算表里给三列参数、取值、来源。来源写监控实测上游承诺行业经验值让读者知道哪个数字是硬的、哪个是猜的。猜的数字后面补一句上线后按实际监控校正比假装精确要专业得多。5. 软件架构文档(样例) doc 的交付验证无法预览、版本漂移与评审清单5.1 拿到 .doc 无法预览时的三步定位对方反馈打不开或无法预览doc先别怀疑文件坏了按三步查。第一步看真实格式file 软件架构文档(样例).doc xxd -l 8 软件架构文档(样例).doc # d0cf11e0 → 真正的旧版二进制 .doc # 504b0304 → 其实是 docx/zip只是后缀叫 doc第二步看兼容性.doc在老版本 WPS 里可能只读、样式错乱在手机端预览器里常常直接拒绝渲染。第三步才是转换用soffice --headless --convert-to docx转成 OOXML 再发一版同时附一份 PDF 只读稿。顺带说一句WPS 的新建菜单里默认只有 docx 模板项没有 doc 项这本身就说明 doc 已经不是首选格式交付时尽量以 docx 为主、doc 为辅。5.2 用 git 管文本源docx 只当产物把docs/下的 Markdown、CSV、PUML 纳入 gitbuild/加进.gitignore只在打 tag 时由流水线生成 docx 并作为发布附件。这样做的直接好处是评审意见是 PR改的是文本冲突好合二进制产物不参与 diff仓库不会越滚越大。注意统一行尾为 LF、文件编码为 UTF-8 无 BOMBOM 会让 pandoc 把第一行标题吞掉。5.3 评审前十分钟的自检清单翻开文档做四件事目录按 F9 刷新过没有每个数字是否有推导或来源每个 ADR 的状态是否最新接口清单里的版本号是否和线上一致。再随手抽一个运行时视图的时序图看图上标注的线程名和超时值在正文里有没有对应说明。如果只能记住一条让样例文档里的每个数字都带上推导过程评审时对方能自己算出同一个值这份 doc 就立住了。本文还有配套的精品资源点击获取
