RESTful 风格 api 设计

港控/mmm° 2022-02-26 15:42 399阅读 0赞

# 一、什么是RESTful? #

是目前流行的api设计规范，用于web数据接口的设计

REST全称为：Representational  state  transfer 表述性状态转移。表述性就是指客户端请求一个资源，服务器拿到这个资源，就是表述。

# 二、为什么会出现RESTful呢？ #

在RESTful之前的操作：

http://127.0.0.1/user/query/1  GET  根据用户id查询用户数据
    http://127.0.0.1/user/save     POST 新增用户
    http://127.0.0.1/user/update   POST 修改用户信息
    http://127.0.0.1/user/delete   GET/POST 删除用户信息

RESTful用法：

http://127.0.0.1/user/1   GET  根据用户id查询用户数据
    http://127.0.0.1/user    POST 新增用户
    http://127.0.0.1/user    PUT 修改用户信息
    http://127.0.0.1/user    DELETE 删除用户信息

第一种方法，每次请求接口的时候都在做描述，例如查询的时候用query，新增的时候用save。其实完全没有这个必要，使用get请求就是查询，使用post请求就是新增，这就是为什么有了RESTful

# 三、URL设计 #

## 1.动词+宾语 ##

<1>ERSTful的核心思想是，客户端发出的数据操作指令是“**动词****+****宾语**”的结构，如：**GET/articles** , **GET**是动词，**/articles**是宾语。

<2>宾语必须是名词！动名词也可以，反正必须是名词。这点超重要。因为在开xxx接口评审会时，如果你写的不规范，大佬就会立即指出并问你该词是什么词性，然后再让你想个名词来替换，一秒钟瞬间回到英语课，顺便扎心地问六级过了么 ┐(ﾟ～ﾟ)┌

<3>动词通常就是五中HTTP方法，对应CRUD操作

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3BhbnppbmE_size_16_color_FFFFFF_t_70][]

## 2.复数URL ##

既然 URL 是名词，那么应该使用复数，还是单数？

这没有统一的规定，但是常见的操作是读取一个集合，比如**GET /articles**（读取所有文章），这里明显应该是复数。

结合实际情况分析使用复数还是单数，比如**GET /articles/2**要好于**GET /article/2。**

## **3.避免多级URL** ##

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

GET /authors/12/categories/2

这种 URL 不利于扩展，语义也不明确，往往要想一会，才能明白含义。

更好的做法是，除了第一级，其他级别都用查询字符串表达。

GET /authors/12?categories=2

# 四、状态码 #

客户端的每一次请求，服务器都必须给出回应。回应包括HTTP状态码和数据两部分

HTTP状态码就是一个三位数，分成五个类别

![20190330134020173.png][]

这五大类总共包含100多种状态码，覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的（或者约定的）解释，客户端只需查看状态码，就可以判断出发生了什么情况，所以服务器应该返回尽可能精确的状态码

# 五、练习 #

<table> 
 <thead> 
  <tr> 
   <th>URI</th> 
   <th>method</th> 
   <th>接口释义</th> 
   <th>body</th> 
   <th>return</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>/person</td> 
   <td>post</td> 
   <td>新增用户</td> 
   <td>ViewPerson</td> 
   <td>ViewPerson</td> 
  </tr> 
  <tr> 
   <td>/person/{personId}</td> 
   <td>put</td> 
   <td>修改指定用户</td> 
   <td>ViewPerson</td> 
   <td>ViewPerson</td> 
  </tr> 
  <tr> 
   <td>/person/{personId}</td> 
   <td>delete</td> 
   <td>删除指定用户</td> 
   <td>&nbsp;</td> 
   <td>boolean</td> 
  </tr> 
  <tr> 
   <td>/person/{personId}</td> 
   <td>get</td> 
   <td>查询指定用户</td> 
   <td>&nbsp;</td> 
   <td>ViewPerson</td> 
  </tr> 
 </tbody> 
</table>

如果有通过某条件查询xxx的api，keyWord就是某条件。

![20190330141718201.png][]

(ps:最后的是张图片↑↑↑，表格怎么都保存不了。。只能截图了)

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3BhbnppbmE_size_16_color_FFFFFF_t_70]: /images/20220226/9733758149a84f279743815231430fea.png
[20190330134020173.png]: /images/20220226/4446393af027439595a2c2f1653c5fe2.png
[20190330141718201.png]: /images/20220226/ef0fb35bcf1443bab40bce68f43fd86a.png