简介这是一份《XX系统概要设计说明书》通用模板面向软件架构师、系统分析师及开发团队用于在项目初期快速搭建规范的设计文档框架解决设计思路零散、文档结构不统一的问题。模板围绕引言、总体设计、接口设计、运行设计、系统数据结构设计等章节展开涵盖编写目的、背景、术语定义、需求规定、运行环境、模块结构、功能与程序关系、人工处理过程及尚未解决的问题等关键条目并给出用户接口、外部接口与内部接口的设计要点可直接替换项目名称后套用。资源包共1个doc文件约42KB体积轻便便于离线查阅与二次编辑。目前已有207人学习下载适合需要撰写概要设计说明书、梳理系统架构或进行课程设计、毕业设计的学生与工程师参考帮助快速理清设计脉络、对齐干系人认知为后续详细设计与实现提供清晰蓝图。1. 概要设计说明书模板为什么你写的文档总被架构评审打回写过概要设计说明书的人都遇到过这种场景功能都实现了代码也跑通了评审会上却被架构师一句“你的模块边界在哪”问得哑口无言。问题不在技术能力在于文档没有把“设计”讲清楚只把“实现”罗列了一遍。概要设计说明书要回答的核心问题是系统由哪些模块组成、模块之间怎么交互、数据怎么流转、关键接口怎么定义、非功能需求怎么落地。它介于需求规格说明书和详细设计说明书之间是承上启下的关键文档。一份合格的概要设计说明书能让没参与过需求讨论的开发者看懂系统全貌能让测试人员据此设计集成测试用例能让运维提前规划部署方案。本文围绕一份可直接套用的概要设计说明书模板拆解每个章节该写什么、写到什么颗粒度、哪些地方最容易翻车适合正在写或准备写概要设计的开发、测试和架构方向从业者。2. 概要设计说明书的标准骨架从需求到模块的映射逻辑2.1 一份模板该包含哪些章节概要设计说明书不是散文它是有固定骨架的工程文档。常见的做法是参照 GB/T 8567 的文档格式结合团队实际情况裁剪。我一般会保留以下核心章节章节核心内容常见页数引言编写目的、范围、术语定义、参考资料1-2 页总体设计系统架构图、模块划分、技术选型3-5 页模块设计每个模块的职责、接口、依赖关系5-10 页数据设计数据库表结构、数据流图、缓存策略3-5 页接口设计内部接口、外部接口、API 契约3-5 页非功能设计性能、安全、可用性、扩展性2-3 页部署设计部署拓扑、环境要求、配置说明2-3 页这个骨架的逻辑是先说清楚“为什么做”再说“做成什么样”然后说“怎么拆”最后说“怎么跑”。每一章都在回答上一章留下的问题。引言回答“这个文档是给谁看的”总体设计回答“系统长什么样”模块设计回答“每个部分干什么”数据设计回答“数据怎么存怎么流”接口设计回答“模块之间怎么说话”非功能设计回答“跑起来稳不稳”部署设计回答“怎么装到机器上”。注意不是每个项目都需要完整包含所有章节。内部工具类系统可以砍掉部署设计但模块设计和接口设计不能省。2.2 模块划分的粒度怎么定模块划分是概要设计里最考验功力的部分。拆得太粗详细设计阶段没法展开拆得太细概要设计就变成了详细设计。我的经验是一个模块应该对应一个可以独立开发、独立测试、独立部署的单元。如果两个模块必须同时修改才能完成一个需求那它们大概率应该合并。具体操作上可以按以下步骤来第一步从需求文档里提取所有功能点列成清单。比如“用户注册”“用户登录”“修改密码”“查看订单列表”“创建订单”“取消订单”等。第二步按业务领域聚类。把“用户注册”“用户登录”“修改密码”归到用户模块把“查看订单列表”“创建订单”“取消订单”归到订单模块。第三步检查聚类结果是否满足高内聚低耦合。如果用户模块需要直接查询订单表才能完成注册比如注册时送优惠券那说明模块边界有问题应该通过接口调用而不是直接查表。第四步为每个模块定义清晰的职责描述和对外接口。职责描述用一句话说清楚“这个模块负责什么”接口定义用表格列出方法名、入参、出参、异常。# 模块定义示例YAML 格式可直接嵌入文档 module: name: user-service responsibility: 负责用户注册、登录、信息管理、权限校验 interfaces: - name: register input: {username, password, email} output: {userId, token} errors: [USERNAME_EXISTS, INVALID_EMAIL] - name: login input: {username, password} output: {userId, token, expiresAt} errors: [USER_NOT_FOUND, WRONG_PASSWORD] dependencies: - notification-service (发送验证邮件) - redis (存储 session)这段 YAML 定义了一个用户模块的职责和接口。responsibility字段用一句话说清楚模块边界interfaces列出对外暴露的方法每个方法明确输入输出和可能的错误码dependencies列出依赖的其他模块或中间件。这样详细设计阶段拿到这个定义就知道该实现哪些方法、处理哪些异常、调用哪些外部服务。参数说明name用短横线分隔的小写字母和代码仓库名保持一致input和output用 JSON 风格的字段描述不需要写具体类型那是详细设计的事errors用大写下划线命名和代码里的错误码枚举对应。2.3 技术选型怎么写才不被挑战技术选型是评审会上最容易被打回的部分。很多文档只写“使用 MySQL 存储数据”但不写为什么不用 PostgreSQL、不用 MongoDB。架构师一问就露馅。正确的写法是每个选型都给出至少两个备选方案然后从业务需求、团队能力、运维成本三个维度对比。比如选 MySQL 而不是 MongoDB可以这样写维度MySQLMongoDB选择理由数据模型关系型强 Schema文档型弱 Schema订单数据关系复杂需要事务事务支持完整 ACID4.0 支持多文档事务支付场景必须强一致团队熟悉度高5 年经验低无生产经验降低维护风险运维成本成熟方案多需要额外学习现有监控体系直接复用这样写的好处是即使别人不同意你的选择也能看到你的思考过程。评审会上讨论的是“选择理由是否成立”而不是“你为什么选这个”。提示技术选型不要写“因为大家都用所以选它”也不要写“因为最新所以选它”。写清楚业务约束和团队现状比追新更重要。3. 模块设计与接口定义把“黑匣子”拆成可测试的单元3.1 模块内部结构怎么描述概要设计不要求写到类和方法级别但必须说清楚模块内部的分层结构。常见的分层是 Controller → Service → Repository 三层。在文档里可以用文字加简单示意图描述但不要贴代码。我一般会为每个模块写一段结构说明包含以下要素分层方式比如“采用 Controller-Service-Repository 三层架构”每层职责Controller 负责参数校验和路由Service 负责业务逻辑Repository 负责数据访问关键流程用文字描述一个典型请求的处理链路比如“用户登录请求先经过 Controller 校验参数格式再调用 Service 查询用户信息并比对密码最后通过 Repository 更新登录时间”异常处理策略哪些异常在 Controller 层捕获哪些抛到全局异常处理器这样写的好处是详细设计阶段开发者知道该把代码放在哪一层测试人员知道该 mock 哪些依赖。3.2 接口契约的四个必写字段接口定义是概要设计里最需要精确的部分。我见过太多文档只写“用户登录接口输入用户名密码返回 token”这种接口定义到了联调阶段必然扯皮。一个完整的接口定义至少包含四个字段{ name: POST /api/v1/auth/login, description: 用户登录验证凭证并返回访问令牌, request: { username: string, 必填, 4-20 字符, password: string, 必填, 8-32 字符, 至少包含字母和数字 }, response: { code: int, 0 表示成功非 0 表示错误, data: { userId: string, 用户唯一标识, token: string, JWT 格式访问令牌, expiresAt: string, ISO 8601 格式过期时间 }, message: string, 错误描述成功时为空 }, errors: { 1001: 用户名或密码错误, 1002: 账号被锁定, 1003: 密码错误次数超限 } }这段 JSON 定义了一个登录接口的完整契约。request里每个字段标注类型、是否必填、取值范围response里定义统一返回结构data里列出所有返回字段errors里列出所有可能的错误码和含义。参数说明name用 HTTP 方法加路径的格式路径里带版本号request里的约束条件要和前端校验规则一致errors里的错误码要全局唯一不能和别的接口冲突。注意接口定义里的字段类型用语言无关的描述string、int、boolean不要写 Java 的 String 或 Python 的 str因为接口可能被不同语言的客户端调用。3.3 数据流图怎么画才不翻车数据流图是概要设计里最容易画错的部分。常见错误有三种一是把数据流图画成了流程图加了判断和循环二是数据流图里出现了“用户”这种外部实体却没有标注三是数据存储没有编号后面引用时找不到。正确的数据流图应该只有四种元素外部实体方框、处理过程圆角矩形、数据存储开口矩形、数据流箭头。画的时候从顶层图开始然后逐层分解。顶层图只画系统和外部实体的交互不画内部处理。第二层图把系统拆成主要模块画模块之间的数据流。第三层图才画每个模块内部的数据流。在文档里可以用文字描述数据流比如“用户提交订单请求 → 订单服务校验商品库存 → 库存服务返回可用数量 → 订单服务生成订单记录 → 订单服务调用支付服务 → 支付服务返回支付结果 → 订单服务更新订单状态”。这种文字描述配合一张简单的数据流图比只贴图更容易检索。4. 非功能设计与部署方案性能、安全、扩展性怎么落到纸面4.1 性能指标怎么写才可验证非功能设计里最虚的是性能指标。写“系统响应快”没有意义写“支持高并发”也没法验证。可验证的性能指标必须包含四个要素指标名称、目标值、测量条件、测量方法。比如指标目标值测量条件测量方法登录接口响应时间P95 200ms100 并发用户持续 5 分钟JMeter 压测统计 P95订单创建吞吐量 500 TPS200 并发用户持续 10 分钟JMeter 压测统计 TPS数据库查询时间P99 50ms单表 100 万行索引命中慢查询日志分析系统可用性99.9%月度统计监控平台告警记录这样写的好处是测试人员知道怎么测运维知道怎么监控开发知道优化目标在哪。如果某个指标达不到评审会上可以直接讨论是降低目标还是增加资源。4.2 安全设计要覆盖哪些层面安全设计不是写“使用 HTTPS”就完了。概要设计阶段的安全设计至少覆盖四个层面传输安全HTTPS 版本、证书管理、加密套件认证授权认证方式JWT/Session、授权模型RBAC/ABAC、令牌有效期数据安全敏感字段加密存储、脱敏展示、备份加密审计日志操作日志记录范围、日志保留时间、日志访问权限每个层面写清楚具体方案和配置参数。比如 JWT 认证要写清楚签名算法HS256 还是 RS256、令牌有效期2 小时、刷新令牌有效期7 天、令牌存储位置HttpOnly Cookie 还是 LocalStorage。提示安全设计不要写“符合等保要求”这种空话要写具体做了什么、参数是多少。评审时被问到“你的令牌有效期为什么是 2 小时”要能回答“因为业务操作平均耗时 30 分钟2 小时覆盖了大部分会话场景同时限制了令牌泄露的风险窗口”。4.3 部署拓扑的三种常见模式部署设计要根据系统规模和团队运维能力来写。常见的三种模式单机部署所有模块部署在一台服务器上适合内部工具和早期项目。写清楚服务器配置CPU、内存、磁盘、操作系统版本、依赖的中间件版本。分层部署Web 层、应用层、数据层分开部署。Web 层用 Nginx 做负载均衡应用层部署多个实例数据层用主从复制。写清楚每层的实例数量、网络拓扑、健康检查方式。容器化部署用 Docker 打包镜像Kubernetes 编排。写清楚镜像仓库地址、Pod 副本数、资源限制CPU/内存 request 和 limit、服务发现方式、配置管理方案。不管哪种模式都要写清楚环境要求JDK 版本、Python 版本、Node 版本、数据库版本、中间件版本。这些版本号要和开发环境保持一致否则联调时会出现“在我机器上能跑”的经典问题。5. 避坑与排查概要设计评审中最常被怼的五个问题5.1 模块职责重叠两个模块都能改同一张表现象评审时架构师问“用户模块和权限模块都操作 user 表那到底谁负责 user 表的写入”文档里两个模块的职责描述都提到了“管理用户信息”。原因模块划分时没有遵循“数据所有权”原则。一张表只能由一个模块负责写入其他模块通过接口读取。解决在模块设计里明确每张表的“所有者模块”。user 表归用户模块所有权限模块需要用户信息时调用用户模块的接口不直接查表。在文档里加一张“数据所有权表”列出表名和所属模块。5.2 接口定义缺少错误码联调时全靠猜现象前端调用登录接口返回 500但文档里只写了成功返回什么没写失败返回什么。前端不知道是用户名错了还是密码错了只能找后端问。原因接口定义时只考虑了正常流程没有枚举异常场景。解决每个接口定义必须包含错误码列表。错误码分两类业务错误码如 1001 用户名不存在和系统错误码如 5000 数据库连接失败。业务错误码由接口自己定义系统错误码全局统一。在文档里用表格列出所有错误码、含义、触发条件。5.3 非功能指标没有测量方法验收时扯皮现象文档里写“系统支持 1000 并发”验收时测试人员用 1000 并发压测响应时间超过 5 秒。开发说“1000 并发是指在线用户数不是同时请求数”。原因性能指标没有定义清楚测量条件。解决每个性能指标必须写清楚“在什么条件下测”。比如“1000 并发用户”要说明是 1000 个用户同时在线还是 1000 个请求同时发出。我一般会写“1000 并发请求每个请求间隔 100ms持续 10 分钟统计 P95 响应时间”。5.4 技术选型只写结果不写理由评审时被反复挑战现象文档里写“使用 Redis 做缓存”评审时被问“为什么不用 Memcached”“缓存穿透怎么办”“缓存和数据库一致性怎么保证”一个都答不上来。原因技术选型只写了“用什么”没写“为什么用这个”和“怎么用”。解决每个选型写三段备选方案对比、选择理由、使用方案。使用方案里写清楚缓存 key 的设计、过期时间、更新策略、降级方案。比如“Redis 缓存用户信息key 格式 user:{userId}过期时间 30 分钟更新时先更新数据库再删除缓存缓存不可用时直接查数据库”。5.5 部署设计忽略环境差异上线时才发现缺依赖现象开发环境用 Python 3.9生产环境用 Python 3.8上线时发现某个库不兼容。或者开发环境用 MySQL 8.0生产环境用 MySQL 5.7SQL 语法报错。原因部署设计没有明确环境要求或者写了但没有和运维确认。解决部署设计里加一张“环境要求表”列出每个组件的版本号并注明“开发、测试、生产环境必须保持一致”。如果生产环境版本较低要在文档里写清楚兼容性处理方案比如“MySQL 5.7 不支持窗口函数订单统计改用子查询实现”。6. 让模板真正可复用从文档到评审通过的两个技巧6.1 用检查清单代替反复评审概要设计说明书最怕的是“写完了才发现漏了东西”。我习惯在文档最后附一张检查清单写完后逐项打勾。清单包含以下条目每个模块的职责是否用一句话说清楚每个接口是否定义了输入、输出、错误码每张数据库表是否指定了所有者模块每个性能指标是否包含测量条件每个技术选型是否写了备选方案和选择理由部署设计是否列出了所有组件的版本号非功能设计是否覆盖了性能、安全、可用性、扩展性这张清单可以直接复制到文档末尾评审前自己先过一遍。我统计过加上这张清单后评审会上被问住的次数减少了七成以上。6.2 用版本记录代替“最终版”很多文档的文件名是“概要设计说明书_最终版_v3_真的最终版.doc”这种命名方式本身就是灾难。正确的做法是在文档开头加一个版本记录表版本日期修改人修改内容v1.02025-01-10张三初稿完成总体设计和模块设计v1.12025-01-12李四补充接口错误码修正数据流图v1.22025-01-15张三根据评审意见调整模块边界这样任何人拿到文档都知道改了什么、为什么改。评审时也不用争论“这个接口上次不是这样定义的”直接看版本记录。提示版本记录里的“修改内容”要写具体不要写“优化文档结构”这种空话。写“把用户模块的权限校验移到权限模块”比写“调整模块划分”有用得多。6.3 一个可以直接套用的文档头模板最后给一个文档头的模板复制到 Word 或 Markdown 文件开头即可# XX系统概要设计说明书 | 项目 | 内容 | |------|------| | 系统名称 | XX系统 | | 文档版本 | v1.0 | | 编写日期 | 2025-01-15 | | 编写人 | 张三 | | 评审人 | 李四、王五 | | 评审日期 | 2025-01-18 | | 文档状态 | 已评审通过 | ## 版本记录 | 版本 | 日期 | 修改人 | 修改内容 | |------|------|--------|---------| | v1.0 | 2025-01-15 | 张三 | 初稿 | ## 1. 引言 ### 1.1 编写目的 ### 1.2 范围 ### 1.3 术语定义 ### 1.4 参考资料 ## 2. 总体设计 ### 2.1 系统架构 ### 2.2 模块划分 ### 2.3 技术选型 ## 3. 模块设计 ### 3.1 模块A ### 3.2 模块B ## 4. 数据设计 ### 4.1 数据库表结构 ### 4.2 数据流图 ## 5. 接口设计 ### 5.1 内部接口 ### 5.2 外部接口 ## 6. 非功能设计 ### 6.1 性能 ### 6.2 安全 ### 6.3 可用性 ## 7. 部署设计 ### 7.1 部署拓扑 ### 7.2 环境要求这个模板可以直接用也可以根据项目规模裁剪。我一般会把“模块设计”和“接口设计”写厚其他章节写薄。因为这两章是详细设计的输入写不清楚后面没法干活。写概要设计说明书这件事我踩过的最大坑是“把文档当任务而不是当工具”。文档写完就扔到一边开发时该怎么做还怎么做那这份文档就白写了。后来我养成了一个习惯写文档的时候打开代码编辑器每写一个模块定义就对照代码里的包结构每写一个接口定义就对照代码里的 Controller 方法。文档和代码对不上的地方要么改文档要么改代码绝不允许“文档是文档代码是代码”。这个习惯让我在后面的项目里少了很多联调时的扯皮也让新加入的同事能更快上手。希望帮到你。本文还有配套的精品资源点击获取 概要设计说明书模板：模块划分、接口定义与评审避坑指南
简介这是一份《XX系统概要设计说明书》通用模板面向软件架构师、系统分析师及开发团队用于在项目初期快速搭建规范的设计文档框架解决设计思路零散、文档结构不统一的问题。模板围绕引言、总体设计、接口设计、运行设计、系统数据结构设计等章节展开涵盖编写目的、背景、术语定义、需求规定、运行环境、模块结构、功能与程序关系、人工处理过程及尚未解决的问题等关键条目并给出用户接口、外部接口与内部接口的设计要点可直接替换项目名称后套用。资源包共1个doc文件约42KB体积轻便便于离线查阅与二次编辑。目前已有207人学习下载适合需要撰写概要设计说明书、梳理系统架构或进行课程设计、毕业设计的学生与工程师参考帮助快速理清设计脉络、对齐干系人认知为后续详细设计与实现提供清晰蓝图。1. 概要设计说明书模板为什么你写的文档总被架构评审打回写过概要设计说明书的人都遇到过这种场景功能都实现了代码也跑通了评审会上却被架构师一句“你的模块边界在哪”问得哑口无言。问题不在技术能力在于文档没有把“设计”讲清楚只把“实现”罗列了一遍。概要设计说明书要回答的核心问题是系统由哪些模块组成、模块之间怎么交互、数据怎么流转、关键接口怎么定义、非功能需求怎么落地。它介于需求规格说明书和详细设计说明书之间是承上启下的关键文档。一份合格的概要设计说明书能让没参与过需求讨论的开发者看懂系统全貌能让测试人员据此设计集成测试用例能让运维提前规划部署方案。本文围绕一份可直接套用的概要设计说明书模板拆解每个章节该写什么、写到什么颗粒度、哪些地方最容易翻车适合正在写或准备写概要设计的开发、测试和架构方向从业者。2. 概要设计说明书的标准骨架从需求到模块的映射逻辑2.1 一份模板该包含哪些章节概要设计说明书不是散文它是有固定骨架的工程文档。常见的做法是参照 GB/T 8567 的文档格式结合团队实际情况裁剪。我一般会保留以下核心章节章节核心内容常见页数引言编写目的、范围、术语定义、参考资料1-2 页总体设计系统架构图、模块划分、技术选型3-5 页模块设计每个模块的职责、接口、依赖关系5-10 页数据设计数据库表结构、数据流图、缓存策略3-5 页接口设计内部接口、外部接口、API 契约3-5 页非功能设计性能、安全、可用性、扩展性2-3 页部署设计部署拓扑、环境要求、配置说明2-3 页这个骨架的逻辑是先说清楚“为什么做”再说“做成什么样”然后说“怎么拆”最后说“怎么跑”。每一章都在回答上一章留下的问题。引言回答“这个文档是给谁看的”总体设计回答“系统长什么样”模块设计回答“每个部分干什么”数据设计回答“数据怎么存怎么流”接口设计回答“模块之间怎么说话”非功能设计回答“跑起来稳不稳”部署设计回答“怎么装到机器上”。注意不是每个项目都需要完整包含所有章节。内部工具类系统可以砍掉部署设计但模块设计和接口设计不能省。2.2 模块划分的粒度怎么定模块划分是概要设计里最考验功力的部分。拆得太粗详细设计阶段没法展开拆得太细概要设计就变成了详细设计。我的经验是一个模块应该对应一个可以独立开发、独立测试、独立部署的单元。如果两个模块必须同时修改才能完成一个需求那它们大概率应该合并。具体操作上可以按以下步骤来第一步从需求文档里提取所有功能点列成清单。比如“用户注册”“用户登录”“修改密码”“查看订单列表”“创建订单”“取消订单”等。第二步按业务领域聚类。把“用户注册”“用户登录”“修改密码”归到用户模块把“查看订单列表”“创建订单”“取消订单”归到订单模块。第三步检查聚类结果是否满足高内聚低耦合。如果用户模块需要直接查询订单表才能完成注册比如注册时送优惠券那说明模块边界有问题应该通过接口调用而不是直接查表。第四步为每个模块定义清晰的职责描述和对外接口。职责描述用一句话说清楚“这个模块负责什么”接口定义用表格列出方法名、入参、出参、异常。# 模块定义示例YAML 格式可直接嵌入文档 module: name: user-service responsibility: 负责用户注册、登录、信息管理、权限校验 interfaces: - name: register input: {username, password, email} output: {userId, token} errors: [USERNAME_EXISTS, INVALID_EMAIL] - name: login input: {username, password} output: {userId, token, expiresAt} errors: [USER_NOT_FOUND, WRONG_PASSWORD] dependencies: - notification-service (发送验证邮件) - redis (存储 session)这段 YAML 定义了一个用户模块的职责和接口。responsibility字段用一句话说清楚模块边界interfaces列出对外暴露的方法每个方法明确输入输出和可能的错误码dependencies列出依赖的其他模块或中间件。这样详细设计阶段拿到这个定义就知道该实现哪些方法、处理哪些异常、调用哪些外部服务。参数说明name用短横线分隔的小写字母和代码仓库名保持一致input和output用 JSON 风格的字段描述不需要写具体类型那是详细设计的事errors用大写下划线命名和代码里的错误码枚举对应。2.3 技术选型怎么写才不被挑战技术选型是评审会上最容易被打回的部分。很多文档只写“使用 MySQL 存储数据”但不写为什么不用 PostgreSQL、不用 MongoDB。架构师一问就露馅。正确的写法是每个选型都给出至少两个备选方案然后从业务需求、团队能力、运维成本三个维度对比。比如选 MySQL 而不是 MongoDB可以这样写维度MySQLMongoDB选择理由数据模型关系型强 Schema文档型弱 Schema订单数据关系复杂需要事务事务支持完整 ACID4.0 支持多文档事务支付场景必须强一致团队熟悉度高5 年经验低无生产经验降低维护风险运维成本成熟方案多需要额外学习现有监控体系直接复用这样写的好处是即使别人不同意你的选择也能看到你的思考过程。评审会上讨论的是“选择理由是否成立”而不是“你为什么选这个”。提示技术选型不要写“因为大家都用所以选它”也不要写“因为最新所以选它”。写清楚业务约束和团队现状比追新更重要。3. 模块设计与接口定义把“黑匣子”拆成可测试的单元3.1 模块内部结构怎么描述概要设计不要求写到类和方法级别但必须说清楚模块内部的分层结构。常见的分层是 Controller → Service → Repository 三层。在文档里可以用文字加简单示意图描述但不要贴代码。我一般会为每个模块写一段结构说明包含以下要素分层方式比如“采用 Controller-Service-Repository 三层架构”每层职责Controller 负责参数校验和路由Service 负责业务逻辑Repository 负责数据访问关键流程用文字描述一个典型请求的处理链路比如“用户登录请求先经过 Controller 校验参数格式再调用 Service 查询用户信息并比对密码最后通过 Repository 更新登录时间”异常处理策略哪些异常在 Controller 层捕获哪些抛到全局异常处理器这样写的好处是详细设计阶段开发者知道该把代码放在哪一层测试人员知道该 mock 哪些依赖。3.2 接口契约的四个必写字段接口定义是概要设计里最需要精确的部分。我见过太多文档只写“用户登录接口输入用户名密码返回 token”这种接口定义到了联调阶段必然扯皮。一个完整的接口定义至少包含四个字段{ name: POST /api/v1/auth/login, description: 用户登录验证凭证并返回访问令牌, request: { username: string, 必填, 4-20 字符, password: string, 必填, 8-32 字符, 至少包含字母和数字 }, response: { code: int, 0 表示成功非 0 表示错误, data: { userId: string, 用户唯一标识, token: string, JWT 格式访问令牌, expiresAt: string, ISO 8601 格式过期时间 }, message: string, 错误描述成功时为空 }, errors: { 1001: 用户名或密码错误, 1002: 账号被锁定, 1003: 密码错误次数超限 } }这段 JSON 定义了一个登录接口的完整契约。request里每个字段标注类型、是否必填、取值范围response里定义统一返回结构data里列出所有返回字段errors里列出所有可能的错误码和含义。参数说明name用 HTTP 方法加路径的格式路径里带版本号request里的约束条件要和前端校验规则一致errors里的错误码要全局唯一不能和别的接口冲突。注意接口定义里的字段类型用语言无关的描述string、int、boolean不要写 Java 的 String 或 Python 的 str因为接口可能被不同语言的客户端调用。3.3 数据流图怎么画才不翻车数据流图是概要设计里最容易画错的部分。常见错误有三种一是把数据流图画成了流程图加了判断和循环二是数据流图里出现了“用户”这种外部实体却没有标注三是数据存储没有编号后面引用时找不到。正确的数据流图应该只有四种元素外部实体方框、处理过程圆角矩形、数据存储开口矩形、数据流箭头。画的时候从顶层图开始然后逐层分解。顶层图只画系统和外部实体的交互不画内部处理。第二层图把系统拆成主要模块画模块之间的数据流。第三层图才画每个模块内部的数据流。在文档里可以用文字描述数据流比如“用户提交订单请求 → 订单服务校验商品库存 → 库存服务返回可用数量 → 订单服务生成订单记录 → 订单服务调用支付服务 → 支付服务返回支付结果 → 订单服务更新订单状态”。这种文字描述配合一张简单的数据流图比只贴图更容易检索。4. 非功能设计与部署方案性能、安全、扩展性怎么落到纸面4.1 性能指标怎么写才可验证非功能设计里最虚的是性能指标。写“系统响应快”没有意义写“支持高并发”也没法验证。可验证的性能指标必须包含四个要素指标名称、目标值、测量条件、测量方法。比如指标目标值测量条件测量方法登录接口响应时间P95 200ms100 并发用户持续 5 分钟JMeter 压测统计 P95订单创建吞吐量 500 TPS200 并发用户持续 10 分钟JMeter 压测统计 TPS数据库查询时间P99 50ms单表 100 万行索引命中慢查询日志分析系统可用性99.9%月度统计监控平台告警记录这样写的好处是测试人员知道怎么测运维知道怎么监控开发知道优化目标在哪。如果某个指标达不到评审会上可以直接讨论是降低目标还是增加资源。4.2 安全设计要覆盖哪些层面安全设计不是写“使用 HTTPS”就完了。概要设计阶段的安全设计至少覆盖四个层面传输安全HTTPS 版本、证书管理、加密套件认证授权认证方式JWT/Session、授权模型RBAC/ABAC、令牌有效期数据安全敏感字段加密存储、脱敏展示、备份加密审计日志操作日志记录范围、日志保留时间、日志访问权限每个层面写清楚具体方案和配置参数。比如 JWT 认证要写清楚签名算法HS256 还是 RS256、令牌有效期2 小时、刷新令牌有效期7 天、令牌存储位置HttpOnly Cookie 还是 LocalStorage。提示安全设计不要写“符合等保要求”这种空话要写具体做了什么、参数是多少。评审时被问到“你的令牌有效期为什么是 2 小时”要能回答“因为业务操作平均耗时 30 分钟2 小时覆盖了大部分会话场景同时限制了令牌泄露的风险窗口”。4.3 部署拓扑的三种常见模式部署设计要根据系统规模和团队运维能力来写。常见的三种模式单机部署所有模块部署在一台服务器上适合内部工具和早期项目。写清楚服务器配置CPU、内存、磁盘、操作系统版本、依赖的中间件版本。分层部署Web 层、应用层、数据层分开部署。Web 层用 Nginx 做负载均衡应用层部署多个实例数据层用主从复制。写清楚每层的实例数量、网络拓扑、健康检查方式。容器化部署用 Docker 打包镜像Kubernetes 编排。写清楚镜像仓库地址、Pod 副本数、资源限制CPU/内存 request 和 limit、服务发现方式、配置管理方案。不管哪种模式都要写清楚环境要求JDK 版本、Python 版本、Node 版本、数据库版本、中间件版本。这些版本号要和开发环境保持一致否则联调时会出现“在我机器上能跑”的经典问题。5. 避坑与排查概要设计评审中最常被怼的五个问题5.1 模块职责重叠两个模块都能改同一张表现象评审时架构师问“用户模块和权限模块都操作 user 表那到底谁负责 user 表的写入”文档里两个模块的职责描述都提到了“管理用户信息”。原因模块划分时没有遵循“数据所有权”原则。一张表只能由一个模块负责写入其他模块通过接口读取。解决在模块设计里明确每张表的“所有者模块”。user 表归用户模块所有权限模块需要用户信息时调用用户模块的接口不直接查表。在文档里加一张“数据所有权表”列出表名和所属模块。5.2 接口定义缺少错误码联调时全靠猜现象前端调用登录接口返回 500但文档里只写了成功返回什么没写失败返回什么。前端不知道是用户名错了还是密码错了只能找后端问。原因接口定义时只考虑了正常流程没有枚举异常场景。解决每个接口定义必须包含错误码列表。错误码分两类业务错误码如 1001 用户名不存在和系统错误码如 5000 数据库连接失败。业务错误码由接口自己定义系统错误码全局统一。在文档里用表格列出所有错误码、含义、触发条件。5.3 非功能指标没有测量方法验收时扯皮现象文档里写“系统支持 1000 并发”验收时测试人员用 1000 并发压测响应时间超过 5 秒。开发说“1000 并发是指在线用户数不是同时请求数”。原因性能指标没有定义清楚测量条件。解决每个性能指标必须写清楚“在什么条件下测”。比如“1000 并发用户”要说明是 1000 个用户同时在线还是 1000 个请求同时发出。我一般会写“1000 并发请求每个请求间隔 100ms持续 10 分钟统计 P95 响应时间”。5.4 技术选型只写结果不写理由评审时被反复挑战现象文档里写“使用 Redis 做缓存”评审时被问“为什么不用 Memcached”“缓存穿透怎么办”“缓存和数据库一致性怎么保证”一个都答不上来。原因技术选型只写了“用什么”没写“为什么用这个”和“怎么用”。解决每个选型写三段备选方案对比、选择理由、使用方案。使用方案里写清楚缓存 key 的设计、过期时间、更新策略、降级方案。比如“Redis 缓存用户信息key 格式 user:{userId}过期时间 30 分钟更新时先更新数据库再删除缓存缓存不可用时直接查数据库”。5.5 部署设计忽略环境差异上线时才发现缺依赖现象开发环境用 Python 3.9生产环境用 Python 3.8上线时发现某个库不兼容。或者开发环境用 MySQL 8.0生产环境用 MySQL 5.7SQL 语法报错。原因部署设计没有明确环境要求或者写了但没有和运维确认。解决部署设计里加一张“环境要求表”列出每个组件的版本号并注明“开发、测试、生产环境必须保持一致”。如果生产环境版本较低要在文档里写清楚兼容性处理方案比如“MySQL 5.7 不支持窗口函数订单统计改用子查询实现”。6. 让模板真正可复用从文档到评审通过的两个技巧6.1 用检查清单代替反复评审概要设计说明书最怕的是“写完了才发现漏了东西”。我习惯在文档最后附一张检查清单写完后逐项打勾。清单包含以下条目每个模块的职责是否用一句话说清楚每个接口是否定义了输入、输出、错误码每张数据库表是否指定了所有者模块每个性能指标是否包含测量条件每个技术选型是否写了备选方案和选择理由部署设计是否列出了所有组件的版本号非功能设计是否覆盖了性能、安全、可用性、扩展性这张清单可以直接复制到文档末尾评审前自己先过一遍。我统计过加上这张清单后评审会上被问住的次数减少了七成以上。6.2 用版本记录代替“最终版”很多文档的文件名是“概要设计说明书_最终版_v3_真的最终版.doc”这种命名方式本身就是灾难。正确的做法是在文档开头加一个版本记录表版本日期修改人修改内容v1.02025-01-10张三初稿完成总体设计和模块设计v1.12025-01-12李四补充接口错误码修正数据流图v1.22025-01-15张三根据评审意见调整模块边界这样任何人拿到文档都知道改了什么、为什么改。评审时也不用争论“这个接口上次不是这样定义的”直接看版本记录。提示版本记录里的“修改内容”要写具体不要写“优化文档结构”这种空话。写“把用户模块的权限校验移到权限模块”比写“调整模块划分”有用得多。6.3 一个可以直接套用的文档头模板最后给一个文档头的模板复制到 Word 或 Markdown 文件开头即可# XX系统概要设计说明书 | 项目 | 内容 | |------|------| | 系统名称 | XX系统 | | 文档版本 | v1.0 | | 编写日期 | 2025-01-15 | | 编写人 | 张三 | | 评审人 | 李四、王五 | | 评审日期 | 2025-01-18 | | 文档状态 | 已评审通过 | ## 版本记录 | 版本 | 日期 | 修改人 | 修改内容 | |------|------|--------|---------| | v1.0 | 2025-01-15 | 张三 | 初稿 | ## 1. 引言 ### 1.1 编写目的 ### 1.2 范围 ### 1.3 术语定义 ### 1.4 参考资料 ## 2. 总体设计 ### 2.1 系统架构 ### 2.2 模块划分 ### 2.3 技术选型 ## 3. 模块设计 ### 3.1 模块A ### 3.2 模块B ## 4. 数据设计 ### 4.1 数据库表结构 ### 4.2 数据流图 ## 5. 接口设计 ### 5.1 内部接口 ### 5.2 外部接口 ## 6. 非功能设计 ### 6.1 性能 ### 6.2 安全 ### 6.3 可用性 ## 7. 部署设计 ### 7.1 部署拓扑 ### 7.2 环境要求这个模板可以直接用也可以根据项目规模裁剪。我一般会把“模块设计”和“接口设计”写厚其他章节写薄。因为这两章是详细设计的输入写不清楚后面没法干活。写概要设计说明书这件事我踩过的最大坑是“把文档当任务而不是当工具”。文档写完就扔到一边开发时该怎么做还怎么做那这份文档就白写了。后来我养成了一个习惯写文档的时候打开代码编辑器每写一个模块定义就对照代码里的包结构每写一个接口定义就对照代码里的 Controller 方法。文档和代码对不上的地方要么改文档要么改代码绝不允许“文档是文档代码是代码”。这个习惯让我在后面的项目里少了很多联调时的扯皮也让新加入的同事能更快上手。希望帮到你。本文还有配套的精品资源点击获取