在现代 Web 开发中，前后端分离已成主流，后端提供 API 接口，前端（Web、移动端、第三方）通过 HTTP 协议调用。RESTful API 是目前最成熟的接口设计风格，无论你用 Django、Flask 还是 FastAPI，设计原则是相通的。
RESTful 接口的核心原则
REST（Representational State Transfer）不是一种协议，而是一种架构风格，其核心理念是将一切抽象为“资源”，并通过 HTTP 动词操作资源。
- 资源（Resource）与 URL
每个资源对应一个唯一的 URL，通常用名词复数形式。例如：
/users：用户列表/users/123：ID 为 123 的用户/users/123/orders：该用户的订单列表
- HTTP 方法（动词）表示操作
使用标准 HTTP 方法对资源执行 CRUD 操作，而不是在 URL 里塞动作词：
GET /users：获取用户列表GET /users/123：获取单个用户POST /users：创建新用户PUT /users/123或PATCH /users/123：更新用户DELETE /users/123：删除用户
- 状态码表达结果
使用有意义的 HTTP 状态码，而不是统一返回 200 再在 body 里定义业务状态码：
200 OK：请求成功201 Created：资源创建成功204 No Content：删除成功，无返回体400 Bad Request：参数错误401 Unauthorized：未认证403 Forbidden：无权限404 Not Found：资源不存在500 Internal Server Error：服务器内部错误
- 无状态（Stateless）
每个请求必须包含服务器处理该请求所需的全部信息，不能依赖服务器端保存的上一次请求的上下文。这意味着认证 token（如 JWT）应放在请求头中，而不依赖 session。
- 统一响应格式
为客户端方便解析，建议所有接口返回统一结构的 JSON，例如：
{
"code": 0,
"message": "success",
"data": { ... }
}
在主流框架中的实现对比
三个主流框架都能轻松实现 RESTful API，但各有特色：
- Django + Django REST Framework (DRF)
DRF 是 Django 生态中构建 API 的事实标准。它提供了序列化器（Serializer）、视图集（ViewSet）、路由器（Router）等高级工具，开发速度快，一套代码即可完成增删改查。适合大型项目，尤其是需要后台管理的系统。
# 示例：用 ModelSerializer 和 ModelViewSet 快速实现资源接口
from rest_framework import serializers, viewsets
from .models import User
class UserSerializer(serializers.ModelSerializer):
class Meta:
model = User
fields = '__all__'
class UserViewSet(viewsets.ModelViewSet):
queryset = User.objects.all()
serializer_class = UserSerializer
一行路由注册即可暴露标准 RESTful 接口。
- Flask
Flask 本身保持微框架的灵活，你可以用函数视图直接实现 RESTful 接口，或使用扩展库如 Flask-RESTful、Flask-RESTX 来结构化。适合小型服务或需要精细控制的场景。
from flask import Flask, request
app = Flask(__name__)
@app.route('/users', methods=['POST'])
def create_user():
# 处理逻辑
return {'code': 0, 'data': {...}}, 201
- FastAPI
FastAPI 是现代异步框架，利用 Python 类型提示自动生成交互式文档（Swagger UI），并内置数据校验（基于 Pydantic）。开发体验极佳，特别适合高性能 API 服务。
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class UserCreate(BaseModel):
name: str
email: str
@app.post("/users", status_code=201)
async def create_user(user: UserCreate):
# user 已自动校验
return {"code": 0, "data": user.dict()}
实践中的关键细节
- 版本管理：接口尽量带上版本号，如
/api/v1/users，便于后续迭代时向下兼容。 - 过滤、排序、分页：列表接口务必支持查询参数，例如
?page=2&per_page=20&sort=-created。 - 错误处理：不要直接抛给客户端原始异常，统一捕获并返回结构化错误信息。
- 认证与鉴权：常用方案有 JWT Token、OAuth2.0；框架层面通常提供中间件或依赖注入来简化验证。
- 限流与防爬：对公开接口应设置频率限制，可使用 Redis + 令牌桶/滑动窗口实现。
- 文档自动生成：FastAPI 天然支持，DRF 有 drf-spectacular，Flask 可集成 flasgger，让 API 文档与代码同步更新。
RESTful 并非银弹，对于实时双向通信场景（如聊天）更适合 WebSocket，而查询复杂度高时可以考虑 GraphQL。但作为通用接口风格，REST 的简单、透明和无状态特性，使其成为绝大多数后端项目的首选。