简介：面向软件设计人员与计算机专业学生的软件设计说明书写作参考模板，以一份完整样例示范如何组织设计文档。内容围绕需求描述、第一层系统结构设计与第二层模块结构设计展开，并细分数据库设计、组件视图、进程视图、模块详细设计及数据库详细设计等章节；样例以仓储管理系统EYP为背景，含Revision Record修订记录、缩略语清单与性能指标表格，可直接对照套用。压缩包内共1个doc文件，约2.96MB，为可编辑的Word文档，便于替换项目名称与章节内容后复用。已有1741人学习下载。读者可从中了解设计说明书的章节层级、各部分应写什么、OO设计视角下组件与进程视图如何落地，以及修订记录与密级标注等文档规范细节，适合作为课程设计、CMMI流程文档或企业设计文档的起步框架。

1. 从一份 76 页的软件设计说明书模板说起：它到底能替代哪些评审材料

第一次拿到这份 76 页的软件设计说明书模板，很多人的反应是把它当 Word 格式规范：改页眉、填目录、贴几张图就交差。真到评审现场，问题往往不在排版，而在需求描述、第一层系统结构设计描述、第二层模块结构设计描述、数据库设计、组件视图、进程视图、模块详细设计之间能不能互相对上。软件设计说明书模板及案例说明的价值，不是多一份文档外壳，而是给出一套可复用的软件设计说明书样例：从简介、需求描述到详细设计，每一节都对应一个可检查的交付物。适合谁？要带新人写设计文档的负责人、准备过程评审的团队、以及需要把 MVC 分层说清楚的开发骨干。下面按这份仓储教学管理案例（模板中代号 EYP）的章节顺序拆一遍，重点说清楚哪些字段必须填、哪些图不能只当装饰、哪些坑最容易在评审前翻车。

2. 先定章节骨架：软件设计说明书样例的九个章节怎么落到可评审字段

2.1 九个章节与评审关注点的映射

这份模板的目录不是按“写作习惯”排的，而是按设计信息的粒度从粗到细推进：简介和需求描述先把边界定住，第一层系统结构设计描述定架构和分层，第二层模块结构设计描述定模块职责，数据库设计、组件视图、进程视图分别从数据、部署、运行三个角度补证，模块详细设计和数据库详细设计再落到类、方法、存储过程。很多团队写软件设计说明书样例时喜欢从“系统架构”开始，结果需求描述里的性能指标和后面的进程视图对不上，评审一问就露馅。

这张表可以直接当评审 checklist 用。比如第 4 章“第二层模块结构设计描述”里，用户管理模块不能只写“查询、新增、修改、删除”，还要写清楚谁调用谁、失败返回什么、权限校验放在哪一层。模板里给出的UserPage、UsersManagerImpl、UserDaoImpl这条链路，就是让评审能沿着页面层、服务层、数据访问层一路追到数据库表。

2.2 简介与需求描述：先把范围、功能、性能写成可测参数

模板第 1 章要求写目的、范围、软件名称、软件功能、业务整体性能列表、软件应用。第 2 章要求写系统上下文定义、业务用户类型、运营考虑、主流程、设计可选方案、设计约束。这里的填写顺序建议反过来：先锁定软件名称和范围，再列功能清单，最后补性能指标。因为性能指标一旦写成“响应快”“支持多人”，后面进程视图和数据库设计就没有验收锚点。

简介部分的最小填写参数可以按下面这张表落地：

性能列表里有一个细节值得单独说：模板原文的运行环境写的是 Win Server 2002、2.8GHz CPU、4G 内存。实际填写时不要照抄这个版本号，先确认目标环境的真实版本和资源配额；如果只是教学案例，也要在表下注明“示例值，验收时以实际环境为准”。在线用户 200 个、并发 50 个/1 秒、导入导出 100000 条/20 秒这些数字，最好同时写进第 7 章进程视图的线程模型说明里，否则性能指标和运行设计是两张皮。

需求描述里的“业务用户类型说明”也要注意区分业务角色和系统角色。模板写的是老师与学生使用，老师把系统当教学材料。落到设计上，老师是业务角色，系统里对应的是“教师账号”或“教学管理员账号”；学生是另一类业务角色，可能只有查询权限。不要把“老师”“学生”直接写成数据库用户表里的角色字段值，角色字段应该用可配置的角色编码，比如ROLE_TEACHER、ROLE_STUDENT，再在权限模块里映射。

主流程部分，模板给出了用户到 WebServer 再到 DataServer 的请求/响应链路：用户发起请求，WebServer 处理并返回错误信息，WebServer 再查询或保存数据库，最后把操作结果返回客户端。填写时至少补三类分支：参数校验失败、数据库访问超时、权限不足。只写正常路径，第 5 章数据库设计和第 8 章详细设计就没有异常设计可写，评审自然会追问。

2.3 缩略语清单与修订记录：让软件设计说明书样例可追溯

缩略语清单看起来是边角料，实际上它决定了后面章节能不能被不同角色读懂。模板要求每个缩略语给出英文全名和中文解释。MVC、ORM、IOC、AOP、VO、POJO、DAO 这些词在这份案例里反复出现，如果不在第 1 章统一，第 3 章和第 4 章就会各写各的。建议用三列表格：缩略语、英文全名、中文解释，再补一列“首次出现章节”。比如 VO 在这份模板里指“保存与查询数据库的值对象”，POJO 指“普通 Java 对象”，两者不要混用。

修订记录同样不能只写“修改”。模板给出的字段是日期、修订版本、CR 号/Defect ID、修改章节、修改描述、作者。CR 号要和需求变更单或缺陷单关联，修改章节要写到“4.1.2 功能实现说明”这种粒度。作者栏写姓名加工号，不要写昵称。页脚的密级、页码、总页数要和文档属性一致；模板里出现“Total 21 pages 共 76 页”这种页码口径不一致的情况，交付前必须统一，否则打印稿和电子稿对不上，评审时会被当成配置管理问题。

注意：模板中的“可选”章节不是可删章节。数据库设计、数据库详细设计标了 Optional，但只要有持久化需求，就要么填写，要么写清楚“本期不涉及，原因是什么，后续由哪份文档承接”。

3. 第一层系统结构设计：用 MVC 分层图和 Tapestry/Spring/Hibernate 依赖关系讲清架构

3.1 系统上下文和主流程图的画法

第 3 章第一层系统结构设计描述要解决的是“系统边界”和“分层职责”。模板给出的系统上下文图很简单：System User 通过 IE 客户端向 WebServer 发请求，WebServer 再访问 DataServer，返回错误信息或操作结果。图不复杂，但填写时要把图上的每条线落到文字：客户端到 WebServer 用什么协议、WebServer 到数据库是直连还是连接池、错误信息在哪一层生成、返回给客户端的是页面还是错误码。

我一般会要求在图下面补一张“交互步骤表”，至少四列：步骤、发起方、接收方、失败处理。以这份案例的主流程为例：

这张表能把模板里“通过 TCP/IP 协议传送请求数据”这种泛化描述落到可检查的设计点。TCP/IP 是传输层事实，不是设计亮点；评审真正关心的是请求边界、错误边界和事务边界。比如“查询用户”这个动作，Page 层只做参数接收和视图选择，权限判断放在 Manager 层，数据库访问放在 Dao 层，异常在 Manager 层转成业务错误码。这样后面第 4 章写模块详细设计时，类职责才有依据。

3.2 三层架构的组件依赖与接口边界

模板的案例采用 MVC 三层构架：Tapestry 做表现层，Service 层承载主要业务实现，Hibernate 做 ORM 映射，Pojo 展示数据，Vo 保存与查询数据库。它还提到 Spring 的 IOC 依赖注入、AOP 日志和权限管理、事务管理，以及 ACEGI 权限、Mail、Remote 等组件。填写这一节时，不要只列框架名，要写清楚依赖方向和接口边界。

这张表可以直接贴进第 3 章的“分解描述”里。模板 3.3 要求对 Tapestry、Spring、Hibernate、ACEGI、Mail、Remote 分别写 Overview 和 Functions 功能列表。Overview 不要写框架介绍，写“在本系统中承担什么职责”；Functions 功能列表写“本系统用到的具体能力”，比如 Tapestry 的页面生命周期、Spring 的 bean 作用域和事务传播、Hibernate 的映射文件和懒加载策略、ACEGI 的 URL 拦截规则。

接口边界可以用一段示例代码说明 Page 层怎么调用 Manager，代码只表达依赖方向，不是完整实现：

// Page 层只做请求编排，不直接拼 SQL，也不直接依赖 Dao 实现 public class UserPage extends BasePage { private UserManager userManager; // 由 Spring IOC 注入，类型是接口不是实现类 public String queryUser(Long userId) { if (userId == null) { return "error: userId is required"; // 参数校验前置，失败信息回到页面 } User user = userManager.findUser(userId); // 只调用 Service 层 return user == null ? "user_not_found" : "user_detail"; } }

这段代码的逻辑说明：UserPage继承BasePage，只负责参数校验和视图选择；userManager声明为接口类型，具体实现由容器注入，避免 Page 层绑死实现类；返回值是视图名或错误标识，不把数据库异常直接抛给页面。参数说明：userId是必填参数，为空时直接返回错误；userManager的生命周期和作用域要在 Spring 配置里写清楚；findUser的返回值为空时走“未找到”分支，不为空时走详情页。实际项目里还要补权限判断，通常放在 Manager 方法入口或 AOP 切面里，而不是散落在 Page 的 if 语句里。

3.3 设计可选方案和约束条件的写法

模板 2.3 要求写设计可选方案和设计约束。案例只写了“MVC 结构处理”，这在评审里偏薄。合格写法至少列出两到三个备选方案，并说明取舍理由。比如表现层可选 Tapestry、纯 Servlet/JSP、前后端分离；持久层可选 Hibernate、MyBatis、手写 JDBC；权限可选 ACEGI、自定义拦截器。选择 Tapestry + Spring + Hibernate 的理由不能写“流行”，要写“页面组件复用、IOC 解耦、ORM 映射减少手写 SQL、团队已有维护经验”这类可验证理由。

设计约束部分，模板写的是“遵循客户验收标准”“硬件限制无”“技术限制无”。这里的“无”不是免填理由，要写成“无额外硬件限制，但运行环境不低于性能表所列配置”“无特殊技术限制，但必须兼容指定浏览器版本”。约束要能影响设计决策：如果客户验收标准要求导入 100000 条数据在 20 秒内完成，那么第 7 章进程视图就要说明导入任务是否单独线程、是否分批提交、进度条如何刷新；如果技术限制要求不能引入外部缓存，那么第 5 章数据库设计就要写清楚查询优化和索引策略。

这一章写完，最好做一次反向检查：架构图上的每个组件，在第 4 章能不能找到对应的模块或类；第 3 章列出的每个接口，在第 8 章能不能找到方法原型；性能表里的每个数字，在第 6 章组件视图和第 7 章进程视图里有没有落点。对不上就说明第一层设计还只是图，不是可执行的设计。

4. 第二层模块结构与数据库设计：用户管理、仓库管理怎么拆到类和表

4.1 模块分解的输入输出和类职责

第 4 章第二层模块结构设计描述，是把第一层的分层落到具体模块。模板给了用户管理和仓库管理两个例子，其中用户管理写得最细：老师登录后进入用户管理模块，查询显示存在用户，对存在用户进行修改与删除，新增不存在的用户。这个描述已经包含了角色、入口、查询、修改、删除、新增六个信息点，填写时要把它们拆成模块边界和类职责。

模块分解不要按“页面菜单”拆，要按“业务能力 + 数据边界”拆。用户管理模块的核心数据是用户实体，核心规则是账号唯一、状态可控、权限可分配；仓库管理模块的核心数据是仓库和库存，核心规则是库位不能超卖、库存变更要留痕。把这两类规则写进模块设计描述，第 8 章的方法设计才有业务含义。

模板 4.1.1 还要求写 CI 标识、Overview 简介、Definition 类定义。以User为例，CI 标识写autoID，Overview 写“用户信息 Pojo，承载账号、展示名、状态和审计字段”，Definition 写类名和包路径。包路径不要写真实公司域名，用示例包名即可，比如demo.user.model。属性表按“可见性、属性名称、类型、说明”四列填写，password这类敏感字段要注明“不参与页面直接展示，传输和存储按安全规范处理”，不要在设计说明书里写明文密码。

4.2 用户管理模块的类图与功能实现说明

模板 4.1.2 的功能实现说明给了一条六步链路：查询用户、业务处理（如查询是否有权限）、返回没有权限或其他错误信息、保存或查看用户、返回操作结果、返回最终结果。这条链路对应到类图上，就是UserPage调用UserManager，UserManagerImpl调用UserDao，UserDaoImpl通过 Hibernate 访问数据库，User作为 Pojo 在层间传递。

填写类图时，至少标出四类关系：继承（UserPage继承BasePage）、实现（UserManagerImpl实现UserManager）、依赖（UserPage依赖UserManager）、关联（User与用户表映射）。模板里的BaseManager、BaseDao、HibernateBaseDaoImpl是公共基类，不要把它们画成业务类；公共基类只放通用 CRUD、分页、事务模板，业务规则放在具体 Manager 里。

功能实现说明可以按“正常、权限不足、数据不存在、数据库异常”四条路径写：

这张表比“查询用户、业务处理、返回结果”更接近可测试的设计。评审时可以顺着表问：权限拦截是在 Page 还是 Manager？如果是在 Manager，事务是否已经开启？数据库异常转成业务异常后，事务回滚规则是什么？这些问题在第 8 章方法描述里要有答案。

4.3 数据库实体、E-R 与存储过程定义的填写

第 5 章数据库设计（可选）要求写实体定义、分解描述、内部依赖性描述、行为定义。模板强调要定义关键表、视图中的字段属性、存储要求、完整性约束、功能、注意事项，静态数据表要考虑初始配置记录。很多软件设计说明书样例在这里只放一张 E-R 图，评审一看字段约束、索引、初始数据全没有，数据库详细设计就没法往下写。

以用户表为例，字段设计至少要把代理主键、业务唯一键、状态、审计字段分开：

-- 用户表：模板要求把主键、业务唯一键、状态、审计字段分开写 CREATE TABLE demo_user ( id BIGINT PRIMARY KEY COMMENT '代理主键，对应 CI 标识 autoID', login_name VARCHAR(64) NOT NULL COMMENT '登录名，业务唯一', display_name VARCHAR(128) NOT NULL COMMENT '展示名', status TINYINT NOT NULL DEFAULT 1 COMMENT '1 启用，0 停用', created_at DATETIME NOT NULL COMMENT '创建时间', updated_at DATETIME NOT NULL COMMENT '更新时间', UNIQUE KEY uk_demo_user_login_name (login_name), KEY idx_demo_user_status (status) ) COMMENT='用户实体，对应设计说明书 4.1.1 的 User';

这段 SQL 的逻辑说明：id是代理主键，对应模板里的autoID；login_name是业务唯一键，必须加唯一约束，不能只靠应用层判重；status加索引，支持按状态筛选；created_at、updated_at是审计字段，支持修订追踪和问题排查。参数说明：VARCHAR长度按实际账号策略调整；TINYINT的状态值要写进数据字典，不能只在代码里约定；字符集、排序规则、存储引擎按目标数据库配置填写，不要照抄示例。

存储过程和触发器部分，模板要求写原型、功能描述、使用的数据库对象、输入参数、输出参数、返回值、实现描述。以“按用户 ID 查询用户”的存储过程为例，填写时要写清楚：入参p_user_id的类型和空值处理；出参是结果集还是状态码；依赖demo_user表；是否需要事务；异常时返回什么。不要只写“查询用户”四个字。数据库详细设计的伪代码要能看出游标、循环、提交频率，否则第 9 章就退化成“见脚本”。

5. 避坑与排查：软件设计说明书样例里最容易翻车的五类问题

5.1 现象一：章节齐全但评审无法追踪需求

现象：目录从简介到数据库详细设计一页不少，评审问“在线用户 200 个这个指标落在哪”时，只能翻到性能表，后面的进程视图和组件视图没有任何对应说明。原因：把模板当填空表，按章节独立填写，没有做需求到设计的追踪矩阵。解决：在第 2 章性能表旁边加一列“设计落点”，写明该指标由第 7 章进程视图的线程模型、第 6 章组件视图的部署节点、第 5 章数据库设计的索引策略共同承接；评审前用一张追踪表逐条核对，缺落点的指标要么补设计，要么改指标口径。

5.2 现象二：架构图和代码目录对不上

现象：第 3 章架构图画了UserPage、UserManager、UserDao三层，第 6 章源码目录却只有web、service、dao三个大文件夹，里面混着工具类、配置文件和测试代码；组件视图里的 EXE/DLL 清单和第 6 章部署图也没有对应关系。原因：画图时按理想分层画，写目录时按实际代码抄，两边没有交叉检查。解决：以组件视图为基准，给每个可执行组件标注源码目录和部署节点；目录树只画到能定位模块的层级，不要把所有文件都列进去；架构图上的每个组件名在目录树里必须能找到同名包或同名模块，找不到就改图或改目录，不要让评审自己猜。

5.3 现象三：数据库设计只画 E-R 不写约束

现象：E-R 图里用户和角色是多对多，但表结构没有中间表，也没有唯一约束；状态字段只写“状态”，没写取值；导入 100000 条数据的性能要求没有索引设计支撑。原因：把数据库设计当成画图任务，忽略了完整性约束、存储要求和初始配置记录。解决：每张关键表补字段表，至少写字段名、类型、是否为空、默认值、约束、说明；静态数据表要写初始记录；存储过程要写依赖表和事务要求。E-R 图只表达关系，约束和索引必须落到文字或 DDL 示例里。

5.4 现象四：详细设计伪代码不可执行

现象：第 8 章方法描述写“查询用户并返回结果”，没有参数校验、没有异常分支、没有事务边界；伪代码里调用了一个方法，但方法清单里找不到被调用方。原因：把详细设计写成功能复述，没有按模板要求写 Prototype、Description、Calls、Called By、Input、Output、Return、Exception。解决：每个方法至少写清函数原型、输入输出、返回值、可能抛出的异常；伪代码要能看出分支和循环，不要用“处理数据”这种词；调用清单里的每个方法都要在类方法表里存在，否则就是悬空调用。

// 反例：只写“查询用户”，没有异常分支和事务边界 queryUser(userId): select * from demo_user where id = userId return user

这段反例的逻辑问题：没有判空，没有处理查不到记录的情况，没有说明数据库异常怎么返回，也没有写权限校验位置。参数问题：userId的类型、是否允许为空、非法值时返回什么，都没有定义。修改方向是补上参数校验、判空分支、异常转换和权限检查点，并把“查不到”和“数据库失败”区分成两个返回结果。

5.5 现象五：版本记录和密级标注混乱

现象：修订记录只写“修改若干章节”，CR 号为空；页脚密级写“内部公开”，封面密级却没勾选；页码显示“Total 21 pages 共 76 页”，打印稿和电子稿页数不一致。原因：文档模板的配置管理字段没有纳入交付检查，大家只关注正文内容。解决：修订记录每次修改必须写日期、版本、CR 号、修改章节、修改描述、作者；密级在封面、页眉页脚、文档属性三处保持一致；页码统计口径统一，目录、表目录、图目录在最终版重新生成。血泪经验是，评审专家不一定逐行看设计，但一定会翻修订记录和页脚，这两处乱，后面写再多也容易被判“配置管理不到位”。

6. 把软件设计说明书样例变成可复用资产：自检表、交叉验证和版本化技巧

6.1 用自检表压住交付质量

这份模板真正好用的地方，是它能被压成一张自检表。我一般会让写的人在提交前逐项打勾：简介里的目的、范围、名称、功能表、性能表是否齐全；需求描述里的上下文图、角色、主流程异常分支、约束依据是否写了；第一层架构图的每个组件是否在第 4 章有模块落点；第二层模块的类图是否标了继承、实现、依赖；数据库设计是否有字段表、约束、索引和初始数据；组件视图的 EXE/DLL 与源码目录是否同名；进程视图是否说明了线程模型和通信方式；详细设计的方法是否写了异常和调用清单；修订记录和密级是否三处一致。自检表不要写“是否完整”这种主观项，要写“第 3 章架构图组件名能否在第 6 章目录树找到同名包”这种可验证项。

6.2 用组件视图和进程视图做交叉验证

组件视图回答“系统由哪些可执行组件组成、部署在哪”，进程视图回答“运行时怎么分解成线程和进程、怎么通信”。这两章最容易各写各的。交叉验证的做法是：组件视图里每出现一个 EXE、DLL 或服务，进程视图里必须能找到对应的进程或线程组；部署图上的每个节点，性能表里要有对应的资源假设；进程视图里说“导入任务单独线程”，组件视图里就要有这个任务所属的组件，数据库设计里还要有分批提交的说明。对不上就说明运行设计没有落到组件上，评审时一問就露馅。

6.3 版本化与评审留痕的具体技巧

版本化不要只靠文件名。每次评审前，把修订记录、目录、表目录、图目录重新生成一遍，CR 号与变更单关联；图号用“图 3-1 系统上下文”这种带章节号的格式，正文引用时只写图号，不写“上图”“下图”；表号同理。评审意见不要贴在文档正文里，单独维护一张问题表，写清楚问题位置、修改人、关闭版本。这样下一版软件设计说明书样例复用时，能直接看出哪些问题是重复出现的。

从那以后我每次把这份软件设计说明书样例交给新人，都强制先跑一遍自检表和组件-进程交叉验证，再谈排版和美化。文档写得再漂亮，架构图、模块类图、数据库约束和详细设计对不上，评审时还是得返工。希望帮到你。

本文还有配套的精品资源，点击获取