输入与输出

输入：

1. 脑图+功能清单
2. 产品原型图
3. 《需求规格说明书》或《产品需求文档》（PRD）
4. 《XXX项目设计分工》干特图
5. 《概要设计文档》

过程活动：针对某个复杂模块做详细设计

参与者：项目经理、团队主力

输出：《详细设计文档》

干货

1. 我们根据项目情况决定是否做详细设计，单纯的CRUD（增删改查）业务不用做详细设计。
2. 《敏捷宣言》有4点敏捷开发的核心价值观，其中第二点的内容是：可工作的软件优先于详尽的文档：更注重实际可用的软件，而非过度关注文档的完整性。
3. 在之前的概要设计中，我们已经做了“系统子模块的划分”， 我们只针对某些复杂模块做详细设计，并不需要整体全做详细设计，由项目经理来把控。

什么时候需要详细设计

在日常开发中，很多开发人员按照MVC模式完成CRUD（增删改查）业务时，不需要详细设计就能很好的完成开发任务。这是因为CRUD业务逻辑简单，框架本身已经提供了足够的支持。然而当项目需求超出常规CRUD业务范围时，开发人员往往面临更大的挑战。例如：

1. 数据访问层（DAL）中间件：如果需要实现基于JDBC代理的数据库读写分离，这要求开发人员掌握JDBC规范知识以及网络通信原理。
2. 开放平台开发：接入OAuth协议以支持第三方登录或授权，涉及复杂的认证流程和安全机制。
3. 数据同步中间件：如基于Canal实现MySQL数据同步，或通过高德地图API实现电子围栏功能，这些场景都需要技术实力和严谨的设计。
4. 非标准业务逻辑：任何脱离框架默认支持的业务，都可能成为开发中的难点。

在这些情况下，针对性的做详细设计显得尤为重要。它能够帮助团队理清思路，避免因设计不足而导致的返工或技术债务。

详细设计的内容

详细设计的主要目标是将概要设计中的高层次模块拆解为可执行的具体实现方案。

详细设计要深入到类、方法、业务逻辑、时序图、类图、伪代码、单元测试、异常处理、审计日志等方面。

以下是详细设计的关键要素：

1 类与方法设计

• 定义类：明确每个类的职责，确保单一责任原则（SRP）。例如，UserService类负责用户相关的业务逻辑。
• 定义方法：为每个方法编写清晰的输入输出说明，确保接口简洁明了。例如，getUserById(int id)返回指定ID的用户信息。

2 业务逻辑设计

• 流程图与时序图：使用UML工具绘制业务流程图和时序图，帮助开发人员理解复杂的业务逻辑。
• 伪代码：编写伪代码来描述关键算法和业务逻辑，确保开发人员有清晰的实现思路。

3 数据库设计

• 表结构设计：详细描述每个表的字段及其含义，确保数据库设计符合第三范式（3NF）。
• SQL查询优化：编写高效的SQL查询语句，避免全表扫描和不必要的JOIN操作。

4 单元测试设计

• 测试用例：为每个重要功能编写单元测试用例，确保代码的正确性和稳定性。
• 自动化测试：利用JUnit、TestNG等工具实现自动化测试，提高测试效率。

5 异常处理设计

• 捕获异常：明确哪些地方可能抛出异常，并编写相应的异常处理逻辑。
• 日志记录：确保所有异常都被记录下来，便于后续排查问题。

6 审计日志设计

• 记录操作：为关键操作添加审计日志，记录用户的每一次重要操作。
• 日志分析：定期分析审计日志，发现潜在的安全隐患或性能瓶颈。

详细设计与概要设计的区别

尽管详细设计和概要设计同属于软件设计阶段，但两者在目标、深度和产出物上有显著差异：

维度	概要设计	详细设计
目标	确定系统架构、模块划分和服务接口	明确具体实现细节，为编码提供直接指导
内容	包括项目背景、人员角色、子系统描述、总体框架设计、核心业务流向、设计要求等。	深入到类、方法、业务逻辑、时序图、类图、伪代码、单元测试、异常处理、审计日志等方面。
深度	停留在模块级别的描述，主要用于团队成员对项目的全局理解。	细致到代码级别，确保每个功能点的实现都经过充分考虑和规划。
产出物	架构图、模块说明、服务接口文档	类图、时序图、伪代码、单元测试用例
适用场景	适用于所有项目	更适合复杂业务、非CRUD场景

简而言之，概要设计解决“做什么”的问题，而详细设计则回答“怎么做”的问题。

详细设计的简单示例

案例1：基于OAuth的开放平台设计

在开发一个开放平台时，需要实现用户授权、令牌生成与验证等功能。详细设计可以包括以下内容：

• 类设计：定义AuthController负责处理授权请求，TokenService用于生成和校验令牌。
• 时序图：展示客户端发起授权请求后，服务器如何与第三方认证中心交互。
• 伪代码：模拟授权流程中的关键步骤，如检查用户权限、生成访问令牌等。
• 异常处理：针对无效令牌、超时等问题设计相应的错误码和提示信息。

案例2：基于Canal的MySQL数据同步

对于数据同步系统，详细设计应重点关注同步策略、冲突解决机制以及性能优化：

• 类设计：定义SyncManager管理同步任务，ConflictResolver处理数据冲突。
• 业务逻辑：描述增量数据捕获、解析、写入目标库的完整流程。
• 性能设计：评估同步频率对源库的影响，设计合理的批量提交策略。

模板

需要模板的读者，请下载附件。