一 背景及目标

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 风险点

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

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