通俗讲解 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 – 标准服务端错误，开发人员应该尽可能避开这种错误

参考资料：

• www.zhihu.com/question/28…
• blog.csdn.net/mingjia1987…