【Web API】通俗讲解 RESTful

1 什么是 RESTful

百度一下 RESTful,查到的资料很多都讲得不清楚,看完了都不知道说的是啥,导致很多人对 RESTful 不甚了解。来看一下常见的解释:

(1)神一样的描述
REST 并不是“休息”的意思,而是 Representational State Transfer 的简称,即 表现层状态转移

“表现层状态转移”是什么鬼?

(2)云里雾里的描述

  • REST 指的是 一组架构约束条件和原则,如果一个架构符合 REST 的约束条件和原则,就称之为 RESTful 架构。
  • RESTful 是一种软件架构风格,而不是标准。

这能看懂一点了,但还是云里雾里的。

(3)大神的总结
再看知乎大神 Ivony 的一句话精辟概括:

用 URL 定位资源,用 HTTP 动词(GET,POST,DELETE,PUT)描述操作。

RESTful 是一种 web 服务设计风格,风格意思就是大家默认的但不是强制的。

2 RESTful 详解

2.1 用 URL 定位资源

REST 的主体是资源,所谓“资源”,就是网络上的一个具体信息,例如:一张图片,一段文字、一种服务。总之就是一个实际存在的东西,而 URL 就是用来指向这个资源的。

例如:

https://api.example.com/users

这个 URL 一看就知道是对 user 资源的操作。URL 中只使用名词来指定资源,不包含操作。为什么呢?

如果要包含操作,那至少有增删改查四种,那么上例中的一个接口至少要变成四个:

https://api.example.com/add_user
https://api.example.com/delete_user
https://api.example.com/update_use
https://api.example.com/get_user

太多了,不够简洁。

2.2 用 HTTP 动词描述操作

那怎么描述操作呢?答案就是用 HTTP 动词。

HTTP 动词,可能很多人第一眼看到的时候有点蒙,不知道是啥,其实就是我们请求网页时用的 GET、POST 等操作。我们平时用的最多的就是 GET 和 POST(例如写爬虫的时候,基本都是这两种),常用的还有 PUT、PATCH、DELETE 。

对资源的操作,无外乎 CRUD(增删改查),RESTful 中,每个 HTTP 动词对应一个 CRUD 操作。

  • GET:对应 Retrieve 操作(查询操作)
  • POST:对应 Create 操作
  • DELETE:对应 Delete 操作
  • PUT:对应 Update 操作
  • PATCH:对应 Update 操作

2.3 POST 和 PUT 的区别

一般说到 HTTP 动词对应 CRUD 的时候,PUT 都是对应 Update 操作的。但其实,PUT 也可以做 Create 操作。二者的区别在于:

  • URL:POST 不需要指定到个体,例如新增 user 的接口 POST /api/users。 PUT 的 URL 需要指定到具体的个体,例如 PUT /api/users/1,如果 1 这个 user 存在,则 Update,否则 Create。这个很好理解,POST 确定是新增,insert 的时候是不需要 where 条件的;PUT 则不行,update 的时候不加 where,干过的小伙伴请举手。另外,PUT 的时候,也不是每个 user 就要建一个接口的,这里需要用到的就是路由,一般是写成 PUT /api/users/{id},这样就具有一般性了。路由在这里就不展开讲了。
  • 幂等性:PUT 是幂等的,而 POST 是非幂等的。关于幂等性,见下文。

2.4 PATCH 和 PUT 的区别

PATCH 是 2010 后成为的正式 http 方法,它是对 PUT 的补充。在没有 PATCH 之前,都是用 PUT 进行更新操作,这时候我们的接口中通常会有一个逻辑规则,如:如果对象的一个属性值为null,那么就不更新该属性(字段)值,通过这种方式来避免全部覆盖的操作。现在有了 PATCH 就解决了这种判断,在 PUT 操作中不管属性是不是 null,都进行更新,在 PATCH 接口中就对非 null 的进行更新。另外,PATCH 是非幂等的。

2.5 变通的 POST

按照 REST 建议,查询操作要使用 GET 方法,但是实际情况中处理起来比较麻烦,如:报表统计查询,需要传递的参数很多,如果采用 GET 方法,那么接口接收的参数非常多,接口很难看,通常会封装为 java 对象,但 GET 方法又不支持对象传参,所以很蛋疼;

对于这种情况,最简单的方式就是改成 POST 方式,而且很多公司都是这么干的。可见 REST 只是建议,并非强制约束。

补充:幂等性

幂等(Idempotence)本来是一个数学上的概念,定义就不说了,看了头晕。

后来拓展到计算机领域,描述为:

一个操作、方法或者服务,其任意多次执行所产生的影响均与一次执行的影响相同。

一个幂等的方法,使用同样的参数,对它进行多次调用和一次调用,对系统产生的影响是一样的。所以,对于幂等的方法,不用担心重复执行会对系统造成任何改变。

举个例子,用户 X 的手机话费余额为 2 元,他用支付宝给手机充了 100 元话费,如果将这个操作描述为“给 X 的账户余额增加 100 元”那就是非幂等的,重复操作几次运营商就亏大了。但是,如果将这个操作描述为“将 X 的账户余额设置为 102 元”,那这个操作就是幂等的。简单来说:

  • 幂等操作:将账户 X 的余额设置为 102 元;
  • 非幂等操作:将账户 X 的余额增加 100 元。

注意:这里的幂等性的例子并不严谨,本文主要不是讲幂等性的,所以只是举个简单的例子,不做深入探讨。

3 RESTful 的其他细节

3.1 命名规则

  • (1)全部小写,用 _- 线连接。

例如我在上面给出的例子 :

https://api.example.com/add_user

之所以不用驼峰命名法,是因为早期的 URI 一般都是表示服务器上的文件路径,而不同服务器对大小写的敏感性是不同的,为了兼容不同服务器所以才规定不能混用大小写字母。

  • (2)URL 中只用名词指定资源,因为 REST 的核心是资源,而表示资源的词语天然就是名词。
  • (3)资源用复数表示。

3.2 版本

一种方法是在 URL 中添加版本号,例如:

https://api.example.com/v1/users

另一种方法是将版本号加在 HTTP 请求头信息的 Accept 字段中,例如:

Accept: version=1.0

虽然有很多博客里推荐里说是推荐在 header 里添加版本信息,因为不同的版本表示的资源依然是同一个,所以不应该用不同的 URL。但是以我目前了解到的情况来看,绝大多数公司都是将版本号放在 URL 中的,并且推荐这么做,简单直观。

网上能找到的版本号加在 URL 中的例子,都是如我上例所示的写法。但是 Jack_Zeng 指出,这样写容易有歧义,会让人误以为 v1 也是资源的一部分,一般都是这么写:

https://api.example.com/users?api-version=1

3.3 HTTP 状态码

知乎上另一大神对 RESTful 的解释,相比于 Ivony 多了一句话,他用了三句话来描述:

  • 看 Url 就知道要什么
  • 看 http method 就知道干什么
  • 看 http status code 就知道结果如何

前两句和 Ivony 的是一个意思。这第三句我觉得总结得也很经典。

http 状态码有 100 多种,我们并不需要全部用到,只需要了解其中常用的就可以了

  • 200 – OK – 一切正常
  • 201 – OK – 新资源已经被创建
  • 204 – OK – 资源删除成功
  • 304 – 没有变化,客户端可以使用缓存数据
  • 400 – Bad Request – 调用不合法,确切的错误应该在 error payload 中描述
  • 401 – 未认证,调用需要用户通过认证
  • 403 – 不允许的,服务端正常解析和请求,但是调用被回绝或者不被允许
  • 404 – 未找到,指定的资源不存在
  • 422 – 不可指定的请求体 – 只有服务器不能处理实体时使用,比如图像不能被格式化,或者重要字段丢失
  • 500 – Internal Server Error – 标准服务端错误,开发人员应该尽量避开这种错误

参考资料:

posted @ 2019-09-26 10:33  丹枫无迹  阅读(1745)  评论(2编辑  收藏  举报