1 · 读书笔记：API设计模式#

API Design Patterns

https://book.douban.com/subject/34701070/

• 是什么（What）— 理论/原则，建立认知模型
• 为什么（Why）— 背后的动机、约束与权衡
• 怎么做（How）— 技巧 + 实践 + 边界（该做与不该做）

1.1 · 核心观点：

API 是应用之间的契约（contract），设计模式为这些契约提供了一套可复用、可预测、可组合的标准化方案，使 API 一致（consistent）、可扩展（scalable）、灵活（flexible）。

• 面向资源（Resource-oriented）设计是核心范式：将一切建模为资源（resource），用标准方法（GET/POST/PUT/DELETE）操作，本质上是受约束的 RPC —— StandardMethod(Resource)
• 好 API 的四个特征：
  1. Operational（可运行）—— 能完成用户的任务
  2. Expressive（可表达）—— 用户能清晰表达意图，无需 workaround
  3. Simple（简单）—— 常见用例保持简单，复杂场景仍可达
  4. Predictable（可预测）—— 命名与行为一致，降低学习曲线
• 全书六大板块：
  1. 设计原则（命名、资源层级、数据类型与默认值）
  2. 基础模式（资源标识、标准方法、部分更新、自定义方法、长时间操作、可重跑任务）
  3. 资源关系（单例子资源、交叉引用、关联资源、多态）
  4. 集合操作（复制/移动、批量操作、条件删除、匿名写入、分页、过滤、导入导出）
  5. 安全保障（版本兼容、软删除、请求去重、请求验证、资源修订）
  6. 安全认证（请求重试、请求认证）

1.2 · 启发点（关键洞察）：

1. Resource-oriented API 是标准化的 RPC——不是在 REST 和 RPC 之间二选一，而是用 REST 的资源抽象来约束 RPC 的自由度，获得一致性
2. Field Mask（字段掩码）实现精准部分更新——客户端只发送需要修改的字段，避免”读-改-写”的竞态问题，也节省带宽
3. Custom Methods 弥补标准 CRUD 的不足——对于”发送邮件""取消订单”等无法自然映射到 CRUD 的操作，用 POST /resources/{id}:action 模式
4. Long-Running Operations（LRO）模式——将耗时操作建模为可查询状态的”操作资源”，支持轮询、过期和错误处理
5. 分页的 pageToken 模式优于 offset/limit——pageToken 基于游标，不受并发插入/删除影响，且对后端更友好
6. 请求去重（Request Deduplication）——通过客户端生成的 idempotency key 保证”恰好一次”语义，解决网络重试导致的重复创建

1.3 · 行动：

1. 在设计 API 时检查是否满足”可运行、可表达、简单、可预测”四项标准
2. 用 Field Mask 替代全量 PUT，特别是在并发修改场景中
3. 为所有创建类接口加入幂等性支持（idempotency key）
4. 分页统一使用 pageToken 模式，弃用 offset/limit

1.4 · 金句：

1. “APIs are contracts that define how applications, services, and components communicate.”
2. “Well-designed APIs often go unnoticed, but significantly enhance user experience and reduce frustration.”（Jon Skeet 序言）
3. “The disparity between theoretical computer science learned in school and the practical, design-oriented challenges faced in real-world applications”——学校教算法，现实教设计