RESTful API风格

wffeige
118 阅读4分钟

rest风格解决了什么问题

不规范造成的适配成本高 image.png

一套结构清晰、符合标准、易于理解、扩展方便让大部分人都能够理解接受 image.png

REST介绍

REST（英文：Representational State Transfer，简称REST，直译过来表现层状态转换）

是一种软件架构风格、设计风格

基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制

特征

  • 客户端和服务端分离, 服务端必须独立
    • 服务端可以服务客户端
      • 前端页面
      • 安卓 ios设备等
  • 无状态
    • 客户端发出的请求中 必须包含所有的必要信息(请求时需要包括用户凭证)
    • 服务器不会在两次请求之间 保存客户端的任何状态
  • 缓存
    • 服务端需回复 是否可以缓存 以让客户端甄别是否缓存提高效率
  • 接口统一
    • 降低耦合
    • 简化、简洁
  • 系统分层
    • 客户端无法直接知道连接的到终端还是中间设备，分层允许你灵活的部署服务端项目
  • 按需编程

RESTful API设计规范

URL设计规范

URI = scheme "://" host  ":"  port "/" path [ "?" query ][ "#" fragment ]

scheme: 指底层用的协议，如http、https、ftp  
host: 服务器的IP地址或者域名  
port: 端口，http默认为80端口  
path: 访问资源的路径，就是各种web 框架中定义的route路由  
query: 查询字符串，为发送给服务器的参数，在这里更多发送数据分页、排序等参数。  
fragment: 锚点，定位到页面的资源

path 规范

通常的情况

/{version}/{resources}/{resource_id}

version：API版本号，有些版本号放置在头信息中也可以，通过控制版本号有利于应用迭代。  
resources：资源，RESTful API推荐用小写英文单词的复数形式。  
resource_id：资源的id，访问或操作该资源。

复杂的情况

/{version}/{resources}/{resource_id}/{subresources}/{subresource_id}

添加动作

/{version}/{resources}/{resource_id}/action

http动作

GET /collection：从服务器查询资源的列表（数组）
GET /collection/resource：从服务器查询单个资源
POST /collection：在服务器创建新的资源
PUT /collection/resource：更新服务器资源
DELETE /collection/resource：从服务器删除资源

put 和patch的区别是什么

PUT：此方法是用于更新整个资源的。当使用PUT请求时，前端需要提供一个完整的资源对象

PATCH：此方法是用于局部更新资源的。PATCH请求只更新指定的字段，而不是整个资源

安全性和幂等性

image.png

其中安全性是指方法不会修改资源状态，

  • 即读的为安全的，
  • 写的操作为非安全的。

幂等性的意思是操作一次和操作多次的最终效果相同，客户端重复调用也只返回同一个结果

http状态码

状态码主要分为五大类

  • 1xx：相关信息
  • 2xx：操作成功
  • 3xx：重定向
  • 4xx：客户端错误
  • 5xx：服务器错误

image.png

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功

avatar
文章
阅读
粉丝