Software Engineering Guide
12.3

View in English

12.3 模板

这些模板都是可直接复制粘贴使用的起点。你可以把任意一份模板搬到你的 wiki、代码仓库或工单系统中，并填写方括号中的占位符。斜体注释和行内注释说明了每个部分应当填写的内容；填写完毕后请将其删除。保持模板的轻量：如果跳过一份模板比填写它更快，那它就不会被使用。你可以根据自己组织的情况调整标题和分节，但要保留每个部分的初衷。

下文使用了以下几项约定：

  • [方括号] 中的文字是需要替换的占位符。
  • 斜体 文字或 <!-- 注释 --> 是需要删除的指导说明。
  • 在仍能回答所有问题的前提下，让完成后的文档尽可能简短。

架构决策记录（ADR）

# ADR [NNNN]：[决策的简短标题]

- 状态：[提议中 | 已接受 | 已弃用 | 被 ADR-XXXX 取代]
- 日期：[YYYY-MM-DD]
- 决策者：[姓名或角色]
- 已咨询：[姓名或角色]

## 背景

<!-- 促成这项决策的问题、驱动力或约束是什么？
     以中立的方式陈述事实和需求。只包含未来读者
     理解这项决策为何是必要的所需的内容。 -->

## 决策

<!-- 用一两句清晰的话陈述所做的选择："我们将……" -->

## 已考虑的替代方案

<!-- 列出你权衡过的现实可行方案，以及每个方案
     被选中或被否决的原因。此处至少应列出两个
     备选方案。 -->

- 方案 A：[摘要]；被否决的原因是 [原因]。
- 方案 B：[摘要]；被否决的原因是 [原因]。
- 已选方案：[摘要]；选择的原因是 [原因]。

## 后果

<!-- 这项决策带来的诚实结果，无论好坏。 -->

- 积极影响：[获得的收益]
- 消极影响：[需要承担的成本、风险或限制]
- 后续事项：[由此触发的迁移工作、新任务或决策]

## 相关内容

<!-- 与之相关的既往 ADR、RFC、工单或文档的链接。 -->

RFC / 设计文档

# RFC：[标题]

- 作者：[姓名]
- 状态：[草稿 | 评审中 | 已批准 | 已拒绝 | 已实现]
- 评审人：[姓名或角色]
- 创建日期：[YYYY-MM-DD]
- 最后更新：[YYYY-MM-DD]
- 工单 / 追踪链接：[链接]

## 摘要

<!-- 用一段话说明：本提案提出了什么、为什么重要。
     读者应当仅凭这一部分就能把握核心内容。 -->

## 问题与动机

<!-- 我们要解决的是什么问题？谁会受到影响？如果
     什么都不做会发生什么？请包含相关背景和约束。 -->

## 目标与非目标

- 目标：[成功的样子是什么，尽可能给出可衡量的标准]
- 非目标：[明确排除在范围之外的内容，以防止范围蔓延]

## 提议的设计

<!-- 文档的核心部分。描述所采用的方法、架构、
     数据模型、接口和关键流程。在有助于说明问题
     的地方使用图示。要解释它是如何工作的，而不
     仅仅是它是什么。 -->

## 已考虑的替代方案

<!-- 其他方案，以及未被选中的原因。向读者表明
     设计空间已被充分探索。 -->

## 影响与风险

- 安全与隐私：[影响和缓解措施]
- 性能与规模：[预期负载和表现]
- 可运维性：[监控、故障模式、发布、回滚]
- 成本：[基础设施或许可方面的影响]
- 向后兼容性：[迁移和弃用方案]

## 测试与发布计划

<!-- 变更将如何被验证并安全发布。 -->

## 待解决的问题

<!-- 你希望评审人给出意见的悬而未决的问题。 -->

事后总结 / 事件评审（无责）

# 事后总结：[事件标题]

- 事件 ID：[ID]
- 事件发生日期：[YYYY-MM-DD]
- 作者：[姓名]
- 状态：[草稿 | 定稿]
- 严重级别：[SEV1 | SEV2 | SEV3]

> 本评审是无责的。我们关注的是系统和诱因，而不是
> 追究个人责任。目标是从中吸取教训，防止再次发生。

## 摘要

<!-- 用两三句话说明：发生了什么、造成了什么影响，
     以及如何解决的，要让非专业人士也能看懂。 -->

## 影响

- 持续时间：[从开始时间到恢复时间，注明时区]
- 受影响用户：[范围和数量]
- 业务影响：[营收、SLA、声誉或其他方面]

## 时间线

<!-- 带时间戳的、真实的事件顺序。应包含检测、
     升级、关键操作和恢复过程。 -->

- [HH:MM] [事件]
- [HH:MM] [事件]

## 诱因

<!-- 导致该事件发生的一连串条件。相较于单一根因，
     更推荐使用"诱因"这一表述。 -->

## 检测与响应

- 是如何被检测到的？[告警、客户反馈等]
- 什么因素帮助了响应工作？
- 什么因素拖慢了响应工作？

## 做得好的地方

<!-- 认可那些有效发挥了作用的举措和保障措施。 -->

## 行动项

<!-- 要具体、有明确负责人、有截止日期。涵盖预防、
     检测和缓解。将其纳入常规待办事项列表跟踪。 -->

| 行动项 | 负责人 | 截止日期 | 类型（预防/检测/缓解） | 工单 |
|--------|-------|----------|--------------------------------|--------|
| [行动项] | [姓名] | [日期] | [类型] | [链接] |

## 经验教训

<!-- 更广泛的组织应当从中汲取的教训。 -->

威胁模型（基于 STRIDE）

# 威胁模型：[系统或功能名称]

- 作者：[姓名]
- 日期：[YYYY-MM-DD]
- 评审人：[安全联系人、负责人]
- 范围：[涵盖和不涵盖的内容]

## 系统概述

<!-- 简要描述该系统、其目的及其用户。 -->

## 资产

<!-- 值得保护的对象：数据、凭据、功能、声誉。
     注明每一项的敏感程度。 -->

## 信任边界与数据流

<!-- 描述或绘图展示各组件、数据存储、外部实体，
     以及信任发生变化的边界。 -->

## 威胁（STRIDE）

<!-- 针对每个元素，逐一考虑 STRIDE 各类别。记录
     每一个可信的威胁、其风险，以及缓解措施或已
     接受的风险。 -->

| 威胁 | STRIDE 类别 | 受影响元素 | 风险（低/中/高） | 缓解措施 | 状态 |
|--------|-----------------|------------------|--------------|------------|--------|
| [威胁] | 伪装（Spoofing） | [元素] | [风险] | [控制措施] | [待处理/已缓解/已接受] |
| [威胁] | 篡改（Tampering） | [元素] | [风险] | [控制措施] | [状态] |
| [威胁] | 抵赖（Repudiation） | [元素] | [风险] | [控制措施] | [状态] |
| [威胁] | 信息泄露（Information disclosure） | [元素] | [风险] | [控制措施] | [状态] |
| [威胁] | 拒绝服务（Denial of service） | [元素] | [风险] | [控制措施] | [状态] |
| [威胁] | 权限提升（Elevation of privilege） | [元素] | [风险] | [控制措施] | [状态] |

## 假设与依赖

<!-- 所依赖的安全假设，以及所信任的外部控制措施。 -->

## 待解决问题与后续事项

<!-- 需要进一步处理的威胁，以工单形式跟踪。 -->

操作手册

# 操作手册：[任务或场景名称]

- 服务：[服务名称]
- 负责人：[团队]
- 最后审阅日期：[YYYY-MM-DD]
- 相关告警：[告警名称]

## 目的

<!-- 何时应使用本操作手册，以及它能完成什么。 -->

## 前提条件

<!-- 开始之前所需的访问权限、工具和权限。 -->

## 检测 / 症状

<!-- 操作人员会观察到什么：告警、错误特征、仪表盘。 -->

## 诊断

<!-- 逐步排查以确认问题、缩小原因范围的步骤。
     请附上确切的命令、查询语句或仪表盘链接。 -->

1. [步骤及预期结果]
2. [步骤及预期结果]

## 解决方案

<!-- 具体的、按顺序排列的修复或缓解步骤。注明任何
     有风险或不可逆的步骤，以及如何验证是否成功。 -->

1. [步骤]
2. [验证是否已恢复]

## 回滚

<!-- 如果解决方案使情况变得更糟，如何撤销这些操作。 -->

## 升级

<!-- 联系谁、何时升级。包括第二线待命人员、
     负责团队和供应商联系方式。 -->

## 参考资料

<!-- 仪表盘、相关操作手册、架构文档。 -->

服务 README / 服务目录条目

# [服务名称]

- 负责团队：[团队]
- 待命安排：[排班链接]
- 层级 / 重要程度：[Tier 1 | 2 | 3]
- 代码仓库：[链接]
- 状态：[使用中 | 已弃用]

## 服务功能

<!-- 用一段话说明该服务的职责及其消费者。 -->

## 架构

<!-- 关键组件、依赖关系（上游和下游），以及设计
     文档或架构图的链接。 -->

## 接口

- API / 接口端点：[规范文档链接]
- 发布 / 消费的事件：[主题]
- 数据存储：[数据库、缓存、存储桶]

## 运行时与部署

- 环境：[开发、预发布、生产]
- 部署方式：[流水线链接和流程]
- 配置与功能开关：[存放位置及使用方式]

## 可观测性

- 仪表盘：[链接]
- 告警：[链接]
- 日志：[存放位置]
- SLO：[链接]

## 运维

- 操作手册：[链接]
- 常见任务：[扩缩容、重启、数据回填]
- 已知问题与限制：[说明]

## 快速上手（面向新贡献者）

<!-- 如何在本地构建、测试和运行。 -->

## 联系方式

- Slack / 聊天频道：[链接]
- 升级路径：[路径]

SLO / 错误预算策略

# SLO 与错误预算策略：[服务或用户旅程名称]

- 负责人：[团队]
- 生效日期：[YYYY-MM-DD]
- 复审节奏：[例如每季度一次]

## 服务水平指标（SLI）

<!-- 精确定义每个 SLI：所度量的量、度量方式，
     以及数据来自何处（理想情况下是用户视角）。 -->

| SLI | 定义 | 数据来源 |
|-----|-----------|-------------|
| 可用性 | [例如：成功请求数 / 总请求数] | [来源] |
| 延迟 | [例如：低于 X 毫秒的请求占比] | [来源] |

## 目标（SLO）

| SLI | 目标值 | 度量窗口 |
|-----|--------|--------------------|
| 可用性 | [例如：99.9%] | [例如：滚动 28 天] |
| 延迟 | [例如：95% 低于 300 毫秒] | [滚动 28 天] |

## 错误预算

<!-- 允许的不可靠程度：100% 减去目标值，在该
     窗口期内计算。用具体的方式表达预算
     （例如：每月分钟数）。 -->

- 预算：[推导出的额度]

## 预算耗尽时的策略

<!-- 双方约定的后果。要具体且可执行。 -->

- [例如：冻结非关键功能发布，直至预算恢复。]
- [例如：在下一个规划周期中优先安排可靠性工作。]
- [例如：如果连续两个窗口期都突破预算，升级至工程领导层。]

## 预算充裕时的策略

<!-- 团队可以承担哪些额外风险，例如更快速的发布。 -->

## 告警

<!-- 与该 SLO 绑定的消耗速率告警和阈值。 -->

风险登记条目

## 风险：[风险简短标题]

- 风险 ID：[ID]
- 提出日期：[YYYY-MM-DD]
- 负责人：[负责管理该风险的姓名或角色]
- 类别：[安全 | 运营 | 合规 | 财务 | 交付 | 供应商]
- 状态：[未处理 | 缓解中 | 已接受 | 已关闭]

### 描述

<!-- 按"原因 -> 事件 -> 后果"的方式陈述该风险。
     可能发生什么，以及为什么重要。 -->

### 评估

- 可能性：[低 | 中 | 高]
- 影响程度：[低 | 中 | 高]
- 总体评级：[由可能性 × 影响程度推导得出]

### 现有控制措施

<!-- 目前已经在降低该风险的措施。 -->

### 缓解计划

<!-- 用于降低可能性或影响程度的计划行动，注明
     负责人和日期。如果选择接受该风险，请记录是
     谁接受的、以及原因。 -->

| 行动项 | 负责人 | 截止日期 | 状态 |
|--------|-------|----------|--------|
| [行动项] | [姓名] | [日期] | [状态] |

### 复审

- 下次复审日期：[YYYY-MM-DD]
- 决定 / 备注：[任何接受签署或变更情况]

项目一页纸 / 产品简报

# [项目或产品名称]：一页纸简报

- 发起人：[姓名]
- 负责人：[姓名]
- 日期：[YYYY-MM-DD]
- 状态：[构想中 | 已批准 | 进行中 | 已上线]

## 问题

<!-- 用一段话说明：客户或业务面临的问题，以及能
     证明该问题真实存在、值得解决的证据。 -->

## 目标受众

<!-- 谁有这个问题，谁会从解决这个问题中受益。 -->

## 提议的解决方案

<!-- 简要描述我们将构建或改变的内容。保持在意图
     层面即可，不涉及实现细节。 -->

## 为何是现在

<!-- 为什么现在做这件事，而不是以后再做。 -->

## 成功指标

<!-- 我们将如何判断它是否成功。优先选择可衡量的
     结果。 -->

- [指标及目标值]

## 范围

- 范围之内：[我们将要做的事]
- 范围之外：[我们不会做的事]

## 风险与待解决问题

<!-- 主要的不确定性和依赖关系。 -->

## 大致计划与里程碑

<!-- 高层次的阶段划分和大致时间安排。 -->

## 成本与资源

<!-- 所需的人力、时间和预算。 -->

待命交接记录

# 待命交接：[YYYY-MM-DD]

- 交接人：[姓名]
- 接手人：[姓名]
- 相关服务：[名称]

## 总体状态

<!-- 用一句话说明：平静、告警频发，或存在正在
     处理的问题。 -->

## 未解决的事件

<!-- 下一位响应者必须了解的、正在进行中或近期
     刚解决的事件，附上链接。 -->

- [事件、状态，以及尚待处理的部分]

## 进行中或计划中的变更

<!-- 可能引发告警的、正在进行的部署、迁移、
     维护窗口或实验。 -->

## 频发或不稳定的告警

<!-- 已触发的告警及其真实含义，避免误导下一
     位响应者。注明任何临时静默设置及其到期时间。 -->

## 需要留意的事项

<!-- 走势令人担忧的指标或系统。 -->

## 待处理的后续事项

<!-- 交给下一班次的任务，附上工单链接。 -->

## 备注

<!-- 其他有用信息：访问权限的特殊情况、供应商
     相关问题、背景信息。 -->

变更请求（用于受监管的变更控制）

# 变更请求：[变更标题]

- 变更 ID：[ID]
- 申请人：[姓名]
- 提交日期：[YYYY-MM-DD]
- 类型：[标准 | 常规 | 紧急]
- 优先级：[低 | 中 | 高]
- 状态：[已提交 | 已批准 | 已拒绝 | 已实施 | 已关闭]

## 变更描述

<!-- 变更内容是什么、为什么变更。引用相关工单
     或需求。 -->

## 受影响的系统和组件

<!-- 受影响的服务、数据、环境和用户。 -->

## 理由与业务影响

<!-- 进行此项变更的原因，以及不进行变更的影响。 -->

## 风险评估

- 风险等级：[低 | 中 | 高]
- 变更失败可能造成的影响：[描述]
- 对安全、隐私或合规方面的影响：[描述]

## 实施计划

<!-- 按顺序排列的步骤、责任方和时间安排。 -->

## 测试与验证计划

<!-- 变更前后将如何验证是否成功。 -->

## 撤回 / 回滚计划

<!-- 如果失败，如何撤销该变更，以及恢复所需时间。 -->

## 排期

- 建议窗口：[开始和结束时间，注明时区]
- 预计停机时间：[时长，或无]

## 审批

| 角色 | 姓名 | 决定 | 日期 |
|------|------|----------|------|
| 变更负责人 | [姓名] | [批准/拒绝] | [日期] |
| 技术评审人 | [姓名] | [批准/拒绝] | [日期] |
| 变更咨询委员会 | [姓名] | [批准/拒绝] | [日期] |

## 实施后复盘

<!-- 结果、遇到的问题，以及是否需要撤回。 -->

数据保护影响评估（DPIA）大纲

# 数据保护影响评估：[处理活动名称]

- 评估人：[姓名]
- 日期：[YYYY-MM-DD]
- 评审人：[数据保护官 / 隐私联系人]
- 状态：[草稿 | 已评审 | 已批准]

## 1. 处理活动描述

<!-- 处理了哪些个人数据、如何处理、由谁处理，
     以及处理目的。请包含从收集到删除的完整
     数据流向。 -->

- 数据主体：[数据所描述的对象]
- 数据类别：[个人数据的类型，注明任何特殊类别]
- 目的：[为何处理该数据]
- 接收方和处理者：[谁接收或处理该数据]
- 保留期限：[数据保留多久，以及删除方式]
- 国际传输：[目的地及传输机制]

## 2. 必要性与相称性

<!-- 该处理活动对于其目的而言是否必要？是否是
     侵入性最小的方案？合法依据或授权是什么？ -->

- 合法依据 / 授权：[每项目的对应的依据]
- 数据最小化：[每个字段为何是必要的]
- 准确性与保留期限的合理性说明：[备注]
- 如何支持数据主体的权利：[访问、删除等]

## 3. 征询意见

<!-- 已征询意见的利益相关方，以及在相关情况下
     征询过的数据主体。 -->

## 4. 对个人的风险

<!-- 识别隐私风险，并对每一项进行评级。 -->

| 对个人的风险 | 可能性 | 严重程度 | 总体评级 |
|---------------------|-----------|----------|---------|
| [例如：未经授权访问敏感数据] | [低/中/高] | [低/中/高] | [评级] |

## 5. 降低风险的措施

<!-- 针对每一项风险，说明缓解措施及采取措施后
     的剩余风险。 -->

| 风险 | 措施 | 剩余风险 | 接受人 |
|------|---------|---------------|-------------|
| [风险] | [控制措施] | [低/中/高] | [姓名] |

## 6. 结论与签署

- 剩余风险是否可接受：[是 | 否]
- 措施批准人：[姓名、角色]
- 是否需要征询监管机构意见：[是 | 否]
- 复审日期：[YYYY-MM-DD]