一定要记得保留数字标题前缀，这样可以在目录里恰当地理解结构深度。

图例

红色代表变更/新增功能

蓝色/黑色代表原有功能

1、需求分析

1.1 原始需求

1.2 需求背景

1.3 需求收益

1.4 术语解释

名称	解释
例子	例子

1.5 流程分析

1.6 用例分析

1.6.1 业务用例分析

1.6.2 系统用例分析

2 功能性设计

2.1 交互设计

2.2 流程变动

2.3 领域模型变更

要有枚举变更、领域名词变更

2.4 数据模型变更

2.5 状态机变更

2.6 关键时序

对 sla 的需求是什么？写在时序的 Note 里。

2.7 接口变更

参考：

《Google API Design Guide (谷歌API设计指南)中文版》。
github 的 REST API

注意 api 的风格、可扩展性、场景的隔离。

List
Get
Create
Update
Delete

接口要素	接口要素值	语义说明
path	/api/v1/account_settings/reclaim_rules
http method	PUT
query params
request body
custom request headers
custom response headers
response body

3 非功能性设计

3.1 风险点评估

3.1.1 高可用风险

3.1.1.1 新增组件/依赖

依赖服务	强弱依赖	风险点	稳定性保障
appkey	弱依赖	接口响应时间超出配给时间，导致用户 xx 环节 xx 接口响应超时。	发现手段：设置 rpc 超时，依赖超时告警。依赖服务保护平台切面的告警（注意监控、注意中断机制）。依赖监控上报的异常。是否依赖于中间件超时/重试，是否使用服务保护平台超时/重试。恢复手段：通过降级来绕开对某个 appkey 的依赖。是否依赖于中间件降级，还是使用服务保护平台降级？冗余措施：是否有请求落库持久化，支持异步化/重试，是否支持内存级重试。

稳定性保障的子表格

关联对上对上接口	对上 sla	依赖接口名称	依赖 qps	依赖 sla
服务名.方法名	目标 40ms tp9999 86 ms avg26ms 对上的 qps 最好能够通过监控看到分钟级数据，对平均值和峰值有所认知需要考虑是不是上线就带有熔断和限流降级能力	服务名.方法名	500	tp9999 10ms 能否在拆解中达到依赖目标？

3.1.2 资损风险

风险点	发现手段	应对措施
交易型风险：交易失败？错漏重
营销型风险：错漏重？如何核销？

3.2 上线计划

3.2.1 代码变更

发布顺序

服务 appkey1
服务 appkey2
前端服务 xxx

3.2.2 配置变更

强弱依赖的区别在于，是否核心用例、核心事务的核心组成部分。
要上线后才能变更的配置一定要和上线前就能变更的配置区分出来。

强依赖梳理

变更项	变更内容
发 jar	确认版本号发布环境 snapshot/release 谁来发布
灰度开关	有没有暗部署设计全局开关还是局部开关是不是基于请求因子灰度的要注意设计灰度时间和事件顺序
rpc 服务鉴权	四个环境的子表格，注意变更点要全部列出：包含服务、接口和是否打开鉴权。
动态配置服务	要注意运用好审批功能。四个环境的子表格，注意变更点要全部列出： key 和 value。
静态properties/yaml新属性	四个环境的子表格，注意变更点要全部列出： key 和 value。
分布式任务框架	四个环境的子表格，注意变更点要全部列出：分布式任务名称、确认执行时间（模式、每次执行时间）、告警模板
mq	四个环境的子表格，注意变更点要全部列出：集群、topic（partition 数、是否延时、死信、有没有负载均衡特殊配置）、消费者（并行消费数、是否延时消费、死信配置、消费异常处理策略）
分布式缓存	四个环境的子表格，注意变更点要全部列出：集群、category、超时时间、命名模板、Value 类型（如有强类型中间件、注意 String 和数值类型的区别）、容量（大规模缓存-如大规模模型的缓存需要专门考虑）
Tair	四个环境的子表格，注意变更点要全部列出：area、value、qps、ttl、容量、value 类型
Rds，加 ddl，加新索引	另见Sql SOP
服务保护平台	配置 key、线程池配置（coreSize、maxSize、maxQueueSize）、熔断规则（异常、超时配置）、重试规则（异常、超时配置）
服务网关	协议类型、URL、api名、appkey、服务名、方法名、TTL等，是否已验证，是否已灰度
OpenResty	四个环境的子表格，注意变更点要全部列出：域名、映射规则
分布式事务引擎	四个环境的子表格，注意变更点要全部列出：事务类型、domain、callbackMethod、配置
KMS	四个环境的子表格，注意变更点要全部列出： key 和 value
分布式序列号服务	四个环境的子表格，注意变更点要全部列出： key 和其他配置
业务团队基础数据配置	线上线下元数据配置
触达服务的分环境配置	线上线下消息配置

弱依赖变更

变更项	变更内容
其他服务的标识	其他服务的配置

SqlSOP

正向 Sql：
- 是否涉及状态、时间、业务主键？
- 索引是否唯一？是否有联合索引？
- 物理主键是自动生成还是外部生成-自动生成要考虑全局不唯一，以后迁移到 newSql 或者 NoSQL 会产生冲突。
- 业务主键是否全局唯一？
- 是否有扩展字段，扩展字段的表达空间有多大？
- 编号类的列长度是否足够？
- 需要考虑单位的列单位是什么？金额类的列精度是否足够？我们是否能够表达某类货币的最小结算单位。
- 基于时间的列是否需要考虑时区问题？是否可空？缺省值是不是 1970-01-01 00:00:00，如果不是可能导致 Java mapping为 null。
- mapper 是否总能正确地使用索引？要做 Java 和 Sql 的双校验，通常 Sql 先行，Java 代码后之。
- 是否可空和缺省值是否能够脱离 Java 代码工作？如果可脱离小心 Java mapping 为 null。
- insert 语句遇到异常怎么办，涉及范围多大，是否引起大事务？
- select 语句是否涉及分页，最好每页不要超过 1000 条记录。
- update/delete 语句的扫描范围多大，是否引起大事务？慎用负向和穷举条件。
- 归档类操作不能破坏业务完整性，破坏幂等性，破坏 consistency。如果有可能出问题，一定要想办法把订正数据和业务热数据错开。
- 新加外键列，一定要带有索引。
- 慎用 now()-current_sys_date 更糟糕。
- 是否有操作时间，是否有操作人。
逆向 Sql：
- 操作时间到底要不要还原？
- 使用新的操作时间可以将变化同步到数仓。
- 使用原操作时间可以将数据完全还原。

3.2.3 灰度方案

灰度过程

要不要分接口灰度、分业务灰度、分环境灰度？
要不要考虑单元化分组，考虑 A/B 互备分组？

沿用普通灰度过程，分若干组，逐步达到全量。

观察正常指标：

上游流量监控
下游流量监控
业务大盘监控。

观察异常指标：观察 error 指标（error log 和 error metric，log4j2.xml 的 root level 是否能够包含全部的 appender 和全部的 error level？）。

验收方案：

谁来验收？
多久时间后验收？
上线要看多久？发布后至少看一天

沿用普通灰度过程，分若干组，逐步达到全量：

分三个分组。
非高峰期发布。
发布第一分组观察 10 分钟，观察：业务大盘、错误监控 problem、其他核对平台处理结果、第一分组机器日志
无问题继续发布剩余分组，观察 10 分钟再发布下一分组。

验收者：

多方验收：产品、qa 和其他系统工程师，输出结果的验收标准。
发布一天后观察剩余数据：
- 业务大盘
- 错误监控 problem

灰度流量设计（要不要压测，要不要灰度开关，要不要调节流量？）
暂时不需要打开灰度开关

3.2.4 监控方案

复用老监控项

异常指标监控（是否复用监控的兜底异常）：
- rpc 调用失败数的绝对值大于阈值告警
- sql transaction 失败数的绝对值大于阈值告警
- rpc 的成功率小于阈值告警
- sql 的成功率小于阈值告警
- rpc 提供服务失败数的绝对值大于阈值告警
- rpc 提供服务成功率小于阈值告警
业务指标监控：
- 业务核心大盘
- 基础指标大盘一，业务监控大盘一。
- 基础指标大盘一，向下监控大盘。
- 基础指标大盘二，向上监控大盘。
中间件系统指标监控：
服务系统指标监控：
操作系统性能指标监控：