使用Spring Boot设计和实现REST API

18-10-31 banq
              

REST端点用于集成应用程序或服务器端向客户端提供服务。在本文中,将介绍基于CRUD的SpringBoot来设计和实现REST端点。

假设有一个客户数据,我将创建一个相应的Spring REST Controller来访问客户数据。为了简单起见,我将只关注控制器类而不是整个spring应用程序。可以在github中下载完整的项目。

这是一个CRUD应用程序,因此控制器将有四种基本方法来支持获取,保存,更新和删除操作。所有这些操作都将适用于客户数据。下面是控制器类的框架。

@RestController

@RequestMapping("/customers")

public class CustomerController {

    @Autowired

    private CustomerRepository customerRepository;

    

    //get, save, update and delete 方法

}

客户资源的所有端点都以/ customers开头。

设计和实施端点

端点应简短易用。例如,为了通过Id获取客户,我们可以使用/ customers / {id}这样的端点。

但是像/ customers / getCustomerById,其URL中含有操作动词是错误的,因为通过Id获取客户是一个操作,我们可以使用HTTP方法实现此操作,因此放在URL中是多余的,它使URL复杂化。

HTTP提供了各种可用于简化端点的方法。HTTP提供了一些标准方法,如GET,PUT,POST或OPTIONS等。所有这些方法都有助于设计简单的REST端点,因为这是标准的,所以每个人都可以理解它们。

GET

GET方法用于访问资源。要根据ID获取客户记录,我们可以使用/ customers / {id}等端点。以下是此终点的实现。

@RequestMapping(value = {"/{id}"})
ResponseEntity byId(@PathVariable String id){
    if(!customerRepository.existsById(id))
        return new ResponseEntity<>(HttpStatus.NOT_FOUND); // HTTP 404

    return new ResponseEntity<>(customerRepository.findById(id).get(), HttpStatus.OK); // HTTP 200
}

当客户端请求无效或不存在的“id”时,我们可以使用标准HTTP响应代码,而不是使用自定义正文或错误消息进行响应。HTTP响应代码是REST中用于通知处理状态的标准方式。有许多类别的代码可用,这里是关于这些代码的一些信息的链接。

  • 404 - 未找到:如果数据存储中没有“id”,则使用此HTTP代码是合适的。请注意,此HTTP代码是一个标准代码,表示没有找到任何数据,因此客户端可以理解这一点,而不会在响应正文中提供任何额外信息。
  • 200 - 确定:已成功处理请求。

POST

此方法用于创建新数据记录。此请求的端是/ customers。数据作为正文的一部分发送,因此不需要请求参数。

@RequestMapping(value = {""}, method = RequestMethod.POST)
ResponseEntity<?> save(@RequestBody Customer customer){
    if(customer == null)
        return new ResponseEntity(HttpStatus.BAD_REQUEST); // HTTP 400
    if(customerRepository.existsById(customer.getId()))
        return new ResponseEntity(HttpStatus.CONFLICT); // HTTP 409

    Customer cust = customerRepository.save(customer);
    return new ResponseEntity<>(cust, HttpStatus.CREATED); // HTTP 201
}

  • 400 - BAD REQUEST:如果请求为null,则通知客户端请求不正确。
  • 409 - 冲突:如果新客户的ID已经存在于数据存储中,那么它就是冲突请求。
  • 201 - 创建:所有验证都成功,数据将插入到存储中。

PUT

此方法允许用户更新现有数据记录。此请求的端点是/ customers,数据作为正文的一部分发送,因此不再需要请求参数。

@RequestMapping(value = {""}, method = RequestMethod.PUT)
ResponseEntity<?> update(@RequestBody Customer customer){
    if(customer == null)
        return new ResponseEntity(HttpStatus.BAD_REQUEST); // HTTP 400
    if(!customerRepository.existsById(customer.getId()))
        return new ResponseEntity(HttpStatus.BAD_REQUEST); // HTTP 400

    return new ResponseEntity<>(customerRepository.save(customer), HttpStatus.CREATED); // HTTP 201
}

  • 400 - BAD REQUEST:如果正文是空的,或者客户在数据存储中不可用。
  • 201 - 创建:没有用于更新的标准HTTP代码,因此我们可以使用201进行更新。

DELETE

此方法应用于删除请求。此请求的端点是/ customers / {id}。请求中的指定ID将从存储中删除。

@RequestMapping(value = "/{id}", method = RequestMethod.DELETE)
ResponseEntity<Object> delete(@PathVariable String id){
    if(!customerRepository.existsById(id))
        return new ResponseEntity<>(HttpStatus.BAD_REQUEST); // HTTP 400

    customerRepository.deleteById(id);
    return new ResponseEntity<>(HttpStatus.NO_CONTENT); // HTTP 204
}

  • 400 - BAD REQUEST:如果数据存储中不存在id,那么这是一个错误的请求。
  • 204 - NO CONTENT:删除后数据将不可用,因此在这种情况下204是合适的。我们也可以考虑使用200。

可以在github中下载完整的项目。

              

1
sinaID75194
2018-11-20 14:32

在controller如果要加入权限判断,且判断权限不通过,应该返回什么http status码到前端?

banq
2018-11-20 14:56

>权限判断,且判断权限不通过,应该返回什么http status码到前端?

401

参考这篇文章:401未经授权的错误:它是什么以及如何解决它