二、Restful介绍-CSDN博客

本文链接：https://blog.csdn.net/weixin_44597347/article/details/135102923

Restful 介绍

简介
其他开发框架
与swagger关系
编码规范

简介

REST（英文：Representational State Transfer，又称具象状态传输）是Roy Thomas Fielding博士于2000年在他的博士论文中提出来的一种万维网软件架构风格，目的是便于不同软件/程序在网络（例如互联网）中互相传递信息。

REST 的核心是可编辑的资源及其集合，用符合 Atom 文档标准的 Feed 和 Entry 表示。每个资源或者集合有一个惟一的 URI。系统以资源为中心，构建并提供一系列的 Web 服务。

在 REST 中，开发人员显式地使用 HTTP 方法，对系统资源进行创建、读取、更新和删除的操作：

使用 POST 方法在服务器上创建资源
使用 GET 方法从服务器检索某个资源或者资源集合
使用 PUT 方法对服务器的现有资源进行更新
使用 DELETE 方法删除服务器的某个资源

如果一个架构符合REST原则，就可以称它为RESTful架构。

RESTful是一种软件架构风格、设计风格，而不是标准，它充分利用了现有的协议。虽然RESTful可以应用于任何网络协议，但它通常是指用于HTTP的应用程序。RESTful架构主要遵循以下几个核心原则：

客户端-服务器结构：RESTful架构通过分离用户界面关注点和数据存储关注点来提高跨多个平台的可移植性，并简化服务器组件的可伸缩性。
无状态：在RESTful架构中，每个请求都包含了处理该请求所需的所有信息。服务器不会在请求之间保存任何客户端状态，每个请求都是独立的。这增加了可见性、可靠性和可伸缩性。
可缓存：RESTful架构中的响应需要被定义为可缓存的或不可缓存的。这样可以消除一些客户端与服务器间的交互，提高系统效率。
统一接口：RESTful架构具有统一的接口，这简化了整个系统架构，提高了各个部分的独立性。这一原则包括以下四个子原则：
- 资源的标识：资源是RESTful架构中的关键抽象概念，每个资源都有其唯一的标识符（例如URI）。
- 通过表示进行资源操作：客户端和服务器之间的交互是通过资源的表示（例如JSON或XML）进行的。客户端对资源的任何操作都是在这些表示上进行的。
- 自描述消息：每个消息包括足够的信息来描述如何处理该消息。
- 超媒体作为应用状态的引擎（HATEOAS）：客户端能够通过服务器提供的动态超媒体链接发现所有可用的动作和资源。
分层系统：RESTful架构中的客户端通常不能直接和存储数据的服务器通信，而是与中间服务器通信，如负载均衡器或缓存服务器。这帮助系统通过层次化来提高可伸缩性和简化组件。
按需编码（可选）：服务器可以临时扩展或定制功能来提供客户端特定的代码，例如Java applets或JavaScript。这是唯一一个可选的约束。

遵循这些原则设计的API称为RESTful API。这些API通过标准HTTP方法如GET、POST、PUT、DELETE和PATCH来实现资源的创建、读取、更新和删除（CRUD）操作。RESTful API设计旨在使用无状态通信和标准操作，使其成为一个可靠、快速和可伸缩的系统。

其他开发框架

是的，除了RESTful API之外，还有其他几种常见的API设计风格，主要包括以下几种：

SOAP (Simple Object Access Protocol)
SOAP是一种较为老旧的协议，它基于XML的消息格式进行数据交换，并且通常依赖于HTTP或SMTP协议来传输信息。SOAP APIs非常严格和正式，因为它们要求每个请求和响应都遵循特定的XML架构。SOAP支持WS-Security、事务管理、消息队列等高级功能，适合于需要高安全性或事务性的企业级应用。
GraphQL
由Facebook开发的GraphQL是一种在API中查询和操作数据的语言。它允许客户端准确指定它们需要哪些数据，从而允许更高效的数据获取。与REST不同，GraphQL通常通过单一端点来处理所有请求，并且允许客户端在一个请求中获取多个资源，而不需要向多个不同的端点发送请求。
OData (Open Data Protocol)
OData是一种基于REST的标准，它提供了一种用于查询和更新数据的方法。OData旨在通过提供一组标准化的查询语言（比如 $f i lt er 、$ select、$expand等）来改善RESTful接口的标准化问题。这使得客户端可以更灵活地查询API，但同时也增加了实现的复杂性。
JSON-RPC 和 XML-RPC
RPC（Remote Procedure Call）是一种通过网络从远程计算机程序上请求服务的协议。JSON-RPC和XML-RPC是两种RPC风格的实现，它们允许客户端发送一个包含方法名和参数的请求。JSON-RPC使用JSON，而XML-RPC使用XML。它们都是协议较简单、定位明确的API风格。
gRPC
由Google开发的gRPC是一个高性能、开源和通用RPC框架，它基于HTTP/2协议，并使用Protobuf（Protocol Buffers）作为接口描述语言来定义服务。gRPC专注于性能和效率，适合于微服务架构中的内部通信。
WebSockets
WebSockets提供了一个相对于HTTP更加轻量级的协议，用于在客户端和服务器之间建立一个持久的双向连接。一旦连接建立，客户端和服务器可以随时发送消息，无需遵循请求/响应模式。这对于实时通信应用程序非常有效。

每种API设计风格都有其优点和缺点，适用于不同的场景。选择最合适的API设计风格通常取决于具体的应用需求、开发和操作的复杂性、以及数据交换的效率要求。

与swagger关系

RESTful 是一种针对网络应用的架构风格，旨在使用现有的广泛标准HTTP技术，并依靠无状态通信进行资源的定义和操作。它使用标准HTTP方法，如 GET、POST、PUT、DELETE 等来处理资源。RESTful 架构使得服务更容易被广泛的客户端访问和理解。

Swagger（现在称为 OpenAPI Specification，简称 OAS）是一套规范和完整框架，用于描述、生产、消费和可视化RESTful Web服务。Swagger的目的是确保API的结构清晰明了，使得人和计算机都能完全理解远程服务的能力。使用Swagger，可以为API生成交互式API文档，生成客户端SDK代码，并提供API的可视化测试工具。

它们之间的关系可以概括如下：

兼容性：Swagger是为RESTful API设计的；因而，任何遵循REST原则的API都可以使用Swagger来描述。
文档化：使用Swagger可以帮助你自动化生成API文档。这意味着当你的API设计符合RESTful原则时，你可以利用Swagger来创建一个清晰、可交互的API文档。
测试和验证：Swagger提供了一些工具，如Swagger UI和Swagger Editor，这些工具可以帮助开发人员测试RESTful API，确保其操作符合文档说明。
设计与实现分离：Swagger允许你在编写代码之前设计API接口。你可以先用Swagger定义好整个API的结构和行为，再根据这个结构去实现每个接口的细节。
代码生成：Swagger还支持自动化的代码生成，可以基于API描述生成服务器端的桩代码（stub）和客户端的SDK，这对于快速开发而言非常有用。

在实际应用中，RESTful API的设计者通常会使用Swagger来定义其API的细节，从而使得API的消费者能够更容易地理解和使用这些API。Swagger的规范和工具集让API设计、测试和文档化工作更加简洁和标准化。

编码规范

RESTful API设计的核心理念是依据HTTP协议的原则，使用URL定位资源，并通过HTTP动词（GET、POST、PUT、DELETE等）描述操作。设计一个良好的RESTful API，需要遵循一些最佳实践，这包括资源命名、请求响应的处理、状态码的使用等。以下是一些详细设计规范的概览以及一个简单的例子：

资源命名和动作

使用名词来命名资源：API中的资源应该以名词表示，而不是动词。例如，如果你有一个关于用户的API，你应该使用/users而不是/getUsers。
复数形式：资源名应该使用复数形式，以表示资源集合（例如，/users代表所有用户，/books代表所有书籍）。
嵌套资源：如果资源是以层次结构组织的，URL应该反映这种层次结构（例如，/users/123/posts表示ID为123的用户的所有帖子）。

HTTP方法

GET：用于检索资源或资源集合。
POST：用于创建新的资源。
PUT：用于更新现有资源。
DELETE：用于删除现有资源。
PATCH：用于部分更新资源。

状态码

200 OK：请求成功，并且对于GET和PUT请求，返回所请求的资源。
201 Created：POST请求成功，并且新资源已被创建。
204 No Content：请求成功，但没有要返回的内容，通常用于DELETE请求。
400 Bad Request：客户端错误，请求无效或格式不正确。
401 Unauthorized：请求未经授权。
403 Forbidden：请求被理解，但是被拒绝执行。
404 Not Found：请求的资源不存在。
500 Internal Server Error：服务器端错误。

请求和响应处理

使用JSON格式：JSON是一种轻量级的数据交换格式，易于人阅读和编写，同时易于机器解析和生成。
统一资源表示：保持API的端点表示统一和一致。
状态码的使用：正确使用HTTP状态码来表示不同的API响应结果。

分页、过滤、排序

分页：对于返回多项资源的API，应该提供分页。例如，GET /items?page=2&per_page=20。
过滤：提供过滤结果的选项。例如，GET /users?role=admin。
排序：提供结果排序的选项。例如，GET /books?sort=author。

示例

假设我们有一个管理图书的RESTful API。下面是一些端点的示例：

获取所有图书：
- GET /books
- 返回码：200 OK
- 响应体：图书信息的JSON数组
创建新图书：
- POST /books
- 请求体：包含图书信息的JSON对象
- 返回码：201 Created
- 响应体：创建的图书信息
获取特定图书：
- GET /books/{id}
- 返回码：200 OK 或 404 Not Found（如果图书不存在）
- 响应体：特定ID的图书信息
更新特定图书：
- PUT /books/{id}
- 请求体：包含图书更新信息的JSON对象
- 返回码：200 OK 或 404 Not Found（如果图书不存在）
- 响应体：更新后的图书信息
部分更新特定图书：
- PATCH /books/{id}
- 请求体：包含图书的部分更新信息的JSON对象
- 返回码：200 OK 或 404 Not Found（如果图书不存在）
- 响应体：更新后的图书信息
删除特定图书：
- DELETE /books/{id}
- 返回码：204 No Content 或 404 Not Found（如果图书不存在）