API 性能与可靠交付：缓存、幂等与异步事件

0. 元信息

• 主题路径：docs/topics/rest-api-design/subtopics/performance-/README.md
• 父主题：rest-api-design
• 主分类：Web 与后端
• 辅助分类：工程技术
• 适合对象：会写 HTTP handler、SQL 与自动化测试的后端开发者
• 建议周期：1～2 周（每周 6～8 小时）
• 前置知识：resource-http-contracts、security-governance
• 最终目标：覆盖 Cache-Control/ETag、条件更新、idempotency、Webhook 与异步可靠性

1. 学习路线

缓存策略 → ETag → 条件请求 → idempotency → outbox → Webhook 签名/重试

2. 阶段周数分配

精简子主题不固定周数。按 §3 顺序完成，卡住时回到 RFC、契约样例和可重复请求。

3. 九阶段表

4. 第一周任务

精简版省略固定日程。做一个最小正常请求，再补认证失败、非法输入、冲突、重试与超时。

5. 阶段通用验收

精简版省略；每个产出至少保留命令、预期、实际与版本。

6. 最终验收

精简版省略；以 §3 第 9 阶段和 §9.4 问题口述检查为准。

7. 综合项目

精简版省略；成果并入父主题电商商品 / 订单 API。

本主题贡献

• 在父主题 rest-api-design 的综合项目「电商商品 / 订单 API」中，本主题（API 性能与可靠交付）负责 HTTP 缓存、条件更新、Idempotency、Webhook 异步 四件套：把 §1 路线「缓存策略 → ETag → 条件请求 → idempotency → outbox → Webhook 签名/重试」落到商品 / 订单接口和 Webhook 出站。
• 工程动作：用 Cache-Control: private, max-age=60 与 ETag: "product-p_123-v7" 实现条件 GET 与 304；用 If-Match 强制 ETag 做并发更新（避免覆盖）；用 Idempotency-Key 在 POST /orders 上保证同 key + 同 body 一次结果（含 24 h 记忆化）；用 HMAC-SHA256 + X-Signature: sha256=... + timestamp 防 Webhook 重放与时间窗口外请求；用 Outbox 把支付结果异步投递到下游并配 dead-letter 兜底。
• 与 rest-api-design 其它子主题对接：复用 resource-http-contracts 的 application/problem+json 错误体（含 422 / 429 / 5xx）；为 security-governance 提交 traceid + signature headers（进 OTel context propagation）；为 openapi-operations 提供 traceparent 串联的发布清单。

交付物清单：

1. /cache.yaml + cache.md：GET /products/{id} 完整缓存策略（Cache-Control / ETag / Vary / Age）+ 304 命中率压测 ≥ 80% 的截图与 If-None-Match 报文；
2. /conditional.{py|go}：PUT /products/{id} 带 If-Match 412 实现 + 集成测试 6 条（含两个 client 并发改同一 ETag，互斥成功一次）；
3. /idempotency.*：POST /orders 用 Idempotency-Key（同 key + body 返回同结果；同 key + 不同 body 报 422），含 24 h 持久化（Redis 或 DB unique index 双重防护）；
4. /webhook.md + sig.{lua|python}：HMAC-SHA256 签名 + 时间戳容差（±300 s）+ partition key = order_id 顺序保证（含 partition rebalance 演练）的可重放证据，并补 Outbox 投递失败演练。

验收标准：

• 同一商品连续 GET 100 次后 304 命中率 ≥ 80%，且 server CPU 工作量减半；
• 同 Idempotency-Key 提交 5 次只产生 1 笔订单（DB unique index 验证 + Redis 去重日志验证）；
• Webhook 接收端 5 分钟内必到达 ≥ 99%（at-least-once + outbox 永久存储），签名验证失败率 < 0.1%；
• 并发改同一资源（ETag 不匹配）只有一个 200，其余 412。

8. 推荐资料

精简版省略；使用 §9.3 和 §9.6 Source。

9. 学习资料汇聚（v0.3 自包含）

9.1 背景与动机

覆盖 Cache-Control/ETag、条件更新、idempotency、Webhook 与异步可靠性。API 一旦被客户端依赖，错误的语义会变成多年兼容成本。我们用规范、可运行样例和失败测试约束选择。

9.2 概念地图

flowchart LR
  Design[设计] --> Contract[HTTP/OpenAPI 契约]
  Contract --> Runtime[实现/网关]
  Runtime --> Client[客户端]
  Runtime --> Evidence[日志/指标/trace]
  Test[契约与失败测试] -.验证.-> Contract
  Test -.验证.-> Runtime

这张图把设计、实现、调用和证据串起来。任何规则都要能落到契约或运行时检查。

9.3 基础知识讲解

9.3.1 论文 / 规范

• Roy Fielding, Architectural Styles and the Design of Network-Based Software Architectures：REST 起源。
• RFC 9110, HTTP Semantics：方法、状态码、缓存语义。
• RFC 7807, Problem Details for HTTP APIs：统一错误对象。

9.3.2 书

• Leonard Richardson, Mike Amundsen, Sam Ruby, RESTful Web APIs。
• Arnaud Lauret, The Design of Web APIs。
• JJ Geewax, API Design Patterns。

9.3.3 博客 / 文档

• Stripe API 文档：idempotency、分页、错误风格。
• Microsoft REST API Gui：兼容与一致性。
• Google API Design Guide：资源导向设计。
• Apigee 文档 与 AWS API Gateway 文档：网关、配额、部署。

9.3.4 人物

• Roy Fielding：REST 与 HTTP 架构。
• Tim Berners-Lee：Web、URI、HTTP。
• Darrel Miller：OpenAPI Initiative 技术治理与工具生态。

9.3.5 方法

• Contract-first：先写 OpenAPI 和示例，再写 handler。
• Consumer-driven review：从调用方任务检查命名、错误和兼容。
• Single-variable test：一次只改变 method、header、身份或并发量。
• Compatibility budget：发布前列出 breaking change 与迁移期。

可运行示例：

# 条件 GET
curl -i https://api.example.com/products/p_123
curl -i -H 'If-None-Match: "product-p_123-v7"' https://api.example.com/products/p_123

# Stripe 风格 idempotency；同一 key + 同一 body 返回同一结果
curl https://api.example.com/orders \
  -H 'Authorization: Bearer test-token' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-20260730-001' \
  -d '{"product_id":"p_123","quantity":1}'

典型响应头：

HTTP/1.1 304 Not Modified
ETag: "product-p_123-v7"
Cache-Control: private, max-age=60

9.4 经典问题与经典案例

9.5 学习难点

• 概念难点：规范术语相近。卡点来自用框架默认值代替 HTTP 语义；回 RFC 和 wire example。
• 思维难点：正常流很短，重试、并发、权限和演进才难；先列状态机与不变量。
• 工程难点：网关、应用、数据库和客户端行为不同；用端到端请求、契约测试和 trace 定位边界。

9.6 技术标准与接口

9.6.1 Entity

9.6.2 Scope

OpenAPI 描述 HTTP API；JSON Schema 描述数据约束；JSON:API 与 HAL 约定表示和链接；Problem Details 约定机器可读错误。它们不替代业务授权、事务设计或运行时保护。

9.6.3 Structure

OpenAPI 必会 paths、operations、parameters、requestBody、responses、components、securitySchemes；JSON Schema 必会 type、required、properties、组合与引用；Problem Details 必会 type/title/status/detail/instance。

9.6.4 Ecosystem

实现与工具包括 Swagger UI、Redoc、Spectral、OpenAPI Generator、Postman、Insomnia、Bruno、httpie、curl。API gateway 常用 Apigee、AWS API Gateway、Kong、Envoy。工具默认值不是规范。

9.6.5 Depth Tiers

本计划目标：L3。

9.6.6 Source

• OpenAPI Initiative 仓库：OpenAPI 3.1 原文与版本历史。
• IETF RFC Editor：RFC 9110、7807/9457、6585 等原文。
• JSON Schema 2020-12 与 JSON:API 1.1。
• 引用快照：2026-07-30。实施前检查更新、勘误与废止关系。

10. 常见误区

• 用框架默认值代替明确契约
• 只测 2xx
• 错误 body 无稳定 code
• 混淆认证与授权
• 重试无 idempotency
• 缓存 key 漏身份/查询条件
• 版本化代替兼容设计
• 文档与实现分开维护
• 日志泄露 secret
• 只有 dashboard，没有可定位的 trace。

11. 所有知识点分类（统一规则）

1. 编程语言 2. 数据结构与算法 3. 计算机基础 4. 工程技术 5. Web 与后端 6. 前端与客户端 7. 数据与人工智能 8. 项目与职业能力 9. 安全与可靠性

本计划归属：Web 与后端 主 + 工程技术 辅。