RESTful接口设计规范-Toy模板网

这篇具有很好参考价值的文章主要介绍了RESTful接口设计规范。希望对大家有所帮助。如果存在错误或未考虑完全的地方，请大家不吝赐教，您也可以点击"举报违法"按钮提交疑问。

RESTful是目前最流行的API设计规范，它是用于Web数据接口的设计。从字面可以看出，他是Rest式的接口，所以我们先了解下什么是Rest。

REST与技术无关，它代表的是一种软件架构风格，REST它是 Representational State Transfer的简称，中文的含义是: “表征状态转移” 或 “表现层状态转化”。

它是基于HTTP、URI、XML、JSON等标准和协议，支持轻量级、跨平台、跨语言的架构设计。

开发工作中，我们有时需要提供API接口给客户端或者第三方使用，那么如何构建一个能让使用者快速理解的API是一项重要的工作。倘若我们在设计API时就严格遵守一些规范，那么在后面的开发过程中沟通成本和效率就会大大改善。

一、理解为什么要使用RESTful API设计规范？

在很久以前，工作时间长的人肯定经历过使用velocity语法来编写html模板代码，也就是说我们的前端页面放在服务器端那边进行编译的，更准确的可以理解为 “前后端没有进行分离”，那么在那个时候，页面、数据及模板渲染操作都是放在服务器端进行的，但是这样做有一个很大的缺点是: 后期维护比较麻烦，前端开发人员还必须掌握velocity相关的语法。

因此为了解决这个问题慢慢就出现了前后端分离的思想: 即后端负责数据接口, 前端负责数据渲染, 前端只需要请求下api接口拿到数据，然后再将数据显示出来。

因此后端开发人员需要设计api接口，因此为了统一规范: 社区就出现了 RESTful API 规范，其实该规范很早就有的，只是最近慢慢流行起来，RESTful API 可以通过一套统一的接口为所有web相关提供服务，实现前后端分离。

二、Rest设计原则

那么怎么样可以设计成REST的架构规范呢? 需要符合如下的一些原则：

每一个URI代表一种资源;
同一种资源有多种表现形式(xml/json);
所有的操作都是无状态的。
规范统一接口。
返回一致的数据格式。
可缓存(客户端可以缓存响应的内容)。

符合上述REST原则的架构方式被称作为 RESTful 规范。

理解为什么所有的操作需要无状态呢?

http请求本身是无状态的，它是基于 client-server 架构的，客户端向服务器端发的每一次请求都必须带有充分的信息能够让服务器端识别到，请求的一些信息通常会包含在URL的查询参数中或header中，服务器端能够根据请求的各种参数, 不需要保存客户端的状态, 直接将数据返回给客户端。无状态的优点是：可以大大提高服务器端的健状性和可扩展性。

客户端可以通过token来标识会话状态。从而可以让该用户一直保持登录状态。

理解规范统一的接口

Rest接口约束定义为: 资源识别；请求动作；响应信息; 它表示通过uri表示出要操作的资源，通过请求动作(http method)标识要执行的操作，通过返回的状态码来表示这次请求的执行结果。

可能看上面的解释还不够理解，下面我通过自己的理解来解释下上面的具体含义; 比如说，我在未使用Rest规范之前，我们可能有增删改查等接口，因此我们会设计出类似这样的接口: /xxx/newAdd (新增接口), /xxx/delete(删除接口), /xxx/query (查询接口), /xxx/uddate(修改接口)等这样的。

增删改查有四个不同的接口，维护起来可能也不好，因此如果我们现在使用Restful规范来做的话，对于开发设计来说可能就只需要一个接口就可以了，比如设计该接口为 /xxx/apis 这样的一个接口就可以了。

然后请求方式(method)有

GET–查询(从服务器获取资源);
POST—新增(从服务器中新建一个资源);
PUT—更新(在服务器中更新资源)，
DELETE—删除(从服务器删除资源)，
PATCH—部分更新(从服务器端更新部分资源)

等这些方式来做，也就是说我们使用RESTful规范后，我们的接口就变成了一个了，要执行增删改查操作的话，我们只需要使用不同的请求动作(http method)方式来做就可以了，然后服务器端返回的数据也可以是相同的，只是我们前端会根据状态码来判断请求成功或失败的状态值来判断。

理解返回一致的数据格式

服务器端返回的数据格式可以是XML、或json. 或者直接返回状态码的方式。比如返回错误的格式json数据如下:

{
    "code": 401,
    "status": "error",
    "message": '用户没有权限',
    "data": null
}

返回正确的数据格式的json数据一般可以为如下:

{
    "code": 200,
    "status": "success",
    "data": [{
        "userName": "fuyou",
        "age": 27
    }]
}

URL及参数设计规范

URL末尾不需要出现斜杠/
在URL中使用斜杠/是表达层级关系的。
在URL中可以使用连接符-, 来提升可读性。
比如 http://xxx.com/xx-yy 比 http://xxx.com/xx_yy中的可读性更好。
在URL中不允许出现下划线字符_.
在URL中尽量使用小写字符。
在URL中不允许出现文件扩展名. 比如接口为 /xxx/api, 不要写成 /xxx/api.php 这样的是不合法的。
在URL中使用复数形式。

在RESTful架构中，每个uri代表一种资源，因此uri设计中不能使用动词，只能使用名词，并且名词中也应该尽量使用复数形式。使用者应该使用相应的http动词 GET、POST、PUT、PATCH、DELETE等操作这些资源即可。

那么在我们未使用RESTful规范之前，我们是如下方式来定义接口的，形式是不固定的，并且没有统一的规范。比如如下形式:

http://xxx.com/api/getallUsers; // GET请求方式，获取所有的用户信息
http://xxx.com/api/getuser/1;   // GET请求方式，获取标识为1的用户信息
http://xxx.com/api/user/delete/1 // GET、POST 删除标识为1的用户信息
http://xxx.com/api/updateUser/1  // POST请求方式 更新标识为1的用户信息
http://xxx.com/api/User/add      // POST请求方式，添加新的用户

如上我们可以看到，在未使用Restful规范之前，接口形式是不固定的，没有统一的规范，下面我们来看下使用RESTful规范的接口如下，两者之间对比下就可以看到各自的优点了。

http://xxx.com/api/users;     // GET请求方式 获取所有用户信息
http://xxx.com/api/users/1;   // GET请求方式 获取标识为1的用户信息
http://xxx.com/api/users/1;   // DELETE请求方式 删除标识为1的用户信息
http://xxx.com/api/users/1;   // PATCH请求方式，更新标识为1的用户部分信息
http://xxx.com/api/users;     // POST请求方式 添加新的用户

如上我们可以看到，增删改成我们都是使用同一个api接口，只是请求的方式 GET(查询)、POST(新增)、DELETE(删除)、PACTH(部分更新)来代表的是增删改查操作的方式。然后开发获取到该请求的header头部信息，就可以知道是什么方式来请求数据的了。

HTTP请求规范

GET (SELECT): 查询；从服务器取出资源.
POST(CREATE): 新增; 在服务器上新建一个资源。
PUT(UPDATE): 更新; 在服务器上更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE): 更新；在服务器上更新部分资源(客户端提供改变的属性)。
DELETE(DELETE): 删除; 从服务器上删除资源。

Content Type

目前，大多数「令人称赞」的 API 都为 RESTful 接口提供 JSON 数据支持。诸如 Facebook，Twitter，Github 等等你所知的。XML 的方法现在已经很少有人在使用（大型企业环境除外）。很幸运的是 SOAP 已几乎没人在使用了，并且现在我们很少看到 API 把 HTML 作为结果返回给客户端（除非你在构建一个爬虫程序）。

只要你返回给他们有效的数据格式，开发者就可以使用流行的语言和框架进行解析。如果你正在构建一个通用的响应对象，通过使用一个不同的序列化器，你也可以很容易的提供之前所提到的那些数据格式（不包括 SOAP）。而你所要做的就是把使用方式放在响应数据的接收头里面。

有些 API 的创建者会推荐把 .json, .xml, .html 等文件的扩展名放在 URL 里面来指示返回内容类型，但我个人并不习惯这么做。我依然喜欢通过 Accept header 来指示返回内容类型（这也是 HTTP 标准的一部分），并且我觉得这么做也比较适当一些。

Content Type的四种格式

Content-Type的格式有四种：分别是application/x-www-form-urlencoded（这也是默认格式）、application/json、text/xml以及multipart/form-data格式。

默认情况下是 application/x-www-urlencoded，当表单使用 POST 请求时，数据会被以 x-www-urlencoded 方式编码到 Body 中来传送。

而如果 GET 请求，则是附在 url 链接后面来发送。GET 请求只支持 ASCII 字符集，因此，如果我们要发送更大字符集的内容，我们应使用 POST 请求。

如果要发送大量的二进制数据（non-ASCII），application/x-www-form-urlencoded 显然是低效的，因为它需要用 3 个字符来表示一个 non-ASCII 的字符。因此，这种情况下，应该用“multipart/form-data” 格式。

application/x-www-form-urlencoded对于发送大量二进制数据或包含非ASCII字符的文本效率低下。“multipart / form-data”应该用于提交包含文件，非ASCII数据和二进制数据的表单。

application/x-www-form-urlencoded

浏览器用x-www-form-urlencoded的编码方式把form数据转换成一个字串（name1=value1&name2=value2…），然后把这个字串append到url后面，用?分割，加载这个新的url。

编码格式就是application/x-www-form-urlencoded（将键值对的参数用&连接起来，如果有空格，将空格转换为+加号；有特殊符号，将特殊符号转换为ASCII HEX值）

在uniapp中最终发送给服务器的数据是 String 类型，如果传入的 data 不是 String 类型，会被转换成 String。转换规则如下：

对于 GET 方法，会将数据转换为 query string。例如 { name: ‘name’, age: 18 } 转换后的结果是 name=name&age=18。
对于 POST 方法且 header[‘content-type’] 为 application/json 的数据，会进行 JSON 序列化。
对于 POST 方法且 header[‘content-type’] 为 application/x-www-form-urlencoded 的数据，会将数据转换为 query string。

application/json

application/json 这个 Content-Type 作为响应头大家肯定不陌生。实际上，现在越来越多的人把它作为请求头，用来告诉服务端消息主体是序列化后的 JSON 字符串。由于 JSON 规范的流行，除了低版本 IE 之外的各大浏览器都原生支持 JSON.stringify，服务端语言也都有处理 JSON 的函数，使用 JSON 不会遇上什么麻烦。

JSON 格式支持比键值对复杂得多的结构化数据，这一点也很有用。

application/json 这个 Content-Type 也是非常常见的，越来越多的人使用该方式传递，该方式传递的是序列化后的字符串，因为采用的是JSON格式的数据，因此支持更多复杂的类型。请求体一般如下：

{
    "username":"admin",
    "password":"admin",
}

text/xml

这就要提到XML-RPC（XML Remote Procedure Call）。它是一种使用 HTTP 作为传输协议，XML 作为编码方式的远程调用规范。

XML-RPC 协议简单、功能够用，各种语言的实现都有。它的使用也很广泛，如 WordPress 的 XML-RPC Api，搜索引擎的 ping 服务等等。JavaScript 中，也有现成的库支持以这种方式进行数据交互，能很好的支持已有的 XML-RPC 服务。不过，我个人觉得 XML 结构还是过于臃肿，一般场景用 JSON 会更灵活方便。

multipart/form-data

multipart/form-data简介

multipart/form-data的基础是post请求，即基于post请求来实现的
multipart/form-data形式的post与普通post请求的不同之处体现在请求头，请求体的2部分。

multipart/form-data请求头

必须包含Content-Type信息，且其值也必须规定为multipart/form-data，同时还需要规定一个内容分割符用于分割请求体中不同参数的内容（普通post请求的参数分割符默认为 &，参数与参数值的分隔符为 =。具体的头信息格式如下：

Content-Type: multipart/form-data; boundary=${bound}   
 
其中${bound} 是一个占位符，代表我们规定的具体分割符；可以自己任意规定，
但为了避免和正常文本重复了，尽量要使用复杂一点的内容。
如：--------------------56423498738365

multipart/form-data请求体：
它也是一个字符串，不过和普通post请求体不同的是它的构造方式。普通post请求体是简单的键值对连接，格式如下：

k1=v1&k2=v2&k3=v3

而multipart/form-data则是添加了分隔符、参数描述信息等内容的构造体。具体格式如下:

POST http://www.xx.com/myproject/service1
Host: 192.168.0.201:8694
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Cache-Control: no-cache
Postman-Token: c3d85a6c-9849-7e3e-5c89-5b994b335b1d
 
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="name1"
 
value1
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="name2"
 
value2
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file1"; filename="94b5b232gw1ewlx3p595wg20ak0574qq.gif"
Content-Type: image/gif
 
 
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file2"; filename="1443175219259.jpg"
Content-Type: image/jpeg

----WebKitFormBoundary7MA4YWxkTrZu0gW