RESTful 风格
什么是Api(接口)
Api的全称是Application Programming Interface,也就是应用程序编程接口,它就是将我们写的功能封装成组件,目的是提供一个应用程序接口给其他程序调用或者其他开发人员进行访问,并且调用的开发人员不需要访问源码和理解内部的逻辑和工作原理,即可直接使用该功能。
前后端分离
在前后端分离的模式下,前端开发人员就需要去调用后端开发人员所提供的接口,根据Api文档进行调用,Api文档可通过Swagger进行生成。
前后端分离并不只是开发模式,也是一种Web应用的架构模式,在开发之前,前后端人员会先约定好数据交互接口,然后同时并行开发,就不会出现总有一方需要等另一方开发完才能继续开发的情况。
后端项目里不会出现页面,只负责给前端提供接口,而前端只需要专心写页面和渲染页面,数据调用后端提供的REST风格接口即可。
前后端分离的核心:前端负责显示,后端负责提供数据,互不干扰。
RESTful 风格
- 概念
RESTFUL是一种网络应用程序的设计风格和开发方式,基于HTTP,可以使用 XML 格式定义或 JSON 格式定义。最常用的数据格式是JSON。由于JSON能直接被JavaScript读取,所以,使用JSON格式的REST风格的API具有简单、易读、易用的特点。
REST与技术无关,代表的是一种软件架构风格,REST是Representational State Transfer的简称,中文翻译为“表征状态转移”或“表现层状态转化”。 - 资源
REST 是面向资源的,每个资源都有一个唯一的资源定位符(URI)。每个URI代表一种资源(resource),所以URI中不能有动词,只能有名词,而且所用的名词往往与数据库的表名对应。一般来说,数据库中的表都是同种记录的"集合"(collection),所以URI中的名词也应该使用复数。 - 请求方式
请求方式 | 含义 |
---|---|
GET(SELECT) | 从服务器取出资源(一项或多项) |
POST(CREATE) | 在服务器新建一个资源 |
PUT(UPDATE) | 在服务器更新资源(更新完整资源) |
PATCH(UPDATE) | 在服务器更新资源, PATCH更新个别属性 |
DELETE(DELETE) | 从服务器删除资源 |
- 与非REST设计对比
-
非Rest设计,以往我们都会这么写:
http://localhost:8080/admin/getUser (查询用户)
http://localhost:8080/admin/addUser (新增用户)
http://localhost:8080/admin/updateUser (更新用户)
http://localhost:8080/admin/deleteUser (删除用户)
总结:以不同的URL(主要为使用动词)进行不同的操作。 -
Rest架构:
GET http://localhost:8080/admin/user (查询用户)
POST http://localhost:8080/admin/user (新增用户)
PUT http://localhost:8080/admin/user (更新用户)
DELETE http://localhost:8080/admin/user (删除用户)
总结:URL只指定资源,以HTTP方法动词进行不同的操作。用HTTP STATUS/CODE定义操作结果。
-
域名
用api关键字来标识接口url
https://api.example.com
https://example.org/api/
注:看到api字眼,就代表该请求url链接是完成前后台数据交互的 -
版本
- 将版本信息放在URL中,如:
https://api.example.com/v1/
https://api.example.com/v2/
v1,v2代表不同数据版本的提现,前提是一种数据资源有多个版本
- 将版本信息放在请求头中。
- url路径
- 视网络上任何东西都是资源,均使用名词表示(一般为复数形式)
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees - 在url链接中不要出现操作资源的动词
错误示范:https://api.baidu.com/delete-user - 特殊的接口可以出现动词,因为这些接口一般没有一个明确的资源,或是动词就是接口的核心含义
https://api.baidu.com/place/search
https://api.baidu.com/login
-
method请求方式
GET :从服务器取出资源(一项或多项)
POST :在服务器新建一个资源
PUT :在服务器更新资源(客户端提供改变后的完整资源)
PATCH :在服务器更新资源(客户端提供改变的属性)
DELETE :从服务器删除资源 -
过滤
通过在url上传参的形式传递搜索条件
https://api.example.com/v1/zoos?limit=10:指定返回记录的数量
https://api.example.com/v1/zoos?offset=10:指定返回记录的开始位置
https://api.example.com/v1/zoos?page=2&per_page=100:指定第几页,以及每页的记录数
https://api.example.com/v1/zoos?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序
https://api.example.com/v1/zoos?animal_type_id=1:指定筛选条件 -
状态码
200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功。
301:永久重定向
302:暂时重定向
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 - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
RESTful 接口代码实例
package com.zy.demo.controller;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import com.zy.demo.entity.OrderEntity;
import com.zy.demo.demo.service.OrderService;
@RequestMapping("restful/order")
@RestController
public class OrderController {
@Autowired
private OrderService orderService;
@GetMapping(value = "{id}")
//@RequestMapping(method = RequestMethod.GET)
public ResponseEntity<OrderEntity> queryOrderById(@PathVariable("id") Long id) {
try {
OrderEntity entity = orderService.queryOrderById(id);
if (null == entity) {
// 资源不存在,响应404
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(null);
}
// 200
// return ResponseEntity.status(HttpStatus.OK).body(entity);
return ResponseEntity.ok(entity);
} catch (Exception e) {
e.printStackTrace();
}
// 500
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
}
@PostMapping
//@RequestMapping(method = RequestMethod.POST)
public ResponseEntity<Void> saveOrder(OrderEntity entity) {
try {
orderService.saveOrder(entity);
return ResponseEntity.status(HttpStatus.CREATED).build();
} catch (Exception e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
// 500
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
}
@PutMapping
//@RequestMapping(method = RequestMethod.PUT)
public ResponseEntity<Void> updateOrder(OrderEntity entity) {
try {
orderService.updateOrder(entity);
return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
} catch (Exception e) {
e.printStackTrace();
}
// 500
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
}
@DeleteMapping
//@RequestMapping(method = RequestMethod.DELETE)
public ResponseEntity<Void> deleteOrder(@RequestParam(value = "id") Long id) {
try {
OrderEntity entity = orderService.queryOrderById(id);
if (null == entity) {
// 不存在返回404
return ResponseEntity.status(HttpStatus.NOT_FOUND).build();
}
orderService.deleteOrderById(id);
// 204
return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
} catch (Exception e) {
e.printStackTrace();
}
// 500
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(null);
}
}
总结
RESTful只是一种软件架构风格、设计风格,而不是标准,只是提供了一组设计原则和约束条件,它主要用于客户端和服务端交互类的软件。基于这个风格设计的软件可以更简介,更有层次,更易于实现缓存等机制。
使用RESful风格进行开发的优点是
- 使请求路径变得更加简洁
- 传递、获取参数值更加方便,框架会自动进行类型转换
- 通过路径变量@PathVariable的类型,可以约束访问参数。
- 若参数值与定义类型不匹配,则访问不到对应的方法,报错400错误的请求。
- 安全,请求路径中直接传递参数值,并用斜线/分隔,不会暴露传递给方法的参数变量名。
- 高效,更易于缓存的实现,让响应更加高效。
RESTful风格简洁,高效,安全,成为了web service开发的标配。