构建RESTful服务

RESTful介绍

• RESTful是目前流行的互联网软件服务架构设计风格
• REST（Representational State Transfer，表述性状态转移）一词是由Roy Thomas Fielding在2000年的博士论文中提出的，它定义了互联网软件服务的架构原则，如果一个架构符合REST原则，则称之为RESTful架构。
• REST并不是一个标准，它更像是一组客户端和服务端交互时的架构理念和设计原则，基于这种架构理念和设计原则的Web API更加简洁，更有层次。

RESTful的特点

• 每一个URI代表一种资源

• 客户端使用GET、POST、PUT、DELETE四种表示操作方式的动词对服务端资源进行操作：

  • GET用于获取资源
  • POST用于新建资源（也可以用于更新资源）
  • PUT用于更新资源
  • DELETE用于删除资源
• 通过操作资源的表现形式来实现服务端请求操作
• 资源的表现形式是JSON或者HTML
• 客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都包含必须的信息

RESTful API

符合RESTful规范的Web API需要具备如下两个关键特性：

• 安全性：安全的方法被期望不会产生任何副作用。当我们使用GET操作获取资源时，不会引起资源本身的改变，也不会引起服务器状态的改变
• 幂等性：幂等的方法保证了重复进行一个请求和一次请求的效果相同（并不是指响应总是相同的，而是指服务器上资源的状态从第一次请求后就不再改变了），在数学上幂等性是指N次变换和一次变换相同

HTTP Method

• HTTP提供了POST、GET、PUT、DELETE等操作类型对某个Web资源进行create、read、update和delete操作
• 一个HTTP请求除了利用URI标志目标资源之外、还需要通过HTTP Method指定针对该资源的操作类型，一些常见的HTTP方法及其在RESTful风格下的使用：

| HTTP方法 | 操作 | 返回值 | 特定返回值 |
| -------------- | ------------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| POST | create | 201（created），提交或保存数据 | 404（Not Found），409（Conflict）资源已存在 |
| GET | read | 200（OK），获取资源或数据列表，支持分页、排序和条件查询 | 200（OK）返回资源，404（Not Found）资源不存在 |
| PUT | update | 200（OK）或204（Not Content），修改资源 | 404（Not Found）资源不存在，405（Method Not Allowed）禁止使用该方法调用 |
| PATCH | update | 200（OK）或204（Not Content），部分修改 | 404（Not Found）资源不存在 |
| DELETE | delete | 200（OK），资源删除成功 | 404（Not Found）资源不存在，405（Method Not Allowed）禁止使用该方法调用 |

Spring Boot实现RESTful API

Spring Boot提供的spring-boot-starter-web组件完全支持开发RESTful API，提供了与REST操作方式（GET、POST、PUT、DELETE）对应的注解。

• GetMapping：处理GET请求，获取资源。
• @PostMapping：处理POST请求，新增资源。
• @PutMapping：处理PUT请求，更新资源
• @DeleteMapping：处理DELETE请求，删除资源
• @PatchMapping：处理PATCH请求，用于部分更新资源

在RESTful架构中，每个网址代表一种资源，所以URI中建议不要包含动词，只包含名词即可，而且所用的名词往往与数据库的表格名对应

用户管理API示例：

RESTful实现

package com.example.demo.controller;

import com.example.demo.entity.User;
import org.springframework.web.bind.annotation.*;

@RestController
public class UserController {

    /**
     * 大括号括起来的id代表这是一个动态的id
     * @PathVariable 需要使用这个注解来接收动态的参数
     * @param id id需要与动态接收的参数一致，即上面接收的是{id}，那么接口方法入参就得是id
     * @return
     */
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable int id){
        return "根据ID获取用户";
    }

    @PostMapping("/user")
    public String save(User user){
        return "添加用户";
    }

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

    @DeleteMapping("/user/{id}")
    public String deleteById(@PathVariable int id){
        return "根据id删除用户";
    }

}

Swagger

什么是Swagger

• Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化RESTful风格的Web服务，是非常流行的API表达工具。
• Swagger能够自动生成完善的RESTful API文档，同时并根据后台代码的修改同步更新，同时提供完整的测试页面来调试API。

使用Swagger生成Web API文档

在Spring Boot项目中集成Swagger同样非常简单，只需在项目中引入springfox-swagger2和springfox-swagger-ui依赖即可。

配置Swagger

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration  // 向Spring容器声明这个类是一个配置类
@EnableSwagger2 // 启用Swagger2功能
public class Swagger2Config {
    // 配置Swagger2相关的Bean
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()   // 选择哪些路径和api会生成document
                .apis(RequestHandlerSelectors.basePackage("com"))   // com包下所有API都交给Swagger2管理
                .paths(PathSelectors.any()).build();
    }

    // API文档页面显示信息
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("演示项目API")   // 标题
                .description("Swagger2演示") // 描述
                .version("1.0") // 版本
                .build();
    }
}

配置完后就可以通过localhost:8080/swagger-ui.html来访问接口文档

常见错误

启动报错

配置完后服务可能会报错，提示如下

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

原因是springboot 版本过高，使swagger 异常，或者说是引入的swagger版本过高导致的问题，或者说是springboot2.6.0更新以后引起的问题。

只需要在配置文件添加下方代码即可

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

swagger-ui页面404

访问的时候提示如下

出现这个问题的原因一般是因为SpringBoot和Swagger的版本不匹配

如果Swagger3.0无法正常启动，可以在pom.xml中修改为2.9.2版本