Django REST Framework（DRF）RESTful 最完整版实战教程

本教程从零开始，带你构建一个专业可上线的 RESTful API ，涵盖 DRF

的核心功能：
Model → Serializer → APIView → GenericAPIView → ViewSet → JWT → 权限 →
分页 → 过滤 → 异常处理

非常适合 Django + SimpleJWT 的后端项目。

---

📌 目录

1. 环境准备
2. 创建 Django 项目
3. 编写 Model
4. Serializer（序列化器）
5. APIView（基础）
6. GenericAPIView + Mixins
7. ViewSet + Router（企业最佳实践）
8. 分页
9. 过滤 / 搜索 / 排序
10. 权限
11. 认证（JWT）
12. 全局异常处理
13. 完整 RESTful API 示例

---

1️⃣ 安装 DRF

pip install djangorestframework

修改 settings.py：

INSTALLED_APPS = [
    ...
    'rest_framework',
]

---

2️⃣ 创建项目与 App

django-admin startproject myapi
cd myapi
python manage.py startapp users

---

3️⃣ Model（资源）

users/models.py：

from django.db import models

class User(models.Model):
    username = models.CharField(max_length=32)
    email = models.EmailField()
    created_at = models.DateTimeField(auto_now_add=True)

---

4️⃣ Serializer（核心）

users/serializers.py：

from rest_framework import serializers
from .models import User

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = "__all__"

Serializer = Python对象 ↔ JSON 的转换器，是 DRF 的灵魂。

---

5️⃣ APIView（最基础的 RESTful）

users/views.py：

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from .models import User
from .serializers import UserSerializer

class UserListCreateView(APIView):

    def get(self, request):
        users = User.objects.all()
        serializer = UserSerializer(users, many=True)
        return Response(serializer.data)

    def post(self, request):
        serializer = UserSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        serializer.save()
        return Response(serializer.data, status=status.HTTP_201_CREATED)

URL：

path("users/", UserListCreateView.as_view()),

---

6️⃣ GenericAPIView + Mixins（更 RESTful）

from rest_framework.generics import ListCreateAPIView, RetrieveUpdateDestroyAPIView
from .models import User
from .serializers import UserSerializer

class UserListCreateView(ListCreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer

class UserDetailView(RetrieveUpdateDestroyAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer

URL：

path("users/", UserListCreateView.as_view()),
path("users/<int:pk>/", UserDetailView.as_view()),

RESTful API：

方法 URL 说明

---

GET /users/ 获取用户列表

POST /users/ 创建

GET /users/1/ 详情

PUT /users/1/ 修改

DELETE /users/1/ 删除

---

7️⃣ ViewSet + Router（企业最常用）

from rest_framework.viewsets import ModelViewSet

class UserViewSet(ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

urls.py：

from rest_framework.routers import DefaultRouter

router = DefaultRouter()
router.register("users", UserViewSet)

urlpatterns = router.urls

自动生成：

GET     /users/
POST    /users/
GET     /users/{id}/
PUT     /users/{id}/
PATCH   /users/{id}/
DELETE  /users/{id}/

企业 95% 采用 ViewSet。

---

8️⃣ 分页 Pagination

settings.py：

REST_FRAMEWORK = {
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
    "PAGE_SIZE": 10
}

示例：

GET /users/?page=2

---

9️⃣ 过滤 / 搜索 / 排序

安装：

pip install django-filter

settings.py：

REST_FRAMEWORK = {
    'DEFAULT_FILTER_BACKENDS': [
        'django_filters.rest_framework.DjangoFilterBackend',
        'rest_framework.filters.SearchFilter',
        'rest_framework.filters.OrderingFilter',
    ]
}

启用：

class UserViewSet(ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

    filterset_fields = ["username"]
    search_fields = ["username", "email"]
    ordering_fields = ["created_at"]

---

🔟 权限（Permissions）

全局：

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": ["rest_framework.permissions.IsAuthenticated"],
}

局部：

permission_classes = [IsAuthenticated]

自定义权限：

class IsAdmin(BasePermission):
    def has_permission(self, request, view):
        return request.user.is_staff

---

1️⃣1️⃣ 认证（Authentication） + JWT 登录

安装：

pip install djangorestframework-simplejwt

设置：

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "rest_framework_simplejwt.authentication.JWTAuthentication",
    ]
}

路由：

path("token/", TokenObtainPairView.as_view()),
path("token/refresh/", TokenRefreshView.as_view()),

请求示例：

Authorization: Bearer <access_token>

---

1️⃣2️⃣ 全局异常处理

settings.py：

REST_FRAMEWORK = {
    "EXCEPTION_HANDLER": "utils.exceptions.custom_handler"
}

utils/exceptions.py：

from rest_framework.views import exception_handler

def custom_handler(exc, context):
    response = exception_handler(exc, context)
    if response:
        response.data = {
            "code": response.status_code,
            "message": response.data,
            "data": None
        }
    return response

---

1️⃣3️⃣ 最终 RESTful API 结构示例

GET     /api/v1/users/
POST    /api/v1/users/
GET     /api/v1/users/<id>/
PATCH   /api/v1/users/<id>/
DELETE  /api/v1/users/<id>/

统一响应格式：

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

---

🎉 你已经掌握 DRF 最完整的 RESTful 实战流程！