如何使用Python Django开发符合RESTful规范的API？-Python教程-PHP中文网

drf是最稳妥的api开发选择，因其内置序列化、请求解析、状态码、分页、权限等机制，避免原生django手动处理导致的校验重复、分页混乱、状态码错误、更新绕过验证、错误格式不统一等问题。

如何使用python django开发符合restful规范的api？

直接用 Django REST Framework（DRF）是最稳妥的选择，原生 Django 虽然能写 API，但手动处理序列化、请求解析、状态码、分页、权限等会迅速失控。

为什么不能只靠 Django 的 `JsonResponse` 写 RESTful API

很多人一开始用 JsonResponse + request.method 分支写接口，很快就会遇到几个硬伤：

每个视图都要重复写字段校验逻辑，request.POST.get("name") 或 json.loads(request.body) 容易漏判空值、类型错误
GET 查询参数（如 ?page=2&limit=20）要自己解析、拼 SQL，分页不一致、偏移越界没防护
HTTP 状态码全靠手写：status=400、status=404 很容易写错或遗漏
PUT/PATCH 更新时，无法自动区分“部分更新”和“全量更新”，Model.objects.filter().update() 会绕过模型验证
没有统一的错误格式，前端收到 {"error": "missing field"} 和 {"detail": "Not found."} 混用，难以封装通用错误处理器

`ModelSerializer` 是 DRF 的核心起点，别跳过它直接写 `APIView`

哪怕你只打算暴露一个 Book 模型的列表和详情，也该先定义 BookSerializer。它不是“多此一举”，而是把三件事一次性绑定：

字段映射：自动从 Book 模型读取 title、author、published_date，不用手写 dict 构造
反向验证：POST/PUT 请求提交的数据，会按 max_length、required=True 等模型约束自动校验，失败时返回标准 400 Bad Request + 字段级错误信息
嵌套支持：比如 author 是外键，加一行 author = AuthorSerializer(read_only=True) 就能展开关联数据，不用在视图里手动 .select_related() 再组装

示例（serializers.py）：

from rest_framework import serializers
from .models import Book
<p>class BookSerializer(serializers.ModelSerializer):
class Meta:
model = Book
fields = ['id', 'title', 'author', 'published_date']
read_only_fields = ['id']  # 防止客户端伪造 id
</p>

URL 路由必须匹配 HTTP 方法语义，别用 `path('book/', ...)` 承担所有操作

RESTful 不是“把接口都塞进一个 URL”，而是让路径表示资源、方法表示动作。常见错误是：

所有操作都走 path('api/book/', views.book_handler)，然后在视图里 if request.method == 'GET' 分支——这违背了 REST 的资源定位原则
用 POST /api/book/delete/ 这种非标准路径删除资源，而不是 DELETE /api/book/123/
版本控制缺失，上线后改接口不敢动 v1，只能新增 v2，导致路由爆炸

正确做法（urls.py）：

testing-python

使用pytest编写和评估有效的Python测试。适用于编写测试、审查测试代码、调试测试失败或提高测试覆盖率。

下载

from django.urls import path, include
from rest_framework.routers import DefaultRouter
from . import views
<p>router = DefaultRouter()
router.register(r'book', views.BookViewSet, basename='book')  # 自动生成 GET/POST/PUT/DELETE</p><p>urlpatterns = [
path('api/v1/', include(router.urls)),  # 版本前缀清晰
]
</p>

DefaultRouter 会自动注册符合 REST 语义的路径：GET /api/v1/book/（列表）、POST /api/v1/book/（新建）、GET /api/v1/book/123/（详情）、PUT /api/v1/book/123/（全量更新）、DELETE /api/v1/book/123/（删除）

认证和权限必须提前配置，否则上线后补会牵一发而动全身

很多项目初期没设权限，所有接口裸奔，后期加 IsAuthenticated 时才发现：

BookViewSet 继承自 viewsets.ModelViewSet，默认没有任何权限限制，连 DELETE 都对游客开放
全局配置 DEFAULT_PERMISSION_CLASSES 后，管理后台登录态（Session）和 API Token 无法共存，导致 admin 页面登不上
第三方调用需要 TokenAuthentication，但忘了在 settings.py 中添加 'rest_framework.authtoken' 到 INSTALLED_APPS，迁移时报错 No migrations to apply

推荐最小可行配置（settings.py）：

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.TokenAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticatedOrReadOnly',  # 列表和详情允许匿名读，写操作需登录
    ],
}

注意：IsAuthenticatedOrReadOnly 对 GET 放行，但 POST/PUT/DELETE 仍需登录；如果某接口真要完全公开（如注册），得在对应 ViewSet 里单独设 permission_classes = [AllowAny]。

真正麻烦的不是写第一个接口，而是当字段增加校验规则、关联关系变复杂、并发请求增多时，裸写逻辑的维护成本会指数上升。DRF 的约定不是束缚，是提前帮你踩过坑的护栏。