一、开发

1. 工具

设计画图（流程图、类图、时序图等）: plantuml
框架画图: drawio（vscode安装插件可直接画图）
接口文档和项目文档: showdoc（支持docker搭建，并支持plantuml）
场景梳理: xmind
接口管理器: yapi

2. 开发流程

需求定义

用户需求，由PO和开发一起给出，主要由用户故事组成，每个用户故事工作量控制在3-5d
系统需求，由开发根据用户需求进行输出，将每个用户故事提出方案和各种考虑，输出场景等

需求讲解、反述
场景梳理和工作量评估

正常场景和异常场景梳理
需求对齐，检视工作量是否可达

设计

安全编码设计
评审、修改

测试用例评审
编码
联调和自测

测试覆盖的场景记录

缺陷预防

代码走读
代码扫描和覆盖率测试
接口测试（自动化或配合接口平台测试）
需求检视
checklist（编码+安全）
BVT测试（配合测试达到自动化）
- 联调和覆盖测试过得可以不测

转测试
问题修改

3. 工作量梳理

按照开发流程每一步进行细化梳理
先根据交互设计图梳理出要做的需求点，不能有遗漏，漏掉的就是加班

4. 设计

4.1. 设计思想

当前需求可能不考虑某些场景，比如多xxx，但是设计上需要考虑，防止以后需求变化需要重构代码
基于未来去设计，基于现在来开发
设计模式
设计流程: 职责->接口->实现->场景
生产者消费者关系明确，观察者角色明确
模块解耦，不要依赖外部某个模块的实现，可以通过定义添加/移除观察者函数来实现不依赖外部
接口限制越死，外部依赖越小
类的区分考虑分层和职责，不能单纯只想模块
将业务分离，通用模块尽量少业务代码，抽象成通用逻辑
不要太过深入技术考虑，特殊场景考虑从用户使用角度分离，如果是此用户使用场景很小，可以进行规避不处理
考虑场景要从业务角度进行考虑，定义好使用场景再从技术角度分析是否可行

防遗漏checklist

对外接口线程安全
状态维护由谁来做
集群分布式状态问题
升级场景是否配置变化需要转换
改动后，如何排查
改动后，是否增加维护成本
能不使用缓存就不使用
使用缓存的生命周期需要明确写出
宏观上考虑一下，设计是否合理，不要总是深入思考
客户端考虑跨平台兼容性

4.2. 模板

1) 中型需求模板（开发周期2周）

# 一、介绍

## 1. 目的

简要介绍为什么会有本模块，本模块承担什么职责，为什么本模块要做这些事情。

## 2. 定义和缩写

定义或解释本文档中使用的所有专用名词和缩略语。

## 3. 参考和引用

列出本文档编写过程中参考的其它文档或资料

# 二、设计目标

设计人员遵照目标书要求完成设计，需自行检查是否达到目标书的要求。本设计文档要求后续设计方案能覆盖目标书中存在风险的设计点，以及与其它模块存在协作的设计点，其它无要求。

## 1. 需求

本章节描述用户层级对本模块提出的设计要求。
从版本需求中提炼需要本模块实现的需求点。不应直接复制需求说明书中的描述，而应当进行抽象、提炼，转换为设计者角度进行描述的需求点。

## 2. 约束

本章节描述系统/版本层级对本模块提出的设计要求。
本设计目标在模块设计开始前由总体设计师下发给模块设计者，或者总体设计师与模块责任人沟通后由模块责任人撰写，总体设计师审核。责任追溯时，如果本章节有问题，则为总体设计师的责任。

### 2.1. 模块间协作(含API)

描述本模块与系统其它部分的交互、协作关系，描述本模块对外提供的支持和接口。

### 2.2. 设计特性约束

| 编号 | 目标项类型    | 要求                                                                                                                                                                                                                          |
| ---- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1    | 性能          | 常见性能指标：并发用户数，并发连接数，PPS（每秒处理包个数），支持规则数，界面响应速度，新建连接速度等等。                                                                                                                     |
| 2    | 资源开销      | 对所使用资源的一些约束。常见资源开销：内存占用，CPU占用，磁盘占用，IO占用等等                                                                                                                                                 |
| 3    | 稳定性/可靠性 | 该功能是否需要长时间运行，会不会影响客户业务，应做什么样的机制保证（比如把某个功能点放到独立进程中进行，使用脚本实现某些功能等等）。需要重点考虑对哪些异常场景的支持（比如程序死锁，CPU100%，崩溃，数据处理过程出现错误等）。 |
| 4    | 可调试/可测试 | 需支持哪些调试手段，需支持哪些测试手段                                                                                                                                                                                        |
| 5    | 可维护性      | 对维护运营工作的支持                                                                                                                                                                                                          |
| 6    | 兼容性        | 允许升级配置的版本，允许对接的版本                                                                                                                                                                                            |
| 7    | 可扩展性      | 哪些功能或接口需要可扩展设计                                                                                                                                                                                                  |
| 8    | 其它          |                                                                                                                                                                                                                               |

## 3. 支持

本章节描述模块本身对设计提出的要求。
模块在后续开发中，为了提高效率，降低风险所需要的一些支持手段、规范和要求。这部分要求一般不会对系统其它部分产生影响，只会影响到这个模块自身。一般包括内部测试方面的机制，代码调试方面的机制，等等。

| 编号 | 目标项类型 | 要求                                                   |
| ---- | ---------- | ------------------------------------------------------ |
| 1    | 测试机制   | 如果要很方便做单元测试或者测试执行，对设计有什么要求？ |
| 2    | 调试机制   | 如果要很方便进行调试，对设计有什么要求？               |
| 3    | 规范       | 为了后续开发顺利，有什么规范要求？                     |

# 三、风险分析

本章对模块运行场景和技术风险进行分析，提炼出模块运行各个环节存在的风险，以及实现模块设计目标所存在的风险。本章节需版本总体设计师认可。

## 1. 场景分析

禁止写一个无，需要结合历史的场景checklist，给出分析结论，并附上结果文档

## 2. 风险分析

基于模块的设计目标，分析哪些点可能存在风险。基于模块的运行场景，分析各个环节可能遇到的问题，面临的风险。
风险分析可采用头脑风暴方法搜集或使用思维导图分析。风险确定后，需要对风险进行排序，确定风险最大，最需要先解决的问题。分析完成后，按风险从大到小排列填写下表。

# 四、方案设计

## 1. 方案选型

此章节，需要使用方案选型表对核心需求项的多个可行方案进行选型，确定最终采用的实现方案。
此处简述本设计的可供选型方案，并说明最终所选的方案，以及选择该方案的原因。此章节需最先完成，并且方案选型表讨论通过，才能展开下一步的设计工作。
说明：
1、合理的方式，应该是如下用打分的方式进行判断
2、如果打分有困难，可以选择优缺点评估方式，并叙述最终所选择方案的优点、风险和缺点，目的是只有考虑周全的方案才是合理的，凭借个人经验、对评估准则个人有个人看法的，所选择的方案有可能存在重大风险，埋下地雷。

**打分方式**

| 评估准则  | 权重 | 评估方法 | 方案1 | 方案2 | 方案3 | 方案4 |
| --------- | ---- | -------- | ----- | ----- | ----- | ----- |
| 评估准则1 | 50%  |          |       |       |       |       |
| 评估准则2 | 15%  |          |       |       |       |       |
| 评估准则3 | 20%  |          |       |       |       |       |
| 评估准则4 | 15%  |          |       |       |       |       |

**优缺点方式**

| 备选方案名称 | 本方案的优点 | 本方案的风险和缺点 | 最终选择 |
| ------------ | ------------ | ------------------ | -------- |
| 方案1        |              |                    |          |
| 方案2        |              |                    |          |
| 方案3        |              |                    |          |
| 方案4        |              |                    |          |

## 2. 对软件总体架构的影响
本章节描述本次新增及调整模块对软件总体架构的影响点，重点参考设计编码红线

## 3. 模块整体思路

### 3.1. 模块结构

描述模块内部各子模块（或对象/实体）之间的结构关系。描述子模块间协作所涉及的数据结构。
使用 draw.io（可以使用VSCode 插件 Draw.io Integration） 画出模块静态结构图

### 3.2. 模块流程

描述模块整体业务流程。描述各关键需求点的实现思路。

## 4. 安全性设计

描述第3章阐述的风险该如何解决，需为每一个风险确定一个行之有效的解决方案。

### 4.1. 威胁建模分析

威胁建模分析，目的是分析该版本总体设计中涉及到的各个模块实体、数据存储、进程服务、开放端口、交互协议等是否存在相关的安全威胁风险，把风险识别出来并填入如下表格，
采用微软的STRIDE方法来开展威胁建模与安全设计活动，具体方法请与产品线安全经理沟通咨询，或发邮件给SDL邮件群组，进行咨询。

### 4.2. 安全设计

根据上一节威胁建模识别出来的风险和建议采取的安全措施，各个模块威胁对应的安全机制，在此章节进行详细描述，比如通信协议要加密，就需要设计相关的加密方案。

## 5. 可靠性设计

分析本模块的每个功能流程运行过程中会出现哪些故障场景（包括在模块流程内部产生的故—例如文件读写失败，以及本模块和其他模块交互时其他模块传递过来或者表现出来的故—例如传递错误的数据或者消息、无响应、超时响应、响应慢），这些故障场景触发的原因以及对本模块流程的影响（中断、卡慢、输出数据错误等等），给出故障容错方案（故障检测方案、故障恢复方案）以避免造成本模块业务流程的失效（中断、卡慢、输出数据错误等等），对于无法自动容错（比如硬盘坏了导致进程无法启动等等）的故障场景需要给出人工介入的处理指导（人工如何感知故障，如何进行恢复）

## 6. 可维护设计

说明为了系统维护的方便而在程序内部设计中作出的安排，包括在程序中专门安排用于系统的检查与维护的检测点和专用模块。

## 7. 技术风险解决方案

描述第3章阐述的风险该如何解决，需为每一个风险确定一个行之有效的解决方案。

### 7.1. XXX方案

描述某个关键技术点的实现方案。每个技术点一个章节。如果该问题有多个可选方案，分析每个方案的优劣点，说明最终采用的方案及其原因，可使用方案选型表进行决策。

### 7.2. YYY方案

# 五、详细设计

本章节对第4章确定的方案作进一步阐述。把一些关键技术点，尤其是涉及到与其它模块协作的技术点（如某些流程，数据结构，API，消息等），作一个清晰明确的定义。确定遵守本章节描述的内容进行编码可保证风险消除，不引起返工即可。
一般来说，模块间的接口在第2章“设计目标”中已经有阐述，本章描述的模块间协作内容侧重于描述方案中可能会影响到其它模块的一些流程方法，侧重于描述本模块怎么使用其它模块提供的接口。

## 1. 方案1

根据方案特点，重点从“模块结构/数据结构/交互逻辑/算法/接口/其它”这几个方面选若干个进行阐述，能把解决风险的关键思路和细节描述清楚即可。

# 六、完成设计自检

此章节，对上述设计内容进行整体自检，并将自检结果备注在6.1和6.2标题后，即通过or不通过，同时，模块设计负责人对以下结果负责，后续出现因设计自检项导致的问题将会进行问题追溯

## 1.设计自检结果：通过/不通过

根据设计checklist产出最终自检结果

## 2.不贰过自检结果：通过/不通过

根据不贰过自检列表产出最终自检结果

# 一、设计背景和目标

**<font color="red">交互稿地址:</font> [xxx](https://xxx)**

## 1. 需求描述

## 2. 设计目标

### 2.1. 设计内容

# 二、需求场景梳理

## 1. 用户使用场景

## 2. 可靠性场景

### 2.1. 性能

### 2.2. 容错

## 3. 可维护性场景

排查和恢复

### 3.1. 可测试性

如何自动化测试

### 3.2. 可调试性

开发自己调试方便

## 4. 兼容性需求

# 三、方案选型

## 1. xxx

### 背景

### 用户故事

### 对比

|                | xxx | xxx |
| -------------- | --- | --- |
| 复杂度（时间） |     |     |
| 可维护性       |     |     |
| 影响           |     |     |

### 最终选型

# 四、技术方案

# 五、概要说明

## 1. 整体架构

## 2. 使用场景流程时序

## 3. 客户场景流程时序

# 六、详细设计

## 1. 模块接口定义

接口地址和数据格式，最好有个api接口管理器

### 1.1. 对外暴露接口和数据结构

**接口约束**

### 1.2. 对外暴露错误信息

### 1.3. 对外通知/触发机制

### 1.4. 配置文件定义

## 2. 模块关系

### 2.1. 层次关系

- 模块划分结构

### 2.2. 依赖关系

- 主要关注相互的引用和依赖

### 2.3. 所属关系

- 主要关注生命周期和持有

## 3. 进程/线程关系

### 3.1. 任务分析

**耗时操作**

**实时性要求**

**数据同步分析**

### 3.2. 进程/线程模型

## 4. 几个关键业务触发时机

## 5. 日志

### 5.1. 日志打印流程点

## 6. xxx

### 内部数据结构

### 细节流程

### 生命周期

# 七、可靠性

## 1. 性能指标

## 2. 容错处理

### 2.1. 关联影响分析

## 3. 安全分析

### 3.1. 安全建模

# 八、可扩展性

负载增加后如何应对

# 九、可维护性考虑

可维护性包含运营团队如何观测解决问题、后续新成员如何维护系统、新功能如何增加

## 1. 运营团队手册

**原则: 测试都可以排查的，技术支持就可以**

### 1.1. 问题快速定位方法

### 1.2. 问题快速恢复方法

### 1.3. 持续观测能力（遥测）

## 2. 可测试性考虑（自动化）

## 3. 可调试性考虑

## 4. 后续演化解决方案（新功能添加）

# 十. 兼容性考虑

5. 编码思想

5.1. 通用工具类开发

参考目录结构

编码只写公用函数/src/common.sh，对于每个平台的配置和代码单独有一个目录/user/xxx
公用函数调用根据平台自己的入口检测返回来决定是否运行此平台配置
输出提供公用库/src/output.py，平台可调用或自己定义
- 考虑以key-value的形式
- 定义优先级
- 输出各个格式提供接口（markdown、html、json、xml、excel）
对不同平台的开发来说，将模板配置拷贝一份放入/user/xxx下，修改其中的config和src即可

5.2. 安全相关

参考安全开发专项笔记

5.3. 日志

原则

出现错误，如果可以客户自己解决，打印用户日志
- 能前置解决的产品才是最好的产品
如果需要开发介入，一定要可以从日志中快速定位问题和流程
日志不暴露符号名称，防止被分析逆向

日志五要素（日志有效性）

What: 什么错误，一般是函数级错误
Reason: 错误信息（排查使用），行级错误和当前状态
CausedBy: 由什么造成（深层次原因）
Will: 造成什么后果，业务级错误
HowTo: 如何进行恢复，给运维人员处理建议

等级输出

fatal
error是需要人为处理的日志
warn是存在问题，重试可以恢复，如果多次需要提升为error
info一般为生命周期、服务启动、配置变更、审计日志
debug是技术支持和运维人员（非开发人员）可以开启排查使用
trace开发自己调试过程的日志，上线不开启trace
流程分支尽量有日志输出如果太多需要降低等级
- 一个流程分支尽量只有一条日志输出，不要每个分支都有一条，可以通过日志定位流程即可

5.4. 注释

代码可以直观了解的不需要注释
代码不可以直观了解或者不告知就无法理解的逻辑需要注释
注释不是描述代码流程，而是解释流程原因

5.5. 命名规范

仅供参考（主要参考linux源码和python库）

变量命名使用下划线
函数命名使用下划线
类命名使用大驼峰
宏定义使用下划线，全字母大写

5.6. 断言和报错

外部输入（纯外部第三方）必须校验，由于外部输入导致的崩溃是不被允许的
如果输入处理完善，内部不会出现的问题，使用断言进行判断
如果外部输入正常，跑动过程出现了异常，使用判断加报错处理
使用智能断言，信息中写明出现的上下文，断言原因机制会保障

5.7. 代码中文字符处理

如果需要使用中文，不能放到代码中去，防止因为编码导致的乱码
需要单独拉出一个json文件或txt文件进行保存，代码进行调用

6. 项目基础模块

6.1. 语言和框架

1. 异常和错误处理

2. 可移植性

模块化、插件化

3. 集群和分布式

6.2. 日志

1. 用户排查日志

2. 开发排查日志

3. 调试日志

6.3. 进程/线程/协程管理

1. 消息通信机制

2. 无锁的几种实现

无锁循环队列
保证逻辑跑在一个线程，如果不在此线程，只push任务（runInLoop()）

6.4. 公共工具

1. 进程/线程锁

2. json解析

3. 共享内存

4. 数据库接口

5. 配置文件接口

6.5. 安全

1. 服务和端口管理

2. 密码管理

3. 配置管理

4. 代码管理

5. 数据管理

二、管理

1. 团队凝聚力

	学生团队	公司团队
凝聚力源头	无	工资绩效
影响	无	收入

学生团队

一人犯错集体受罚
迟到可以连带受罚
- 把握好度，不生成怨恨

团建

去唱K
吃饭
一起出去玩
适当放假

人员和职责

项目经理
- 负责项目进度把控
- 人员和资源协调
- 组织站会
- 问题决策
- 外部对接
敏捷教练(敏捷开发项目需要)
- 监督和指导敏捷项目各项流程
- 敏捷培训
PO团队
- 团队只有一个声音给出需求定义
- 关心用户体验给出界面交互设计方案
研发CTO
- 协助项目经理做事
- 负责版本合入并做代码质量把控和代码走读审查
- 对版本各方原理熟悉，指导各个研发人员
测试CTO
- 负责版本的测试人员测试用例评审
- 负责各项环境搭建和资源调度
架构师
- 根据界面交互设计代码语言、工具、环境
- 设计代码流程和实现方案
- 具体问题跟研发人员共同协商解决方案
- 研发过程实时跟进研发人员的方案是否符合预期
- 技术问题到架构师为止，保证一定有解决方案
安全专员
- 提供安全相关指导
安全测试专员
- 提供安全渗透测试用例
- 发布后出了漏洞的背锅人

2. 进度管理

进度预估

工具：WBS
尽可能细分模块
- 预估时间，单位：人天
- 预估好每个人的工作量是否平均
- 预估每个人的工作效率以及工作质量
风险把控
- 每天检查进度，通过进度和计划预估风险
- 风险提出并想出相应方案解决
- 不要相信成员在时间内能完成，一定要跟进

里程碑

适当制定里程碑，具有时间节点
- 要完成功能
- 可完成功能
- 暂时不需要完成的功能
将项目划分为若干个里程碑
做好每个里程碑完不成的方案

效率保证

写大概10%的时候找负责人讲思路，防止思路不正确重写
晨会
- 昨天做了什么
- 今天要做什么
- 有什么问题需要协调
- 自己模块百分比
  - 跟踪进度
目标导向
- 每天目标
- 每周目标
- 每个阶段目标
白板贴纸
- to do
- doing
- done
bug跟踪记录
- 提一个bug
  - 问题描述
  - 问题复现步骤
  - 问题现象
  - 期望现象
  - 问题环境
  - 问题时间
- 解决一个bug
  - 问题定位过程
  - 问题原因描述
  - 改动原理概述
  - 可能影响模块
  - 额外复现步骤
  - 可验证的版本号
- bug列表整理到项目管理工具中

3. 总结收获

周会进行总结
- 本周计划完成情况
- 总体进度完成情况
- 下周计划
- 个人总结
  - 做得好的
  - 做的不好的
  - 对团队有什么建议和措施
项目结题总结报告
1. 代码审查报告
2. 代码扫描报告
3. 系统测试报告
4. 覆盖率报告
5. 单元测试报告
6. 验收过程记录
7. 测试验收报告
8. 设计及方案文档
9. 代码及代码说明文档
10. 使用手册及注意事项
11. 培训资料及培训记录
12. 结项报告

4. 功能模块开发管理

4.1. 项目跟踪

1) 记录模板

# 一、总述

- 负责人:
- 开发分支:

# 二、需求

## 1. 交互稿

## 2. 系统需求

## 3. 需求变更过程

# 三、设计和工作量评估

## 1. 工作量

## 2. 设计

# 四、风险对齐

# 五、缺陷预防（转测活动）

## 1. 威胁建模分析和评审

## 2. 代码走读

## 3. 单测检视

# 六、转测

- 时间:

5. 工具

git管理工具：gitlab
代码扫描工具：infer、clov
外网穿透：sunny
测试自动化框架: robot framework (python)

技术的路上奔跑

项目开发经验