【Spring Boot】构建RESTful服务 — 构建RESTful应用接口

构建RESTful应用接口

RESTful架构是目前最流行的互联网软件架构规范，是Web API（应用编程接口）的大趋势和主流规范，了解了RESTful的众多优点之后，接下来一步一步地学习如何使用Spring Boot构建RESTful Web API。

1.Spring Boot对RESTful的支持

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

1）@GetMapping：处理GET请求，获取资源。

2）@PostMapping：处理POST请求，新增资源。

3）@PutMapping：处理PUT请求，更新资源。

4）@DeleteMapping：处理DELETE请求，删除资源。

5）@PatchMapping：处理PATCH请求，用于部分更新资源。

通过这些注解就可以在Spring Boot项目中轻松构建RESTful接口。其中比较常用的是@GetMapping、@PostMapping、@PutMapping、@DeleteMapping四个注解。

使用Spring Boot开发RESTful接口非常简单，通过@RestController定义控制器，然后使用@GetMapping和@PostMapping等注解定义地址映射，实现相应的资源操作方法即可。

    @GetMapping(value="/user/{id}")
    public String getUserByID(@PathVariable int id){
        return "getUserByID:"+id;
    }
    @PostMapping(value="/user")
    public String save(User user) {
        return "save successed";
    }
    @PutMapping(value="/user")
    public String update(User user){
        return "update successed";
        }
    @DeleteMapping(value="/{id}")
    public String delete(@PathVariable int id){
        return "delete id:"+id;
    }

在上面的示例中，通过Spring Boot提供的@GetMapping等注解简单实现了对用户（user）的操作。其实，这些注解就是@RequestMapping注解的简化：

    @RequestMapping(value = "/user/(id}", method = RequestMethod.GET)
    public String getUserByID(@PathVariable int id){
        return "getUserByID:"+id;
    }
    @RequestMapping(value ="/user", method = RequestMethod.POST)
    public String save(User user) {
        return "save successed";
    }
    @RequestMapping(value ="/user", method = RequestMethod.PUT)
    public String update(User user){
        return "update successed";
    }
    @RequestMapping(value = "/user/{id}", method = RequestMethod.DELETE)
    public String delete(@PathVariable int id) {
        return "delete id:" + id;
    }

之前介绍的@RequestMapping注解通过method参数定义映射的HTTP请求方法，就相当于@RequestMapping+ RequestMethod的简化版。

我们看到，Get和Delete、Post和Put请求的URL是相同的，不同的Method（GET、PUT、POST、DELETE）会被映射到对应的处理方法上。这就是REST的魅力，简单明了的URL就能显示它的功能和作用。

2.Spring Boot实现RESTful API

接下来根据之前介绍的RESTful设计风格，以用户管理模块为例演示Spring Boot如何实现RESTful API。

步骤01 设计API。

在RESTful架构中，每个网址代表一种资源，所以URI中建议不要包含动词，只包含名词即可，而且所用的名词往往与数据库的表格名对应。下表是用户管理模块的接口定义，实际项目的RESTful API文档要更详细，还会定义全部请求的数据结构体。

表中定义了用户管理模块的接口，根据REST的定义，我们将用户定义为一种资源，通过POST、DELETE、PUT、GET等HTTP Method实现对用户的增、删、改、查。

可能大家会有疑问，为什么URI中没有我们习惯的getUser、saveUser这类路径？这正是RESTful优雅的地方，它将对资源的操作都定义在HTTP Method中，使得URL地址看起来更简洁。

除了设计URL接口之外，还需要定义服务端向客户端返回的状态码和提示信息。详细的状态码说明见下表。

表中除了定义用户管理相关的业务状态码之外，还需要定义通用的错误码，如400对应数据校验错误、401对应数据无权限等。

步骤02 实现用户管理接口。

上面定义了RESTful API以及接口返回的状态码，接下来根据之前的接口定义先创建UserController，再实现用户管理模块的用户新增、用户修改、用户删除、用户查询等接口。

1）用户新增：

    @PostMapping(value = "user")
    public JSONResult save(@RequestBody User user) {
        System.out.println("用户创建成功:" + user.getName());
        return JSONResult.ok(201,"用户创建成功");
    }

@PostMapping注解表示此为POST接口。通过POST方法传入用户数据，然后调用Save方法保存用户数据。

2）用户修改：

    @PutMapping(value = "user")
    public JSONResult update(@RequestBody User user) {
        System.out.println("用户修改成功:" + user.getName());
        return JSONResult.ok(203,"用户修改成功");
    }

3）用户删除：

    @DeleteMapping(value = "user/{userId}")
    public JSONResult delete(@PathVariable String userId) {
        System.out.println("用户删除成功:" + userId);
        return JSONResult.ok(204,"用户删除成功");
    }

@DeleteMapping注解表示此为删除接口。通过传入参数userId删除人员信息。

4）获取用户：

    @GetMapping(value = "user/{userId}")
    public JSONResult queryUserById(@PathVariable String userId) {
        User user = new User();
        user.setUserId(userId);
        user.setName("zhang");
        user.setAge(20);
        System.out.println("获取用户成功:" + userId);
        return JSONResult.ok(200,"获取用户成功",user);
    }

@GetMapping注解表示此为查询接口。@PathVariable注解用于参数映射，获取传入的参数。

步骤03 验证测试。

至此，用户管理的模块接口都实现了。接下来验证接口调用。我们可以使用单元测试或者Postman工具调用用户管理模块的相关接口，测试接口是否正常。这里就以Postman工具演示RESTful API的测试。

打开Postman，使用POST方法请求/user接口，验证新增人员的接口是否正常，如图所示。

通过Postman发送POST请求，调用人员新增接口，后台接口处理成功后，返回人员信息保存成功。

接下来，使用GET方法请求/user/2001获取userId为2001的人员信息，从而验证获取人员的接口是否正常，如图所示。

通过Postman向后台接口发送GET方法请求/user/2001，RESTful API成功返回人员详细信息。