文章目录
  1. 一，背景
  2. 二，RESTful 架构
  3. 三，API 设计规范
  4. 三，参考资料

一，背景

之前实验室里开发的时候，大多都是使用 get 获取资源，使用 post 更新和查询，使用 delete 删除。

这里面之前我们检索数据的时候都是使用 post，但是今天新实验室的后端小伙伴很疑惑地问我，为啥检索数据使用 post 呢，不是获取都使用 get 吗？

我忽然有点懵了，好像是这个理，我胡诌是 post 检索参数放在请求体里更加安全，但是其实我也不太清楚。所以晚上就阅读了一些文章，写一个小笔记分享一下。

二，RESTful 架构

首先大家都知道，现在我们 Web 开发主要是 B/S 架构，即浏览器（Browser）/服务器（Server）架构，这种双节点的模式下相互之间的沟通显得尤为重要，RESTful 架构就是一种适合目前以网络为基础的前提下的适合通信的架构设计。

REST（representational state transfer）翻译过来是表现层状态转化。

REST 的解读（阮老师解读的很易懂）：

  1. 这个名词省略了主语，主语应该是资源（resource），我们的 resources 就是网络上的一个实体，而想要获取这个资源我们就需要一个路径指向它，这就是 URI（统一资源定位符）
  2. 而我们的表现层指的是资源的表现层，也就是资源是什么东西，它的表现形式。可以是 html、文本或者仅仅是一段 JSON。
  3. 状态转化又是什么意思呢？当我们访问网站，代表的是客户端和服务器的一个沟通互动，这里面势必会涉及到状态变化。而我们常用的 HTTP 是无状态协议，也就是说所有的状态都发生在服务端，客户端想要去让服务端的数据发生状态变化（比如增删改），就必须通过一种手段来进行，这种手段在 HTTP 里就是 get（获取）、post（新增）、put（更新）、delete（删除）这四个关键词。

总结的说：我们通过 URI 找到实体，之后通过在 URI 后加入行为路径和参数，并通过 HTTP 的四种关键词手段，来达到对服务端的实体数据进行状态转化的效果。

三，API 设计规范

我们知道了什么是 RESTful 架构，那么在这样的架构下我们要对我们的 API 进行设计和规范来让大家都明白这个 API 指的是什么，怎么写更加的通俗易懂。

API（application programming interface）：指的是应用开发接口，它并不仅仅局限于我们这篇文章所说的客户端和服务端交互的接口，它还泛指绝大部分包暴露出来的方法和函数（说的不规范，但是是这么个理），接口的意思就是一个抽象复杂的事物让其他人使用的，相互沟通的一个门户。

  1. 应该尽量把域名放到专用域名下。

  2. 应该将 API 的版本号放入 URL，方便直观。

    http://api.example.com/v1/

  3. 路径代表的是一种资源，所以路径中不要包含动词，只能有名词，而且所用名词往往和数据库中的表名相对应（建议都是复数，统一一下，别乱了）。使用小写字母，多个单词使用-分隔，提高 url 的可读性

  4. HTTP 动词方面

    1. GET：获取资源

      url 问题：主键使用路径参数（url/1，使用永远不变的部分作为路径参数），其他查询字段使用查询参数（url?name = lcy）

    2. POST：新建资源

    3. PUT：更新资源（完整更新） PATCH：更新资源（提供更新的属性）。这里两种动词大家一般都用 PUT

    4. DELETE：删除资源

    5. 另外两个不常用的 HEAD 和 OPTIONS（自行了解）

  5. 当返回数量很多时要提供过滤信息和限制信息。一般放在查询参数，比如分页数据，limit 数据以及筛选条件

  6. 状态码（列举一下比较常见的）

    • 200（ok）：操作正常
    • 400（invalid request）：请求有错误
    • 401（unauthorized）：用户权限错误
    • 403（forbidden）：访问自己权限访问不了的请求
    • 404（not found）：请求操作失败
    • 500（internal server error）：服务器发生错误

  7. 错误处理：一般用 error 作为键

  8. 返回结果：get/post 返回查询的结果，put 更新返回更新后的结果，delete 返回删除 id 或者空都可以

    格式定义一般这样：

    {
    ”error“:2000,//业务码
    ”message“:"信息"//具体信息
    "data":{
    }
}

  9. 返回数据格式：一般选用 JSON 格式

三，参考资料

理解 RESTful 架构 - 阮一峰的网络日志 (ruanyifeng.com)

RESTful API 设计指南 - 阮一峰的网络日志 (ruanyifeng.com)

Related Issues not found

Please contact @mlhiter to initialize the comment