Django-RESTful Api之基于类的视图

这篇讲什么

  • DRF 的类视图分三层:APIView、GenericAPIView + Mixin、以及开箱即用的通用视图。
  • 这篇把三层各写一遍能跑的代码,比出什么时候该往下沉一层、什么时候该停下来。新手卡点清单来自本机 Django 5.2.19 + DRF 3.18.3 的真实报错。

为什么用类视图

  • 函数式视图里 if request.method == "GET" 一路分支下去会越来越长;类视图按 HTTP 方法拆成独立方法,读起来直接。
  • 代码复用方式变了:get_object()、get_serializer() 这类小方法可以被继承、覆写。
  • DRF 把常用 CRUD 做成了 Mixin 和通用视图,实测能少写很多代码(详见下面三层结构)。
  • 本篇实测环境:Django 5.2.19 + DRF 3.18.3。

第一层:APIView

school/views.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
from django.http import Http404
from rest_framework.views import APIView

from school.models import Student
from school.serializers import StudentSerializer


class StudentsList(APIView):
def get(self, request, format=None):
return Response(StudentSerializer(Student.objects.all(), many=True).data)

def post(self, request, format=None):
serializer = StudentSerializer(data=request.data)
if serializer.is_valid():
serializer.save()
return Response(serializer.data, status=status.HTTP_201_CREATED)
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)


class StudentDetail(APIView):
def get_object(self, pk):
try:
return Student.objects.get(pk=pk)
except Student.DoesNotExist:
raise Http404

def get(self, request, pk, format=None):
return Response(StudentSerializer(self.get_object(pk)).data)
school/urls.py
1
2
3
4
urlpatterns = [
path("cbv/students/", views.StudentsList.as_view()),
path("cbv/students/<int:pk>", views.StudentDetail.as_view()),
]
  • 实测 GET /api/cbv/students/ 返回 200、9 条数据;Http404 会被协商成 404 响应。
  • 只写 get 不写 post 时,POST 自动 405(实测 Allow: GET, OPTIONS),不用自己判断方法。
  • 类视图的方法签名里 format=None 要留着:一旦路由用了 format_suffix_patterns,少了它实测就 TypeError(见《Django-RESTful-Api之请求与响应》)。

第二层:GenericAPIView + Mixins

  • DRF 把「查列表、建、查单条、改、删」做成五个 Mixin:ListModelMixin、CreateModelMixin、RetrieveModelMixin、UpdateModelMixin、DestroyModelMixin。

  • 继承结构实测得很清楚:

    1
    2
    GenericAPIView 的 MRO: ['GenericAPIView', 'APIView', 'View', 'object']
    Mixin 是否继承 APIView: False
    • 也就是说五个 Mixin 本身不继承 APIView,只有 GenericAPIView 继承;所以老笔记那句「只有一个父类能继承自 APIView」是对的,但原因不是约定,而是 Mixin 压根不带 dispatch。
  • 手写 Mixin 组合:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    class MixinsList(mixins.ListModelMixin, mixins.CreateModelMixin,
    generics.GenericAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentSerializer

    def get(self, request, *args, **kwargs):
    return self.list(request, *args, **kwargs)

    def post(self, request, *args, **kwargs):
    return self.create(request, *args, **kwargs)
    • 实测 GET /api/mixins/students/ 200;PATCH /api/mixins/students/ 是 405——因为这个类只挂了 list / create,没挂 update,方法名也没写。
    • 每个 Mixin 提供的动作方法名是固定的:list()、create()、retrieve()、update()、partial_update()、destroy(),覆写它们就能改行为(比如 perform_create 里塞 owner)。

第三层:通用视图(generics)

  • 实测 rest_framework.generics 里现成的 *APIView 类有 10 个:

    1
    2
    3
    CreateAPIView, DestroyAPIView, GenericAPIView, ListAPIView, ListCreateAPIView,
    RetrieveAPIView, RetrieveDestroyAPIView, RetrieveUpdateAPIView,
    RetrieveUpdateDestroyAPIView, UpdateAPIView
  • 于是最常用的两种写法变成四行:

    1
    2
    3
    4
    5
    6
    7
    8
    class GenericStudents(generics.ListCreateAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentSerializer


    class GenericStudentDetail(generics.RetrieveUpdateDestroyAPIView):
    queryset = Student.objects.all()
    serializer_class = StudentSerializer
    urls.py
    1
    2
    3
    4
    urlpatterns = [
    path("generic/students/", views.GenericStudents.as_view()),
    path("generic/students/<int:pk>", views.GenericStudentDetail.as_view()),
    ]
  • 实测三种写法返回的数据完全一致:

    1
    2
    3
    4
    5
    /api/cbv/students/     GET -> 200 | 条数 9
    /api/mixins/students/ GET -> 200 | 条数 9
    /api/generic/students/ GET -> 200 | 条数 9
    generics POST: 201 | {'id': 13, 'name': '泛型', 'sex': False, 'age': 18, 'content': '', 'grade': 1, 'owner': None}
    generics PATCH: 200 | age: 33
    • 注意 RetrieveUpdateDestroyAPIView 自带 PATCH(实测 200),而 ListCreateAPIView 没有 PATCH(实测 405)。
  • 常用的可覆写钩子:

    钩子 用途
    get_queryset() 按登录用户过滤数据
    get_serializer_class() 列表用轻量序列化器、详情用完整序列化器
    get_object() / lookup_field / lookup_url_kwarg 改主键查找规则(比如用 slug)
    perform_create() / perform_update() / perform_destroy() 保存前后加动作
    filter_backends / pagination_class / permission_classes / authentication_classes 配置挂载点
    1
    2
    3
    4
    5
    6
    7
    8
    class MyStudents(generics.ListCreateAPIView):
    serializer_class = StudentSerializer

    def get_queryset(self):
    return Student.objects.filter(owner=self.request.user)

    def perform_create(self, serializer):
    serializer.save(owner=self.request.user)

三层怎么选

  • 需要完全自定义逻辑、或者一个视图里混着好几张表 → APIView。
  • 标准 CRUD、但想在某一步插自己的代码 → GenericAPIView + 需要的 Mixin。
  • 就是标准 CRUD → generics.*APIView,四行搞定。
  • 同一资源既要列表又要详情、还想要自动路由 → 用 ViewSet(下一篇)。

新手卡点清单

  • 都是实测踩过的:

    卡点 症状(实测原文) 正确做法
    只写 get 忘了 post 405,Allow: GET, OPTIONS 需要哪个方法就写哪个
    以为 Mixin 能单独当视图用 Mixin 不继承 APIView,路由挂不上 必须搭配 GenericAPIView
    给 ListCreateAPIView 发 PATCH 405 用 RetrieveUpdateDestroyAPIView 或加 UpdateModelMixin
    忘了写 serializer_class 无法 guess serializer 的告警(实测 spectacular 也报 unable to guess serializer) 显式声明 serializer_class
    路由里 as_view() 写成类名 TypeError(Django 要求可调用对象) StudentsList.as_view()
    用了 format_suffix_patterns 却没 format=None TypeError: got an unexpected keyword argument 'format' 方法签名加 format=None
    在 get_queryset 里用 self.kwargs 查用户 未登录时 KeyError / 权限绕过 用 self.request.user 并配权限类

参考

本文结束 感谢您的阅读
正在加载今日诗词....