测试开发研发设计规范
0、研发设计背景
XX总：整个研发部开展业务设计评审-常态化。
XX哥：工程效能和测试开发要有自己的评审流程和代码规范。
目前，应用平台已开始实施常态化的研发设计评审，作为面向内部用户的开发团队，我们也应当跟进并制定类似的规范。随着未来项目将全部迁移至微服务架构，研发设计的规范化变得尤为重要。
有人认为测开和运开这种内部平台开发不需要太多规范，开发人员少，随便做做即可。但我认为，正是因为开发人员少，才更需要系统化的文档沉淀。
1、为什么要做研发设计？
个人角度：积累和沉淀，IT人员素质、能力的提高。
团队角度：方便其他成员共建共享，新人快速上手，方便工作交接。
公司角度：积累知识资产，保证产出物的质量，不能开发完毕就重构。
2、怎么做研发设计？
全部项目应该走devOps流水线。
大需求-初建版本（0-1
小需求-迭代版本（1+）
研发设计流程
graph LR
系统需求阶段-->系统设计阶段-->系统开发阶段-->系统测试阶段
2.1、系统需求阶段
在DevOps项目管理中，提交需求级的研发设计评审，主要内容包括：需求描述、现状分析、设计方案、实现方法。
需求文档：
- 需求来源： 内部工具需求通常来自现实需求、用户反馈及业界动态。
- 需求描述： 清晰描述产品需求。
- 需求现状： 当前需求的实现情况。
- 需求设计： 提出解决方案。
- 需求实现： 描述系统的实现思路、方法与逻辑。
必要图示：
- 用户流程图： 展示真实世界用户的操作流程，使用竖行泳道图。
- 应用架构图： 描述系统内部模块与外部模块之间的关系，尤其是在微服务架构下。
- 业务对象图： 描述业务对象之间的关联关系。
2.2、系统设计阶段
系统概要设计
- 应用架构图： 描述开发团队与合作团队的协作，及本应用模块的层次架构和职责。
- 部署架构图： 基于应用架构图，描述部署的各个工程包及其职责。
系统详细设计
- 服务接口说明： 包括时序图、业务用例、状态图、数据库ER图等详细设计文档。
- 数据库设计： 明确系统所需的数据库结构与实现。
2.3、系统实现阶段
开发文档
- 需求实现： 描述如何根据需求进行具体开发和实现。
代码评审规范
代码规范
- 命名与代码编写规范： 可参考Google代码规范。
- 注释规范：
- 对所有对外提供的接口，必须有清晰注释，详细说明参数、返回值及功能。
- 修改核心功能时，需增加注释，说明修改的业务场景、作者及修改时间。
- 关键逻辑代码必须有注释，帮助他人理解。
- 常量使用： 对于固定数值（如状态值），避免硬编码，需使用常量。
- Maven依赖： 应使用正式版本的Maven依赖，避免使用snapshot版本。
日志规范
- 业务异常日志： 所有业务异常必须记录日志。
- 关键业务日志： 关键逻辑需要记录详细业务日志。
- 日志数据： 日志中应尽量记录业务相关数据，如userId等。
- 日志关键词： 日志内容应包含能定位问题的英文或拼音关键词，方便日志查询与搜索。
设计规范
-
模块划分规范： 各模块功能应清晰独立，符合设计原则。
-
包划分规范： 同一包内的功能和业务类型应保持一致。
-
接口设计规范： 确保接口设计遵循六大原则：
- 开闭原则： 模块应可在不修改已有代码的前提下扩展。
- 里氏代换原则： 使用基类的地方应能替换为其子类。
- 依赖倒转原则： 依赖抽象，不依赖具体实现。
- 接口隔离原则： 使用多个专门接口而非一个通用接口。
- 合成/聚合复用原则： 优先使用合成/聚合，避免继承。
- 迪米特法则： 一个对象应尽可能少地了解其他对象。
a) 优先考虑将类设置为不可变类（如：String、BigInteger等）。 b) 尽量降低类的访问权限。 c) 谨慎使用Serializable接口。 d) 方法访问权限尽量设置为private。 e) 替代C结构体，使用属性的getXX和setXX方法。 f) 系统类继承树的叶子节点应为具体类，枝干节点应为抽象类或接口。
方法设计规范
- 功能应明确，任务单一。
- 步骤应清晰，避免复杂操作。
- 操作的变量应尽量减少。
- 单个方法的代码行数不应过长，建议最长不超过50行。
- 重复的代码应提取为公共方法，避免冗余。
数据设计规范
- 数据库设计应符合规范，保证数据结构的合理性。
- DO对象设计要合理，避免过大或复杂对象的多重依赖。
2.4、系统测试阶段
- BUG List： 缺陷应通过DevOps流程管理，并记录于缺陷列表中。
2.5、系统交付阶段
系统开发完成后，应提供详细的用户手册，并根据后续需求变化进行版本迭代和维护。
