哪些项目必须写设计文档
DEV工作量大于等于2PD的项目必须写设计文档,建议所有项目都根据设计大纲确认一下有没有问题。
设计的坏味道
线上频繁执行SQL来修复问题
有大量的JSP后门
机制和策略不分离,任何修改都牵一发而动全身
设计大纲
按照项目研发流程设计
需求解析
分析相关方、计算收益,定义评估方法
描述背景、要解决的问题
名词及术语定义
总体设计
技术选型:涉及技术选型,需要对比候选方案的优缺点,特别要关注一个技术方案的缺点自己是否可以接受。
确定边界:系统边界、代码边界、接口边界等
确定交互流程:
- 交互流程划分:业务交互流程、系统交互流程、模块交互流程
- 交互流程检查点:一致性、性能
- 策略算法相关功能:需要画出流程图
结构设计:
- 逻辑结构:数据模型、时序模型、状态机模型;
- 物理结构:DB;
- 部署结构:分析依赖关系,后续要根据以来关系来撰写上线步骤
详细设计
存储设计:
- 抽象出业务实体
- 画出实体之间的ER关系图
- 定义表结构,写出MySQL scheme变化
- 考虑数据如何初始化
接口设计:
- 接口组成:存储层接口、模块间接口、系统间接口
- 接口应该抽象一组能力,良好的设计应该做到“机制和策略分离”,而接口应该承担分离的职责
- 接口变化需要检查是否有兼容性问题
类图:类描述业务实体,需要描述清楚类之间的关系;类图的设计可以参考各种设计模式,
测试设计
可测性:尽量减少对环境的依赖,确定自测方法;策略算法相关的功能,需要提前想好如何获取数据、如何度量好坏;
测试范围:写明项目的影响面、确定测试范围。测试范围评估不准,会影响自测质量,进而导致联调时间偏长、QA测试时间偏长、QA测试评估不充分导致质量偏低。
测试用例:包括单元测试用例、接口测试用例、系统测试用例、面向C端的用例等
发布流程
写上线步骤:包括上线步骤、回滚步骤(必须和上线步骤相反,每一步都需要有回滚方案)、线上检查方法、应急方案(回滚或者降级);要重点检查兼容性。
上线前评估:上线时间(上线要评估对业务的影响,进而决定可行的上线时间)
阿里技术三板斧:可灰度,可监控,可回滚。
按照系统层次结构设计
存储设计
- 抽象出业务实体
- 画出实体之间的ER关系图
- 定义表结构,写出MySQL scheme变化
- 考虑数据如何初始化
API设计
构成:API可以划分为存储API、模块间API、对外API
方法:建议使用OOA、DDD等设计方法;一个良好的接口应该描述一组能力,可以尝试使用一句话来描述接口的能力。
模块设计
根据API粒度,按照服务原则,规划模块及模块关系
流程设计
- 交互流程划分:业务交互流程、系统交互流程、模块交互流程
- 交互流程检查点:一致性、性能
- 策略算法相关功能:需要画出流程图
系统结构设计
- 逻辑结构:数据模型、时序模型、状态机模型;
- 物理结构:DB;
- 部署结构:分析依赖关系
关键检查点和设计组成
工作量拆分
性能:
- 存储性能:选择DB、设计表结构、设计Cache机制
- 接口性能
- 吞吐量
- 数据规模
一致性:
- 数据一致性:事务处理是否正确,是否涉及分布式数据一致性,是否需要分布式事务
- 并发处理:锁、幂等机制等
监控
附录:设计流水账
- 明确交互流程:系统之间、业务、模块
- 交互流程关键节点:一致性、性能
- 底层API(对外、存储)、DB数据库设计(实体关系、scheme-SQL)
- 对现有系统影响范围,评估、应对方案
- 详细设计:接口、前端接口、类图
- 发布流程:兼容性、上线步骤、历史刷数
- 数据:增加字段如何处理,如何刷数据
- 用例Case(C端)
- 上线前前评估:吞吐量、性能、时间、数据规模
- 涉及状态:状态机
- 测试要点:TestCase、单元测试Case、自测方法、测试范围(事后用联调、QA测试状况来评估)、可测性(免环境)
- 业务模型、模块、层次图
- 工作量拆分
- 背景,要解决的问题
- 采用的代码设计模式
- 监控
- 性能(核心API)
- 边界:系统、代码、接口
- 拆出来提测文档
- 需求解析
- 逻辑结构:数据模型、时序模型、状态机模型;物理结构:DB;部署结构:依赖=>上线步骤
- 线上检查方法
- 事务:特例考虑分布式事务
- 数据处理方式:DB、Cache;一致性处理
- 并发处理:锁、幂等操作
- 发布考虑:监控、灰度、应急方案(回滚、降级)
- 技术选型:对比优缺点
- 数据模型
- 策略算法:需要画流程图
- 名词定义、术语
- 相关方、利益(收益)
- 问题:代码与设计不符
- 线上问题度量:线上执行SQL刷数据次数、JSP后门执行次数、蜂利器任务提报问题数量
- API类别:存储、对外、模块间
- API设计之前:先一句话描述