【一】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:删除成功}