restful请求风格使用详解

1. 什么是Restful请求风格

参考：https://www.cnblogs.com/MTRD/p/12153561.html
RestFul风格：一个资源定位和资源操作的风格，不是标准，也不是协议。基于此风格的路径访问可以隐藏真实的参数传递，以提高网站的安全访问。

2. 使用Restful请求风格有什么好处

• 使路径变得更加简洁。

• 获得参数更加方便，框架会自动进行类型转换。

• 通过路径变量的类型可以约束访问参数，如果类型不一样，则访问不到对应的请求方法，如这里访问的路径是/commit/1/a，则路径与方法不匹配。而不会是参数转换失败。

传统方式操作资源：通过不同参数实现不同的效果！方法单一，POST和GET
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 删除，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

3. 使用Restful请求风格要求

1. RESTful架构风格规定，数据的元操作，即CRUD(create, read, update和delete,即数据的增删查改)操作，分别对应于HTTP方法：

GET用来获取资源（查询）
POST用来新建资源（添加）
PUT用来更新资源（修改）（客户端提供改变后的完整资源）
PATCH用来更新资源（修改）(客户端提供改变的属性)
DELETE用来删除资源（删除）

这样就统一了数据操作的接口，仅通过HTTP方法，就可以完成对数据的所有增删查改工作

2. RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees



下面是一些例子:
GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

3. 如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数：

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

1、URL 中不应该出现任何表示操作的动词，链接只用于对应资源；

2、URL 中应该单复数区分，推荐的实践是永远只用复数；比如GET /api/users表示获取用户的列表；如果获取单个资源，传入 ID，比如/api/users/123表示获取单个用户的信息；（个人觉得还是要区分一下单复数，/api/users表示获取用户的列表；/api/user/123表示获取单个用户的信息。这样写的好处是通过地址就能得知返回的是实体是一个对象，还是一个集合）

3、按照资源的逻辑层级，对 URL 进行嵌套，比如一个用户属于某个团队，而这个团队也是众多团队之一；那么获取这个用户的接口可能是这样：GET /api/teams/123/members/234 表示获取 id 为 123 的小组下，id 为234 的成员信息。

按照类似的规则，可以写出如下的接口
/api/teams （对应团队列表）
/api/teams/123 （对应 ID 为 123 的团队）
/api/teams/123/members （对应 ID 为 123 的团队下的成员列表）
/api/teams/123/members/456 （对应 ID 为 123 的团队下 ID 未 456 的成员）

4. Restful 风格列子

@RestController
@RequestMapping("/user")
public class UserController {

    @Resource
    private UserMapper userMapper;

    //@RequestMapping("/listByUser")
    @GetMapping("/")
    public List<User> listByUser() {
        return userMapper.list();
    }

    //@RequestMapping("/getOneUser")
    @GetMapping("/{id}")
    public User getOneUser(@PathVariable("id") int id) {
        return userMapper.selectByPrimaryKey(id);
    }

    //@RequestMapping("/addUser")
    @PostMapping("/")
    public int addUser(User user) {
        return userMapper.insert(user);
    }

    //@RequestMapping("/deleteUser")
    @DeleteMapping("/{id}")
    public int deleteUser(@PathVariable("id") int id) {
        return userMapper.deleteByPrimaryKey(id);
    }

    @PutMapping("/")
    public int updateUser(User user) {
        return userMapper.updateByPrimaryKey(user);
    }
}