首页/Restful API 设计规范
更新于：2026-03-12

RESTFUL API 设计规范 ​

一、为什么要用 RESTful API ​

RESTful API有以下优点：

  • 统一规范接口
  • 提高开发效率
  • 降低团队沟通成本

二、RESTful API 设计规范 ​

2.1 客户端发送请求 ​

2.1.1 确定资源 ​

资源用URI统一资源标识符来表示，核心规则是用名词来表示资源，不用动词。

  • 名称复数表示资源集合，如：
    • /users 表示用户列表；
    • /products 表示商品列表
  • 具体某个资源，就加上 ID ，如：
    • /users/123 表示ID为123的用户
  • 支持嵌套，如：
    • /users/123/orders 获取用户123的所有订单

注意：不建议嵌套层级太深

2.1.2. 选择动作 ​

是指处理资源的方式, RESTful API主要通过不同的HTTP方法来表示增删改查操作。

方法作用幂等性安全性示例
GET获取资源✓✓GET /users/123
POST创建资源✗✗POST /users
PUT全量更新✓✗PUT /users/123
PATCH部分更新✗✗PATCH /users/123
DELETE删除资源✓✗DELETE /users/123

2.1.3. 添加查询条件(可选) ​

有时我们需要更精确的筛选数据。

js
GET xxx/users
  • 分页：/users?page=2&limit=10 — 查询第2页，每页10条用户数据
  • 筛选：/users?gender=male&age=25 — 查询性别为男性，年龄为25的用户
  • 排序：/users?sort=created_at&order=desc — 按照创建时间倒序排列用户

查询参数本身不是RESTful特有的，但Restful 风格强调把筛选、排序、分页这些操作都通过URL参数来表达，而不是在请求体里面传一堆复杂的Json对象。

Restful 风格 ​

js
GET xxx/users?age=25&page=2&sort=created_at
  • 筛选 age=25
  • 分页 page=2
  • 排序 sort=created_at

2.1.5. 保持无状态 ​

无状态 (Stateless) 是 RESTful 架构的核心约束之一。 其含义是，服务器不应保存客户端的会话状态。每个来自客户端的请求都必须包含处理该请求所需的全部信息（如身份凭证、上下文等）。

典型实现方式是： ​

  1. 用户登录后，服务器生成一个唯一的身份凭证（如 Token），并将其返回给客户端。
  2. 此后客户端的每一个请求都必须在HTTP标头（如 Authorization: Bearer <token>）中携带此凭证。
  3. 服务器不关心请求之间的关联，仅根据当前请求提供的 Token 和参数进行验证、处理并返回响应。

请求标头 ​

js
GET /orders
Header: Authorization: Bearer xxx

这样做带来的关键优势：

  • 极高的可扩展性： 由于请求完全独立，无需会话亲和性（Session Affinity），任何服务器实例都能处理任何请求。这使得通过简单地增加服务器节点来实现水平扩展变得非常容易。
  • 简化服务器设计： 服务器无需实现复杂的状态同步、会话存储和清理机制，降低了复杂度和资源消耗。
  • 提升可靠性： 单点故障的影响更小。客户端请求可以无缝地由其他可用服务器处理，无需担心会话丢失。
  • 便于缓存和负载均衡： 无状态的请求使得HTTP缓存机制（如CDN、反向代理）和标准的负载均衡策略能更高效地工作。

因此，“无状态”是构建大规模、高性能、可伸缩分布式服务的基石，它将状态管理的责任转移给客户端，使服务器集群变得简单而强大。

2.2 服务端给出响应 ​

2.2.1. 统一响应格式 ​

目前大多数 RESTful API 基本都使用 JSON 格式，因为轻量、容易解析，但并不是强制的。

json
{
  "id": 123,
  "name": "张三",
  "email": "xxx@xxx.com"
}

2.2.2. 返回合适的HTTP状态码 ​

响应需要带上合适的状态码，前端开发者或运维人员通过查看状态码，就能快速定位问题方向。

HTTP 状态码有很多，大致可以分为5类：

  1. 1xx 系列：信息提示（用的少，了解即可）
  • 100 Continue ：继续请求

  1. 2xx 系列：成功

    • 200 OK：请求成功，正常返回数据（用于 GET、PUT、PATCH）
    • 201 Created：创建成功(用于POST 请求)，通常会在响应头的Location 中返回新的资源地址URI
    • 202 Accepted：请求已接受，但还在处理中（常用于异步操作）
    • 204 No Content：请求成功，但无返回数据（常用于 DELETE ）

  2. 3xx 系列：重定向

    • 301 Moved Permanently：请求的资源已永久移动到新位置
    • 302 Found：请求的资源已临时移动到新位置
    • 304 Not Modified：资源未修改,客户端可以使用缓存。

  3. 4xx 系列：客户端错误

    • 400 Bad Request：请求参数格式错误
    • 401 Unauthorized：为验证身份，需要登录
    • 403 Forbidden：已认证但没有权限访问
    • 404 Not Found：资源不存在
    • 405 Method Not Allowed：请求方法不被允许（比如对只读资源用DELETE）
    • 409 Conflict：请求冲突（比如尝试创建已存在的资源）
    • 422 Unprocessable Entity：请求格式正确，但语义错误（比如邮箱格式不对）
    • 429 Too Many Requests：请求过于频繁，触发限流

  4. 5xx 系列：服务器错误

    • 500 Internal Server Error：服务器内部错误
    • 502 Bad Gateway：网关错误（服务器作为网关时，从上游服务器收到无效响应）
    • 503 Service Unavailable：服务器暂时不可用(通常是服务器维护或过载)
    • 504 Gateway Timeout：网关超时

三、RESTful API 开发与测试 ​

1. 开发框架推荐 ​

  • Python的Django REST Framework
  • VSCode的REST Client插件，可以在编辑器里测试接口

版权声明：本文部分笔记截取于此CSDN博主少莫千华的原创文章，遵循CC 4.0 BY-SA版权协议，

原文链接：CSDN blog