1 · 读书笔记：WebAPI设计#

The Design of Web APIs https://book.douban.com/subject/34847654

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

1.1 · 核心观点：

API 设计的本质是以消费者为中心（consumer-first），在业务目标与技术约束之间取得平衡，创造出让开发者乐于使用的”产品”。

• API 是产品，不仅仅是接口：API 暴露的是能力（capabilities），而非内部实现。设计时应从”消费者能用它做什么”出发，而不是从”系统内部长什么样”出发
• 设计先于编码（Design-first）：用 API Capabilities Canvas 识别用例、参与方与目标，在写第一行代码之前就完成设计
• 用户友好性四层递进：
  1. 可用（does the job）—— 满足功能需求
  2. 易用（user-friendly）—— 命名一致、操作语义清晰、数据流自然
  3. 安全（secure by design）—— 权限最小化、敏感数据脱敏、scope 精确控制
  4. 高效（efficient）—— 缓存、分页、批量操作、压缩
• 可互操作性（interoperability）：REST/OpenAPI 是基线，但思维方式同样适用于 GraphQL、gRPC 等范式
• 演进与版本策略：修改 API 前必须评估破坏性后果（breaking change analysis），善用语义化版本和弃用策略来 future-proof

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

1. 任何 API 都需要设计——即使是”只有自己用的私有 BFF API”，不设计就会后悔（作者原话：“Even if it’s just a private API, you need to think about it because if you don’t, you will deeply regret it later.”）
2. API Capabilities Canvas 是需求分析的实用工具：识别参与方（who）、用例（what）、操作（how），从用户视角穷举能力，避免遗漏
3. 从 REST 角度观察操作（Observing operations from the REST angle）：将业务操作映射为资源 + HTTP 动词，而不是直接暴露函数调用
4. 用 OpenAPI + JSON Schema 描述 API 是一种沟通工具——不仅用于生成文档，更是团队对齐设计意图的契约
5. 非破坏性修改是一门艺术：添加可选字段、扩展枚举值通常安全；删除字段、改变语义总是危险的

1.3 · 行动：

1. 在设计新 API 时，先用 API Capabilities Canvas 列出所有参与方和用例，再动手写 OpenAPI spec
2. 对现有 API 做一次 breaking change audit，评估哪些修改会破坏消费者
3. 建立团队内的 API 设计评审流程（API design review），在实现前对齐命名、数据模型和操作语义

1.4 · 金句：

1. “Well-designed web APIs are a joy. The bad ones are a nightmare, with endless impact on system performance, developer productivity, and end-user experience.”
2. “A well-designed and properly-documented API gives your users autonomy—and saves you from constant explanations and hand-holding.”
3. “You need to design it. Even if it’s just a private API. If you don’t do that, you will deeply regret it later.”