一、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 数据格式) |
@PathVariable | URL 中的 {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