使用DRF快速搭建API接口，Django REST Framework ModelViewSet 用法总结

：本站 2026-03-01 09:10:09 ：4

Django REST Framework ModelViewSet 用法总结

1. ModelViewSet 简介

ModelViewSet是 Django REST Framework (DRF) 中的一个视图集类，它继承自多个 mixin 类（如 CreateModelMixin、RetrieveModelMixin、UpdateModelMixin、DestroyModelMixin、ListModelMixin），提供了完整的 CRUD（创建、读取、更新、删除）操作。使用时，你只需指定 queryset和 serializer_class，即可快速构建 RESTful API。

2. 原生的路由

当使用 DRF 的路由器（如 SimpleRouter或 DefaultRouter）注册 ModelViewSet时，会自动生成以下标准路由：

HTTP 方法	URL 路径	视图集方法	操作描述
GET	/articles/	list	获取文章列表
POST	/articles/	create	创建新文章
GET	/articles/{id}/	retrieve	获取单篇文章详情
PUT	/articles/{id}/	update	全量更新文章
PATCH	/articles/{id}/	partial_update	部分更新文章
DELETE	/articles/{id}/	destroy	删除文章

这些路由基于视图集的默认方法自动映射，无需手动定义。

3. 新建自定义路由

你可以通过 @action装饰器在视图集中添加自定义动作，从而生成额外的路由。@action装饰器允许你定义非标准 CRUD 的端点，例如发布文章、统计数据等。

@action参数：
- detail: 布尔值。如果为 True，路由将包含对象的 ID（如 /articles/{id}/publish/）；如果为 False，路由为列表级别（如 /articles/publish/）。
- methods: 列表，指定允许的 HTTP 方法，如 ['post', 'get']。
- url_path: 自定义 URL 路径后缀，默认为方法名。
- url_name: 路由名称后缀。

自定义路由会自动注册到路由器中，与原生路由一起工作。

4. 以 Article 模型为例的完整示例

4.1 模拟 Article 模型

在 Django 的 models.py中定义一个简单的文章模型：

# models.py
from django.db import models

class Article(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    author = models.CharField(max_length=100)
    is_published = models.BooleanField(default=False)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    def __str__(self):
        return self.title

4.2 创建序列化器

在 DRF 的 serializers.py中定义序列化器：

# serializers.py
from rest_framework import serializers
from .models import Article

class ArticleSerializer(serializers.ModelSerializer):
    class Meta:
        model = Article
        fields = ['id', 'title', 'content', 'author', 'is_published', 'created_at', 'updated_at']
        read_only_fields = ['created_at', 'updated_at']

4.3 定义 ModelViewSet

在 views.py中创建 ArticleViewSet，继承自 ModelViewSet，并添加自定义动作：

# views.py
from rest_framework import viewsets, status
from rest_framework.decorators import action
from rest_framework.resp***e import Resp***e
from .models import Article
from .serializers import ArticleSerializer

class ArticleViewSet(viewsets.ModelViewSet):
    queryset = Article.objects.all().order_by('-created_at')
    serializer_class = ArticleSerializer

    # 自定义动作示例1：发布文章（修改 is_published 为 True）
    @action(detail=True, methods=['post'])
    def publish(self, request, pk=None):
        article = self.get_object()
        article.is_published = True
        article.save()
        return Resp***e({'status': '文章已发布'}, status=status.HTTP_200_OK)

    # 自定义动作示例2：获取已发布文章列表（列表级别路由）
    @action(detail=False, methods=['get'])
    def published(self, request):
        published_articles = Article.objects.filter(is_published=True)
        serializer = self.get_serializer(published_articles, many=True)
        return Resp***e(serializer.data)

4.4 配置路由

在 urls.py中，使用 DRF 的路由器注册 ArticleViewSet：

# urls.py
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from .views import ArticleViewSet

# 创建路由器并注册视图集
router = DefaultRouter()
router.register(r'articles', ArticleViewSet)  # 自动生成标准路由和自定义路由

urlpatterns = [
    path('', include(router.urls)),
]

4.5 生成的路由总览

注册后，路由器将生成以下路由：

原生路由（自动）：
- GET /articles/-> 文章列表
- POST /articles/-> 创建文章
- GET /articles/{id}/-> 文章详情
- PUT /articles/{id}/-> 全量更新文章
- PATCH /articles/{id}/-> 部分更新文章
- DELETE /articles/{id}/-> 删除文章
自定义路由（通过 @action添加）：
- POST /articles/{id}/publish/-> 发布单篇文章
- GET /articles/published/-> 获取已发布文章列表

4.6 使用示例

获取所有文章：GET http://yourdomain/articles/
创建文章：POST http://yourdomain/articles/附带 JSON 数据，如 {"title": "示例", "content": "内容", "author": "作者"}
发布文章：POST http://yourdomain/articles/1/publish/（假设文章 ID 为 1）
获取已发布文章：GET http://yourdomain/articles/published/

总结

ModelViewSet 提供了开箱即用的 CRUD 操作，适合快速开发标准 API。
原生路由 通过路由器自动映射到标准 HTTP 方法。
自定义路由 使用 @action装饰器轻松添加，支持列表级或详情级端点。
在实际项目中，你可以根据业务需求扩展自定义动作，例如添加权限、过滤、分页等（在视图集中设置 permission_classes、filter_backends等）。

这个示例展示了从模型定义到 API 路由的完整流程，你可以直接复制代码并调整以适应实际项目。

本文编辑：admin

： ModelViewSet 用法，DRF

上一篇：CentOS 7怎么安装低版本Chrome谷歌浏览器以及Chrome驱动

下一篇：sitemap无静态时怎么防止恶意访问，sitemap防御方法

更多文章：

使用DRF快速搭建API接口，Django REST Framework ModelViewSet 用法总结

Django REST Framework ModelViewSet 用法总结1. ModelViewSet 简介ModelViewSet是 Django REST Framework (DRF) 中的一个视图集类，它继承自多个 mixin

2026年3月1日 09:10

django 使用selenium注意事项：Service /usr/local/bin/chromedriver unexpectedly exited. Status code was: 1解决办法

在实操当中有一项目需要使用selenium进行浏览器模拟，但是测试了很多都不行，最后通过了，总一下系统级安装chrome浏览器及驱动这些都不细说了测试项目运行用户：check_user.py建立一个API，使用check_user获取用户，

2026年1月6日 00:58

Django移除模型后的content_type操作

旧应用（apps.content.download）的模型虽然已删除，但其在 django_content_type表中的记录仍然存在，与新应用（user_space.apps.download）的记录产生了混淆。您需要清理这些过时的记录。

2025年12月22日 11:36

django.utils中都有哪些功能？django.utils工具都详情的举例说明

Django 的 django.utils模块是一个“百宝箱”，它提供了大量用于处理日常底层任务的实用工具。下面这个表格汇总了其中一些最常用的工具模块及其核心功能，可以帮助你快速了解其概貌。模块/工具类别主要功能/工具举例简要说明djang

2025年11月27日 22:32

Django 的基于类的视图总结，Django CBV类的详细使用方法整理

Django 的基于类的视图（Class-based Views，简称 CBV）通过类的形式封装了常见的 Web 开发模式，提供了清晰的结构和强大的可复用性。下面这个表格汇总了这些核心基类的主要作用和典型应用场景，可以帮助你快速了解其用途。

2025年11月17日 08:52

Django transaction.atomic() 的具体作用和用法？

transaction.atomic()是 Django 中用于管理数据库事务的核心工具，它能确保一系列数据库操作作为一个不可分割的“原子”单元来执行。下面这个表格能帮你快速抓住要点。特性说明核心目标保证一系列数据库操作的原子性(Atomi

2025年10月31日 23:35

django 批量操作的方法有哪些？如何高效的批量更新django内容

Django 提供了多种批量操作方法，能显著提升数据库操作的效率，特别是在处理大量数据时。下面为你梳理这些方法，并说明其适用场景和注意事项。下表总结了主要的批量操作方法及其核心用途：方法类别核心方法主要用途关键特点📦 批量创建bulk_cr

2025年10月31日 23:30

django的分页器以及django分页器中有哪些变量

Django 的分页器（Paginator）是一个用于管理数据分页的强大工具，它能将大量数据分割成多个页面，并生成相应的导航链接。下面这个表格汇总了 Django 分页器中的核心类及其主要属性和方法，方便你快速了解其构成。组件/类别名称说明

2025年10月20日 10:16

Django get_FOO_display() 方法,Django模型中原生方法总结

在Django中有一种方法被称为 get_FOO_display() 方法，对模型中定义了 choices选项的字段名的灵活使用方法。在Django中，choices参数用于为模型字段提供一组固定的可选值，它在数据库层面存储简洁的值

2025年10月13日 20:56

django字段查找（Field Lookups）总结，django查询中指定特定的条件或对字段的处理方法

在Django ORM中，双下划线 __后跟的关键词（如 __date、__icontains）被称为字段查找（Field Lookups）。它们用于在查询中指定特定的条件或对字段进行某种处理。 📊

2025年10月8日 23:07

开启智能数字体验 Djacore CMS 驱动未来

使用DRF快速搭建API接口，Django REST Framework ModelViewSet 用法总结

Django REST Framework ModelViewSet 用法总结

1. ModelViewSet 简介

2. 原生的路由

3. 新建自定义路由

4. 以 Article 模型为例的完整示例

4.1 模拟 Article 模型

4.2 创建序列化器

4.3 定义 ModelViewSet

4.4 配置路由

4.5 生成的路由总览

4.6 使用示例

总结

更多文章：

开启智能数字体验
Djacore CMS 驱动未来