api-status-communication

API 状态沟通

你正在设计 API 平台如何向外部使用者说明当前情况：状态页、事件更新、公开事后复盘、SLA/SLO 报告和维护通知。交付成果是一套沟通实践，而非监控技术栈：指标测量属于平台的可观测性工具；你负责决定外界看到什么，以及何时看到。

以下每个步骤都以可信度为设计约束。状态页首先是信任信号，其次才是技术工具；有记录的失效模式是“状态作秀”：一个有来源的案例（OneUptime）显示，在一次持续 54 分钟的事件中，页面前 35 分钟一直显示正常，因为必须由人工决定何时切换状态。

信任流失的明显表现，是用户转向第三方投诉聚合平台（如 DownDetector）——用户选择它们并非因为它们更准确，而是因为它们不受发生故障的公司控制。将这种转移视为这套实践的失败指标，并在整个过程中将状态信息与真实监控挂钩，而非由人工把关。

记忆（建议）： 如果记忆存储在文件中，可考虑使用 developer-platform-context.md；如果使用其他记忆系统，则以其为准。该文件仅供参考，并非强制要求。将不同任务的信息分开放在不同章节中。完成的任务应予以删除。为任务添加日期；一般项目背景则不添加日期。不同任务中的部分访谈回答可能有所不同。

澄清问题

设计任何内容之前先询问以下问题；每个答案都会影响后续步骤。将问题合并询问——这是一项战术设计任务，而非战略访谈。

1. 已有状态页，还是从零开始？如果已有，请提供其 URL 以及最近 2–3 起事件的完整更新历史。
2. 目前状态由监控自动设置，还是由人工切换？已有哪类健康检查、延迟阈值和正常运行时间探测？
3. 谁会查看页面：负责集成的开发者、业务相关方／终端客户、企业客户——各自所占比例如何？（见下一节）
4. 是否有附带违约后果的合同 SLA？是否有合同规定最低维护通知时长？
5. 状态页是否与平台共用基础设施（相同的 DNS、CDN、云账户）？（这会影响步骤 3 中的渠道冗余）
6. 最近几起事件中，使用者实际是如何得知情况的？是否有第三方比状态页更早报告故障？
7. 截止日期和工作量上限——分为三个小问题：
   • 这套实践最迟何时必须上线？
   • 这是一次糟糕事件后的临时修复，还是一项要持续多年、不断积累价值的信任资产？
   • 可投入哪些资源：接入监控的工程工时、负责保持更新节奏的值班轮班、按消息收费渠道的预算？

设置问题 7，是因为渠道和事后复盘的选项在工作量和价值持续时间上差异很大，而且没有问题 7 的答案，就无法确定步骤 3 和步骤 5 中的任何优先级。

• 严格的截止日期意味着优先选择托管工具几乎免费提供的层级。
• 要打造持续增值的资产，则应优先考虑带外冗余和深入的复盘报告。

如果你的运行环境具备持久记忆，请保存这套实践的核心决策：组件模型和合并规则、升级阈值、渠道组合、事后复盘深度策略、已发布 SLA 的边界情况。之后的运行——无论是实时事件、事后复盘还是维护通知——都可以从这套实践出发，而不必重新推导。

读者角色

无论是谁购买了产品，事故期间查看状态页的人都可按角色划分，而两种角色需要不同的页面：

• 集成开发者——需要组件级技术细节：涉及哪些端点、区域范围、延迟数据、时间戳，以及足够详尽、值得信赖的事后复盘。他们会将状态接入自己的告警系统，因此机器可读的推送渠道（webhook、RSS）至关重要。
• 业务相关方和终端客户——需要通俗易懂的信息：是否发生故障、影响范围是什么、何时能修复。对他们来说，延迟指标只会造成干扰。

当 API 提供商的受众构成有此需求时，按受众分层提供页面已是成熟做法：

• 面向公众的开发者页面，提供 API 级别的详细信息。
• 通过 SSO 访问的企业页面，展示 SLA 合规情况。
• 面向终端用户的通俗信息。

默认采用一个面向公众的开发者页面；只有当问题 3 表明确实存在第二类受众时，才增加分层页面——每增加一层，就多了一个需要在实时事故期间保持信息一致的页面。

工作流

1. 建立状态用语和组件粒度模型。
2. 将状态接入监控——这是建立信任的关键一步。
3. 选择渠道：供用户主动查看的页面，加上推送订阅。
4. 设计事故生命周期沟通流程。
5. 制定事后复盘政策。
6. 发布 SLA/SLO 报告。
7. 制定维护窗口规范。

以下各节将按顺序介绍每个步骤。

1. 建立状态和组件模型

• 使用以下四种事实上的事故生命周期状态。订阅者已经熟悉这套用语（这是 Statuspage 的用语，也是整个行业通用的用语）；自定义一套只会增加理解成本，没有任何好处。
  • Investigating——已收到告警，正在调查潜在问题。
  • Identified——已确认原因或受影响的组件。
  • Monitoring——已部署修复，正在观察情况。
  • Resolved
• 将组件严重程度建模为影响范围，而非用户感受到的严重程度——这是这里影响最大的单项决策。
  • 性能下降：所有人都能使用，但速度变慢。
  • 部分中断：部分用户（例如某个区域）无法使用。
  • 重大中断：所有人都无法使用。
• 将页面的视觉状态限制为四种（正常／性能下降／部分中断／重大中断，即行业通用的绿、黄、橙、红）。在事故期间，读者无法在脑中处理许多组件对应五种严重程度的矩阵。
• 根据状态最差的组件汇总顶层页面状态，并记录所选的状态合并规则，以便始终如一地应用，而不是每次事故都重新争论。
• 根据用户对产品的认知模型，而非内部架构，选择组件粒度——几十个微服务名称会让页面变得杂乱，恰恰让它在最需要清晰易读时无法读懂。将组件归纳为少数用户易于识别的类别（例如 API、仪表盘、webhook、文档），而不是列出一长串内部组件。
• 按区域标明区域性事故：一个数据中心宕机时，应显示为特定范围内的部分中断，而非笼统的“性能下降”，以免让其他地区的用户担心——Cloudflare 的状态页正是出于这个原因按区域显示状态。
• 现在就注意正常运行时间计算的影响：按照惯例，在 SLA 计算中，性能下降按 0% 停机时间计，因此醒目的正常运行时间数据可能看起来非常出色，却掩盖了真实事故。第 6 步将介绍如何诚实报告这一情况。

2. 将状态页与监控联动

• 将页面状态直接关联到健康检查、延迟阈值和正常运行时间数据。不应由人工把关来决定客户「是否值得知情」——正是这道关卡造成了那场持续 35 分钟的绿色谎言。
• 根据监控警报自动创建 调查中 事件；然后由人工补充实质内容、影响范围和更新频率。人工的职责是补充信息，而不是首次披露。
• 写下你自己的分阶段升级流程——明确规定内部事件何时转为公开沟通。参考下方可引用的 Cloudflare 分阶段流程，并设定你自己的阈值。
  1. 事件触发警报。
  2. 部分警报升级为值得关注的事件。
  3. 所有事件都会经过分诊。
  4. 部分事件升级为问题。
  5. 「重大」问题触发状态页更新。
  6. P1 级重大问题必须发布完整的事件报告。
• 至少加入一个工作流级探测（模拟真实的多步骤用户旅程），而不只是基础设施检查：基础设施正常和产品不可用是两种不同的说法。作为警示案例，资料来源中提到 Sentry：一家零售商的运行时间显示完美无缺，但某个用户群体的结账功能却悄然失效。
• 坦诚面对细粒度与整体状态之间的张力，而不是武断地给出结论：几乎在任何真实的服务中断期间，大多数组件仍会显示绿色；而 ThousandEyes 指出，被拒之门外的用户并不关心除了身份验证以外的所有功能是否正常。
• 满屏红色的页面会从另一个方向辜负读者——这就是针对 AWS 的「一片绿色圆点海洋」批评，双方的问题都存在。第 1 步的细粒度状态正是这里的缓解措施，而不是一句口号。
• 追求准确、适度的告警，而不是最大程度的警报。长期保持绿色的记录若真实可信，本身就很有价值（Splunk）：这样一次服务中断就不会让人觉得「整个产品都不可靠」。
• 相信透明会带来回报：围绕 Cloudflare 做法记录的信任与透明度悖论在于，坦诚承认失败，反而能增强客户对服务提供商处理下一次故障的能力的信任。妥善处理的公开事件是一种证明，而不只是责任。

3. 选择渠道

状态页是一种拉取式渠道——客户必须主动查看。订阅（电子邮件、RSS、webhook、SMS）则是推送式渠道。Cloudflare 对自家仅支持拉取式的页面进行自我批评时指出，它会在实时事故期间造成“混乱和资源浪费”——这正是设计上的考量：成熟的实践需要兼顾两者，而非二选一。

• 效率：页面 + 内置电子邮件/RSS 订阅 > webhook 推送 > SMS 推送

• 实时事故期间的价值：任何推送渠道 > 仅有拉取式页面

• 工作量：SMS 推送 > webhook 推送 > 页面 + 电子邮件/RSS 订阅

• 默认选项：启用电子邮件和 RSS 订阅的状态页。 使用托管状态工具时，这几乎不费什么成本；订阅是减轻支持负担的手段，而非礼节性服务——让受影响的用户自行查找答案，可显著减少事故期间收到的咨询工单（Atlassian）。

• 当问题 3 的答案是开发者时，升级为 webhook 推送： 集成方受众会将状态接入自己的告警系统，而机器可读的推送正是实现这一点的关键。如果平台已经运行 webhook 基础设施，这一档的成本就很低——传递机制属于相关项目 samber/developer-platform-skills@webhook-platform-design 的范畴；你只需定义状态事件。

• 面向有合同 SLA 的企业客户，升级为 SMS/电话级推送： 这类受众的合同（问题 4）通常会有此要求；也只有这一档的单条消息成本和送达率保障工作足以证明其投入是合理的。

• 删除，而非降级：没有合同受众时的 SMS/电话级推送。 当问题 4 的答案表明没有附带后果的 SLA，且问题 3 表明没有企业级服务时，这一档应直接从选项中移除，而不是放在菜单底部——单条消息成本和送达率保障工作没有服务对象。不要把它排在最后，因为每次事故看起来很严重时，“以后可以加 SMS”都会再次变成范围需求。重新纳入的触发条件：第一份明确指定通知渠道的合同。

• 最容易被搁置的选项：带外冗余——将页面托管在平台自身基础设施之外，并至少保留一个在 DNS 或 CDN 故障时仍能使用的渠道。它的工作量最高，在顺利时又看不到价值，因此每轮效率比较都会落败；问题 5 决定是否将它提级，因为状态页若与平台同时宕机，就会在唯一重要的时刻毫无用处。状态页在本应报告故障的宕机期间无法访问，是有记录的故障模式。

• 此排序是默认方案，而非铁律。请根据你对用户的了解重新排序，并说明哪个答案调整了哪个档位：

  • 企业客户占比较高，则提高 SMS 的优先级。
  • 集成方受众已经在使用平台的 webhook，则 webhook 推送几乎不增加成本。
  • 如果页面已托管在共享基础设施上，冗余就应成为首要任务，而非最后一项。
  • 问题 7 的工作量上限决定首轮能落实多少个档位。

4. 设计事件生命周期沟通实践

按照步骤 1 中的四种状态处理每起事件，并依据 Atlassian 的五项实践——行业检查清单——撰写更新：

1. 及时——哪怕只是说“仍在调查，暂时没有新进展”，也胜过保持沉默；沉默会让读者往最坏处想。
2. 频繁——承诺固定的更新频率：每次更新都要说明下次更新时间，并且即使没有新消息，也要兑现承诺。
3. 准确——陈述事实，而非猜测；说明已确认的情况，而非怀疑的情况。
4. 各渠道保持一致——状态页、社交媒体和电子邮件必须在同一时间发布相同内容；事件发生期间，客户只会觉得“你们的服务出了问题”，不管技术上是谁的责任。
5. 勇于承担并展现同理心——承认造成的影响，在适当时道歉；即使根本原因确实在上游供应商，也绝不推卸责任。

使用通俗语言为事件命名，说明问题性质（“eu-west 的 REST API 错误率升高”），绝不要使用内部代号——内部模板名称仅用于团队组织，不得对外公开。用书面形式明确说明一次如何将内部严重程度分类（SEV1-4 或同类分类）映射到组件状态，让响应人员知道该切换什么状态，无需在事件发生时争论。

参见 references/incident-update-templates.md，了解各状态的更新模板、严重程度到组件状态的映射，以及好坏更新示例。

5. 制定事后复盘政策

是否对外发布事后复盘是一项慎重的决定——它会影响法律风险、客户信任和可靠性文化。根据相关资料，开发者平台的默认倾向是照常发布。

Google SRE 认为，事后复盘的价值与其带来的学习成正比，因此分享复盘，“甚至可能与客户分享”，会倍增其价值。Google SRE 还称，经过深思熟虑且诚实的事后复盘是“恢复受损信任的关键工具”。

每次事件的发布内容层级：

• 重建开发者信任的价值：engineering-blog postmortem > status-page summary postmortem > resolved-note only

• 所需投入：engineering-blog postmortem > status-page summary postmortem > resolved-note only

• 合规成本：engineering-blog postmortem > status-page summary postmortem > resolved-note only——深入的复盘会因原因表述和第三方实名而触发法务与传播团队审批；而且发布后每一层级都不可逆：你可以追加更正，却无法撤回已经被企业客户截图保存的承认。

• 效率：status-page summary postmortem > resolved-note only > engineering-blog postmortem

• 默认层级：状态页摘要式事后复盘——用几段文字说明影响、原因、修复和预防措施，并附在事件条目中。任何消费者明显感受到的事件都应提供此类复盘。

• 对影响短暂且除事件条目本身外没有消费者可见影响的情况，降至仅发布解决说明。

• 对重大（P1 级）事件，以及明显动摇信任的情况，提升至完整的公开事后复盘。 Cloudflare 要求此级别的事件发布事件报告。对于 API 受众，工程博客是合适的渠道：这类受众具有技术背景，会阅读深入版本来建立信任，而不只是确认问题已解决。

• 完整的博客复盘是最少采用的层级——价值最高、投入最大、在效率方面总是落后——而上述提升条件正是凌驾于此的理由。这一排序是默认方案，不是铁律：应结合问题 7 和用户的资源重新排序，并说明哪个答案改变了哪个层级。

• 如果工程博客活跃且作者训练有素，深入复盘几乎无需额外投入，投入方面的排序就会反转。

• 如果是在严格期限内完成的一次性修复，则所有事件都维持在摘要层级。

对外文档应围绕客户真正关心的三个问题展开——为什么会发生这种情况？情况可能会更糟吗？你们如何确保这种情况不再发生？并且要做到不归咎于个人：具体来说，绝不提及任何个人。没有后续跟进的事后复盘只是作秀；行动项的完成情况是衡量这项技能的一部分，而非事后才考虑的事情。

有关完整结构、从内部内容筛选为对外内容的步骤、不归咎于个人的写作规则及模板，请参阅 references/public-postmortem-structure.md。

6. 发布 SLA/SLO 报告

• 在所有公开内容中区分这三个术语：
  • SLI 是测量指标。
  • SLO 是内部目标。
  • SLA 是附带后果的合同承诺。
• 把私下视为理想目标的数字公开，会引发纠纷。
• 公开的 SLA/正常运行时间页面与状态页面是不同的内容，不是换个名称：前者展示历史正常运行时间与承诺的对比；后者展示当前发生的具体事件，也可以涵盖没有正式 SLA 的组件。成熟的做法会同时提供两者——它们分别回答“是否达到了目标”和“现在发生了什么”。
• 在公布任何数字之前，先书面明确边界情况；每一项都可能成为纠纷来源：
  • 响应时间超过什么阈值才算服务中断。
  • SLA 是按整个服务评估，还是按受影响的组件分别评估。
  • 只有在充分提前通知的情况下，计划内维护才会被排除在外。
• 把百分比转化为实际影响：除了百分比，还要说明每月允许的停机分钟数；如采用错误预算模型，还要显示错误预算消耗情况。
• 在醒目的正常运行时间数据旁公布事件历史。第 1 步中关于正常运行时间计算的注意事项意味着，单看百分比可能会掩盖实际服务退化——诚实的页面应让读者对照相关事件核实数字。“只监控不报告，就只是旁观”；报告能让指标成为兑现承诺的证据，或坦诚承认未能兑现承诺。

边界情况定义、百分比与分钟数对照表以及示例，请参阅 references/sla-maintenance-reporting.md。

7. 制定维护窗口惯例

本技能负责提前 24 小时至 2 周通知的时间范围。提前 6 至 12 个月通知弃用和破坏性变更，则属于兄弟技能 samber/developer-platform-skills@api-versioning-policy 的职责——维护窗口和弃用是时间安排不同的两种沟通方式；切勿将它们混为一则公告。

• 根据影响和受众调整通知时间：
  • 对于影响较小的轻微工作，提前约 24 小时通知。
  • 对于重大变更，提前数周通知并发送提醒。
  • 按照惯例，企业客户至少会提前一周收到通知，即使面向自助服务用户的同类变更会在当天通知。
• 检查问题 4 中的合同是否规定了最低通知期限——5 个工作日的合同最低期限就是一个记录在案的真实案例。
• 明确写出准确的开始和结束时间，并注明时区——时间含糊是维护安排引发混乱的最常见原因；安排时应选择受影响用户的低流量时段，而不是服务提供方的办公时间。
• 准确说明范围：哪些端点和功能会受到影响，哪些仍可用；切勿笼统地说“API 将不可用”。
• 即使维护窗口很短，也要发布开始和完成确认；明确可见的进度信息能表明工作在受控范围内。
• 通过状态页面和至少一个推送渠道发布通知，切勿只使用状态页面（第 3 步中关于拉取与推送的逻辑同样适用于计划内工作）。
• SLA 对维护的免责不代表信任也能免责：即使计算规则不追究责任，沟通不当的维护窗口仍会损害信任。

通知模板请参阅 references/sla-maintenance-reporting.md。

失效模式

反模式检查清单——每一项都是直接的审计发现：

• 状态作秀：监控显示红色，页面却显示绿色，只因为人还没决定切换状态。
• 第三方聚合平台或社交媒体比状态页更早报告故障。
• 静默降级：所有人的延迟都翻倍了，却没有发布任何信息，因为服务“技术上仍然在线”。
• 组件照搬内部架构；页面在事故期间难以阅读。
• 严重程度依据主观感受建模，而不是影响范围。
• 状态页与平台共用基础设施，并随平台一起宕机。
• 事故仍处于进行中，却没有更新，也没有承诺下次更新时间。
• 公开更新把责任推给上游供应商。
• 复盘点名某个个人，或其中的行动项悄无声息地不了了之。
• 只公布总体正常运行时间百分比，却不附上事故历史。
• 维护通知没有时区，或笼统地说“API 将停机”。

衡量指标

• 从检测到披露的延迟：首次公开状态变更由监控触发；衡量每次事故从警报触发到页面更新的时间，并将其缩短至几分钟。延迟达到几十分钟，说明流程中仍有人为关卡——35 分钟仍显示绿色的案例是反面基准。
• 第三方先行披露：没有任何事故是由外部聚合平台或社交媒体帖文抢先于页面披露的。按每次事故进行二元判定。
• 生命周期完整性：每次事故都显示全部四种状态及其时间戳，并且每次更新承诺的下次更新时间都得到遵守。
• 复盘跟进情况：跟踪公开行动项的完成情况；低于约 50% 是资料指出的复盘沦为作秀的临界值，因此应将目标设得更高，并据此报告。
• 支持请求量趋势：随着状态订阅人数增加，事故期间收到的请求应减少——这是资料指出的趋势方向（Atlassian）；行业内没有统一门槛，因此应以你们下一次事故为基线，并持续改进。

前三项是门槛——反复迭代设计，直到满足要求。后两项是后续需要关注的趋势指标，永远不要将它们设为通过门槛。

调用示例

• “为我们的公共 API 设计一个状态页——目前只有出问题时我们才会发推文。”
• “昨天发生故障时，我们的状态页一直显示绿色，客户是从 DownDetector 才得知的——改进处理方式，而不只是页面。”
• “为上周持续 90 分钟的 API 故障撰写公开复盘，并告诉我应该把它放在状态页还是工程博客上。”
• “我们将在十天后停用 API 两小时进行迁移——规划维护通知。”

参考资料

• references/incident-update-templates.md - 各状态的更新模板、严重程度与组件状态的映射、优劣更新对照，以及扩展版的五项实践检查清单。
• references/public-postmortem-structure.md - 公开事后复盘的结构、内部信息对外发布的筛选规则、无责写作规范、行动项跟踪及框架。
• references/sla-maintenance-reporting.md - SLI/SLO/SLA 的区别、边界情况定义、百分比到分钟数对照表、维护通知的范围调整及示例。

另请参阅同一合集中的内容：

• samber/developer-platform-skills@api-error-design - 设计单个失败请求的返回内容；当大规模故障由平台引起时，本技能负责告知所有人。
• samber/developer-platform-skills@api-versioning-policy - 负责沟通未来 6-12 个月内的弃用和破坏性变更；本技能仅涵盖提前 2 周发布的维护通知。
• samber/developer-platform-skills@webhook-platform-design - 状态页的 webhook 推送渠道所依赖的 webhook 投递机制，以及 webhook 本身的投递状态。
• samber/developer-platform-skills@integration-error-observability - 面向单个使用者呈现各集成的错误；本技能则负责向多人广播。
• samber/developer-platform-skills@developer-portal-design - 将状态页作为一级入口链接到其中的门户。
• samber/developer-platform-skills@public-roadmap-strategy - 计划延期的路线图事项应作为路线图更新，而非事故；绝不能发布在状态页上。