玩转 SpringBoot 2 快速搭建 | RESTful Api 篇

Posted 2022-09-13 jerry126

概述

RESTful 是一种架构风格，任何符合 RESTful 风格的架构，我们都可以称之为 RESTful 架构。我们常说的 RESTful Api 是符合 RESTful 原则和约束的 HTTP 协议的Web 接口，需要注意的是它和 HTTP 协议并非绑定关系。我的个人理解就是：通过HTTP协议不同请求方法（GET、POST、PUT、Patch，DELETE）来判断如何操作统一命名的资源，并且通过不同的响应码来知道执行的状态。

关于 RESTful API 具体详细介绍，我推荐阅读下面 3 篇博客：
API设计：https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design By MicroSoft Azure
RESTful API设计：让您的用户满意的13个最佳实践：https://blog.florimond.dev/restful-api-design-13-best-practices-to-make-your-users-happy By Florimond Manca
RESTful API 最佳实践：http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html By 阮一峰

正如 RESTful API设计：让您的用户满意的13个最佳实践中所说：I have no authority to say that the following practices comply 100% with the holy REST principles (if there is such a thing!).
我没有权力说下面的做法100％符合神圣的REST原则（如果有这样的话！）。
我也不敢保证我的这篇文章绝对符合 REST ，但是我会尽最大努力向 REST 靠拢。

文中为了快速展示前台 RESTful 使用操作，所以示例并没有对接数据库，示例代码只是写死的逻辑返回。后期文章会将这个洞补上。

本文代码示例是在 SpringBoot 上进行操作的，如果你不会搭建SprignBoot项目可以查看我关于 SpringBoot 2 快速搭建 3 篇总结：
玩转SpringBoot 2 快速搭建 | Spring Initializr 篇
玩转 SpringBoot 2 快速搭建 | SpringToolSuite 篇
玩转 SpringBoot 2 快速搭建 | IntellJ IDEA篇

示例程序环境版本：
SpringBoot Version：2.1.0.RELEASE
SpringMVC Version：5.1.2RELEASE
Maven Version：3.2.5
JDK Version：1.8.0_144

实战

用户 Model 的代码：

下面是用户的 Model 类，用户类里面包含用户名称和用户年龄 2 个成员变量。

package cn.lijunkui.springbootlearn.restful.model;

public class User 
    private String name;
    private Integer age;
    //省略get and set 方法

用户接口 Controller 类：

@RestController()
@RequestMapping("/user")
public class UserController 
    
    Logger log = LoggerFactory.getLogger(UserController.class);
    
    /**
     * 根据用户id 查询用户
     * @return
     */
    @GetMapping("/id")
    public ResponseEntity<User> get(@PathVariable(name = "id") Long id)
        User user = new User("lijunkui",18);
        log.info("查询用户成功："+"id:",id);
        return ResponseEntity.ok(user);
    
    /**
     * 查询所有的用户
     * @return
     */
    @GetMapping("/")
    public ResponseEntity<List<User>> getAll()
        
        List<User> userList = new ArrayList<User>()
            add(new User("lijunkui1",18));
            add(new User("lijunkui2",18));
            add(new User("lijunkui3",18));
        ;
        return  ResponseEntity.ok(userList);
    
    /**
     * 添加用户
     */
    @PostMapping("/")
    public ResponseEntity<User> add(@RequestBody User user)
        log.info("添加用户成功："+"name:,age:",user.getName(),user.getAge());
        return  ResponseEntity.status(HttpStatus.CREATED).body(user);
    
    /**
     * 更新用户
     * @param user
     * @return
     */
    @PutMapping("/")
    public  ResponseEntity<Void> updatePut(@RequestBody User user)
        log.info("修改用户成功："+"name:,age:",user.getName(),user.getAge());
        return ResponseEntity.ok().build();
    
    /**
     * 局部更新
     * @return 
     */
    @PatchMapping("/name")
    public ResponseEntity<Void> updatePatch(@PathVariable("name") String name)
        log.info("修改用户成功："+"name:",name);
        return ResponseEntity.ok().build();
    
    /**
     * 删除用户
     */
    @DeleteMapping("/id")
    public ResponseEntity<Void> delete(@PathVariable("id") Long id)
        log.info("删除用户成功："+"id:",id);
        return  ResponseEntity.status(HttpStatus.NO_CONTENT).build();
    

@RestController()：声明在 Controller 上，表明该 Controller 为 RestFul 风格的Controller。

该注解在 Spirng 4.0 中也同样适用，但是在SpringMVC 3.0 中我们需要通过@Controller 和
@ResponseBody 来达到 @RestController()的效果。

@GetMapping()：声明使用 Get 方式访问的接口，该方式主要用于数据查询。

@PostMapping()：声明使用 Post方式访问的接口，该方式主要用于数据新增。

@PutMapping()：声明使用 Put方式访问的接口，该方式主要用于全部更新。

@PatchMapping()：声明使用 Patch方式访问的接口，该方式主要用于局部更新。

@DeleteMapping()：声明使用 Delete 方式访问的接口，该方式主要用于数据删除。

对于@GetMapping() 和 @PostMapping() == @RequestMapping(value = "",method
= RequestMethod.GET) @RequestMapping(value = "",method = RequestMethod.POST) 。

ResponseEntity ：用于封装响应回客户端数据和响应状态码的。常用用法如下：

ResponseEntity.ok().build()：表示无返回数据，并且响应状态码是 200
ResponseEntity.ok(user)：表示有回数据，并且响应状态码是 200
ResponseEntity.status(HttpStatus.NO_CONTENT).build()：表示无返回数据，并且响应状态码是 204
ResponseEntity.status(HttpStatus.CREATED).body(user)：表示有返回数据，并且响应状态码是 201

@PutMaping() BUG

Put 方式接受不到参数问可以通过配置 HttpPutFormContentFilter 来解决。具体处理代码如下：

/**
 * 解决restFul put 参数无法接收的问题
 */
@Component
public class PutFilter extends HttpPutFormContentFilter 

参考文献：HTTPS：//www.aliyun.com/jiaocheng/852091.html

测试

RESTful 接口测试是通过 PostMan 来进行演示的，你也可以选择你顺手的工具进行测试哈。

根据用户id 查询用户：选择 GET 调用方式，然后在地址栏输入： localhost:8080/sbe/user/1 最后点击 Send。如下图所示成功返回用户信息和200 响应码。

查询所有的用户：选择 GET 调用方式，地址栏输入 localhost:8080/sbe/user/。

添加用户：选择 POST 调用方式，地址栏输入 localhost:8080/sbe/user/ 。选择Body -- JSON(application/json) 输入要添加用户json 信息。如下图所示：

修改用户： 选择 PUT 调用方式，地址栏输入 localhost:8080/sbe/user/ 。选择Body -- JSON(application/json) 输入要修改用户json 信息。如下图所示：

修改用户：选择 Patch 调用方式，地址栏输 localhost:8080/sbe/user/你想要修改的名称。如下图所示：

删除用户：选择 DELETE 调用方式，地址栏输入： localhost:8080/sbe/user/1。如下图所示：

小结

SpringBoot 开发 RESTful Api 还是比较简单的，将 Controller 通过 @RestController 声明后 在通过具体的动作Mapping注解 + ResponseEntity 定义返回数据和响应的状态码 基本就可以搞定。如果你没有操作过，建议跟着博客敲一遍哈。

代码示例

本文具体代码可以查看我的 GitHub 仓库 springbootexamples 中模块名为 spring-boot-2.x-restful-api 的 cn.lijunkui.restful.basic包下进行查看

Github：https://github.com/zhuoqianmingyue/springbootexamples 如果您对这些感兴趣，欢迎 点个赞或者关注给予支持！