跳转至

加餐 软件设计文档示例模板

第9篇文章中,我讲了每种UML模型图的画法,以及这些画法分别适用于什么样的设计阶段,我们也可以将不同阶段输出的模型图放在一个文档中,对每张模型图配以适当的文字说明,构成一篇设计文档。

对于规模不太大的软件系统,我们可以将概要设计文档和详细设计文档合并成一个设计文档。这一篇文章中,我会展现一个设计文档示例模板,你可以参考这个模板编写你的设计文档。

文档开头是设计概述,简单描述业务场景要解决的核心问题领域是什么。至于业务场景,应该在专门的需求文档中描述,但是在设计文档中,必须要再简单描述一下,以保证设计文档的完整性,这样,即使脱离需求文档,阅读者也能理解主要的设计。

此外,在设计概述中,还需要描述设计的非功能约束,比如关于性能、可用性、维护性、安全性,甚至开发和部署成本方面的设计目标。

然后就是具体的设计了,第一张设计图应该是部署图,通过部署图描述系统整个物理模型蓝图,包括未来系统长什么样。

如果系统中包含几个子系统,那么还需要描述子系统间的关系,可以通过子系统序列图,子系统活动图进行描述。

子系统内部的最顶层设计就是组件图,描述子系统由哪些组件组成,不同场景中,组件之间的调用序列图是什么样的。

每个组件内部,需要用类图进行建模描述,对于不同场景,用时序图描述类之间的动态调用关系,对于有复杂状态的类,用状态图描述其状态转换。

具体示例模板如下:

1 设计概述

……系统是一个……的系统,是公司……战略的核心系统,承担着公司……的目标任务。

1.1 功能概述

系统主要功能包括……,使用者包括……。

1.2 非功能约束

……系统未来预计一年用户量达到……,日订单量达到……,日PV达到……,图片数量达到 ……。

  1. 查询性能目标:平均响应时间<300ms,95%响应时间<500ms,单机TPS>100;
  2. 下单性能目标:平均响应时间<800ms,95%响应时间<1000ms,单机TPS>30;
  3. ……性能目标:平均响应时间<800ms,95%响应时间<1000ms,单机TPS>30;
  4. 系统核心功能可用性目标:>99.97%;
  5. 系统安全性目标:系统可拦截…… 、……、……攻击,密码数据散列加密,客户端数据HTTPS加密,外部系统间通信对称加密;
  6. 数据持久化目标:>99.99999%。

2 系统部署图与整体设计

系统上线时预计部署……台物理机,……个子系统,和公司……系统交互,和外部第三方……个系统交互。

2.1 系统部署图


子系统1的功能职责为……,部署……台服务器,依赖……和……子系统,实现 ……功能。

子系统2参照子系统1来写。

2.2 下单场景子系统序列图

  1. 下单时,子系统先发送……消息到子系统3,子系统3需要执行……完成……处理,然后发送……消息到财务系统,消息中包含……数据。
  2. 收到……的处理结果……后,子系统1发送……消息到……子系统2……。

2.3 退款场景子系统序列图

  1. 退款子系统先发送……消息到子系统3,子系统3需要执行……完成……处理,然后发送……消息到财务系统,消息中包含……数据。
  2. 收到……的处理结果……后,子系统1发送……消息到……子系统2……。

2.4 退款场景子系统活动图


如图所示:

  1. 退款开始时,子系统1处理XXX,然后判断m的状态,如果m为真,请求子系统3处理ZZZ,如果m为假,子系统继续处理ZZZ并结束。
  2. 子系统3处理ZZZ后,一方面继续处理XYZ,一方面将……消息发送给财务通进行AAA处理。
  3. 子系统在处理完XYZ后,返回子系统继续梳理YYY,然后退款处理结束。

3 子系统1设计

子系统1的主要功能职责是……,其中主要包含了……组件。

3.1 子系统1组件图


子系统1包含6个组件:

组件1的功能主要是……,需要依赖组件2完成……,是子系统1的核心组件,用户……请求主要通过组件1完成。

同样的,组件2也可以参照组件1来这样写。

3.1.1 场景A组件序列图


对于场景A,首先组件1收到用户消息CCC,然后组件1调用组件2的XXX方法……。

3.1.2 场景B组件活动图


在场景B中,首先组件收到……消息,开始处理……,然后判断……,如果为true,那么……,如果为false,那么……。

3.2 组件1设计

组件1的主要功能职责是……,其中主要包含了……类。

3.2.1 组件1 类图


Class1实现接口Interface1,主要功能是……,Class1聚合了Class2和Class3,共同对外提供……服务,Class1依赖Class4实现……功能,Class4……。

3.2.2 场景A 类序列图


在场景A中,当外部应用调用类1的create方法时,类1……。

3.2.3 对象1状态图


对象1运行时有4种状态,初始状态是状态1,当条件1满足是,状态1转换为状态2,当条件3满足时,状态2转换为状态4……。

3.3 组件2设计

重复上面的格式。

4 子系统2设计

重复上面的格式。

精选留言(15)
  • 许童童 👍(31) 💬(1)

    这个加餐不错,直接上干货,这个设计文档只要稍做修改,就可以在公司内部直接使用了,老师牛啊。

    2019-12-11

  • 老男孩 👍(9) 💬(0)

    一个很好的设计文档模板。看了这个我才知道,之前的一些文档有些地方就是胡写了。很多公司,而且是有一定规模的公司,设计文档也是后补的,为了应付领导或者甲方。产品和开发也不看,就盯着产品原型图死磕。关于一个核心问题域,有时候连名词都没统一。project,你说的是项目管理,他说的是工程管理,或者一会儿工程一会儿项目。这样的文档写了也没人看,然后就真的成了软件系统的“遗产”了。

    2019-12-11

  • 天天向上 👍(6) 💬(1)

    老师 您好!类似文档丰富的Java开源项目,您能否推荐一个?

    2019-12-11

  • 丁丁历险记 👍(4) 💬(0)

    给markdown 打个广告,我现在blog 全是md 格式了。

    2019-12-18

  • 几点了 👍(2) 💬(0)

    终于理解公司的设计文档的章节了,学习到了

    2019-12-17

  • escray 👍(1) 💬(0)

    其实不久之前是看过这篇加餐的,当然也学过文档模板,但是再次打开,却有一些不一样的发现。 其实这个不仅仅是一个模板,在这个模板的下面,是一个相对完整的设计思路。 之前写过架构师训练营的课程作业,画一个食堂餐卡系统的 UML 图。我自己画的比较简陋,而那些“学霸”们的优秀作业,和这里的结构比较类似,可能是师出同门,也可能是因为优秀的脑袋总是相通的。 我不喜欢写冗长的文档,不过类似这样的文档,无论是作为作者还是读者,对于理解系统架构都很有帮助。

    2020-10-21

  • king5699 👍(1) 💬(0)

    加餐优秀,谢谢老师

    2020-03-23

  • 探索无止境 👍(1) 💬(0)

    这样的干货加餐,应该多来点!感谢老师!

    2020-03-02

  • 靠人品去赢 👍(1) 💬(0)

    这个mark一下,设计文档之前一个公司都是A复制B换个图,换个描述,也不知道对不对。这个最起码是模版,到时候用的时候可以拿出来。

    2019-12-16

  • 北天魔狼 👍(1) 💬(0)

    🙏🙏🙏直接上模板。以前一直都是确定一下功能逻辑就开始,规范化的东西一直没有,谢谢老师

    2019-12-11

  • 曹翔 👍(0) 💬(0)

    如果系统小型重构,或者微服务之间有变动,都要先更新这些文档吗?这样的话,发版频繁的系统文档操作太频繁了

    2021-03-02

  • pinteressante 👍(0) 💬(0)

    这个很棒了, 希望老师再多上一些类似的干货

    2021-02-28

  • def 👍(0) 💬(0)

    非常不错的模板,甚至可以直接上手用,感谢老师!

    2021-02-24

  • Lin大坑haha~ 👍(0) 💬(0)

    加餐很棒,逻辑清晰,谢谢老师

    2020-10-19

  • 火锅小王子 👍(0) 💬(1)

    老师您好,想问下第三部分中的组件图是不是改为模块图更合理些?组件应该是属于工具,而我们这个应该是属于业务系统设计的层面

    2020-08-19