Spring Boot 项目全流程文档体系梳理：从需求调研到运维交付
前言
做了几年后端开发，经常遇到一个问题：项目做完之后，资料散落在各个地方——需求文档在飞书，设计图在语雀，接口文档在 Swagger，测试记录在禅道……等到项目复盘或者交接的时候，才发现很多”应该有”的文档根本没人写，或者写了但不知道该归到哪一类。
更麻烦的是边界模糊：同一张时序图，A 觉得该放需求、B 觉得该放设计；同一条”验证码 5 分钟有效”的规则，有人写进 PRD、有人写进接口文档、有人干脆只留在代码注释里。结果就是——想找的时候找不到，找到的又互相矛盾。
这篇文章梳理一套完整的项目资料库目录结构，覆盖从立项到运维的全生命周期，并重点讲清楚几个最容易混淆的边界问题：
- 概要设计和详细设计到底怎么分
- 时序图应该放在需求阶段还是设计阶段
- PRD 和需求规格说明书（SRS）的本质区别
- 接口设计和接口文档是不是一回事
- 业务流程图的”第一落脚点”在哪
本文聚焦文档体系与归属边界。如果你想要的是”每个流程节点该做什么、该产出什么、有哪些坑”的项目管理视角，可以看同系列的《项目开发全流程手册：8 个节点，每个节点的产出物与避坑清单》，两篇配合看更完整。
为什么要有一套文档体系
一句话：让每一份文档都有明确的读者和明确的用途。
很多团队不是不写文档，而是写得”没有章法”——一份文档里既有业务背景、又有接口字段、还夹着几段临时讨论，谁都能往里塞，结果谁都看不下去。好的文档体系解决三个问题：
- 可定位：想找某个信息，能凭直觉判断它在哪一份文档里。
- 不重复：同一条信息只在一个地方是”权威源”，其他地方引用它，避免多处维护、互相矛盾。
- 可交接：新人或接手方，顺着目录就能理解项目全貌，不依赖”问老人”。
全流程概览
flowchart LR
A[00 变更管理] -.贯穿全程.-> B
B[01 立项] --> C[02 需求]
C --> D[03 设计]
D --> E[04 开发]
E --> F[05 测试]
F --> G[06 验收]
G --> H[07 上线]
H --> I[08 运维]
style A fill:#f9f0ff,stroke:#9254de
style C fill:#e6f7ff,stroke:#1890ff
style D fill:#fff7e6,stroke:#fa8c16
完整目录结构
1 | |
每份核心文档：谁写、谁读、写什么
目录结构解决”放哪”，这张表解决”每份文档到底该写什么、写给谁看”。抓住”读者是谁”，就不容易越界。
| 文档 | 谁写 | 谁读 | 核心内容（最小要点） |
|---|---|---|---|
| 项目立项书 | 项目经理 | 决策方 | 目标、范围（含”不做什么”）、预算、周期 |
| 调研报告 | 产品经理 | 产品、业务方 | 现状痛点、现状业务流程图、机会点 |
| PRD | 产品经理 | 业务、开发、测试、UI | 业务价值、用户故事、未来业务流程图、原型、功能点 |
| SRS | 产品/开发 | 开发、测试、架构师 | 精确业务规则、边界条件、非功能性指标 |
| 概要设计 | 架构师 | 开发、运维 | 架构图、技术选型、模块边界、部署拓扑 |
| 详细设计 | 架构师/开发 | 开发、测试 | 表结构+DDL、接口契约、细粒度时序图、安全方案 |
| 开发计划 | 开发负责人/项目经理 | 开发、测试 | 任务拆解（WBS）、迭代排期、任务与人的对应；区别于立项的项目计划书（初版）和贯穿全程的进度跟踪 |
| 接口文档 | 开发 | 前端、联调方 | 当前真实可调用的 API（最好由代码生成） |
| 测试用例 | 测试 | 测试、开发 | 覆盖功能/边界/异常/性能的可执行用例 |
| 发布方案 | 运维/发布负责人 | 全体 | 发布步骤、窗口、回滚预案 |
| 运维手册 | 运维 | 运维、值班 | 部署结构、常见故障处置、监控告警说明 |
几个容易踩坑的边界问题
1. 概要设计 vs 详细设计，怎么分？
一句话：概要设计回答”分几块、怎么连”，详细设计回答”每块里面具体怎么写”。
| 内容 | 归属 | 原因 |
|---|---|---|
| 系统架构图 | 概要设计 | 宏观视角，回答模块怎么拆 |
| 部署拓扑 | 概要设计 | 网络/环境规划，不涉及代码 |
| 技术选型说明 | 概要设计 | 定框架/中间件，属方向决策 |
| 数据库表结构 | 详细设计 | 细到字段、索引，可直接建表 |
| 接口的具体字段定义 | 详细设计 | 细到入参出参、状态码 |
对于中小型项目，两者完全可以合并成一份文档；但如果项目复杂、需要多人协作或后期交接，拆开更有利于架构师把关方向、开发人员分头落地。
判断口诀：如果这段内容改动会影响”整个系统怎么搭”，它是概要；如果只影响”某一块怎么实现”，它是详细。
2. 时序图应该放在需求阶段吗？
不需要。时序图本质上是一种技术设计工具，前提是已经知道系统内部有哪些模块/服务——这个前提在需求阶段通常还不成立。
需求阶段真正需要的是：
- 业务流程图：描述业务本身怎么流转，纯粹是用户视角，不涉及任何系统内部实现
- 泳道图：涉及多角色协作时使用（比如客服审核、财务打款）
- 状态流转图：涉及状态机时使用（比如订单状态）
时序图本身也要按颗粒度拆到两处：
flowchart TD
T[时序图] --> T1["粗粒度<br/>(模块/服务级别)"]
T --> T2["细粒度<br/>(方法/参数级别，含异常分支)"]
T1 --> D1[放入概要设计]
T2 --> D2[放入详细设计]
判断标准：画的是”谁调用谁”（系统/模块级别）→ 概要设计；画的是”怎么调用、传什么参、错了怎么办”（方法/代码级别）→ 详细设计。
3. PRD 与需求规格说明书（SRS），本质区别是什么？
以”手机号验证码登录”功能为例：
PRD 里会这样写：
为了提升用户体验，支持用户通过手机号+验证码快速登录，降低登录门槛。用户打开App，输入手机号，获取验证码，输入后完成登录，跳转首页。
讲清楚了”为什么做”和”用户怎么用”，但没告诉你验证码有效期多长、并发登录怎么处理。
SRS 里会这样写：
- 验证码有效期：5分钟
- 同一手机号，60秒内只能发送1次
- 同一手机号，24小时内最多发送10次
- 连续错误5次后，锁定该手机号15分钟
- 单接口 QPS ≥ 500，平均响应时间 ≤ 300ms
每一条都可以直接写成代码的 if-else 分支，也可以直接写成测试用例。
注意：SRS 不应该包含具体的接口 URL、字段定义、错误码——这些属于详细设计的接口设计范畴。SRS 只描述”需要什么能力、有什么业务规则限制”，不描述”接口具体长什么样”。这个边界很容易混淆，也是团队里最常见的越界现象之一。
对比表格：
| 维度 | PRD | SRS |
|---|---|---|
| 面向对象 | 产品、业务方、UI设计师 | 开发、测试、架构师 |
| 关注点 | 用户是谁、业务价值 | 系统怎么响应、边界条件 |
| 能否直接指导编码 | 不能 | 能 |
| 非功能性需求 | 很少涉及 | 必须明确写出 |
| 验收标准 | 模糊（”体验流畅”） | 明确（”响应时间≤200ms”） |
4. 接口设计 vs 接口文档，是一回事吗？
不是。这俩长得像，但产生时间和用途不同，也是很容易混的一处。
- 接口设计（在详细设计里）：开发之前产出的契约，用来约定前后端/服务间”要提供哪些接口、入参出参长什么样、错误码怎么定”。它是给大家约定用的，一旦评审通过就应冻结，改动走变更。
- 接口文档（在开发产出物里）：开发之后、随代码演进的说明，描述”当前真实可调用”的接口，最好由 Swagger/OpenAPI 从代码生成，保证前端拿到的永远是最新版本。
一句话：接口设计是”我们约定要做成这样”，接口文档是”现在实际就是这样”。 前者防止各写各的，后者防止文档过期。小团队可以让接口文档”长成”接口设计的延续，但要清楚这两个阶段的职责不同。
5. 业务流程图放在哪个文档？
第一落脚点是 PRD。产品经理画流程图的过程，本身就是梳理需求逻辑的过程，画完才能写清楚后面的功能点。
产出顺序是：
1 | |
需要区分两种流程图：调研报告里的是”现状痛点分析”（现在人工怎么做的），PRD 里的是”新方案设计”（未来系统怎么走），两者容易混淆，但本质不同。
文档归属速查表
| 判断问题 | 归属 |
|---|---|
| 讲”业务现状怎么做” | 调研报告 |
| 讲”未来功能怎么用” + 流程图 | PRD |
| 讲”每条业务规则的精确定义”（不含接口） | SRS |
| 讲”系统怎么拆、模块怎么分” | 概要设计 |
| 讲”每个模块具体怎么实现”（含接口/表结构） | 详细设计 |
| 时序图画到”模块级别” | 概要设计 |
| 时序图画到”方法/参数级别” | 详细设计 |
| “约定要提供哪些接口”（开发前的契约） | 接口设计（详细设计） |
| “当前实际可调用的接口”（开发后的说明） | 接口文档（开发产出） |
中小团队怎么裁剪
这套目录看起来节点多，但不必生搬硬套。按团队和项目规模，可以这样合并：
| 场景 | 建议裁剪 |
|---|---|
| 小型内部项目 | PRD 与 SRS 合成一份；概要与详细设计合成一份 |
| 快速迭代的 Web 项目 | 接口设计直接用 Swagger 注解维护，不单独出文档 |
| 一次性交付项目 | 简化运维手册，但保留部署手册和回滚预案 |
但下面这几项，无论项目大小都别省，因为它们涉及责任边界或止损底线：
- 需求变更单——出现争议时唯一有效的凭证
- 客户签收单——项目”完成”的法律与结算依据
- 发布方案里的回滚预案——上线出事时唯一的退路
写在最后
这套目录结构和边界划分，本质上是在解决一个问题：让每一份文档都有明确的读者和明确的用途，避免”什么都往一份文档里塞”或者”重要信息散落在没人知道的地方”。
文档体系是”骨架”，配合流程节点上的产出与门禁才能真正跑起来——后者可以参考同系列的《项目开发全流程手册》，而贯穿全程的计划与进度怎么管，见《项目计划与进度管理》。三者结合：流程告诉你每一步该做什么，文档体系告诉你产出该放哪、给谁看，计划与进度告诉你怎么排期和盯进度。
本文梳理内容来自项目实践中的持续讨论和总结，欢迎交流指正。