我是如何根据豆瓣api来理解Restful API设计的

淡淡的烟草味﹌ 2022-06-18 01:58 133阅读 0赞

### 1.什么是REST ###

REST全称是Representational State Transfer,表述状态转移的意思。它是在Roy Fielding博士论文首次提出。REST本身没有创造新的技术、组件或服务，它的理念就是在现有的技术之上，更好的使用现有的 web规范。用REST规范的web服务器，能够更好的展现资源，客户端能够更好的使用资源。每个资源都由URI/ID标识。REST本身跟http无关，但是目前http是与它相关的唯一实例。REST有着优雅、简洁的特性，本文是根据豆瓣api来谈谈自己对restful的一些理解。

### 2.URI规范 ###

*  URI(Uniform Resource Identifiers) 统一资源标示符
 *  URL(Uniform Resource Locator) 统一资源定位符

URI 的格式：

URI的格式定义如下：  
    URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

*  uri代表的是一种资源，要做到优雅、简洁。
 *  最好在api地址标明版本

比如

https://api.douban.com/v2

*  关于分隔符“／”，比如：

"/"分隔符一般用来对资源层级的划分,比如：
    
    https://api.douban.com/v2/book/1220562
    
    表述了豆瓣api，version2下的图书仓库下的编号为1220562的图书。

*  URI尽量使用“-”代替下划线“\_“。
 *  URI统一使用小写字母
 *  URI不包含文件扩展名
 *  使用？用来过滤资源，比如？limit=10 :指定返回10条记录。
 *  不使用无意义的字符串、数字，要做到简洁。

### 3.正确使用method ###

*  get -只用做资源的读取。
 *  post-通过用作创建一个新的资源。
 *  delete-通过用作资源的删除。
 *  put -通过用作更新资源或者创建资源
 *  head-只获取某个资源的头部信息。

比如 [豆瓣图书api][api]：

<table> 
 <thead> 
  <tr> 
   <th>name</th> 
   <th>method</th> 
   <th>api</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>获取图书信息</td> 
   <td>get</td> 
   <td>/v2/book/:id</td> 
  </tr> 
  <tr> 
   <td>用户收藏某本图书</td> 
   <td>post</td> 
   <td>/v2/book/:id/collection</td> 
  </tr> 
  <tr> 
   <td>用户修改对某本图书的收藏</td> 
   <td>put</td> 
   <td>/v2/book/:id/collection</td> 
  </tr> 
  <tr> 
   <td>用户删除对某个图书的收藏</td> 
   <td>delete</td> 
   <td>/v2/book/:id/collection</td> 
  </tr> 
 </tbody> 
</table>

*  另外，在一些不符合curd的情况下，使用　post。
 *  把动作转换成资源

比如，上述接口中，用户收藏某本书对外暴露的接口是"/v2/book/:id/collection",收藏动作通过post方法来展现，而不直接写着api中，collection “收藏”，名次，动作直接转换成了资源。

\#\#\#4.选择合适的状态码

http请求需要返回状态码，约定俗成的状态码能够帮助开发团队提高沟通效率。

*  2xx: 请求正常处理并返回
 *  3xx: 重定向
 *  4xx: 客户端请求有错误
 *  5xx: 服务端请求有错误

比如豆瓣api返回的状态码说明：

<table> 
 <thead> 
  <tr> 
   <th>状态码</th> 
   <th>含义</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>200</td> 
   <td>ok</td> 
   <td>请求成功</td> 
  </tr> 
  <tr> 
   <td>201</td> 
   <td>created</td> 
   <td>创建成功</td> 
  </tr> 
  <tr> 
   <td>202</td> 
   <td>accepted</td> 
   <td>更新成功</td> 
  </tr> 
  <tr> 
   <td>400</td> 
   <td>bad request</td> 
   <td>请求不存在</td> 
  </tr> 
  <tr> 
   <td>401</td> 
   <td>unauthorized</td> 
   <td>未授权</td> 
  </tr> 
  <tr> 
   <td>403</td> 
   <td>forbidden</td> 
   <td>禁止访问</td> 
  </tr> 
  <tr> 
   <td>404</td> 
   <td>not found</td> 
   <td>资源不存在</td> 
  </tr> 
  <tr> 
   <td>500</td> 
   <td>internal server error</td> 
   <td>内部错误</td> 
  </tr> 
 </tbody> 
</table>

### 5.使用通用的错误码 ###

通用错误码，具体产品由具体产品api给出。比如豆瓣api:

<table> 
 <thead> 
  <tr> 
   <th>错误码</th> 
   <th>错误信息</th> 
   <th>含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>999</td> 
   <td>unknow_v2_error</td> 
   <td>未知错误</td> 
  </tr> 
  <tr> 
   <td>1000</td> 
   <td>need_permission</td> 
   <td>需要权限</td> 
  </tr> 
  <tr> 
   <td>1001</td> 
   <td>uri_not_found</td> 
   <td>资源不存在</td> 
  </tr> 
  <tr> 
   <td>…</td> 
   <td>…</td> 
   <td>…</td> 
  </tr> 
 </tbody> 
</table>

太多了，只列出几条，具体见豆瓣 api。

### 6. 安全 ###

这部分内容不属于这篇文章，但是稍微说明下：

*  使用https
 *  使用jwt验证
 *  使用参数签名，防止参数被篡改。
 *  使用权限验证，shiro ,或者自己建数据库（用户、角色、权限）

### 7.api文档 ###

接口文档的编写至关重要，最好是写一个在线接口文档。接口文档能够方便团队查阅，减少不必要的沟通。如果对外公开api，api文档的质量直接反应了一个公司的技术水平，甚至一个公司的文化气质。

### 8.参考资料 ###

本文参考了以下的资料:

[豆瓣api][api]

[理解restful架构][restful]

[restful introduction][]

[跟着github学习restful api设计][github_restful api]

[REST接口设计规范][REST]

[restful api 设计指南][restful api]

![SouthEast][]  
扫码关注公众号有惊喜

**（转载本站文章请注明作者和出处 [方志朋的博客][Link 1]）**

[api]: https://developers.douban.com/wiki/?title=book_v2
[restful]: http://mccxj.github.io/blog/20130530_introduce-to-rest.html
[restful introduction]: https://www.tutorialspoint.com/restful/restful_introduction.htm
[github_restful api]: http://cizixs.com/2016/12/12/restful-api-design-guide
[REST]: http://wangwei.info/about-rest-api/
[restful api]: http://www.ruanyifeng.com/blog/2014/05/restful_api.html
[SouthEast]: /images/20220618/3bb46d29c30a4a3e8ead927d965e5044.png
[Link 1]: https://www.fangzhipeng.com