Python从入门到精通（第58章）：RESTful API设计规范

萤火阳光

382人浏览 · 2026-04-15 07:37:26

萤火阳光 · 2026-04-15 07:37:26 发布

开头导语

这是本系列第58章。本章围绕 RESTful API 设计规范展开。URL 代表资源（名词），HTTP 方法代表操作。统一响应格式 {code, data, message} 方便前端处理。分页返回 total 加 items。版本管理（URL 前缀或 Header）。接口文档（Swagger/OpenAPI）是前后端协作的基础设施。阅读时建议边看边动手敲代码，所有示例都亲自运行一次后再往下走。

章节摘要

本章围绕 RESTful API 设计规范展开。URL 代表资源（名词），HTTP 方法代表操作。统一响应格式 {code, data, message} 方便前端处理。分页返回 total 加 items。版本管理（URL 前缀或 Header）。接口文档（Swagger/OpenAPI）是前后端协作的基础设施。

关键词

REST、HTTP方法、状态码、统一响应格式、分页、版本管理

学习目标

掌握本章核心概念，能说清楚适用场景和边界条件。
每个知识点都配有可直接运行的 Python 示例。
能独立完成本章案例，并具备基础排错能力。

先修知识

掌握前章内容（见本章"下一章预告"中的先修建议）。
有基本的代码编写和调试经验。

环境准备

python --version
python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1

核心知识讲解

知识点1：REST资源设计

URL 代表资源，HTTP 方法代表操作。

错误示例（不要这样写）：

REST API 用动词 URL

问题说明：REST 用名词 URL，动词放 HTTP 方法里，/users/1 DELETE

正确写法：

GET /users; POST /users; DELETE /users/{id}

这段代码建议你自己改两次：先改输入数据观察行为变化，再改函数结构验证理解。

知识点2：HTTP方法对应CRUD

GET查、POST增、PUT/PATCH改、DELETE删。

错误示例（不要这样写）：

每个接口单独定义格式

问题说明：统一响应格式 {code, data, message}，所有接口保持一致

正确写法：

这段代码建议你自己改两次：先改输入数据观察行为变化，再改函数结构验证理解。

知识点3：状态码正确使用

200成功、201创建、204无内容、400参数错误、404不存在、500服务器错误。

错误示例（不要这样写）：

分页不传总数

问题说明：分页接口返回 total 和 items，方便前端分页组件渲染

正确写法：

这段代码建议你自己改两次：先改输入数据观察行为变化，再改函数结构验证理解。

知识点4：统一响应格式

所有接口返回同结构的 JSON {code, data, message}。

错误示例（不要这样写）：

HTTP 状态码乱用

问题说明：不能为了省事所有错误都返回 200，前端通过业务 code 判断

正确写法：

{"code": 0, "data": {...}, "message": "ok"}

这段代码建议你自己改两次：先改输入数据观察行为变化，再改函数结构验证理解。

知识点5：分页返回

列表接口返回分页信息：total/page/per_page/items。

错误示例（不要这样写）：

接口文档不更新

问题说明：接口变更后文档必须同步更新，过期文档比没文档更误导人

正确写法：

{"total": 100, "items": [...], "page": 1, "per_page": 20}

这段代码建议你自己改两次：先改输入数据观察行为变化，再改函数结构验证理解。

知识点6：版本管理

URL前缀或请求头管理 API 版本。

错误示例（不要这样写）：

API 版本管理混乱

问题说明：URL 版本和 Header 版本各有权重，项目内保持统一

正确写法：

/api/v1/users

这段代码建议你自己改两次：先改输入数据观察行为变化，再改函数结构验证理解。

案例实战

本章主案例目标：用本章知识实现一个可运行的小工具，覆盖"输入 -> 处理 -> 输出"三个环节。

def main():
    # 1. 准备输入
    data = [1, 2, 3]
    # 2. 业务处理（用本章知识点）
    result = []
    # 3. 输出结果
    print(result)

if __name__ == '__main__':
    main()