四、RESTFul风格设计和实战

1、RESTFul风格简介

1、RESTful（Representational State Transfer）是一种软件架构风格，用于设计网络应用程序和服务之间的通信。它是一种基于标准 HTTP 方法的简单和轻量级的通信协议，广泛应用于现代的Web服务开发。

2、通过遵循 RESTful 架构的设计原则，可以构建出易于理解、可扩展、松耦合和可重用的 Web 服务。RESTful API 的特点是简单、清晰，并且易于使用和理解，它们使用标准的 HTTP 方法和状态码进行通信，不需要额外的协议和中间件。

3、总而言之，RESTful 是一种基于 HTTP 和标准化的设计原则的软件架构风格，用于设计和实现可靠、可扩展和易于集成的 Web 服务和应用程序！

4、图解

2、RESTFul风格特点

1、每一个URI代表1种资源（URI 是名词）；

2、客户端使用GET、POST、PUT、DELETE 4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源；

3、资源的表现形式是XML或者JSON；

4、客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。

5、图解

3、RESTFul风格设计规范

1、HTTP协议请求方式要求

1、REST 风格主张在项目设计、开发过程中，具体的操作符合HTTP协议定义的请求方式的语义。

2、操作

2、URL路径风格要求

1、REST风格下每个资源都应该有一个唯一的标识符，例如一个 URI（统一资源标识符）或者一个 URL（统一资源定位符）。资源的标识符应该能明确地说明该资源的信息，同时也应该是可被理解和解释的！

2、使用URL+请求方式确定具体的动作，他也是一种标准的HTTP协议请求！

3、例子

4、总结

• 根据接口的具体动作，选择具体的HTTP协议请求方式
• 路径设计从原来携带动标识，改成名词，对应资源的唯一标识即可！

3、RESTFul风格好处

1、含蓄、安全

• 使用问号键值对的方式给服务器传递数据太明显，容易被人利用来对系统进行破坏。使用 REST 风格携带数据不再需要明显的暴露数据的名称

2、风格统一

• URL 地址整体格式统一，从前到后始终都使用斜杠划分各个单词，用简单一致的格式表达语义

3、无状态

• 在调用一个接口（访问、操作资源）的时候，可以不用考虑上下文，不用考虑当前状态，极大的降低了系统设计的复杂度。

4、严谨，规范

• 严格按照 HTTP1.1 协议中定义的请求方式本身的语义进行操作。

5、简洁，优雅

• 过去做增删改查操作需要设计4个不同的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

6、丰富的语义

• 通过 URL 地址就可以知道资源之间的关系。它能够把一句话中的很多单词用斜杠连起来，反过来说就是可以在 URL 地址中用一句话来充分表达语义。
• http://localhost:8080/shop
• http://localhost:8080/shop/product
• http://localhost:8080/shop/product/cellPhone
• http://localhost:8080/shop/product/cellPhone/iPhone

4、RESTFul风格实战

1、需求分析

1、数据结构： User {id 唯一标识,name 用户名，age 用户年龄}

2、数据结构

• 用户数据分页展示功能（条件：page 页数 默认1，size 每页数量 默认 10）
• 保存用户功能
• 根据用户id查询用户详情功能
• 根据用户id更新用户数据功能
• 根据用户id删除用户数据功能
• 多条件模糊查询用户功能（条件：keyword 模糊关键字，page 页数 默认1，size 每页数量 默认 10）

2、接口设计

1、图解

2、接口

3、问题讨论

1、为什么查询用户详情，就使用路径传递参数，多条件模糊查询，就使用请求参数传递？

• 误区：restful风格下，不是所有请求参数都是路径传递！可以使用其他方式传递！

2、在 RESTful API 的设计中，路径和请求参数和请求体都是用来向服务器传递信息的方式。

• 对于查询用户详情，使用路径传递参数是因为这是一个单一资源的查询，即查询一条用户记录。使用路径参数可以明确指定所请求的资源，便于服务器定位并返回对应的资源，也符合 RESTful 风格的要求。
• 而对于多条件模糊查询，使用请求参数传递参数是因为这是一个资源集合的查询，即查询多条用户记录。使用请求参数可以通过组合不同参数来限制查询结果，路径参数的组合和排列可能会很多，不如使用请求参数更加灵活和简洁。

3、此外，还有一些通用的原则可以遵循：

• 路径参数应该用于指定资源的唯一标识或者 ID，而请求参数应该用于指定查询条件或者操作参数。
• 请求参数应该限制在 10 个以内，过多的请求参数可能导致接口难以维护和使用。
• 对于敏感信息，最好使用 POST 和请求体来传递参数。

4、代码实现

1、只实现了Controller层面，没有实际业务

package com.atgui.controller;

import com.atgui.pojo.User;
import jakarta.ws.rs.PathParam;
import org.springframework.web.bind.annotation.*;

import java.util.List;

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

    @RequestMapping
    public List<User> page(@RequestParam(required = false,defaultValue="1") int page,
                           @RequestParam(required = false,defaultValue = "10") int size){
        return null;
    }

    @PostMapping
    public User save(User user){
        return user;
    }

//    用户详情
    @RequestMapping("{id}")
    public User detail(@PathVariable() int id){
        return  null;
    }

//    用户更新
    @PutMapping()
    public User update(@RequestBody User user){
        return  user;
    }

//  用户删除
    @DeleteMapping("{id}")
    public User delete(@PathVariable() int 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;
    }

}

2、得有个实体类User

package com.atgui.pojo;

import lombok.Data;

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