DRF快速构建RESTful API指南

在 Django REST Framework (DRF) 中，viewsets.ModelViewSet 是一个预定义的视图集类，它整合了常见的 CRUD（创建、读取、更新、删除）操作的逻辑，允许你通过极少的代码快速实现一个完整的 RESTful API 端点。

核心特点

1. 继承关系
   ModelViewSet 继承了 GenericViewSet 并混入了 5 个常用的动作类（ListModelMixin、RetrieveModelMixin、CreateModelMixin、UpdateModelMixin、DestroyModelMixin），因此自带以下 6 个核心 API 动作：

   • list()：获取资源列表（GET 请求）
   • retrieve()：获取单个资源详情（GET 请求，带 ID）
   • create()：创建新资源（POST 请求）
   • update()：全量更新资源（PUT 请求，带 ID）
   • partial_update()：部分更新资源（PATCH 请求，带 ID）
   • destroy()：删除资源（DELETE 请求，带 ID）

2. 使用场景
   当你需要为一个 Django 模型（Model）提供完整的 CRUD 接口时，ModelViewSet 是最简洁的选择。例如，为 UserInfo 模型提供用户管理接口、为 Organization 模型提供机构管理接口等。

基本用法

步骤 1：定义序列化器（Serializer）

首先需要为模型定义一个序列化器，用于数据的序列化（模型→JSON）和反序列化（JSON→模型）：

# serializers.py
from rest_framework import serializers
from .models import YourModel  # 导入你的模型class YourModelSerializer(serializers.ModelSerializer):class Meta:model = YourModelfields = "__all__"  # 或指定需要的字段，如 ["id", "name", "is_available"]

步骤 2：定义 ViewSet

通过继承 ModelViewSet，并指定 queryset（查询集）和 serializer_class（序列化器），即可快速实现完整的 API 接口：

# views.py
from rest_framework import viewsets
from .models import YourModel  # 导入你的模型
from .serializers import YourModelSerializer  # 导入你的序列化器class YourModelViewSet(viewsets.ModelViewSet):# 指定查询集：获取所有数据（可自定义过滤、排序等）queryset = YourModel.objects.all()# 指定序列化器serializer_class = YourModelSerializer

步骤 3：注册路由

在 urls.py 中通过 DefaultRouter 注册 ViewSet，自动生成对应的 URL 路由：

# urls.py
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import YourModelViewSet# 创建路由器并注册视图集
router = DefaultRouter()
router.register(r'your-models', YourModelViewSet)  # 路由前缀为 your-models# 包含自动生成的路由
urlpatterns = [path('api/', include(router.urls)),  # 最终接口路径为 /api/your-models/
]

自动生成的 API 端点

完成上述配置后，会自动生成以下 6 个 API 端点：

扩展与定制

ModelViewSet 支持灵活定制，例如：

1. 过滤、排序、分页
   通过配置 filter_backends、pagination_class 等属性实现：

   from rest_framework.filters import SearchFilter, OrderingFilter
   from rest_framework.pagination import PageNumberPaginationclass YourModelViewSet(viewsets.ModelViewSet):queryset = YourModel.objects.all()serializer_class = YourModelSerializer# 支持搜索和排序filter_backends = [SearchFilter, OrderingFilter]search_fields = ['name']  # 可搜索的字段ordering_fields = ['created_at']  # 可排序的字段# 分页配置pagination_class = PageNumberPagination
   

2. 自定义权限
   通过 permission_classes 控制接口访问权限：

   from rest_framework.permissions import IsAuthenticated, IsAdminUserclass YourModelViewSet(viewsets.ModelViewSet):# 仅登录用户可访问，管理员可修改permission_classes = [IsAuthenticated]# 其他配置...
   

3. 新增自定义动作
   通过 @action 装饰器添加额外的 API 动作：

   from rest_framework.decorators import action
   from rest_framework.response import Responseclass YourModelViewSet(viewsets.ModelViewSet):# 其他配置...@action(detail=True, methods=['post'])  # detail=True 表示需要 ID 参数def enable(self, request, pk=None):"""自定义动作：启用某个资源"""obj = self.get_object()obj.is_available = 1  # 假设 1 代表启用obj.save()return Response({"status": "enabled"})
   

   会生成新的端点：POST /api/your-models/1/enable/（启用 ID=1 的资源）。

总结

viewsets.ModelViewSet 是 DRF 中高效开发 CRUD 接口的核心工具，它通过整合常用动作，大幅减少重复代码。实际开发中，你可以根据需求在其基础上扩展过滤、权限、自定义动作等功能，快速构建符合业务需求的 RESTful API。