RESTful API规范
前言
我现在工作的公司是在毕业前实习的公司, 实习结束后直接转正, 因此也是我任职过的唯一一家公司.
在日常工作进行 HTTP 接口的开发时, 发现了一个疑惑, 只用到了POST和GET请求, 但我们知道 HTTP还有PUT/DELETE等等, 为什么不用呢?
并且, 接口的响应码也只有200, 接口是否出错, 会在响应体中额外添加status字段来标识. 当然, 偶尔也会碰到404/500之类的响应码, 不过他们都还没有到业务层就返回了, 因此并不是我们主动设计的响应码. 但是, HTTP 响应码辣么多, 为什么不用呢?
就在我苦苦思索仍不得其解的时候, 我去翻看了一下 HTTP 协议的RFC文档, 发现官方对不同的HTTP Method已经给出解释了. 并且我还发现了一个叫做RESTful API的接口设计规范.
介绍
HTTP
让我们先看看设计者是如何说明不同HTTP Method的, RFC 文档地址:
| Method | 介绍 | 幂等 |
|---|---|---|
| GET | 数据的查询操作 | Yes |
| HEAD | 与GET相同, 区别是响应中不包含响应体. 可以用来获取资源的元数据, 如 header 等 |
Yes |
| POST | 信息的创建 有意思的是, 创建成功应该返回响应码 201 |
No |
| PATCH | 用于局部更新 从 POST 请求分出来的, POST 全量更新, PATCH 局部更新. 文档地址 |
No |
| PUT | 信息的更新 | Yes |
| DELETE | 数据删除 | Yes |
| OPTIONS | API 相关信息 如探测服务支持的所有 Method, 或者检测服务通不通. |
Yes |
| CONNECTED | 与服务器建立链接, 通过服务器代理客户端请求 说白了就是一个 HTTP 代理 |
Yes |
| TRACE | 对请求路径的环回测试 | Yes |
幂等, 上面表格中幂等的意思就是, 接口调2次和调1次结果一样, 既可以重复调用.
同时, RFC对响应码的定义, 也仅仅定义了一部分, 也就是说仍然有很大一部分响应码是可以根据我们的需求自行使用的. 响应码文档地址
| 响应码 | 介绍 |
|---|---|
| 1xx | 请求已收到, 需要继续操作 |
| 2xx | 请求成功处理 |
| 3xx | 重定向, 需要进一步请求 |
| 4xx | 客户端错误 |
| 5xx | 服务器错误 |
我们已经了解了在定义HTTP协议的时候已经对Method及响应码做出了规定, 基于此, 我们可以前去了解这个叫做REST的玩意了.
顺便提一句, HTTP响应码非200, Response Body中也是可以传输错误信息的. RFC 文档说明
RESTful API规范
而RESTful API就是符合REST规范的Web API.
简单来说, RESTful API对接口提出的规范如下
- 通过
URI进行资源的定位 - 通过
HTTP Method指定操作类型 - 将响应码放到
Response Code
举个简单的例子, 比如对一篇博客文章的增删改查操作, 按照之前的涉及, 应该出这样4个 POST 接口 insertArchive/deleteArchive/updateArchive/getArchive
但若是按照REST风格来, 就应该是这样4个接口
PUT /archiveDELETE /archive/<ID>PATCH /archive/<ID>GET /archive/<ID>
其中URI仅用作对资源的标识, 是没有动词的, 然后通过HTTP Method来指定要执行什么操作.
PS: 仔细看了HTTP RFC 文档后, 发现RESTful API就是HTTP设计者当初设计时想要的模样呀. (规范使用HTTP Method 与 Response Code)
PS: 发现了一个开源项目OpenAPI, 指导API设计的, 有时间详细看看
优点
REST风格必定不是无根之木, 一定是为了解决某些问题而提出的.
REST风格和全部使用POST的区别在哪呢? 比较了一下, 主要是:
- 将操作动词从
URI挪到了HTTP Method - 将返回的响应码从
body挪到了Response Code
其带来的直接效果, 就是当中间服务(比如 nginx)拿到一个请求与响应时, 因为数据格式的统一, 可以方便的知道此请求是做什么用的及是否成功.
如此一来, 中间层就可以据此做一些事情了:
- 缓存 将
GET请求进行缓存 - 读写分离 将读写请求路由到不同服务器上
- 性能分析 将各种操作进行整合
- 权限控制 可以直接根据
HTTP Method进行权限控制, 不用再一个个指定URI了.
当然, 据说改为REST风格后, API 的也会更加简介且清晰, 不过我导没什么直观的感受.
个人理解
以上, 看起来大佬提出的REST风格确实不错. 谷歌 API 设计指南也是遵循REST风格的. 此风格的接口也确实会带来一些好处.
那么在实际工作中如果将风格转换为REST是否可行呢? 我觉得可能会碰到如下阻碍(暂时想到):
- 对于现实较为复杂的业务场景, 不同人可能会有不同理解. 比如批量删除, 同时更新用户信息与店铺信息等等.
- 若两个人根据
REST风格提出两个接口, 那就公说公有理婆说婆有理了 - 如果是之前的
POST风格, 接口名直接翻译业务场景就可以了
- 若两个人根据
- 开发思想的转变
REST要求面向资源, 而现实中往往是面向业务的
- 现实问题
- 看到有人说, 有些防火墙直接将
PUT/DELETE请求屏蔽了(我没碰到过) - 还有人说在浏览器上也碰到过类似的问题?? 不过需要实际调研
- 看到有人说, 有些防火墙直接将
以上, 仅仅是我目前想到的可能会出现的问题. 未来如果有机会施行REST风格接口的话, 可能会发现其他问题吧, 当然也可能发现REST风格确实很好.
各位看客有没有实际体验过的? 分享一下使用体验.
