当前位置：首页 > news >正文

‌RESTful API 设计规范

news 2025/6/26 8:15:33

‌RESTful API的核心概念‌

‌RESTful API是一种遵循REST架构风格的应用程序编程接口，它通过统一的HTTP方法（如GET、POST、PUT、DELETE）对网络资源进行操作，强调无状态通信、资源标识和可扩展性‌。其核心设计原则包括资源化URI、标准HTTP动词使用、无状态性及可缓存性，广泛应用于Web服务开发。

‌资源与URI‌

一切网络实体（如用户、订单）均抽象为资源，每个资源通过唯一URI标识（如/users/123），URI设计需具有自描述性和可寻址性。‌‌

‌HTTP方法映射操作‌

GET：读取（Read）
POST：新建（Create）
PUT：更新（Update）
PATCH：部分更新（Update）
DELETE：删除（Delete）
通过标准动词实现操作统一性，避免自定义动作命名。‌‌‌‌

‌无状态性‌

服务器不保存客户端会话状态，每次请求需包含完整上下文信息，提升系统可扩展性和可靠性。‌‌‌‌

‌关键设计原则‌

‌统一接口‌：使用标准HTTP方法和状态码（如200成功、404未找到），支持JSON/XML等多种数据格式。‌‌‌‌
可缓存性‌：利用HTTP缓存机制（如Cache-Control头）优化性能。‌‌

分层系统：客户端与服务器解耦，允许中间层（如网关、代理）增强安全性和负载均衡。‌‌

‌实际应用优势‌

‌协议无关性‌：虽常基于HTTP，但REST本身不依赖特定协议。‌‌
‌灵活性‌：资源的多重表示（如JSON、HTML）适应不同客户端需求。‌‌
‌易维护性‌：清晰的URI和HTTP语义降低团队协作成本。‌‌

示例：


GET    /v1/vms：列出全部虚拟机（默认分页）
POST   /v1/vms：新建虚拟机
GET    /v1/vms/ID：查询指定ID虚拟机的信息
PUT    /v1/vms/ID：更新指定ID虚拟机的信息（提供该虚拟机的全部信息）
PATCH  /v1/vms/ID：更新指定ID虚拟机的信息（提供该虚拟机的部分信息）
DELETE /v1/vms/ID：删除指定ID虚拟机
GET    /v1/vms/ID/disks：列出指定ID虚拟机的所有磁盘
DELETE /v1/vms/ID/disks/ID：删除指定ID虚拟机的指定ID磁盘

1.版本号

2.资源为名称，使用复数形式

3.使用小写字母，多个单词用"-"分隔

4.资源嵌套层次避免过深，尽量不超过2层

5.过滤查询

6.不符合 CRUD 情况、扩展请求

1.使用 POST，为需要的动作增加一个 endpoint，使用 POST 来执行动作
2.增加控制参数，添加动作相关的参数，通过修改参数来控制动作
3.把动作转换成资源，把动作转换成可以执行 CRUD 操作的资源
4.扩展请求 action=？ type=？

7.动词覆盖，应对服务器不完全支持 HTTP 的情况

有些客户端只能使用GET和POST这两种方法。服务器必须接受POST模拟其他三个方法（PUT、PATCH、DELETE）。
这时，客户端发出的 HTTP 请求，要加上X-HTTP-Method-Override属性，告诉服务器应该使用哪一个动词，覆盖POST方法。

其他参考：

RESTful API 设计规范详解_restful api接口规范-CSDN博客

Restful API规范_restful api接口规范-CSDN博客