美文网首页springboot
SpringBoot--实战开发--Restful(三十三)

SpringBoot--实战开发--Restful(三十三)

作者: 无剑_君 | 来源:发表于2019-07-15 13:04 被阅读26次

    一、RESTful简介

    RESTful 的核心思想就是,客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如,GET /articles这个命令,GET是动词,/articles是宾语。

    动词通常就是五种 HTTP 方法,对应 CRUD 操作。
    GET:读取(Read)
    POST:新建(Create)
    PUT:更新(Update)
    PATCH:更新(Update),通常是部分更新
    DELETE:删除(Delete)

    根据 HTTP 规范,动词一律大写。

    1. 动词的覆盖

    有些客户端只能使用GET和POST这两种方法。服务器必须接受POST模拟其他三个方法(PUT、PATCH、DELETE)。
    这时,客户端发出的 HTTP 请求,要加上X-HTTP-Method-Override属性,告诉服务器应该使用哪一个动词,覆盖POST方法。

    POST /api/Person/4 HTTP/1.1  
    X-HTTP-Method-Override: PUT
    

    上面代码中,X-HTTP-Method-Override指定本次请求的方法是PUT,而不是POST。

    2. 宾语必须是名词

    宾语就是 API 的 URL,是 HTTP 动词作用的对象。它应该是名词,不能是动词。比如,/articles这个 URL 就是正确的,而下面的 URL 不是名词,所以都是错误的。

    /getAllCars
    /createNewCar
    /deleteAllRedCars
    

    3. 复数 URL

    既然 URL 是名词,那么应该使用复数,还是单数?
    这没有统一的规定,但是常见的操作是读取一个集合,比如GET /articles(读取所有文章),这里明显应该是复数。
    为了统一起见,建议都使用复数 URL,比如GET /articles/2要好于GET /article/2。

    避免多级 URL
    常见的情况是,资源需要多级分类,因此很容易写出多级的 URL,比如获取某个作者的某一类文章。

    GET /authors/12/categories/2
    

    这种 URL 不利于扩展,语义也不明确,往往要想一会,才能明白含义。
    更好的做法是,除了第一级,其他级别都用查询字符串表达。

    GET /authors/12?categories=2
    

    下面是另一个例子,查询已发布的文章。你可能会设计成下面的 URL。

    GET /articles/published
    

    查询字符串的写法明显更好。

    GET /articles?published=true
    

    二、状态码

    1. 状态码必须精确

    客户端的每一次请求,服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。
    HTTP 状态码就是一个三位数,分成五个类别。

    • 1xx:相关信息
    • 2xx:操作成功
    • 3xx:重定向
    • 4xx:客户端错误
    • 5xx:服务器错误
      这五大类总共包含100多种状态码,覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的(或者约定的)解释,客户端只需查看状态码,就可以判断出发生了什么情况,所以服务器应该返回尽可能精确的状态码。
      API 不需要1xx状态码,下面介绍其他四类状态码的精确含义。

    2. 2xx 状态码

    200状态码表示操作成功,但是不同的方法可以返回更精确的状态码。

    GET: 200 OK
    POST: 201 Created
    PUT: 200 OK
    PATCH: 200 OK
    DELETE: 204 No Content
    

    上面代码中,POST返回201状态码,表示生成了新的资源;DELETE返回204状态码,表示资源已经不存在。

    三、服务器回应

    1. 不要返回纯本文

    API 返回的数据格式,不应该是纯文本,而应该是一个 JSON 对象,因为这样才能返回标准的结构化数据。所以,服务器回应的 HTTP 头的Content-Type属性要设为application/json。
    客户端请求时,也要明确告诉服务器,可以接受 JSON 格式,即请求的 HTTP 头的ACCEPT属性也要设成application/json。下面是一个例子。

    GET /orders/2 HTTP/1.1 
    Accept: application/json
    

    2.发生错误时,不要返回 200 状态码

    有一种不恰当的做法是,即使发生错误,也返回200状态码,把错误信息放在数据体里面,就像下面这样。

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
      "status": "failure",
      "data": {
        "error": "Expected at least two items in list."
      }
    }
    

    上面代码中,解析数据体以后,才能得知操作失败。

    这张做法实际上取消了状态码,这是完全不可取的。正确的做法是,状态码反映发生的错误,具体的错误信息放在数据体里面返回。下面是一个例子。

    HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    {
      "error": "Invalid payoad.",
      "detail": {
         "surname": "This field is required."
      }
    }
    

    相关文章

      网友评论

        本文标题:SpringBoot--实战开发--Restful(三十三)

        本文链接:https://www.haomeiwen.com/subject/axqnkctx.html