第4章：需求文档编写——如何写出清晰、完整、一致的需求规格说明书（SRS）
说实话，我见过太多项目死在需求文档上。
有的写得像天书，开发看完一脸懵。有的漏洞百出，测试都不知道该测什么。还有的，嗯，干脆就没写。
我自己带团队那会儿，最怕听到一句话：「需求都在我脑子里，你们先做着。」结果呢？返工率高达60%。
所以这一章，咱们就聊聊怎么把需求文档写明白。说白了，就是一份能让所有人——产品、开发、测试、运营——都看懂且不吵架的文档。
4.1 需求规格说明书（SRS）到底是什么？
SRS，全称 Software Requirements Specification。它不是产品经理的「自嗨笔记」，而是整个项目的「宪法」。
我个人的习惯是：SRS 必须回答三个问题——系统要做什么？在什么条件下做？做到什么程度算好？
核心三要素：
- 清晰：每句话只有一个解释，没有歧义
- 完整：覆盖所有功能、性能、约束条件
- 一致：前后不矛盾，术语统一
你想想看，如果文档里写着「系统应快速响应用户请求」，那「快速」是多快？2秒还是200毫秒？这就是典型的模糊表述，必须避免。
4.2 SRS 的标准结构（附模板）
我这些年用过不少模板，最顺手的是基于 IEEE 830 标准改良的版本。下面这个模板，我几乎每个项目都会微调后使用。
| 章节 | 内容 | 常见坑点 |
|---|---|---|
| 1. 引言 | 目的、范围、定义、参考文献 | 范围写得太宽，什么都往里塞 |
| 2. 总体描述 | 产品视角、用户特征、约束条件 | 忽略非功能需求，比如并发量 |
| 3. 具体需求 | 功能需求、接口需求、性能需求 | 功能描述太抽象，无法测试 |
| 4. 验收标准 | 每个需求的通过条件 | 验收标准写成了「开发自测」 |
| 5. 附录 | 术语表、变更记录、待办事项 | 变更记录没人维护 |
小技巧：我习惯在引言里加一段「不做什么」。比如「本系统不涉及支付功能」。这能有效避免需求蔓延。
4.3 如何写出「清晰」的需求？
清晰，是SRS的第一生命线。怎么做到？我总结了三条铁律。
4.3.1 用「主语+谓语+宾语+条件+结果」句式
举个例子：
❌ 模糊版：「用户登录后可以看到订单。」
✅ 清晰版：「当已登录用户访问‘我的订单’页面时，系统应展示该用户最近30天内的所有订单，按时间倒序排列，每页显示20条。」
看到了吗？多了条件、范围、排序规则、分页数量。开发拿到这种需求，直接就能写代码。
4.3.2 量化一切可量化的指标
我在项目中遇到过最典型的案例：客户说「系统要快」。结果上线后，客户觉得慢，开发觉得已经很快了。为什么？因为没有量化。
正确的写法是：
- 页面加载时间 ≤ 1.5秒（在4G网络下）
- API响应时间 ≤ 200ms（P95）
- 并发用户数 ≥ 1000
4.3.3 使用「必须/应当/可以」等关键词
这是IEEE 830里的规范，我一直在用：
- 必须（shall）：强制要求，不实现就不能上线
- 应当（should）：建议实现，但可以协商
- 可以（may）：可选功能，锦上添花
注意：千万不要混用。我曾经见过一份文档里「必须」和「应当」混着写，结果开发把「应当」当「必须」做了，工期翻了一倍。
4.4 如何保证「完整性」？
完整性，说白了就是「别漏东西」。我有个笨办法，但很管用——需求检查清单。
每次写完SRS，我都会对照这个清单过一遍：
- 所有用户角色都覆盖了吗？（普通用户、管理员、访客）
- 所有状态都考虑了吗？（正常、异常、边界）
- 所有输入都有验证规则吗？（格式、长度、范围）
- 所有输出都有格式定义吗？（JSON结构、错误码）
- 所有非功能需求都列了吗？（性能、安全、可维护性）
嗯，这里要注意一点：完整性不等于「事无巨细」。比如「用户点击按钮后按钮变灰」这种UI细节，可以放到设计稿里，不需要写进SRS。
4.5 如何保证「一致性」？
一致性，是SRS里最容易出问题的地方。我见过最离谱的：文档前面说「用户ID是邮箱」，后面又说「用户ID是手机号」。
怎么避免？三个方法：
4.5.1 建立术语表
在附录里维护一个术语表，所有关键概念统一定义。比如：
| 术语 | 定义 |
| 用户 | 已注册并登录的账户 |
| 访客 | 未登录的浏览者 |
| 订单 | 用户提交并支付成功的交易记录 |
4.5.2 使用「唯一引用编号」
每个需求都给它一个编号，比如 REQ-FUNC-001。这样在文档里引用时，直接写编号，不会混淆。
4.5.3 做一次「交叉检查」
我习惯的做法是：把文档打印出来，用两种颜色的笔。一种颜色标功能需求，另一种标非功能需求。然后看它们之间有没有冲突。比如功能需求说「支持视频上传」，非功能需求说「单文件不超过10MB」，这就不一致——视频10MB能传几秒？
4.6 最佳实践总结
最后，分享几个我踩过坑之后总结出来的经验：
- 写完后找「局外人」评审：找一个不熟悉项目的人读一遍，如果他看不懂，那就是文档的问题。
- 版本控制要严格：每次修改都要更新版本号，并在变更记录里写明「改了啥、为什么改、谁改的」。
- 不要用「等等」这个词：比如「支持Excel、PDF等格式」。这个「等」字，就是未来的坑。
- 每个需求都要可测试：如果你写了一个需求，但想不出怎么测试它，那这个需求就不合格。
一句话总结：好的SRS，是让开发看完直接写代码，测试看完直接写用例，产品看完直接拍板——而且三方不吵架。
我曾经因为一份写得稀烂的SRS，导致项目延期两个月。从那以后，我花在写文档上的时间，从来不少于总工时的20%。你想想看，前期多花两天写清楚，后期省下两周改bug，这笔账怎么算都划算。
下一章，咱们聊聊功能定义——怎么把SRS里的需求，变成开发能直接落地的功能列表。