“权衡”（trade-off）
概念
什么是 Web API？
• API，即 Application Programming Interface
• Web API 指的依然是应用程序接口，只不过它现在暴露在了 Web 的环境里
Web API 需要包括哪些内容呢？
• 功能、性能、入参、返回值
• 承载协议. HTTP, TCP
• 请求和响应格式
Web API 的设计步骤
关于 Web API 的设计步骤，不同人有不同的理解，争论不少，涉及到的内容也非常广泛。这里我综合了自己的经验和观点进行介绍，希望你能有所启发。
第一步：明确核心问题，确定问题域
一组 Web API，就是要专注于一类问题，核心问题必须是最重要的一个。
第二步：结合实际需求和限制，选择承载技术
• 网络传输的效率, 时延
• 兼容性
• 鉴权, 访问控制
• 库依赖限制
• 易测试性, 可维护性
• 平滑发布
承载技术指的是实现接口，以及它的请求响应传输所需要使用到的技术集合，比如 HTTP + JSON。我们前面提到的要求网络传输效率高、时延短，Protobuf 就是一个值得考察的技术；但有时候，我们更需要消息直观、易读，那么显然 Protobuf 就不是一个适合的技术。这里我们通过分析技术优劣来做选择，这就是权衡。
虽说 Web API 主要的工作在服务端，但在技术分析时还需要考虑客户端。特别是一些技术要求自动生成客户端，而有些技术则允许通过一定方式“定制”客户端（例如使用 DSL，Domain Specific Language，领域特定语言）。
第三步：确定接口风格
技术的选择将很大程度地影响接口的风格。
• 角度一：易用性和通用性的平衡，或者说是设计“人本接口”还是“最简接口”。
比如一个图书管理的接口，一种设计是让其返回“流行书籍”，实际的规则是根据出版日期、借阅人数、引进数量等等做了复杂的查询而得出；而另一种设计则是让用户来自行决定和传入这几个参数，服务端不理解业务含义，接口本身保持通用。
• 角度二：接口粒度的划分。
比如用户还书的过程包括：还书排队登记、检查书本状况、图书入库，这一系列过程是设计成一个大的接口一并完成，还是设计成三个单独的接口分别调用完成？设计成大接口往往可以增加易用性，便于内部优化提高性能（而且只需调用一次）；设计成小接口可以增加可重用性，便于功能的组合。
第四步：定义具体接口形式
在上面这三步通用和共性的步骤完成之后，我们就可以正式跳进具体的接口定义中，去确定 URL、参数、返回和异常等通用而具体的形式了。还记得上一讲中对 REST 请求发送要点的分解吗？在它的基础上，我们将继续以 REST 风格为例，进行更深刻的讨论。
在上面这三步通用和共性的步骤完成之后，我们就可以正式跳进具体的接口定义中，去确定 URL、参数、返回和异常等通用而具体的形式了。还记得上一讲中对 REST 请求发送要点的分解吗？在它的基础上，我们将继续以 REST 风格为例，进行更深刻的讨论。
- 条件查询
/books/123
/books/123/price
/books?author=Smith&page=2&pageSize=10&sortBy=name&order=desc
/category/456/books?author=Smith
/books?author=Smith&category=Arts
- 消息正文封装
json
xml
{
"name": "...",
"category": "Arts",
"authorId": 999,
"price": {
"currency": "CNY",
"value": 12.99
},
"ISBN": "...",
"quantity": 100,
...
}
对象关联:
• 传递唯一业务字段：例如上面的 category 取值是具备实际业务意义的“Arts”；
• 传递唯一 id：例如上面的 authorId，请注意，这里不能传递实际作者名，因为作者可能会重名；
• 传递关联对象：例如上面的 price，这个对象通常可以是一个不完整的对象，这里指定了货币为人民币 CNY，也指定了价格数值为 12.99。
响应和异常设计
HTTP 协议中规定了返回的状态码:
• 1xx: 表示请求已经被接受，但还需要继续处理
• 2xx
• 3xx
• 4xx: 表示客户端错误
• 5xx
我们需要告知用户是哪个请求出错了，什么时间出错了，以及为什么出错。比如：
{
"errorCode": 543,
"timeStamp": 12345678,
"message": "The requested book is not found.",
"detailedInfomation": "...",
"reference": "https://...",
"requestId": "..."
}
注意这里的 errorCode 不是响应中的 HTTP 状态码，而是一个具备业务意义的内部定义的错误码。在有些设计里面，也会把 HTTP 状态码放到这个正文中，以方便客户端处理，这种冗余的设计当然也是可以的。
扩展阅读
- 【基础】HTTP 状态码 和 HTTP 头字段，我们在工作中会反复和各式各样的状态码和请求、响应中的头部字段打交道，因此通读并熟知一些常见的状态码是很有必要的。关于 HTTP 状态码，有人把一些常见的状态码形象地对应到猫的照片，或许能帮助你记忆，当然，如果你喜欢狗，那你可以看看这个。
- Any API，我们不能光闭门造车，还要去学习其它网站的 Web API 设计，了解互联网上大家都是怎么做的。我们学习它们的实现，但请不要盲目，有不少接口由于种种原因，设计有一些亟待商榷的地方，请带上你批判的眼光。
- Richardson Maturity Model，这篇会有一些深度，大名鼎鼎的马丁·福勒（Martin Fowler）的文章，讲 REST 的一种成熟度模型，里面划分了从 0 级到 3 级这样 4 种成熟度级别，这种分级方式被一些人奉为圭臬。
