写点什么

迭代技术方案设计文档规范

发布于: 2020 年 09 月 03 日
迭代技术方案设计文档规范

一 背景及目标

1.1 背景

规范在团队管理中的意义无需多言,对于开发团队来说,技术方案的设计和执行无疑是日常工作中很重要的一块。编码一定要在思考清楚之后在开始,以免把问题带入线上,或者反复修改造时间、精力的浪费。

大家在日常研发过程中更多的是迭代类的需求,以中小型迭代需求为主,严格按照大规模系统设计文档模板填写内容过多,导致执行度偏低,所以决定整理一个简化后的设计文档规范,可作为技术设计时的checklist,研发同学可参考执行。

1.2 目标

通过遵守规范,各位RD同学在方案调研、技术设计时充分考虑,包括需求的理解与合理性评估、技术上实现的可行性调研、对现有系统或外部依赖的影响范围评估、各成员角色的职责划分与关注内容充分沟通、风险点预知等等,确保方案可行,减少因理解偏差、调研与沟通不充分导致的线上问题,提升个人的技术、设计、沟通等各方面的能力,培养良好的开发习惯。

1.3 适用范围

所有需求迭代的技术方案设计,都按照本规范执行。输出格式:xxx (word、wiki、pdf等,推荐使用有版本管理的工具,方便查看变更)

二 技术设计前期准备

开始做方案设计之前,一定确保两个前提条件已经完成:需求评估 和 技术调研。

2.1 需求评估

(1)确保需求的真实性、可行性、必要性,以及与产品的发展方向是否一致;伪需求、无收益需求 可在PM同学这层直接驳回

(2)与PM同学充分沟通需求内容,确保双方理解一致,没有偏差;对PM同学在需求预审阶段,存在的逻辑不完整或潜在问题,在此阶段做好完善和修改

(3)参与人:RD、PM、QA必须同时参加,PO视实际情况决定。低阶同学如果无法确认(1)的要求,可以请高阶同学一起参与需求评审,确保需求考虑充分,不会导致线上出现业务逻辑问题 或 导致反复修改

2.2 技术调研

(1)确定需求在技术上实现的可行性

(2)调研各备选方案的实现成本,对当前系统的影响,以及可能导致的潜在风险

三 文档格式

3.1 需求背景

项目/需求背景,如当前功能现状,需求的必要性、可行性,预期带来的收益;如果涉及一些专业词汇或指标时,需要给出准确的文字描述

3.2 需求理解

1、RD角度需求理解

RD角度对PM同学提出的需求的理解,不是复述,而是总结和抽象;对需求进行拆解,映射到功能层面;作为流程、接口定义的依据;

描述角度:新增了哪些功能,已有的功能做了哪些变更

2、引申需求

除了原始需求外,可能会涉及历史遗留的逻辑问题,或优化类的需求(响应耗时、实时返回调整为异步处理等),不属于PM同学所提的需求范围,但对需求的实现存在影响,需要纳入考虑。

3、内容要求

能够让参与评审的同学(PM、非该模块负责的RD、项目QA),基本明确需求影响的功能模块,预期实现的目标,和影响范围。

3.3 概要设计

需要包括:基本介绍、系统环境(涉及时包含)、数据规模、方案可行性调研结果;

设计思路和折衷

系统设计:系统架构图(简单的功能迭代不必包含,技术项目涉及架构变更时必须体现)、流程图、外部服务依赖、子模块(子系统)简要描述。

重点:体现自己的设计决策。

3.4 详细设计

3.4.1 内容结构

1、模块划分、依赖关系 (必须)

2、流程图(必须)

3、数据结构设计(必须)

(1)确认数据code、name明确,理解无歧义;

(2)确认历史数据是否存在异常(重要)!!!

(如某张业务表,字符串类型字段存储的是整数数组的结构;但如果历史数据中存在记录字符串数组),必然会影响接口的数据返回。

4、接口设计(必须)

(1)涉及与FE、外部服务交互,必须确保相关人员都已经明确了需要关注的接口和参数、返回值,接口文档格式:路径,入参(字段名称、类型、是否必填、备注说明),返回值(字段名称、类型、是否必填、备注说明);

(2)入参和返回值,必须提供demo数据;

(3)返回值约定错误码、异常信息、是否需要前端接收并展示异常消息内容

5、存储设计(依据实际情况,非必须)

6、配置项 (依据实际情况,非必须)

7、数据量及压力评估(依据实际情况,非必须)

8、上线步骤考虑(必须)

(1)上线顺序,包括web机、脚本机、sql、外部服务;

(2)是否需要清理/刷历史数据?

3.4.2 checklist

1、是否涉及表结构变更

新建/已有表增加字段,或新的业务导致新的查询场景,原表结构/索引设计无法满足要求,可能会导致慢查询

注意事项:

(1)表名、字段命名规范

(2)业务场景,常用查询条件,决定索引的设计 (索引字段、单列/联合索引、索引类型:BTREE,HASH

(3)数据规模,决定是否需要进行拆分(分表、分库设计)

2、是否引入外部服务依赖

(1)确认外部服务是否可用,包括:功能、稳定性、响应时间指标。不只是服务接口本身耗时,还包括引入之后,对接口整体耗时的影响。通常接口的响应时间应该在1s以内,复杂业务建议5s以内。非特殊需求,耗时操作需要使用异步实现

(2)外部服务不可用时,是否可以降级?降级时机和检测方式(监控/业务反馈)?降级方式(手动、自动)?恢复方式(手动、自动)?如果使用自动降级,是否有可能因为判断条件有误导致误降级,这种情况是否被允许?

(3)如果功能尚未完成,需要确认完成时间,决定是否可以引入,且不影响项目进度,调研阶段需要明确,并制定备用方案,以防依赖无法按时保质交付时,项目整体推迟。

3、必要的校验

请求的来源,除了系统内部的前后端交互,还会有诸如小工具、Postman(for chrome)或HttpClient(for firefox)等接口请求测试工具,设计时切记:所有的外部输入都是不可靠的,必须进行校验。

(1)输入参数必填项、类型校验

(2)用户权限校验

(3)参数准确性校验,如需要下载的备件不属于传入的交易单,可能是人为构造导致,避免越权、SQL注入

(4)涉及外部对接时,必须包含加密或验签环节

4、异常情况捕获处理、报警方式

包括但不限于:非法参数、数据库异常、网络异常、数据错误、依赖服务异常

方案中需要体现:

(1)每一种异常可能出现在流程中的位置

(2)是需要进行捕获还是直接抛出

(3)日志等级

(4)报警方式,关注成员(RD?PM?PO?)

(5)问题发生后应该怎样进行后续处理(可忽略?需要PM刷补单、数据?需要PO通知业务方修改?)

5、关于资源和成本【非必须,建议考虑】

线上资源由多个业务线共享(混布)时,避免相互影响。

(1)部署使用的机器数量,cpu负载、内存占用率、磁盘空间、硬盘IO、网络带宽,

(2)数据库、redis、HDFS等的数据量和存储空间,

(3)云服务的使用空间

6、存储采用主从结构时,考虑各个环节的线上主从延迟问题【不一定有,必须考虑】

3.5 工作量评估

开发、自测、联调、cr、showcase、测试、上线;

注意考虑项目并发,和紧急插入需求带来的风险

3.6 风险点

技术上的不确定性,潜在的人力、时间风险,存在需求通知上下游的变更等;

方案变更、上下游通知必须正式的邮件通知,并确保相关各方已经明确变更内容 和 截止时间点



发布于: 2020 年 09 月 03 日阅读数: 266
用户头像

磨炼中成长,痛苦中前行 2017.10.22 加入

8年的程序员

评论

发布
暂无评论
迭代技术方案设计文档规范