RESTful（Representational State Transfer，表述性状态转移）是一种基于HTTP协议的架构风格，利用URI、HTTP方法（如GET、POST、PUT、DELETE等）以及表示层数据格式（如JSON）来创建具有高度可扩展性的服务‌。其核心原则包括资源导向设计、无状态通信、标准HTTP方法使用（GET/POST/PUT/DELETE）以及统一接口规范，广泛应用于微服务、移动应用和物联网等领域。

参考原文：Restful API

什么是 RESTful API

  • REST API是一种应用程序编程接口（API 或 Web API），遵循一组关于应用程序如何使用 HTTP 方法相互通信的架构规则。 RESTful Web 服务使用 REST API 协议，因此有时也称为 RESTful API。
  • REST 通常用于构建 Web API，允许客户端与服务器之间通过 HTTP 协议进行交互。
  • REST 并不是一种协议或标准，而是一组指导原则，旨在帮助开发人员创建可扩展、性能良好且易于维护的 Web 服务。
  • REST 的核心思想是通过一组简单、统一的接口来管理和操作服务器上的资源。

资源Resource

资源可以被视为 Web 服务中的“实体”或“对象”，它可以是用户、订单、文件等任何具有唯一标识符的事物。每个资源都由一个 URI（Uniform Resource Identifier，统一资源标识符）标识。
资源的表示（Representations）
资源可以有多种不同的表示形式，例如 JSON、XML、HTML 等。当客户端请求资源时，服务器会以特定的表示形式返回资源。表示形式通常通过 HTTP 头中的 Content-Type 指定，例如 application/json 表示 JSON 格式。

URI（统一资源标识符）

URI(Uniform Resource Identifier)，URI既可以看成是资源的地址，也可以看成是资源的名称，它是用于标识资源的唯一地址，每个资源都应该有一个唯一的 URI，这个 URI 可以看作是资源的“地址“，如api/user/profile/get：表示获取用户信息。
URI 应该是稳定的，不应该因为资源内部状态的变化而发生变化。URI 应该是自解释的，即可以从 URI 大致了解所表示的资源。

HTTP 方法

在 REST 中，HTTP 方法用于指定对资源执行的操作。每种方法都应该在其相应的上下文中使用。常用的 HTTP 方法包括：

  • GET：检索资源。请求不会改变服务器状态。
  • POST：创建资源或在现有资源中执行子资源的创建操作。
  • PUT：更新资源。通常用于更新整个资源。
  • PATCH：部分更新资源。通常用于更新资源的部分字段。
  • DELETE：删除资源。

image-20250624142317574

HTTP 动词

在非RESTful风格的API中，查询和删除一般使用GET方式请求，更新和插入一般使用POST请求。从请求方式上无法知道API具体是干嘛的，所有在URL上都会有操作的动词来表示API进行的动作，例如：query，add，update，delete等。而RESTful风格的API则要求在URL上都以名词的方式出现，从几种请求方式上就可以看出想要进行的操作，这点与非RESTful风格的API形成鲜明对比。

1
2
3
4
5
GET /collection：从服务器查询资源的列表（数组）
GET /collection/resource：从服务器查询单个资源
POST /collection：在服务器创建新的资源
PUT /collection/resource：更新服务器资源
DELETE /collection/resource：从服务器删除资源
HTTP Method 安全性 幂等性 解释
GET 安全 幂等 读操作安全，查询一次多次结果一致
POST 非安全 非幂等 写操作非安全，每多插入一次都会出现新结果
PUT 非安全 幂等 写操作非安全，一次和多次更新结果一致
DELETE 非安全 幂等 写操作非安全，一次和多次删除结果一致

安全性是指方法不会修改资源状态，即读的为安全的，写的操作为非安全的。而幂等性的意思是操作一次和操作多次的最终效果相同，客户端重复调用也只返回同一个结果。

RESTful API设计规范

URL设计规范

URL为统一资源定位器，接口属于服务端资源，首先要通过URL这个定位到资源才能访问，一个完整的URL组成由以下几个部分构成：

1
URI = scheme "://" host  ":"  port "/" path [ "?" query ][ "#" fragment ]
  • scheme：指底层用的协议，如http、https、ftp
  • host：服务器的IP地址或者域名
  • port： 端口，http默认为80端口
  • path：访问资源的路径，就是各种web 框架中定义的route路由
  • query： 查询字符串，为发送给服务器的参数，在这里更多发送数据分页、排序等参数。
  • fragment： 锚点，定位到页面的资源

在设计API时URL的path是需要认真考虑的，而RESTful对path的设计做了一些规范，通常一个RESTful API的path组成如下：

1
/{version}/{resources}/{resource_id}
  • version：API版本号，有些版本号放置在头信息（headers）中也可以，通过控制版本号有利于应用迭代。
  • resources：资源，RESTful API推荐用小写英文单词的复数形式。
  • resource_id：资源的id，访问或操作该资源。

有时候可能资源级别较大，其下还可细分很多子资源也可以灵活设计URL的path，例如：

1
/{version}/{resources}/{resource_id}/{subresources}/{subresource_id}

有时可能增删改查无法满足业务要求，可以在URL末尾加上action，其中action就是对资源的操作。例如：

1
/{version}/{resources}/{resource_id}/action

RESTful API的URL具体设计规范

  • 不用大写字母，所有单词使用英文且小写。

  • 连字符用中杠"-"而不用下杠"_"

  • 正确使用 "/"表示层级关系，URL的层级不要过深，并且越靠前的层级应该相对越稳定

  • 结尾不要包含正斜杠分隔符"/"

  • URL中不出现动词，用请求方式表示动作

  • 资源表示用复数不要用单数

  • 不要使用文件扩展名

返回结果

请求的处理执行结果

使用各类状态码来表示，状态码主要分为五大类：

状态码 表示意义
1xx 相关信息
2xx 操作成功
3xx 重定向
4xx 客户端错误
5xx 服务器错误

响应的返回结果

响应结果包含状态码和返回数据两个部分。状态码同请求结果一致，返回结果针对不同操作，服务器向用户返回数据，基本都是返回JSON格式数据给客户端