RESTful 规范风格

一、RESTful简介

REST: (Representational State Transfer,表述性状态转移)是一种软件架构风格,由 Roy Fielding 博士在 2000 年提出。是一种软件架构风格、设计风格,而不是标准,只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制。
满足REST设计风格的程序或接口我们称之为RESTful。

二、RESTful风格核心特点

1.无状态

每个请求包含处理所需的所有信息。
服务器不能保存客户端的信息, 每一次从客户端发送的请求中,要包含所有必须的状态信息,会话信息由客户端保存, 服务器端根据这些状态信息来处理请求。
当客户端可以切换到一个新状态的时候发送请求信息, 当一个或者多个请求被发送之后, 客户端就处于一个状态变迁过程中。 每一个应用的状态描述可以被客户端用来初始化下一次的状态变迁。

2.统一接口

使用标准 HTTP 方法进行操作。
对资源的操作包括获取、创建、修改和删除,这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。换言而知,使用RESTful风格的接口但从接口上你可能只能定位其资源,但是无法知晓它具体进行了什么操作,需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断。具体的HTTP方法和方法含义如下:

HTTP方法描述幂等性安全性
GET从服务器取出资源(一项或多项)
POST在服务器新建一个资源
PUT在服务器更新完整资源(客户端提供资源数据)
PATCH在服务器更新部分资源(客户端提供需要修改的资源数据)
DELETE从服务器删除资源

幂等性:同样的操作无论执行一次或多次,结果都保持一致且无副作用。

3.以资源为基础

所有内容都被抽象为资源。
资源可以是一个图片、音乐、一个XML格式、HTML格式或者JSON格式等网络上的一个实体,除了一些二进制的资源外,普通的文本资源更多以JSON为载体、面向用户的一组数据(通常从数据库中查询而得到)。

4.可缓存

服务端需回复是否可以缓存以让客户端甄别是否缓存提高效率。

5.URI指向资源

URI: Universal Resource Identifier 统一资源标志符,用来标识抽象或物理资源的一个紧凑字符串。URI包括URL和URN,在这里更多时候可能代指URL(统一资源定位符)。RESTful是面向资源的,每种资源可能由一个或多个URI对应,但一个URI只指向一种资源。

三、RESTful API使用

1.URL设计规范

URL为统一资源定位器 ,接口属于服务端资源,首先要通过URL这个定位到资源才能去访问,而通常一个完整的URL组成由以下几个部分构成:

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

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

通常一个RESTful API的path组成如下:

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

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

当然,有时候可能资源级别较大,其下还可细分很多子资源也可以灵活设计URL的path,例如:

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

此外,有时可能增删改查无法满足业务要求,可以在URL末尾加上action,例如

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

其中action就是对资源的操作。

RESTful API的URL具体设计的规范如下:

不用大写字母,所有单词使用英文且小写。
连字符用中杠"-“而不用下杠”_"
正确使用 “/“表示层级关系,URL的层级不要过深,并且越靠前的层级应该相对越稳定
结尾不要包含正斜杠分隔符”/”
URL中不出现动词,用请求方式表示动作
资源表示用复数不要用单数
不要使用文件扩展名

2.相关注解

注解作用
@RestController由 @Controller + @ResponseBody组成(返回 JSON 数据格式)
@PathVariableURL 中的 {xxx} 占位符可以通过@PathVariable(“xxx“) 绑定到控制器处理方法的形参中
@RequestMapping注解用于请求地址的解析,是最常用的一种注解
@GetMapping查询请求
@PostMapping添加请求
@PutMapping更新请求
@DeleteMapping删除请求
@RequestParam将请求参数绑定到你控制器的方法参数上(是springmvc中接收普通参数的注解)

3.HTTP响应状态码

状态码含义
200 OK - [GET]服务器成功返回用户请求的数据
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 - [*]用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的
405 Method Not Allowed方法不允许,服务器没有该方法
406 Not Acceptable - [GET]用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)
410 Gone -[GET]用户请求的资源被永久删除,且不会再得到的
422 Unprocesable entity - [POST/PUT/PATCH]当创建一个对象时,发生一个验证错误
500 INTERNAL SERVER ERROR - [*]服务器发生错误,用户将无法判断发出的请求是否成功

4.案例

4.1查询1号用户的A课程详细信息
/api/courses?course_id=A
4.2增删改查一个用户信息

错误的设计:没必要,不用写 create,delete,show

/api/accounts/create

/api/accounts/delete

/api/accounts/show

/api/accounts/update

正确的做法:

post /api/accounts/ 这个是当不知道id是什么时。

delete /api/accouts/1 下面url一样,只是方法不一样。

get /api/accounts/1/ 获取1号用户信息,

put /api/accounts/1/ 修改1号用户信息
4.3从1号用户,转账500,给2号用户

错误设计:

post /api/accounts/1/transfer/500/to/2

正确的设计,当然放在方法体是最好的。

post /api/transaction?from=1&to=2&money=500

参考地址:
https://www.runoob.com/restfulapi/restful-api-tutorial.html
https://zhuanlan.zhihu.com/p/334809573
https://blog.youkuaiyun.com/zzvar/article/details/118164133

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值