【SpringMVC】RESTFul风格接口设计和实战 第三期

---

概述

URL 设计

Java接口设计_参考

POST /users
GET /users
PUT /users
DELETE /users

GET /users/12
PUT /users/12
DELETE /users/12

一、 RESTFul风格简介

RESTful（Representational State Transfer） 是一种基于 HTTP 和标准化的设计原则的软件架构风格。

学习RESTful设计原则可以帮助我们更好去设计HTTP协议的API接口！！

二、 RESTFul风格特点

1. 每一个URI代表1种资源（URI 是名词）；
2. 客户端使用GET、POST、PUT、DELETE 4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源；
3. 资源的表现形式是XML或者JSON；
4. 客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。
   

三、 RESTFul风格设计规范

3.1 HTTP协议请求方式要求

具体的操作要符合HTTP协议定义的请求方式的语义。

操作	请求方式
查询操作	GET
保存操作	POST
删除操作	DELETE
更新操作	PUT

3.2 URL路径风格要求

操作	传统风格	REST 风格
保存	/CRUD/saveEmp	URL 地址：/CRUD/emp 请求方式：POST
删除	/CRUD/removeEmp?empId=2	URL 地址：/CRUD/emp/2 请求方式：DELETE
更新	/CRUD/updateEmp	URL 地址：/CRUD/emp 请求方式：PUT
查询	/CRUD/editEmp?empId=2	URL 地址：/CRUD/emp/2 请求方式：GET

根据接口的具体动作，选择具体的HTTP协议请求方式

路径设计从原来携带动标识，改成名词，对应资源的唯一标识即可！

---

实战

一、需求分析

• 数据结构： User {id 唯一标识,name 用户名，age 用户年龄}
• 功能分析
  • 用户数据分页展示功能（条件：page 页数 默认1，size 每页数量 默认 10）
  • 保存用户功能
  • 根据用户id查询用户详情功能
  • 根据用户id更新用户数据功能
  • 根据用户id删除用户数据功能
  • 多条件模糊查询用户功能（条件：keyword 模糊关键字，page 页数 默认1，size 每页数量 默认 10）

二、RESTFul风格接口设计

接口设计

功能	接口和请求方式	请求参数	返回值
分页查询	GET /user	page=1&size=10	{ 响应数据 }
用户添加	POST /user	{ user 数据 }	{响应数据}
用户详情	GET /user/1	路径参数	{响应数据}
用户更新	PUT /user	{ user 更新数据}	{响应数据}
用户删除	DELETE /user/1	路径参数	{响应数据}
条件模糊	GET /user/search	page=1&size=10&keyword=关键字	{响应数据}

对于敏感信息，最好使用 POST 和请求体来传递参数

三、后台接口实现

• 用户实体类

@Data
public class User {
    private Integer id;
    private String name;
    private Integer age;
}

• controller

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

    /**
     * 模拟分页查询业务接口
     * @param page
     * @param size
     * @return
     */
    @GetMapping
    public List<User> show(@RequestParam(required = false,defaultValue = "1") int page,
                           @RequestParam(required = false,defaultValue = "10") int size){
        System.out.println("分页查询业务！如果参数名和属性名不一样 需要 name = \"page\", 加上名字 ");
        return null;
    }

    /**
     * 模拟添加 保存 业务接口
     * @return
     */
    @PostMapping
    public User add(@RequestBody User user){
        return user;
    }

    /**
     * 模拟用户详情业务接口
     * @param id
     * @return
     */
    @GetMapping("{id}")
    public User detail(@PathVariable Integer id){
        return null;
    }

	// 模拟用户更新业务接口
    @PutMapping
    public User update(@RequestBody User user){
        return user;
    }

    @DeleteMapping("{id}")
    public User delete(@PathVariable Integer id){
        return null;
    }

	// 模拟条件分页查询业务接口
    @GetMapping("search")
    public List<User> search(String keyword,
                       @RequestParam(required = false,defaultValue = "1") int page,
                       @RequestParam(required = false,defaultValue = "10") int size){

        return null;
    }
}

---

总结

模糊查询 有范围 返回多数据

@RequestParam

    /**
     * 模拟分页查询业务接口
     * @param page
     * @param size
     * @return
     */
    @GetMapping
    public List<User> show(@RequestParam(required = false,defaultValue = "1") int page,
                           @RequestParam(required = false,defaultValue = "10") int size){
        System.out.println("分页查询业务！如果参数名和属性名不一样 需要 name = \"page\", 加上名字 ");
        return null;
    }

    @GetMapping("search")
    public List<User> search(String keyword,
                       @RequestParam(required = false,defaultValue = "1") int page,
                       @RequestParam(required = false,defaultValue = "10") int size){

        return null;
    }

用户 添加 与 更新 请求参数接收数据

@RequestBody

    /**
     * 模拟添加操作
     * @return
     */
    @PostMapping
    public User add(@RequestBody User user){
        return user;
    }
    
    @PutMapping
    public User update(@RequestBody User user){
        return user;
    }

显示用户详情/删除用户 需要 id 确认查询显示与删除

@PathVariable

    /**
     *用户详情
     * @param id
     * @return
     */
    @GetMapping("{id}")
    public User detail(@PathVariable Integer id){
        return null;
    }
    
    @DeleteMapping("{id}")
    public User delete(@PathVariable Integer id){
        return null;
    }