Python开发之 RESTful API简记

原创已于 2025-06-18 09:34:31 修改 · 520 阅读

4 ·

CC 4.0 BY-SA版权

文章标签：

#python #restful

于 2025-06-17 15:49:07 首次发布

开发专栏收录该内容

1 篇文章

订阅专栏

一、RESTful API是什么？

REST是一种软件架构风格，可扩展、松耦合。在Web开发中，RESTful API是一种应用程序之间通信的标准方式，用于构建网络应用程序接口。

REST原则六大特点：

无状态：每个请求必须包含处理所需的所有信息，服务器不保存客户端状态（如不使用session）。这使得API简化服务器设计、易于扩展和负载均衡；
统一接口：URI唯一标识资源（如/users/123），通过HTTP方法操作资源（GET/POST/PUT/DELETE），请求/响应包含足够信息描述如何处理，所有 API 都遵循相同的规则和格式；
客户端-服务器架构：客户端与服务器完全分离；
可缓存：响应必须显式或隐式标记为可缓存或不可缓存，客户端/中间件可以缓存响应，通过Cache-Control头部缓存存储控制和ETag/Last-Modified缓存验证机制可以实现条件缓存；
分层系统：客户端不知道是否直接连接最终服务器还是中间层；
按需代码（可选服务）：服务器可以临时扩展客户端功能（如返回JavaScript代码），唯一非强制约束；

前五个是REST必须遵守的约束，后一个是可选的约束。

API的功能：

系统解耦：让客户端和服务器完全分离，可以独立开发；
数据交换：让不同系统之间能够传递信息；
功能复用：不用重复造轮子，可以直接使用现成的模块；
安全控制：控制谁可以访问什么数据；

二、怎么写

路由设计命名规范：

使用名词复数，不使用动词
使用小写字母和连字符(-)，避免文件扩展名

现代RESTful API主要是使用JSON数据格式来传递数据。统一的响应格式如下：

1.资源集合请求

请求

GET /api/v1/products?page=1&limit=5 HTTP/1.1
Accept: application/json

响应

{
  "success": true,
  "code": 200,
  "data": [
    {
      "id": "p001",
      "name": "无线鼠标",
      "price": 99.99,
      "stock": 50
    },
    {
      "id": "p002",
      "name": "机械键盘",
      "price": 299.99,
      "stock": 30
    }
  ],
  "meta": {
    "page": 1,
    "limit": 5,
    "total": 2
  },
  "timestamp": "2025-06-17T10:00:00Z"
}

2.单个资源请求

请求

GET /api/v1/products/p001 HTTP/1.1
Accept: application/json

响应

{
  "data": {
    "id": "p001",
    "type": "products",
    "attributes": {
      "name": "Wireless Mouse",
      "price": 29.99,
      "stock": 150,
      "description": "Ergonomic wireless mouse with 2-year battery life"
    },
    "relationships": {
      "category": {
        "data": { "id": "c12", "type": "categories" },
        "links": {
          "related": "/api/v1/categories/c12"
        }
      }
    },
    "links": {
      "self": "/api/v1/products/p001"
    }
  },
  "included": [
    {
      "id": "c12",
      "type": "categories",
      "attributes": {
        "name": "Computer Accessories"
      }
    }
  ]
}

3.创建资源

请求

POST /api/v1/products HTTP/1.1
Content-Type: application/json

{
  "name": "蓝牙耳机",
  "price": 199.99,
  "stock": 100
}

响应

//成功
{
  "success": true,
  "code": 201,
  "data": {
    "id": "p003",
    "name": "蓝牙耳机",
    "price": 199.99,
    "stock": 100
  },
  "links": {
    "self": "/api/v1/products/p003"
  },
  "timestamp": "2025-06-17T10:05:00Z"
}

//失败
{
  "success": false,
  "code": 400,
  "error": {
    "type": "validation_error",
    "message": "价格不能为负数",
    "details": {
      "field": "price",
      "rule": "min:0"
    }
  },
  "timestamp": "2025-06-17T10:06:00Z"
}

data 数组：包含返回的核心资源数据；
meta 对象：提供与数据集合相关的元信息，如total: 总记录数、page: 当前页码、per_page: 每页显示数量等；
links 对象：实现HATEOAS（超媒体作为应用状态引擎）、self: 当前请求的完整URL、next: 下一页数据的访问URL（当page=1时指向第2页）等。

如果有未来升级为WebSockets协议等非HTTP协议的打算，最好显式在 JSON 响应中加入 success 字段、保留 HTTP 状态码（便于现有 HTTP 客户端）、统一错误格式（如 code + message）等。

基础路由结构参考：

// 产品相关
GET    /api/v1/products                  // 获取产品列表
GET    /api/v1/products/{id}              // 获取特定产品
POST   /api/v1/products                  // 创建新产品
PUT    /api/v1/products/{id}              // 全量更新产品信息
DELETE /api/v1/products/{id}              // 删除产品

// 分类相关
GET    /api/v1/categories              // 获取全部分类
GET    /api/v1/categories/{id}/products   // 获取分类下的产品列表

常见网络状态码合集
1xx（信息性状态码）表示临时响应，客户端应继续等待或处理请求
2xx（成功状态码）表示请求已被成功处理
3xx（重定向状态码）表示需要客户端进一步操作以完成请求
4xx（客户端错误状态码）表示客户端请求有误
5xx（服务器错误状态码）表示服务器处理请求时出错

100 Continue：服务器已收到请求头，客户端应继续发送请求体1。
101 Switching Protocols：服务器同意客户端请求，切换协议（如HTTP升级到WebSocket）1。
102 Processing（WebDAV）：服务器已接收请求但仍在处理，避免客户端超时1。

200 OK：请求成功，响应中包含请求的数据1。
201 Created：请求成功且服务器创建了新资源（如POST请求）1。
202 Accepted：请求已接受但尚未处理完成（适用于异步任务）1。
204 No Content：请求成功，但响应无返回内容（如DELETE请求）1。
206 Partial Content：服务器成功返回部分数据（如断点续传）1。

301 Moved Permanently：资源已永久重定向至新URL1。
302 Found（临时重定向）：资源暂时移至新URL，后续请求仍用原地址1。
304 Not Modified：客户端缓存未过期，服务器未返回新内容1。
307 Temporary Redirect：类似302，但要求HTTP方法不变1。
308 Permanent Redirect：类似301，但要求HTTP方法不变1。

400 Bad Request：请求语法错误，服务器无法解析1。
401 Unauthorized：请求需身份验证（如未登录）1。
403 Forbidden：服务器理解请求但拒绝执行（如权限不足）1。
404 Not Found：请求的资源不存在1。
405 Method Not Allowed：请求方法（如GET/POST）不被允许1。
429 Too Many Requests：客户端发送请求过多（限流）1。

500 Internal Server Error：服务器内部错误（如代码异常）1。
502 Bad Gateway：代理服务器从上游收到无效响应1。
503 Service Unavailable：服务器暂时不可用（如过载或维护）1。
504 Gateway Timeout：代理服务器等待上游响应超时1。
505 HTTP Version Not Supported：服务器不支持请求的HTTP协议版本1。