测试开发研发设计规范

0、研发设计背景

XX总：整个研发部开展业务设计评审-常态化。

XX哥：工程效能和测试开发要有自己的评审流程和代码规范。

目前，应用平台已开始实施常态化的研发设计评审，作为面向内部用户的开发团队，我们也应当跟进并制定类似的规范。随着未来项目将全部迁移至微服务架构，研发设计的规范化变得尤为重要。

有人认为测开和运开这种内部平台开发不需要太多规范，开发人员少，随便做做即可。但我认为，正是因为开发人员少，才更需要系统化的文档沉淀。

1、为什么要做研发设计？

个人角度：积累和沉淀，IT人员素质、能力的提高。

团队角度：方便其他成员共建共享，新人快速上手，方便工作交接。

公司角度：积累知识资产，保证产出物的质量，不能开发完毕就重构。

2、怎么做研发设计？

全部项目应该走devOps流水线。

大需求-初建版本（0-1

小需求-迭代版本（1+）

研发设计流程

graph LR
    系统需求阶段-->系统设计阶段-->系统开发阶段-->系统测试阶段

2.1、系统需求阶段

在DevOps项目管理中，提交需求级的研发设计评审，主要内容包括：需求描述、现状分析、设计方案、实现方法。

需求文档：

  • 需求来源： 内部工具需求通常来自现实需求、用户反馈及业界动态。
  • 需求描述： 清晰描述产品需求。
  • 需求现状： 当前需求的实现情况。
  • 需求设计： 提出解决方案。
  • 需求实现： 描述系统的实现思路、方法与逻辑。

必要图示：

  • 用户流程图： 展示真实世界用户的操作流程，使用竖行泳道图。
  • 应用架构图： 描述系统内部模块与外部模块之间的关系，尤其是在微服务架构下。
  • 业务对象图： 描述业务对象之间的关联关系。

2.2、系统设计阶段

系统概要设计

  • 应用架构图： 描述开发团队与合作团队的协作，及本应用模块的层次架构和职责。
  • 部署架构图： 基于应用架构图，描述部署的各个工程包及其职责。

系统详细设计

  • 服务接口说明： 包括时序图、业务用例、状态图、数据库ER图等详细设计文档。
  • 数据库设计： 明确系统所需的数据库结构与实现。

2.3、系统实现阶段

开发文档

  • 需求实现： 描述如何根据需求进行具体开发和实现。

代码评审规范

代码规范
  1. 命名与代码编写规范： 可参考Google代码规范。
  2. 注释规范：
    • 对所有对外提供的接口，必须有清晰注释，详细说明参数、返回值及功能。
    • 修改核心功能时，需增加注释，说明修改的业务场景、作者及修改时间。
    • 关键逻辑代码必须有注释，帮助他人理解。
  3. 常量使用： 对于固定数值（如状态值），避免硬编码，需使用常量。
  4. Maven依赖： 应使用正式版本的Maven依赖，避免使用snapshot版本。
日志规范
  1. 业务异常日志： 所有业务异常必须记录日志。
  2. 关键业务日志： 关键逻辑需要记录详细业务日志。
  3. 日志数据： 日志中应尽量记录业务相关数据，如userId等。
  4. 日志关键词： 日志内容应包含能定位问题的英文或拼音关键词，方便日志查询与搜索。
设计规范

  1. 模块划分规范： 各模块功能应清晰独立，符合设计原则。

  2. 包划分规范： 同一包内的功能和业务类型应保持一致。

  3. 接口设计规范： 确保接口设计遵循六大原则：

    • 开闭原则： 模块应可在不修改已有代码的前提下扩展。
    • 里氏代换原则： 使用基类的地方应能替换为其子类。
    • 依赖倒转原则： 依赖抽象，不依赖具体实现。
    • 接口隔离原则： 使用多个专门接口而非一个通用接口。
    • 合成/聚合复用原则： 优先使用合成/聚合，避免继承。
    • 迪米特法则： 一个对象应尽可能少地了解其他对象。

    a) 优先考虑将类设置为不可变类（如：String、BigInteger等）。 b) 尽量降低类的访问权限。 c) 谨慎使用Serializable接口。 d) 方法访问权限尽量设置为private。 e) 替代C结构体，使用属性的getXX和setXX方法。 f) 系统类继承树的叶子节点应为具体类，枝干节点应为抽象类或接口。

方法设计规范
  • 功能应明确，任务单一。
  • 步骤应清晰，避免复杂操作。
  • 操作的变量应尽量减少。
  • 单个方法的代码行数不应过长，建议最长不超过50行。
  • 重复的代码应提取为公共方法，避免冗余。
数据设计规范
  • 数据库设计应符合规范，保证数据结构的合理性。
  • DO对象设计要合理，避免过大或复杂对象的多重依赖。

2.4、系统测试阶段

  • BUG List： 缺陷应通过DevOps流程管理，并记录于缺陷列表中。

2.5、系统交付阶段

系统开发完成后，应提供详细的用户手册，并根据后续需求变化进行版本迭代和维护。