做过几年项目的人都清楚概要设计书这种东西写的时候没人看验收和交接的时候人人翻。我见过太多团队把需求文档写得像模像样到了概要设计就变成几页截图加几句系统采用分层架构等到半年后新人接手、或者甲方要查设计合规性翻出来的文档连模块边界都对不上。这也是为什么能直接套用的Word原件这件事本身有价值——它省掉的不是打字时间而是让你不必每次从零纠结该写哪几章、每章写到什么颗粒度。下面这份内容围绕一份可复用的软件概要设计书Word模板展开它包含哪些章节、每个章节具体怎么填、模板在Word里怎么搭才不会一改就乱、以及复制别人文档时那些必然踩到的坑。适合刚接手文档工作的开发、需要给团队定规范的负责人以及被评审卡过几次想搞清楚门道的人。1. 概要设计书在项目里真正承担的角色很多人把它当成需求文档的复述这是最要命的误解。需求文档回答要做成什么样概要设计回答用什么结构去把它做出来。前者是承诺后者是方案。评审会上被挑刺最多的从来不是文笔而是这句话你这个模块划分依据是什么1.1 和需求规格说明书的边界写什么、坚决不写什么需求文档里写用户可以按条件筛选订单并导出概要设计里就该出现订单查询模块负责条件解析与分页导出模块订阅查询结果集采用异步任务方式生成文件——注意是模块和职责不是界面长什么样也不是某个方法怎么实现。我在模板里通常给每一章配一句本节不该出现的内容的提示语比如架构章节下面标注不写部署IP、不写具体中间件版本号接口章节下面标注不写SQL语句。这种反向提示比正向要求管用得多因为写文档的人最容易犯的错就是越界往下写把详细设计的内容提前塞进来导致后面详细设计阶段无话可写。界限模糊的地方集中在两处一是数据设计二是接口设计。我的处理办法是概要设计里的数据设计只到实体—属性—关系和关键表的主外键字段类型长度这些留给详细设计接口设计只到谁调谁、传什么业务语义、同步还是异步、失败怎么反馈具体的报文结构和字段编码同样后置。这个分界一旦定死两份文档就不会互相抄。1.2 颗粒度怎么卡一张表说清楚颗粒度是概要设计书最难拿捏的东西。写太粗评审说没有设计写太细后面改一处要连带改三份文档。我给团队用的判断标准很土但好用读者拿着这一章能不能独立画出模块之间的关系图并且指出每个模块的输入输出。能做到颗粒度就够了做不到说明还缺东西。章节该有的颗粒度明显越界的写法总体架构分层、模块清单、模块间调用关系、关键技术选型理由具体类图、框架版本对比长文模块设计每个模块的职责、边界、对外提供的功能点函数签名、伪代码逐行注释接口设计调用方、提供方、协议类型、业务语义、异常约定完整报文样例、字段校验正则数据设计实体清单、关系、关键表主外键、数据流走向建表语句、索引设计运行设计启动流程、关键时序、并发与降级策略线程池参数、超时毫秒数出错处理错误分类、统一处理原则、用户可见提示策略异常堆栈、日志格式串这张表我一般直接放在模板的扉页说明里写的人对照着看一眼能省掉一半返工。1.3 一份能过评审的文档最小闭环是什么别追求大而全。评审真正会盯的是四个问题有没有答案系统由哪些部分组成、这些部分怎么协作、关键数据怎么流动、出问题时怎么办。这四件事答清楚了哪怕文档只有二十页也是合格的反过来堆了八十页架构图却说不清订单创建失败时库存怎么回滚一样过不了。我习惯在模板最后放一个设计决策记录的小节格式极简决策点、备选方案、选定理由、影响范围。这个东西平时写起来五分钟半年后接手的人能少问十个问题。它也是唯一一个我建议每份文档都必须手写、不许套用的部分因为一旦套用就说明你没做决策。2. Word模板的骨架样式、编号、题注三件套模板能不能直接套用九成取决于Word本身的工程化程度而不是内容写得多漂亮。我见过太多所谓的模板打开一看全是手工排版的产物标题是加粗放大的正文编号是手打的1.1图是截图贴上去配一行手打说明。这种文件用一次就废改一次就崩。2.1 用样式而不是手工排版正确做法是先建样式表再写内容。需要定义的样式至少有这些标题1到标题4、正文、图题注、表题注、表格内文字、代码块、提示框、页眉页脚。几个容易忽略的细节正文样式的首行缩进要用字符单位而不是厘米在段落设置里选首行缩进 2 字符这样换字号时缩进不会跑偏中文字体设为宋体、西文设为Times New Roman在字体对话框里分开设置别只设一个段落的中文版式里把允许西文在单词中间换行取消勾选否则英文术语会被拆得很难看行距用固定值或1.5倍别用多倍行距 1.15这种在不同版本里渲染不一致的设置。表格内部的文字单独建一个样式字号比正文小一号行距设单倍这样表格自动适应时不会因为行距过大而撑得很高。还有一条血泪教训样式的基准关系要理清楚。如果你把标题2的基准样式设成标题1那改标题1的字体时标题2会跟着变这本来是好设计但如果你在标题2上做了手工的直接格式比如手动加粗那基准变更就管不到它了。团队里最常见的文档失控就是每个人都在标题上手动调格式最后样式面板一片标题2 加粗 小四这种带加号的脏状态。2.2 多级列表绑定样式编号才会自动走这是整个模板里技术含量最高、也最容易做错的一步。正确路径是先定义好多级列表把每一级链接到对应标题样式再让标题样式去用这个列表。顺序反了就得重来。具体操作光标放在标题1上进入定义新的多级列表点更多展开完整面板选中级别1在将级别链接到样式里选标题1编号格式填1编号样式选阿拉伯数字然后在输入编号的格式框里自己补一个点变成1.。级别2 链接到标题2格式填1.1勾选正规形式编号起始编号设1。级别3 同理到1.1.1。关键的一步在右下角把重新开始列表的间隔设为级别1这样每个一级标题下面的二级编号才会从1重新开始而不是全文连续编号。做完之后正文里按CtrlAlt1就能直接出标题1编号自动生成。这条链路一通后面所有编号问题都不会再有——因为编号根本不是文字是域。2.3 题注、交叉引用和目录改稿不崩的三个支撑图表的编号千万不要手打。用插入题注新建标签图和表编号里勾选包含章节号章节起始样式选标题1分隔符用点。这样插入的图会自动变成图 3-2这种形式。如果你们的规范是图3.2就在编号设置里把分隔符改成句点。交叉引用是配套动作正文里写如图3-2所示这个图3-2要用插入交叉引用选图类别、引用仅标签和编号来生成。这样后面插入一张新图全文引用会自动更新。图题注放在图的下方居中表题注放在表的上方居中这个约定要在模板里写死别让每个人自由发挥。目录用引用→目录→自定义目录显示级别设到3生成的是TOC域。目录样式目录1、目录2、目录3单独调别去改目录里的字体——你改了字体下次更新目录时如果选了更新整个目录手工格式就没了。需要提醒一个交付环节的动作给外部交付PDF或者定稿时选中全文按CtrlShiftF9把所有域转成静态文本。这样对方打开不会看到更新链接的弹窗也不会因为对方机器上没装字体而编号错乱。当然本地要留一份带域的版本方便后续修订。3. 各章节到底怎么填逐节拆给你看拿到模板只是开始真正花时间的是往格子里填东西。这一节按模板的章节顺序把每章的写法、容易糊弄的地方和我会额外要求的内容都摆出来。3.1 总体架构与模块划分职责表比架构图重要架构图画得再漂亮说不清模块边界也是白搭。我的要求是架构图配一张模块职责表表格五列模块名、一句话职责、输入、输出、依赖的其他模块。这张表填不满说明模块划分没想清楚表里出现两个模块职责高度重叠说明该合并出现一个模块依赖几乎所有其他模块那是个隐患评审时一定会被问到。分层要给出理由。写系统采用三层架构是废话写业务逻辑集中在服务层是为了让后续新增的渠道接入不必改动数据访问代码才是设计。技术选型也一样选了什么不重要为什么选、备选是什么、放弃了什么代价这三句才值钱。我在模板里给每个选型点留了一个固定格式的小框候选方案、决定性因素、放弃原因、风险。模块划分的常见毛病是按技术分层硬切成控制层、服务层、持久层三块就交差。这只描述了技术栈没描述业务。业务流程角度至少要有两三个核心场景的模块协作说明比如下单流程涉及订单、库存、支付三个模块调用顺序为…其中库存预占失败时订单模块回滚。这段话写出来架构才开始有说服力。3.2 接口设计把约定写清楚别写报文接口章节只写约定。每个接口一条记录字段建议固定为接口名、调用方、提供方、交互方式同步请求、异步消息、批量文件、业务语义、输入的业务要素、输出的业务要素、失败时的处理约定。失败约定是最容易被跳过、又最容易在联调时打架的部分。比如某个查询接口超时了调用方是重试还是直接失败重试几次重复调用会不会产生副作用这些在概要设计阶段定下来联调时能少吵架。我会在模板里放一个幂等性说明的小字段凡是涉及写操作的接口必须填。内外部接口要分开列。外部接口指跨越系统边界的需要写清楚对端是谁、协议、认证方式的大方向内部接口指模块之间的写清楚调用关系和数据流向就够了。数据接口单独一类包括批量导入导出的文件格式约定、数据同步的频率和方向。这三类混在一起写读者会疯。3.3 数据设计实体关系加数据流够用就停概要设计阶段的数据设计核心是让读者看懂系统里有哪些核心数据对象它们之间什么关系数据在模块之间怎么流动。实体清单可以做成表实体名、业务含义、关键属性只列标识性和状态性的三五个、所属模块。关系用文字描述比强上ER图更省事尤其是关系不复杂的时候——一个订单对应多条明细一个明细对应一个商品商品可以没有订单这种句子比画一堆菱形方框清楚。数据流部分我建议至少画一条主链路的流向从用户输入进来经过哪几个模块落到哪个实体中间产生哪些中间状态。这条链路写清楚了后面排查问题、做数据迁移、评估影响面都有依据。字段类型、索引、分库分表策略一律不进这一章进了就是越界。3.4 运行设计启动、时序、并发、降级四件事这一章很多模板干脆没有我觉得是重大缺失。运行设计回答的是系统跑起来是什么样包含四块内容。启动与初始化系统启动时加载什么配置、建立哪些连接、有没有预热动作。写清楚这些部署出问题时排查有方向。关键时序挑三到五条最核心的业务链路用步骤列表描述调用顺序和每步的产出。不必画复杂的时序图列表形式反而更易读易改。并发与容量给出量级判断比如峰值并发按日常的5倍估算按此配置连接池和线程数。数字可以不精确但方向必须有因为它是后面性能测试的输入。降级与兜底哪些非核心功能可以关闭、关闭后主流程是否受影响、缓存的失效策略是什么。这一段写得好运维会感谢你。3.5 出错处理与安全设计拒绝口号化系统应具备良好的容错能力——这句话出现在文档里等于没写。有效的写法是把错误分类然后针对每一类给出统一处理原则。错误类别典型场景处理原则用户可见表现输入校验类必填缺失、格式错误前置拦截不进入业务逻辑明确字段提示业务规则类库存不足、状态不允许事务内回滚返回业务错误码可理解的业务话术依赖调用类外部服务超时、返回异常有限重试加降级记录上下文提示稍后重试系统内部类空指针、数据不一致捕获兜底记录完整链路标识统一提示不暴露细节安全设计同理。写加强安全防护没有意义写用户身份在入口统一校验数据访问按归属过滤敏感字段在日志中脱敏输出操作类接口记录审计痕迹才是可执行的设计要求。这几条不涉及具体实现也不会踩到任何敏感边界纯粹是工程约定。4. 复制别人模板后必踩的坑与排查链路真实的场景往往不是从零建模板而是拿来一份别人的文档改改用。这条路我走过很多次坑几乎是必然的关键在于知道怎么定位。4.1 样式错乱的根因同名不同定义最典型的症状是粘贴进来的段落明明显示正文样式可字体行距跟自己的完全不一样。原因是源文档里有个同名样式但定义不同粘贴时Word默认保留源格式就把对方的样式定义一起带进来了甚至可能反过来覆盖你自己的样式定义。定位方法打开样式面板鼠标悬在样式名上看弹出的说明里有没有基于XX或者带加号的描述再看管理样式里的编辑标签页两边对比定义。修复方式分两步先切断源头把粘贴默认方式改成只保留文本文件→选项→高级→剪切复制粘贴此后粘贴只带文字不带格式再清理存量全选内容后按Ctrl空格清除字符格式CtrlQ清除段落格式然后重新套样式。还有一个隐蔽的开关模板里的自动更新文档样式如果被打开打开文档时会用模板的样式覆盖当前文档导致你调好的格式莫名回退。这个开关在开发工具→文档模板→模板里团队模板一定要关掉。4.2 编号从头乱五步排查顺序编号问题是最让人抓狂的因为它看不见摸不着。我总结的排查顺序是这样的按这个走基本五分钟能定位第一步看光标所在段落的样式到底是什么。很多人以为自己在写标题2其实样式面板显示的是正文 加粗那编号当然不生效。第二步看多级列表有没有链接到样式。点定义新的多级列表逐级检查将级别链接到样式是否为空。为空就是断链重新链接即可。第三步找手动编号残留。用显示编辑标记CtrlShift8把隐藏字符显示出来如果标题前面有一串普通文字形式的1.1那就是手打的删掉让自动编号接管。第四步看是不是被重新开始编号打断过。有些人在中间某个标题上右键选了重新开始于1那一节之后的编号就会重新从1开始看起来像跳号。第五步检查分节符。分节符会把编号上下文切断如果某一段突然从头开始很可能是上一页插了个分节符而列表没设继续编号。提示不要靠手动改编号去修问题。手改一处后面每一处都会跟着错而且改完就再也回不到自动状态。宁可花十分钟重建多级列表也不要手打一个数字。4.3 域代码残留与那些莫名其妙的弹窗打开文档弹出此文档包含指向其他文件的链接是否更新多半是复制时带进来了外部引用域或者图片是以链接方式插入的。处理方式CtrlA全选后按AltF9切换显示域代码搜索INCLUDEPICTURE和LINK关键字把相关域删掉或把图片改成嵌入型重新插入。图片一定要用嵌入型在图片布局选项里选嵌入型不要用浮于文字上方。浮动图片在别人机器上、在换页时、在转PDF时都可能跑位而且没法跟题注绑定在一起。嵌入型图片配合居中段落和题注才是稳定的组合。另外交付前记得跑一遍检查文档文件→信息→检查问题把批注、修订、隐藏属性、文档属性里的作者信息清掉。这些残留信息在实际工作中造成过不少尴尬属于必须做但不能省的一步。5. 模板落地版本管理、自检清单与评审要点模板做好只是第一步能在一个团队里长期用下去靠的是分发方式和检查机制。5.1 用dotx分发用版本号约束把模板存成.dotx格式放到共享位置新人双击打开就是基于模板新建文档不会误改原始文件。文件名里带版本号和日期比如概要设计书模板_v2.1_202406。每次调整样式或章节结构就升一个版本同时在文档末尾的修订记录里写清楚改了什么。要克制改模板的冲动。我见过模板一个月改三版结果团队里同时存在四五种格式的文档汇总的时候痛苦不堪。规矩定成样式相关的调整走版本升级内容提示语的措辞微调直接改、不升版本。5.2 一份可以直接照着打勾的自检清单写完文档之后花十分钟过一遍下面这张表能挡掉大部分评审意见。检查项判据常见不通过表现章节完整模板章节一个不缺不适用的写明本项目不涉及及理由直接删章导致编号断档编号自动全文无手打编号插入新章节后编号自动顺延中间某节编号跳号图表规范图表均有题注正文有交叉引用手打如下图模块边界每个模块有一句话职责职责之间无重叠两个模块都写负责数据处理接口约定每个接口有失败处理与幂等说明只写正常流程数据一致实体清单与数据流描述能对上数据流里出现清单外的实体异常覆盖四类错误均有处理原则只写做好异常捕获目录页码更新目录后页码正确页眉页脚分节正确目录页码全是15.3 评审会上最容易被追问的三处按经验概要设计评审被打回八成集中在这三个地方。模块划分依据说不清。评审人会问为什么这两个功能放一个模块回答因为它们相关是不行的。要能说出耦合度、变更频率、职责归属这类理由。关键链路没有异常路径。正常流程谁都会画评审人往往专门问这一步失败了会怎样。提前在时序描述里补上失败分支能省掉一轮返工。容量与性能全是形容词。写高性能高并发没有意义哪怕给个粗略的估算过程也好日活多少、峰值集中在什么时段、单次请求的数据量级、据此推出大概的并发数。数字不必准推导过程要能看。我自己的习惯是在写文档的时候就把这三处当成三个必答题先写完其余章节再补。这样即使时间紧张只写了一半被问到的核心问题也有答案。模板的价值不在于让你少想而在于把该想的问题提前摆在你面前你想跳过都难。
