权衡的艺术：漫谈Web API的设计

2020-11-06 本文已影响0人码农架构

“权衡”（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 风格为例，进行更深刻的讨论。

条件查询

/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 种成熟度级别，这种分级方式被一些人奉为圭臬。

更多内容分享.png