一切尽在不言中 RESTful API设计指南(上)

一切尽在不言中(RESTful API设计指南)

开场白

RESTful 这个名词相信大家都不陌生吧，但是真正能理解其含义的工程师其实很少。大家每天都在使用，但是却知之甚少，这是为什么？因为缺乏系统性的整理和学习。目前大部分人学习知识的方式都是来自网上的博客和微信公众号上零散的文章，而且在做项目的时候，项目或技术经理也没有做很严格的要求或本身他们自己也知道的不多，所以技术只要能用，用的好不好很少有人关心，只要满足业务需求就好了。

这其实对我们自己成长很不利，可能会导致我们大部分的技术都停留在会用的层面，长期以往将丧失前期优势和竞争力。可以这么说，你如果熟练掌握了今天的RESTful课程中的内容，在RESTful知识领域，你将超过80%的工程师。是不是迫不及待的要开始了？

开始之前我想问一个问题：有没有人知道为什么我取的题目叫一切尽在不言中？现在不知道没关系，相信听完或看完课程后你就明白了

本课程一共分为三个部分：概念篇，设计篇，实践篇

概念篇

主要包含：RESTful历史 ，名字解释 ， 核心思想，关键概念

诞生历史

REST全称是Representational State Transfer，中文意思是表述（编者注：通常译为表征）性状态转移。

它首次出现在2000年Roy Fielding的博士论文中，Roy Fielding是HTTP规范的主要编写者之一。 他在论文中提到："我这篇文章的写作目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。" 如果一个架构符合REST的约束条件和原则，我们就称它为RESTful架构。

我们当然无需记住RESTful的准确解释以及约束和原则，但是我们必须要弄清楚其出现的初衷是为了得到功能强、性能好、适宜通信的架构。

RESTful 是什么？

它是一种技术标准吗？NO，RESTful并没有提出技术标准相关东西
它是一种技术规范吗？NO，RESTful并没有提出技术规范，它使用到了多种技术
那RESTful是什么？从刚才的介绍中，其实不难看出，它是一种架构风格或者是我们软件设计的一种风格

希望下面的判断题你能够做对：

核心思想

假如你参加面试，面试官要求用最简短的一句话来概括RESTful的核心思想，你会怎么说？先思考15秒......
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
好，15秒时间到。

RESTful的核心思想就是：一切都是资源。不理解的人，说明你们都在用假的RESTful，理解的人肯定是入门了。

我们以前在做软件设计的时候常常会说面向对象，面向服务，那么RESTful就是要我们面向资源去设计API。
我会从5个关键词来全面介绍中的RESTful：定义、获取、表述、关联、状态变迁。

是不是有点陌生，好像和你知道的RESTful不太一样？我猜你印象中的RESTful关键词应该是这些：HTTP，GET/POST/PUT/DELETE，JSON等。其实这两组关键词是有关联的。

关键概念

接下来介绍下RESTful用到的一些关键概念，其中有些大家是很熟悉的。

• 资源和URI(定义)：如何定义资源？
• 统一资源接口(获取)：如何获取资源？
• 资源表述(表述)：如何对资源进行表述？
• 资源链接(关联)：如何构建资源之间的连通性？
• 状态转移(状态变迁)：如何理解状态转移或状态变迁？

这些问题在下面PPT页中都有涉及，但是我这里只是提供一个线索，先不细说，随着后面的讲解，相信大家都清楚了。

设计篇

主要包含：协议与操作， 端点设计，响应， 连通性，兼容性， 挑战， 优缺点

通讯协议和操作

RESTful规范推荐的通讯协议是HTTPS，服务端必须支持：GET/POST/PUT/DELETE操作，如果客户端技术或业务限制只支持GET/POST的话，服务端应该和客户端进行协商，模拟实现其它几个方法。

比如推荐使用下面这种模拟实现的方式：请求头中带上X-HTTP-Method-Override属性，其值为其他动词，以此来模拟。

常见操作说明

接下来我们来看下RESTful通讯中常见的操作，我们会从安全性(操作是否改变资源的状态)和幂等性(对同一资源的多次操作，服务端对资源改变是否相同)两个方面对操作进行讲述，并列举常见的响应状态码

GET操作

• GET：获取服务提供的资源；既是安全的也是幂等的；结果一般可以被缓存(与其类似的操作还有head和option)

常见响应状态码：

200（OK） - 表示已在响应中发出
204（无内容） - 资源有空表示
301（Moved Permanently） - 资源的URI已被更新
303（See Other） - 其他（如，负载均衡）
304（not modified）- 资源未更改（缓存）
400 （bad request）- 指代坏请求（如，参数错误）
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务端当前无法处理请求

PUT操作

• PUT：全量更新或添加资源(唯一主键情况下可用于添加资源，个人不推荐)；非安全但是幂等；它是通过替换的方式更新资源，采用乐观锁的机制

常见响应状态码：

200 （OK）- 如果已存在资源被更改
201 （created）- 如果新资源被创建
301（Moved Permanently）- 资源的URI已更改
303 （See Other）- 其他（如，负载均衡）
400 （bad request）- 指代坏请求
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
409 （conflict）- 通用冲突
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
415 （unsupported media type）- 接受到的表示不受支持
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务当前无法处理请求503 （Service Unavailable）- 服务当前无法处理请求

PATCH操作

• PATCH：局部更新资源；非安全但是幂等；和PUT一样都是用于资源更新，PATCH是通过具体字段方式进行更新，比较常用，也是采用乐观锁的机制

常见响应状态码：

200 （OK）- 如果已存在资源被更改
301（Moved Permanently）- 资源的URI已更改
303 （See Other）- 其他（如，负载均衡）
400 （bad request）- 指代坏请求
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
409 （conflict）- 通用冲突
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
415 （unsupported media type）- 接受到的表示不受支持
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务当前无法处理请求

POST操作

• POST：添加服务资源；非安全非幂等；它用于新增服务资源场景下，也是采用乐观锁机制

常见响应状态码：

201（created）- 如果新资源被创建
202（accepted）- 已接受处理请求但尚未完成（异步处理）
301（Moved Permanently）- 资源的URI被更新
303（See Other）- 其他（如，负载均衡）
400（bad request）- 指代坏请求
404 （not found）- 资源不存在
406 （not acceptable）- 服务端不支持所需表示
409 （conflict）- 通用冲突
412 （Precondition Failed）- 前置条件失败（如执行条件更新时的冲突）
415 （unsupported media type）- 接受到的表示不受支持
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务当前无法处理请求

DELETE操作

• DELETE：删除服务资源；非安全但幂等；

常见响应状态码：

204 （OK）- 资源已被删除
301 （Moved Permanently）- 资源的URI已更改
303 （See Other）- 其他，如负载均衡
400 （bad request）- 指代坏请求
404 （not found）- 资源不存在
409 （conflict）- 通用冲突
500 （internal server error）- 通用错误响应
503 （Service Unavailable）- 服务端当前无法处理请求

这几种操作操作比较容易理解，相信大家平时也经常用到，就不多说了，主要多注意几个常用的返回值使用，我已经用其他颜色在PPT中标注出。我们接下来看看RESTful 端点设计规范。

RESTful 三层标准

RESTful 设计标准有的资料上介绍是从0级开始的，我个人觉得0级的就不是，所以直接从1级开始。 我借鉴下王国维《人间词话》中形容人生三重境界来对应介绍RESTful 的三层标准。

• 第一层：昨夜西风凋碧树，独上高楼，望尽天涯路(人生是需要目标和精神彼岸的)。对应RESTful 就是要有清晰的资源抽象，也就是基于资源URI地址

• 第二层：衣带渐宽终不悔，为伊消得人憔悴（有了目标需要努力求索）。对应RESTful 就是要努力用统一的CURD式web服务，端点就是RESTful 中的伊人，你设计的时候你是要为她憔悴的。

• 第三层：蓦然回首，那人却在灯火燃珊处（有了目标也努力了，成功与否看得看运气，学会释然后你要追求的东西在你蓦然回首时便能发现）。对应RESTful 就是使用超媒体状态应用引擎HATEOAS，资源之间构建连通性。让客户端有种蓦然回首，资源就在灯火阑珊处感觉。

前面两层还是比较好理解的，对于第三层很多人可能使用RESTful 后还是第一次听说或者不太理解，这里暂时不展开，后面会专题介绍。

(上篇结束，我们下篇见)