软件设计说明书模板：CMMI评审与详细设计文档编写指南

简介软件设计说明书模板及案例说明面向软件设计人员、开发人员与项目文档撰写者用于解决设计文档缺乏统一结构、难以评审维护的问题。模板基于Rose建模工具完整覆盖软件设计说明书的核心章节简介、需求描述、第一层系统结构设计、第二层模块结构设计、数据库设计可选、组件视图、进程视图、模块详细设计、数据库详细设计可选并附有修订记录便于版本追踪。内容以仓储管理系统EYP为例包含系统上下文定义、业务整体性能指标、主流程等具体描述展示如何将需求转化为结构化设计文档。整个资源为1个doc文件压缩包大小2.96MB适合直接套改使用。已有1733人浏览学习特别适合需要按CMMI规范编写设计文档的团队或个人。1. 软件设计说明书样例一份能过评审的正文骨架这份软件设计说明书样例是一份按 CMMI V3.0 流程要求编写的仓储管理系统EYP V100R001C01B010设计文档建模工具用 Rose覆盖简介、需求描述、两层系统与模块结构设计、数据库设计、组件/进程视图、模块详细设计共九章。它的价值不在存档而在于把设计怎么实现逼成可检查的条目类图、时序图、方法表、性能指标一一落位。适合要给同行评审或 CMMI 审计交差、又不知道文档该写到什么粒度的人也适合开发人员快速判断自己手里那份设计文档离可开发还差几章。下面我按实际拆文档的习惯把这份模板一层层剥开讲。2. 从目录看设计九章结构背后是评审的九连问拿到任何一份 SDD我第一件事不是读正文而是看目录。目录能反映作者有没有把设计决策链走完整。这份模板的九章其实对应评审官会依次追问的九组问题范围是什么、需求约束有哪些、系统整体怎么分、模块内部怎么分、数据怎么落、运行形态是什么、进程间怎么协作、类和方法的粒度够不够、数据库对象有没有细化到实现级。2.1 九章结构与评审关注点的对应关系先把模板章节和评审关注点对齐我习惯列一张表章节模板标题评审官真正想确认的新手最容易跳过的地方1简介文档范围、软件名称、功能清单、性能指标缩略语清单觉得没必要填2需求描述功能边界、主流程、运营考虑把 SDD 写成 SRS大段抄需求3第一层系统结构设计架构分层、技术选型理由、依赖关系只写框架名不写协作逻辑4第二层模块结构设计模块切分、类静态关系、时序流程图全但类定义和方法表空白5数据库设计可选实体定义、E-R 关系、存储过程归类看到可选就直接跳过6组件视图可执行文件、源码目录组织目录树不画部署形态靠口头讲7进程视图进程划分、通信模式多模块系统不画进程间通信8模块详细设计类的方法级实现、异常处理方法表只写一句话描述9数据库详细设计可选存储过程/触发器的详细实现留白评审时靠临时口答九章里真正会被当场翻开的通常是第 3、4、8 章但第 1、2、6、7、9 章会在评审意见里变成范围不清、指标缺失、部署未知、存储过程未定义这类一行行问题。原因在于 SDD 的受众不止是开发还有测试性能指标、主流程、运维组件视图、进程视图和审计修订记录。填模板时眼里要有不同角色别把文档当成给自己看的草稿。注意模板第 1.1 节下方那页缩略语清单不是装饰。文档后面大量出现 Tapestry、ACEGI、Pojo、Vo 这类缩写不先定义Review 的时候会被一条条揪出来问。2.2 三层架构在文档中如何呈现Tapestry、Spring、Hibernate 的分工模板标题里带OO正文第 3.2.1 节又把实现原理写成 MVC 三层结构Tapestry 做表现层Service 层管业务Hibernate 做 ORM 映射。这四句话是整套架构的核心值得拆开看Tapestry 的 page 层主要用于 Control 作用Html 装载数据发回客户端。这里定义的是控制权在 page视图由页面模板组装数据处理完回填到 Html 再发回浏览器。Page 层依赖 Service 的 Manager 以及 Pojo并通过 Spring 的 IOC 依赖注入把 Manager 与 Pojo 注入 Page。这句话实际是在交代对象间的装配方式也就是谁创建谁、谁引用谁。Manager 依赖 Dao通过 Hibernate ORM 映射把 Pojo 动态生成 Vo并将 Vo 数据储存到数据库相应表及字段。这里描述的是持久化策略Pojo 用于展示Vo 用于存取二者通过 ORM 转换。Manager 可以通过 AOP 模式过滤或处理日志信息及权限管理事物管理由 Spring 管理。这是横切关注点的落位日志、权限、事务不散落在业务方法里。我一般会这样读这一段先看系统里用了哪些框架再看每个框架的职责能不能用一句话说清。文档里出现在 3.3 节的 ACEGI 安全框架和 Mail 组件也属于横切模块必须有对应的依赖描述和接口描述否则第三层依赖关系画不完整。模板里 2.3.1 的Design Alternatives 设计可选方案写的虽然只是MVC结构处理一句话但它的作用是提示作者选型要有候选意识。真正写文档时哪怕只补一句不用 MVC 则需要把业务逻辑塞进页面类测试和维护都会变难评审观感就完全不同。2.3 性能指标不是摆设从参数表反推设计约束模板第 1.2.2 节下方有一张业务整体性能列表三行参数分别对应三类设计约束指标项模板中的描述对设计产生的要求在线用户200 个Web 容器线程数、数据库连接池上限要有估算依据并发量处理50 个/1 秒Service 层方法的事务粒度要控制长事务会直接顶掉并发额度文件导入导出不超过 100000 条/20 秒超过 20 秒必须以进度条显示超过 20 秒的界面不能同步等待必须改为异步任务加进度展示这三行参数要落到设计里而不是躺在需求页里当装饰。比如超过 20 秒用进度条这个约束表面上是界面需求实际上要求模块详细设计中的页面处理方法拆分出异步任务和进度查询接口。又比如50 个并发/1 秒如果方法调用链里有跨表更新、锁等待这个数字很难达标设计文档里就应该在 Method 表的 Exception 或实现描述中写明对应策略。把这张性能表读明白再去看第 3 章的系统结构才能理解为什么文档要强调 Web 应用服务器与数据库可以分设或者同在同一个服务器。分设与否直接决定第 6 章组件视图、第 7 章进程视图怎么画。很多项目评审不过不是代码问题而是这些指标没有一个和设计章节产生关联。3. 照着模板落地以用户管理为例的类图、时序图与方法表模板再完整不套到自己的项目上也是空转。这一章我以文档里的用户管理模块为例演示从功能清单一路写到方法表的过程。仓储管理系统一共有五个功能域用户管理是最典型的一个因为它同时涉及页面控制、业务管理、数据访问和权限校验四层逻辑。3.1 先把功能清单映射到设计章节模板第 1.2.2 节列了功能清单用户管理、产品管理、仓库管理、客户管理、运筹管理。很多人写完这张表就再也不管了后面章节各写各的评审时无法追踪某个功能到底对应哪些类和哪些数据表。我一般的做法是画一张功能到章节的映射表业务功能设计落点章节需要交付的内容用户管理4.1 5.x 8.x模块类图、时序图、用户表实体、页面动作方法表产品管理4.2 5.x 8.x产品类设计、产品表实体、库存关联、导入导出方法仓库管理4.2 5.x 8.x仓库实体、库位关系、仓储事务控制客户管理4.2 5.x 8.x客户实体、联系人结构、查询方法运筹管理4.2 5.x 8.x运筹算法接口、任务队列、结果存储这张映射表不需要写进正式文档但写文档前先把它列出来能保证每个功能域在第二层模块设计、数据库设计、模块详细设计三个层面都有对应内容。模板里第二层模块设计只展开了用户管理和仓库管理两节这是样例的取舍实际文档里每个功能域都至少占一节哪怕只有一页。3.2 用户管理模块的类图拆分模板 4.1.1 节给出的类清单按职责可以分成四组页面与事件类BasePage、UserPage、UserActionPage。UserPage 负责页面展示数据装载UserActionPage 负责接收页面动作在 action 方法里调用 Manager。这一层对应 Tapestry 的 Control 职责。业务管理类UserManager、UserManagerImpl、ServiceBaseManagerImpl、BaseManagerImpl。Manager 定义业务接口Impl 提供实现公共逻辑放在 ServiceBaseManagerImpl 和 BaseManagerImpl 里避免每个模块重复写权限校验或日志代码。数据访问类UserDao、UserDaoImpl、HibernateBaseDaoImpl、BaseDaoImpl。Dao 接口定义持久化操作Impl 通过 Hibernate 会话实现HibernateBaseDaoImpl 封装通用增删改查。模型类User标识为 autoID。这是 Pojo用于展示层数据装载实际存取时通过 ORM 动态生成 Vo再落到数据库表。这四组类在文档里要有静态关系图同时要有一个时序图交代一次请求的完整链路。模板 4.1.2 节画了六步时序对应关系可以写成一张表时序步骤参与对象文档中要写清楚的内容1 request系统用户 → WebServer浏览器端发起请求通过 TCP/IP 提交数据2 DoActionUserActionPage → UserManagerPage 层调用 Manager 的业务方法3 ResponseManager → Page无权限或参数错误时返回错误信息4 Save Or GetManager → UserDao → 数据库Manager 通过 Dao 查询或保存用户5 return resultDao → Manager数据访问层返回操作结果6 ResponseWebServer → 客户端最终结果回传浏览器页面刷新这张表写清楚后用户管理这一个模块的逻辑链就闭合了。需要注意时序图里第 2 步和第 4 步是最容易被评审追问的因为涉及业务逻辑放在 Manager 还是 Page的边界问题。模板 3.2.1 已经给过答案Page 层只做控制转发业务处理在 Manager 中进行。如果自己项目里把业务判断写进了页面类要在文档里说明理由否则评审会认为架构分层没有贯彻。3.3 方法表怎么填以查询用户为例模板第 8.1.5 节把 Methods 的说明要素列得很全Prototype、Description、Calls、Called By、Input、Output、Return、Exception。这是详细设计的重点也是 HLD 与 LLD 的分界线。我一般要求每个核心方法都按这个格式填一行以查询用户为例要素填写内容Prototypepublic List findUser(UserCondition condition)Description按姓名、角色和分页参数条件查询用户列表CallsUserDao.findByCondition(condition)Called ByUserActionPage.handleQuery()InputUserCondition含姓名关键字、角色 ID、页码、每页条数OutputListUser符合条件的分页结果Return非空列表无数据时返回空列表不返回 nullExceptionDataAccessException表示数据库访问失败这样填完方法的行为边界就清楚了。Calls 和 Called By 能让评审者顺着调用链往上往下查Input 和 Output 能验证传参是否完整Exception 能看出作者有没有考虑异常路径。模板第 8.1.5 节还专门说这部分是详细设计的重点要求用伪代码覆盖分支与边界条件。提示详细设计不建议贴完整业务代码。伪代码写到分支和边界即可目的是让开发人员在编码阶段不需要再做设计决策而不是把代码提前复制一遍。3.4 数据库、组件与进程视图的填空策略这三个部分模板都标注了可选但实际评审中往往被追问。数据库设计至少要给出实体定义表和 E-R 图模板 5.1 节要求把关键字段属性、完整性约束、存储要求写清楚对静态数据表还要考虑初始配置记录。如果项目里有存储过程或触发器模板 5.2 节要求按功能归类详细定义每个对象的输入输出参数、返回值、依赖的表和特殊要求。组件视图要做两件事一是描述可执行组件包括 EXE、DLL 等运行二进制及网络部署情况二是画源码目录树说明每个目录下放什么文件。进程视图要说明系统如何分解为轻量级进程和重量级进程以及进程间的主要通信模式。这三部分往往会被新手跳过但恰好是评审提意见的高发区。实际项目中只要存在定时任务、导出任务、外部接口调用就必须在进程视图里给它们一个归属否则运维阶段没人知道某个任务跑在哪个进程里。4. 避坑指南五个高频返工现场与对应的补救动作模板本身没什么问题问题大多出在填模板的方式上。以下五个场景是我拆这份文档时最常见的返工现场都不是技术难题全是文档纪律问题。4.1 需求章节成了流水账SRS 与 SDD 混写现象第 2 章需求描述占了全文一半篇幅功能列表、界面原型、用户操作说明全都写了到第 3 章架构设计和第 8 章方法表反而大段空白。原因作者把软件设计说明书当成需求文档的延续认为需求写细就是设计实际上 SRS 回答做什么SDD 回答怎么做两份文档的读者和评审标准完全不同。解决SDD 里的需求部分只保留与设计直接相关的约束比如性能指标、软硬件配置、主流程功能需求引用 SRS 章节号即可把写作时间分配架构决策和类方法定义。模板第 2 章本身也写得很克制三页左右就切到了系统结构。4.2 类图画了不少方法表却一句话带过现象类图、时序图画了满满几页翻到第 8 章方法表每个方法只有一句处理用户登录或查询用户列表。原因把详细设计当成了概要设计的延续没有理解模板第 8.1.5 节为什么强调使用伪代码来描述详细实现这部分是详细设计的重点。解决核心类的方法必须按六要素填全原型、功能描述、调用函数、被调用函数、输入输出参数、返回值与异常。拿不准怎么写时先挑一个穿越页面层、业务层、数据访问层的方法完整填一遍后面的方法就照此办理。4.3 数据库设计标注可选就直接留白现象第 5 章数据库设计整章空白评审问用户表和仓库表的主外键关系、库存事务怎么控制作者现场翻代码才能回答。原因模板里Optional被理解成了不用写。实际上可选指的是按项目范围决定详略程度不是按心情决定写不写。解决项目里只要有数据持久化需求数据库设计至少要有实体列表、关键属性定义、E-R 关系图和完整性约束存储过程或触发器哪怕只有一个也要按模板 5.2 的格式把输入输出参数和依赖关系写清楚。4.4 组件视图和进程视图缺失评审看不到运行形态现象第 6、7 章只写无或略没有可执行组件说明没有源码目录树没有进程分组和通信模式。原因作者默认设计文档只管代码逻辑部署形态和进程结构是运维文档的事。解决组件视图至少给出源码目录树和主要可执行文件清单进程视图写明进程分组及通信模式。模板 7 章提到了消息传递、中断和会合三种模式实际系统里 Web 请求处理、异步导出任务、定时任务之间都会用到挑最相关的两三种写清楚即可。4.5 修订记录空白版本失控的起点现象整份文档只有 v1.00 一条初稿完成后面评审改了三轮章节内容变了版本号还是一动不动。原因修订记录在模板第一页表格位置显眼但和正文没有强关联不更新不影响文档编译于是被所有人忽略。解决每次评审后强制新增一行日期、修订版本、CR 号、修改章节、修改描述、作者。这条纪律能让后来人在出问题时快速定位到改动点和责任人。模板给的列正好是这六项别删。5. 最后一招把目录反着用做一张评审自检清单模板的正向用途是指导写文档反向用途更值钱当评审自检清单。我常用的是把九章压成七问输出前按顺序过一遍检查项对应章节与过关标准范围清楚吗第 1 章有软件名、功能清单、性能指标、缩略语定义需求约束到位了吗第 2 章有主流程、用户类型、硬件配置且没有大段抄 SRS架构选型有理由吗第 3 章有系统结构图、MVC 分层说明、框架职责分工模块边界闭合吗第 4 章每个功能域都有类图、时序图和接口描述数据落得下来吗第 5 章有实体定义、E-R 关系、存储过程归类运行形态可见吗第 6、7 章有组件视图、目录树、进程分组和通信模式方法级能落地吗第 8 章核心方法六要素齐全异常有处理策略这七问用来检查别人文档也用来检查自己文档。写详细设计时我会先把第 8 章的方法表铺出来再回头看第 3、4 章的类图和时序图是否覆盖了所有方法。类图里有而方法表没有的类说明设计尚未闭环方法表里有而类图没有的类说明类图漏画了。这个交叉验证比逐章通读更快也更接近评审官的思路。从那以后我不管是自己出设计文档还是帮同事过评审都会先拿这份模板的目录当自检清单过一遍。哪个章节空白就说明哪个设计决策还没想清楚跟写得好看不好看没关系。这份模板可以作为新手起步的骨架也可以当评审的问题清单先把要讲的章节填满再谈讲得好不好。希望帮到你。本文还有配套的精品资源点击获取