REST API系列—（6）REST API 基于 HTTP 的交互设计规范

目录

一、概述

1.1 背景

1.2 目标

1.3 适用范围

二、REST 与 HTTP 的设计原则

2.1 REST 核心思想

2.2 REST 设计特征

三、HTTP 方法与资源操作

四、URI 设计规范

4.1 基本要求

4.2 示例

五、HTTP 状态码使用规范

六、响应体设计规范

6.1 统一格式

6.2 错误响应示例

七、请求与参数设计

7.1 请求体格式

7.2 查询参数与分页

八、幂等性设计

九、缓存与条件请求

十、安全机制与认证

十一、版本控制与弃用策略

十二、接口文档与自动化

十三、示例交互流程

13.1 创建用户流程

十四、附录：HTTP 常见响应与操作语义对照表

---

一、概述

1.1 背景

本规范用于指导系统中 RESTful API 的设计、开发与维护，确保所有接口在 HTTP 协议交互 层面遵循统一的语义、结构和安全标准。

1.2 目标

• 提高 API 可读性与一致性；

• 降低前后端对接与版本维护成本；

• 支持自动化文档生成与测试；

• 便于第三方集成与外部开放。

1.3 适用范围

适用于所有基于 HTTP/HTTPS 协议的 REST API，包括但不限于：

• 设备物联网平台

• 用户与权限管理系统

• 云服务后台 API

• 业务数据接口层

---

二、REST 与 HTTP 的设计原则

2.1 REST 核心思想

REST（Representational State Transfer）是一种基于 资源（Resource） 的分布式系统架构风格。 核心理念：

“资源以 URI 表示，操作通过 HTTP 方法完成，状态通过表示（Representation）传输。”

2.2 REST 设计特征

特征	说明
无状态（Stateless）	每个请求独立，服务器不保存客户端会话状态。
统一接口（Uniform Interface）	使用标准 HTTP 动词语义化操作。
可缓存（Cacheable）	利用 HTTP 缓存头提升性能。
分层系统（Layered System）	客户端无需关心服务内部结构。

---

三、HTTP 方法与资源操作

HTTP 方法	操作语义	是否幂等	是否返回Body	示例
GET	查询资源	✅ 是	✅ 通常返回资源	GET /users/123
POST	新建资源	❌ 否	✅ 返回创建结果	POST /users
PUT	更新或替换资源	✅ 是	✅ 返回修改结果	PUT /users/123
PATCH	局部更新资源	⚠️ 视实现而定	✅	PATCH /users/123
DELETE	删除资源	✅ 是	❌ 或空Body	DELETE /users/123
HEAD	获取元数据	✅ 是	❌	HEAD /users/123
OPTIONS	查询可用方法	✅ 是	✅	OPTIONS /users

---

四、URI 设计规范

4.1 基本要求

规则	示例
使用 小写字母 + 短横线（-）	/device-events
使用 名词复数 表示资源	/users、/devices
层级表示资源关系	/users/{userId}/devices
避免动词和动作词	❌ /getUser ✅ /users/{id}
过滤与分页用查询参数	/devices?status=online&page=1&size=10
版本管理通过前缀控制	/api/v1/users

4.2 示例

功能	URI	方法	描述
获取所有用户	/api/v1/users	GET	查询用户列表
获取单个用户	/api/v1/users/{id}	GET	获取用户详情