【2.0】DRF之Restful规范

【一】Restful

【1】介绍

  • Restful（Representational State Transfer）是一种软件架构风格，它定义了一组规范和约束，用于设计可伸缩、可维护和易于集成的分布式系统。

  • Restful 架构的核心概念是资源（Resource）和资源的表述（Representation）。

    • 资源是指系统中的任何信息，可以是一个文档、图像、视频、数据库记录等。
    • 每个资源都有唯一的标识符（URI，Uniform Resource Identifier）用于定位和访问资源。

  • Restful 架构中，客户端通过HTTP协议向服务器发送请求，并根据不同的HTTP方法（GET、POST、PUT、DELETE等）执行不同的操作。

【2】常用的HTTP方法在Restful架构中的含义：

  • GET：

    • 用于获取一个或多个资源的表示。
    • 可通过URL参数传递过滤、排序等条件。

  • POST：

    • 用于创建新资源。
    • 客户端将资源的表述作为请求体发送给服务器。

  • PUT：

    • 用于更新已有资源。
    • 客户端将更新后的资源的表示作为请求体发送给服务器。

  • DELETE：

    • 用于删除资源。
    • 客户端发送一个请求，指示要删除的资源的URI。

【3】常见的状态码

Restful 架构中，服务器返回的响应通常使用 HTTP 状态码来表示操作的结果。

  • 200 OK：

    • 请求成功，服务器返回资源的表示。

  • 201 Created：

    • 请求成功，服务器成功创建了新资源，并返回其表示。

  • 204 No Content：

    • 服务器成功处理了请求，但没有返回任何内容。

  • 400 Bad Request：

    • 请求无效，服务器无法理解或处理请求。

  • 404 Not Found：

    • 请求的资源不存在。

  • 500 Internal Server Error：

    • 服务器内部错误，无法完成请求。

【4】Restful 架构具有以下优点：

  • 可伸缩性：

    • 通过使用轻量级的HTTP协议和无状态的通信方式，可以轻松地扩展系统的规模，适应高并发的访问需求。

  • 可维护性：

    • 通过将系统分解为资源和表述的概念，使得修改和更新系统的不同部分变得更容易，减少了系统之间的依赖性。

  • 可移植性：

    • 由于Restful 架构遵循标准的HTTP协议，不依赖于特定的技术实现，因此可以在不同的平台和语言之间进行互操作。

  • 缓存支持：

    • Restful 架构通过定义缓存规则，可以有效利用缓存机制，提高系统性能和可用性。

【5】总结

（1）RESTful

  • RESTful是一种定义API接口的设计风格，AIP接口的编写规范，，尤其适用于前后端分离的应用模式中

  • 这种风格的理念认为后端开发任务就是提供数据的，对外提供的是数据资源的访问接口

    • 所以在定义接口时，客户端访问的URL路径就表示这种要操作的数据资源

  • 我们可以使用任何一个框架都可以实现符合restful规范的API接口

（2）10条规范

1、数据的安全保障，通常使用https协议进行传输

2、url地址中带接口标识：一般这样

-https://api.baidu.com
-https://www.baidu.com/api

3、多版本共存，url地址中带版本信息

https://api.baidu.com/v1/login/
https://api.baidu.com/v2/login/

4、数据即是资源，均使用名词

  • url地址尽量使用名词

  • 接口一般都是完成前后台数据的交互，交互的数据我们称之为资源

https://api.baidu.com/users
https://api.baidu.com/books
https://api.baidu.com/book

注：一般提倡用资源的复数形式，在url链接中不要出现操作资源的动词

错误示范：https://api.baidu.com/delete-user

  • 特殊的接口可以出现动词，因为这些接口一般没有一个明确的资源，或是动词就是接口的核心含义
https://api.baidu.com/place/search
https://api.baidu.com/login

5、资源操作由请求方式决定

  • 操作资源一般都会涉及到增删改查
  • 我们提供请求方式来标识增删改查动作
# get请求：获取所有书
https://api.baidu.com/books   

# get请求：获取主键为1的书
https://api.baidu.com/books/1 

# post请求：新增一本书书
https://api.baidu.com/books   

# put请求：整体修改主键为1的书
https://api.baidu.com/books/1 

# delete请求：删除主键为1的书
https://api.baidu.com/books/1

6、url地址中带过滤条件 ？后带过滤条件

# get请求表示查询所有图书，要查名字中有红的图书
https://api.baidu.com/books 
https://api.baidu.com/books?name_contains=红
# ：指定返回记录的数量
https://api.example.com/v1/zoos?limit=10
# ：指定返回记录的开始位置
https://api.example.com/v1/zoos?offset=10
# ：指定第几页，以及每页的记录数
https://api.example.com/v1/zoos?page=2&per_page=100
# ：指定返回结果按照哪个属性排序，以及排序顺序
https://api.example.com/v1/zoos?sortby=name&order=asc
# ：指定筛选条件
https://api.example.com/v1/zoos?animal_type_id=1

7、响应状态码(http响应中带状态码)

-1xx：请求正在处理
-2xx：请求成功 200  201
-3xx：重定向
-4xx：客户端错误
-5xx：服务的错误

-http的响应的数据中带状态码(公司自己规定的)
-{code:100}

1xx（信息性状态码）：表示服务器已接收请求，正在处理。

  • 100 Continue：服务器已成功接收到请求的起始部分，客户端应继续发送剩余部分。
  • 101 Switching Protocols：服务器要求客户端切换协议。

2xx（成功状态码）：表示请求已成功被服务器接收、理解和处理。

  • 200 OK：请求成功，服务器正常返回数据。
  • 201 Created：请求已经成功处理，并创建了新的资源。
  • 202 Accepted：服务器已接受请求，但尚未处理完成。
  • 204 No Content：请求已成功处理，但没有返回任何内容。

3xx（重定向状态码）：表示客户端需要采取进一步的操作才能完成请求。

  • 301 Moved Permanently：请求的资源已被永久移动到新位置。
  • 302 Found：请求的资源暂时被移动到新位置。
  • 304 Not Modified：客户端使用缓存数据，请求资源未被修改。

4xx（客户端错误状态码）：表示客户端发出的请求有误。

  • 400 Bad Request：服务器无法理解客户端的请求。
  • 401 Unauthorized：请求要求用户验证身份。
  • 403 Forbidden：服务器拒绝执行请求，权限不足。
  • 404 Not Found：请求的资源在服务器上不存在。

5xx（服务器错误状态码）：表示服务器无法完成明显有效的请求。

  • 500 Internal Server Error：服务器遇到了一个未曾预料的错误。
  • 502 Bad Gateway：服务器作为网关或代理服务器时，从上游服务器收到无效的响应。
  • 503 Service Unavailable：服务器当前无法处理请求（可能由于过载或维护）。

8、返回的数据中带错误信息

{code:101,msg:用户名或密码错误}
{code:100,msg:成功}

9、返回结果，针对不同操作，服务器向用户返回的结果应该符合以下规范

GET  /books：返回资源对象的列表（数组）
    -[{name:梦梦，price:88},{name:西游记，price:88}]
    -{code:100,msg:成功,data:[{name:梦梦，price:88},{name:西游记，price:88}]}

GET /books/1：返回单个资源对象
    -{name:梦梦，price:88}    ---{code:100,msg:成功,data:{name:梦梦，price:88}}

POST /books：返回新生成的资源对象
    -{id:4,name:梦梦，price:88}  ---{code:100,msg:成功}

PUT /books/4：返回完整的资源对象
    -{id:4,name:梦梦，price:188}  ---{code:100,msg:修改成功}

DELETE /books/4： 返回一个空文档      ---{code:100,msg:删除成功}

10、返回的结果中带url链接

posted @ 2023-07-31 12:18  Chimengmeng  阅读(38)  评论(0)  编辑  收藏  举报