3 RESTful接口规范
1 发展来源和必要性
|
RESTful是目前最流行的API设计规范，它是用于Web数据接口的设计；REST它是 Representational State Transfer的简称，中文的含义是: "表征状态转移" 或 "表现层状态转化" 1 发展来源和必要性 RESTful API 设计由 Roy Fielding 博士在其 2000 年的博士论文中定义。后来经过社区以及互联网发展的趋势需要就慢慢成为了一个标准； 目前我们实现一个RESTful接口，可以在web端 pc端及移动端，实现多端同时调用，而且前后端分离，使得前端开发无须关注过多后端业务逻辑；这是我们目前想当然的一个使用；其实在之前我们的页面、数据以及模板渲染工作都是在服务端进行的；也就是说以前开发者都是全栈开发；像我们上学时的.net Form等.net框架、flex开发；都是服务器端渲染，一个人进行前端页面以及后台数据查询、数据和页面模板绑定工作php接口，一人负责多项工作； 维护工作比较困难；这里可能更应该强调是目前这个互联网环境下 换人的成本太大； 所以这里所说的维护并不是人员的维护系统难度大小，更可能是如果一个这样的系统直接换人去维护的难度和成本大小，因为需要找一个对前端、服务端、数据查询等都需满足的人，这对于咱目前各大企业如此频繁的人员流动的市场简直就是噩梦，从这个角度来看，前后端分离势在必行，可能不仅仅是因为技术原因，市场才是主要导向吧； 所以伴随着前后端分离潮流，RESTful api标准就慢慢流行起来了； 2Rest设计原则 后端实现的接口怎么才能算是一个rest风格的接口呢，需要满足以下风格 2.1每一个URI代表一种资源 这个很好理解，就是一个URI只代表一种类型的资源 2.2同一种资源有多种表现形式(xml/json) 一种资源可以用多种格式返回，客户端请求的时候，我们可以在请求头中设置参数，要求restful返回指定类型的数据，这是RESTful接口需要满足的元原则；比如 Accept:application/xml 请求时设置返回形式是xml，如使用ajax请求，则需要设置contentType:application/xml Accept:application/json 请求时设置返回形式是json，如使用ajax请求，则需要设置contentType:application/json 2.3所有的操作都是无状态的 http请求本身是无状态的，而RESTful是建立在无状态http协议基础上的；所以本身RESTful的各种请求也是无状态的； 怎么理解这个无状态呢 可以这么理解:协议对于事务处理没有记忆能力。缺少状态意味着如果后续处理需要前面的信息，则它必须重传，这样可能导致每次连接传送的数据量增大。但另一方面，在服务器不需要先前信息时它的应答就较快。 举个，当浏览器发送请求给服务器的时候，服务器响应，但是同一个浏览器再发送请求给服务器的时候，他会响应，但是他不知道你就是刚才那个浏览器，简单地说，就是服务器不会去记得你； 所以如果需要有状态之类的记忆功能，就借助浏览器的cookie、session及token技术去实现即可； 2.4 规范统一接口 Rest接口约束定义为: 资源识别：它表示通过uri表示出要操作的资源； 请求动作：通过请求动作(http method)标识要执行的操作； 响应信息;：通过返回的状态码来表示这次请求的执行结果； 直接对比下 达不到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风格接口规范： 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请求方式 添加新的用户 2.5返回一致的数据格式 这个也好理解，比如返回的数据格式，最起码有我们标准要求的几个字段，比如状态、code、信息、data等。如下 { "code": 401, "status": "error", "message": '用户没有权限', "data": null } { "code": 200, "status": "success", "data": [{ "userName": "小白GIS", "age": 7 }] } 2.6 可缓存(客户端可以缓存响应的内容) 现在接口基本都提供了可缓存的功能，也就是说在接口开发阶段，我们会设置浏览器是否可以缓存，以及缓存的类型和有效时间等等.比如强缓存、协商缓存规范都是服务器端设置的 3 RESTful接口规范 3.1 uri规范 我们在接口路径定义的时候，尽量使用如下规范即可 1) uri末尾不需要出现斜杠/ 2) 在uri中使用斜杠/是表达层级关系的。 3) 在uri中可以使用连接符-, 来提升可读性。 比如 比 中的可读性更好。 4) 在uri中不允许出现下划线字符_. 5) 在uri中尽量使用小写字符。 6) 在uri中不允许出现文件扩展名. 比如接口为 /xxx/api, 不要写成 /xxx/api.php 这样的是不合法的。 7) 在uri中使用复数形式。 注意:在RESTful架构中，每个uri代表一种资源，因此uri设计中不能使用动词，只能使用名词，并且名词中也应该尽量使用复数形式。使用者应该使用相应的http动词 GET、POST、PUT、PATCH、DELETE等操作这些资源即可。 3.2 请求方式 GET (SELECT): 查询；从服务器取出资源. POST(CREATE): 新增; 在服务器上新建一个资源。 PUT(UPDATE): 更新; 在服务器上更新资源(客户端提供改变后的完整资源)。 PATCH(UPDATE): 更新；在服务器上更新部分资源(客户端提供改变的属性)。 DELETE(DELETE): 删除; 从服务器上删除资源。 3.3 参数命名规范 参数建议使用下划线 http://xxx.com/api/male_users // 获取男性用户。 http://xxx.com/api/male_users&sort=age_desc // 获取年纪降序的男性用户 4 状态码 分类分类描述 1** 信息，服务器收到请求，需要请求者继续执行操作 2** 成功，操作被成功接收并处理 3** 重定向，需要进一步的操作以完成请求 4** 客户端错误，请求包含语法错误或无法完成请求 5** 服务器错误，服务器在处理请求的过程中发生了错误 状态码状态码英文名称中文描述 100 Continue 继续。客户端应继续其请求 101 Switching Protocols 切换协议。服务器根据客户端的请求切换协议。只能切换到更高级的协议，例如，切换到HTTP的新版本协议 200 OK 请求成功。一般用于GET与POST请求 201 Created 已创建。成功请求并创建了新的资源 202 Accepted 已接受。已经接受请求，但未处理完成 203 Non-Authoritative Information 非授权信息。请求成功。但返回的meta信息不在原始的服务器，而是一个副本 204 No Content 无内容。服务器成功处理，但未返回内容。在未更新网页的情况下，可确保浏览器继续显示当前文档 205 Reset Content 重置内容。服务器处理成功，用户终端（例如：浏览器）应重置文档视图。可通过此返回码清除浏览器的表单域 206 Partial Content 部分内容。服务器成功处理了部分GET请求 300 Multiple Choices 多种选择。请求的资源可包括多个位置，相应可返回一个资源特征与地址的列表用于用户终端（例如：浏览器）选择 301 Moved Permanently 永久移动。请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。今后任何新的请求都应使用新的URI代替 302 Found 临时移动。与301类似。但资源只是临时被移动。客户端应继续使用原有URI 303 See Other 查看其它地址。与301类似。使用GET和POST请求查看 304 Not Modified 未修改。所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。客户端通常会缓存访问过的资源，通过提供一个头信息指出客户端希望只返回在指定日期之后修改的资源 305 Use Proxy 使用代理。所请求的资源必须通过代理访问 306 Unused （编辑：晋中站长网） 【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容! |
