RESTful接口规范（学习笔记）

1、URI

在了解RESTful接口规范之前，我们先来了解一下什么是URI。

1、URI

它是一种通一的资源标志符，大致的意思就是在web上的每一个可用的资源，例如 HTML、图片、程序等都有一个URI进行唯一标识,而这些资源一般对应的是服务器端中的实体类。

2、规范

• 字母无需大写

• 多个单词连接在一起作为一个整体时，中间可以用-分割，不推荐使用__

• URI中名词表示资源的集合且要使用复数形式

3、样例

/schools //表示所有的学校
/schools/1/classes //表示第一个学校的所有班级

4、注意

在使用URI表示层级的时候应该避免层级过深，因为这会使得URI非常长，不容易维护，例如 GET /schools/1/classes/4/students/2 ，像这个就可以用 GET /students?school=1 & class=4 来替代

2、RESTful 的特性

1、C-S架构

这个特性其实想要表达的意思就是前后端分离，两端单独开发，互不影响

2、无状态

简单来说就是服务端可以根据客户端的各种请求参数，来将正确的结果响应给客户端，无需保存客户端的状态

3、统一的接口

客户端只需要关注接口即可，这个也是实现前后端分离的一个重要条件

3、RESTful 规范

1、URL中不能有动词

在RESTful规范中，每一个网址代表的都是一个资源，在网址当中不能包含动作，只可以使用名词且名词也应该使用复数形式。

错误写法

https://example.com/api/getallUsers GET 获取所有用户 
https://example.com/api/getuser/1 GET 获取标识为1用户信息 
https://example.com/api/user/delete/1 GET/POST 删除标识为1用户信息 
https://example.com/api/updateUser/1 POST 更新标识为1用户信息 
https://example.com/api/User/add POST 添加新的用户

正确写法

https://example.com/api/users GET 获取所有用户信息 
https://example.com/api/users/1 GET 获取标识为1用户信息 
https://example.com/api/users/1 DELETE 删除标识为1用户信息 
https://example.com/api/users/1 Patch 更新标识为1用户部分信息,包含在body中 
https://example.com/api/users POST 添加新的用户

通过上面的两个例子我们也可以看出，如果URL中出现一些动词，这样很容易造成接口的形式不固定，需要了解文档后才可以调用，但是如果我们规范了我们的写法后，我们的URL可读性也大大的增强了。

那么上面的操作是怎么实现的呢？

实际上在http协议中有一些动词，可以替代URL中的动词来表示一些动作

例如:

GET : 就表示从服务器中检索特定的资源，或资源列表（相当于数据库中的SELECT操作）

POST : 在服务器上创建一个新的资源 （相当于数据库中INSERT操作）

PUT : 更新服务器上的资源，更改整个资源的属性 （相当于数据库中UPDATE操作）

PATCH : 更新服务器上的资源，更改资源的部分属性（相当于数据库中UPDATE操作）

DELETE : 从服务器中删除资源。（相当于数据库中DELETE操作）

2、多表查询，多参查询该如果设计URL

例如我想查询一个获取在6月份的订单中大于500元的且用户地址是北京，用户年龄在22岁到40岁、购买金额降序排列的订单列表

https://example.com/api/orders?order_month=6&order_amount_greater=500&address_city=北京&sort=order_amount_desc&age_min=22&age_max=40

这个URL参数很多，导致不容易进行维护，遇见这种问题，我们可以采取下面的方式来解决

我们可以使用属性路由，大致的操作就是在特定的控制器或者操作方法上用Controller进行装饰并使用[Route]属性来定义路由的方法，好处就是可以精确的控制URL

[Route(“api/orders/{address}/{month}”)] 

那么上面的那个URL就可以写成

https://example.com/api/orders/beijing/6?order_amount_greater=500&sort=order_amount_desc&age_min=22&age_max=40

查询参数就只有金额、排序、年龄。减少了查询参数、API的可读性和可维护行增强了。

3、统一返回的数据格式

• code —— Http的响应状态码

• message —— 当状态值为”fail”和”error”时有效，用于显示错误信息。

• data——包含响应的body。当状态值为”fail”或”error”时，data仅包含错误原因或异常名称、或者null也是可以的

成功响应的json返回格式

{
  "code": 200,
  "message": "success",
  "data": {
    "userName": "123456",
    "age": 16,
    "address": "beijing"
  }
}

失败响应的json返回格式

{
  "code": 401,
  "message": "error  message",
  "data": null
}

4、Http状态码

1、常见的状态码

200 —— OK                    // 成功返回
201 —— Created               // 成功创建
204 —— No Content            // 成功销毁
400 —— Bad Request           // 语法错误
401 —— Unauthorized          // 没有权限
403 —— Forbidden             // 请求被拒
404 —— Not Found             // 找不到资源
500 —— Internal Server Error // 内部服务器错误
501 —— Not Implemented       // 服务器无法受理

2、完整的状态码

1. 1XX（平常基本上用不到）

2. 2xx（Success）

   
   200 —— OK                   // 成功返回了资源
   201 —— Created              // 成功创建了资源
   202 —— Accepted             // 请求接受但未处理
   203 —— Non-Authoritative Information // 返回资源未授权
   204 —— No Content           // 成功销毁了资源
   205 —— Reset Content        // 重置内容，无任何资源返回
   206 —— Partial Content      // 处理了部分请求
   

3. 3xx（redirect）

   300 —— Multiple Choice      // 选择服务器提供的多种操作
   301 —— Moved Permanently    // 永久移除，自动转跳到新的资源
   302 —— Found                // 自动转跳到新的资源
   303 —— See Other            // 查看资源位置
   304 —— Not Modified         // 请求资源未修改
   305 —— Use Proxy            // 需要代理
   307 —— Temporary Redirect   // 临时重定向
   308 —— Permanent Redirect   // 永久重定向
   

4. 4xx（error）

   400 —— Bad Request              // 请求字段语法错误
   401 —— Unauthorized             // 请求未经授权
   403 —— Forbidden                // 请求被服务器拒绝
   404 —— Not Found                // 找不到资源
   405 —— Method Not Allowed       // 请求方法不允许
   406 —— Not Acceptable           // 请求不可接受
   407 —— Proxy Authentication Required // 服务器代理需要授权
   408 —— Request Timeout          // 请求超时
   409 —— Conflict                 // 请求冲突
   410 —— Gone                     // 请求的资源已销毁
   411 —— Length Required          // 指定有效内容长度标头
   412 —— Precondition Failed      // 请求条件无法满足
   413 —— Payload Too Large        // 请求体过大
   414 —— URI Too Long             // 请求URL过长
   415 —— Unsupported Media Type   // 请求的类型不支持
   416 —— Requested Range Not Satisfiable // 请求的范围不符合要求
   417 —— Expectation Failed       // 服务器未满足请求标头的要求
   426 —— Upgrade Required         // 升级所需
   428 —— Precondition Required    // 要求先决条件
   429 —— Too Many Requests        // 太多的要求
   431 —— Request Header Fields Too Large // 请求头字段太大
   451 —— Unavailable For Legal Reasons  // 因法律原因不可用
   

5. 5xx（fail）

   500 —— Internal Server Error        // 内部服务器错误
   501 —— Not Implemented              // 服务器无法受理
   502 —— Bad Gateway                  // 服务器网关错误
   503 —— Service Unavailable          // 服务器不可用
   504 —— Gateway Timeout              // 服务器代理超时
   505 —— HTTP Version Not Supported      // 不支持的HTTP版本
   511 —— Network Authentication Required // 网络认证要求
   
   

   参考资料:https://blog.csdn.net/kebi007/article/details/102927209