RESTful API详解-优快云博客

本文链接：https://blog.youkuaiyun.com/Bruce_Up/article/details/83314403

定义：

REST就是Representational State Transfer的缩写，翻译为中文就是‘表述性状态转移

Restful就是一个资源定位及资源操作（面向资源）的风格。不是标准也不是协议，只是一种风格。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

概念及特点：

资源：互联网所有的事物都可以被抽象为资源
REST 系统的特征：
客户-服务器（Client-Server），提供服务的服务器和使用服务的客户需要被隔离对待。
无状态（Stateless），来自客户的每一个请求必须包含服务器处理该请求所需的所有信息。换句话说，服务器端不能存储来自某个客户的某个请求中的信息，并在该客户的其他请求中使用。无状态是相当于于有状态的，有状态的每一步操作都依赖于前一步操作，只要前置操作不成功，后续操作就无法执行；
可缓存（Cachable），服务器必须让客户知道请求是否可以被缓存。（Ross：更详细解释请参考理解本真的REST架构风格以及 StackOverflow 的这个问题中对缓存的解释。）
分层系统（Layered System），服务器和客户之间的通信必须被这样标准化：允许服务器和客户之间的中间层（Ross：代理，网关等）可以代替服务器对客户的请求进行回应，而且这些对客户来说不需要特别支持。
统一接口（Uniform Interface），客户和服务器之间通信的方法必须是统一化的。（Ross：GET,POST,PUT.DELETE, etc）
支持按需代码（Code-On-Demand，可选），服务器可以提供一些代码或者脚本（Ross：Javascrpt，flash，etc）并在客户的运行环境中执行。这条准则是这些准则中唯一不必必须满足的一条。（Ross：比如客户可以在客户端下载脚本生成密码访问服务器。）

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）。
PATCH（UPDATE）：在服务器更新资源（客户端提供需要修改的资源数据）。
DELETE（DELETE）：从服务器删除资源。

传统API接口和RESTful比较：

传统API缺点：

Url的命名混乱，Url是统一资源定位符，重点是资源。在Url上对应的都是一个资源，不会有多余的Url跟他对应。

注意，这里点的是Url地址，并不是单独的参数，他就是一个/room/{room_id}这样的东西，举个栗子,/room/3242 这就表示3242号房间。这是一个清爽的世界啊，你想想，之前的Url是什么都要，我开房，可能是/open/room/3242 我要退房可能是/exit/3242/room，我要打理房间，可能是room/3242?method=clean.够了！这些乱七八糟的东西全够了，让世界回归清爽的本质，一间房，就是/room/3242 没有别的Url地址了。

对比：

传统方式操作资源 
http://127.0.0.1/item/queryItem.action?id=1 查询,GET 
http://127.0.0.1/item/saveItem.action 新增,POST 
http://127.0.0.1/item/updateItem.action 更新,POST 
http://127.0.0.1/item/deleteItem.action?id=1 删除,GET或POST

使用RESTful操作资源 
http://127.0.0.1/item/1 查询,GET 
http://127.0.0.1/item 新增,POST 
http://127.0.0.1/item 更新,PUT 
http://127.0.0.1/item/1 删除,DELETE

而且传统的API后台我们可能会写出很多返回值，而且各种各样的，比如操作成功返回 操作成功或者1 操作失败返回 操作失败或者0

这还要我们自己去解析，还要前端和后端去协商你返回的0是啥意识啊。但是REST返回值是标准的，

格式固定，第一行永远是操作失败或者成功的状态码，第二行是返回的类型，第三行内容的长度，第五行开始是内容。

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx

{
   "url" : "/api/categories/1",
   "label" : "Food",
   "items_url" : "/api/items?category=1",
   "brands" : [
         {
            "label" : "张三",
            "brand_key" : "32073",
            "url" : "/api/brands/32073"
         }, {
            "label" : "乐事",
            "brand_key" : "56632",
            "url" : "/api/brands/56632"
         }
         ...
   ]
}

这样我只需写一个程序解析返回的信息就可以了，可以重用，但是我们上面传统的不仅仅要协商，还有有不同的解析程序，稍微改变，就不能正常使用了。所以rest的明显更加通用。

RESTful例子：

需求
RESTful方式实现商品信息查询，返回json数据

取参
使用RESTful风格开发的接口，根据id查询商品，接口地址是：
http://127.0.0.1/item/1
我们需要从url上获取商品id，步骤如下：
1.使用注解@RequestMapping(“item/{id}”)声明请求的url
{xxx}叫做占位符，请求的URL可以是“item /1”或“item/2”

2.使用(@PathVariable() Integer id)获取url上的数据

如果@RequestMapping中表示为”item/{id}”，id和形参名称一致，@PathVariable不用指定名称。如果不一致，例如”item/{ItemId}”则需要指定名称@PathVariable(“itemId”)。

/**
 * 使用RESTful风格开发接口，实现根据id查询商品
 * 
 * @param id
 * @return
 */
@RequestMapping("item/{id}")
@ResponseBody
public Item queryItemById(@PathVariable() Integer id) {
    Item item = this.itemService.queryItemById(id);
    return item;
}

http://127.0.0.1/item/123?id=1
注意两个区别
1.@PathVariable是获取url上数据的。@RequestParam获取请求参数的（包括post表单提交）

2.如果加上@ResponseBody注解，就不会走视图解析器，不会返回页面，目前返回的json数据。如果不加，就走视图解析器，返回页面

地址① http://localhost:8989/SSSP/emps?pageNo=2

地址② http://localhost:8989/SSSP/emp/7

如果想获取地址①中的 pageNo的值 ‘2’ ，则使用 @RequestParam ，

如果想获取地址②中的 emp/7 中的 ‘7 ’ 则使用 @PathVariable

	@RequestMapping("/emps")
	public String list(@RequestParam(value="pageNo",required=false,
			defaultValue="1")String pageNoStr,Map<String, Object>map){
		
		int pageNo = 1;
		
		try {
			//对pageNo 的校验 
			pageNo = Integer.parseInt(pageNoStr);
			if(pageNo<1){
				pageNo = 1;
			}
		} catch (Exception e) {}
		
		Page<Employee> page = employeeService.getPage(pageNo, 5);
		map.put("page",page);
		
		return "emp/list";
	}

	@RequestMapping(value="/emp/{id}",method=RequestMethod.GET)
	public String edit(@PathVariable("id")Integer id,Map<String , Object>map){
		Employee employee = employeeService.getEmployee(id);
		List<Department> departments = departmentService.getAll();
		map.put("employee", employee);
		map.put("departments", departments);
		return "emp/input";
	}

RESTful优点&缺点:

优点是因为他对uri进行了限制，只用于定义资源。这样看起来比较容易理解。尤其是对简单的对象的增删改查，很好理解。

缺点是因为这种限制，导致设计uri变得复杂了。尤其是复杂的关系，操作，资源集合，硬性套用rest原则设计非常困难。在rest基础上的HATEOAS，返回的json里增加了相应的关系和url。这也同样带来问题。好处是对简单的关系，的确可以通过url进一步处理。但对复杂的关系和操作，HATEOAS并不能胜任描述。反而在单纯的数据中增加了一堆垃圾信息。