Django 前后端分离开发深度指南
引言 (Introduction)
前后端分离的架构模式已成为现代 Web 应用开发的主流趋势。它将用户界面（前端）的逻辑与业务逻辑和数据处理（后端）分离开来，带来了诸多优势，如更清晰的职责划分、独立的技术选型、并行开发、更好的可扩展性和可维护性。Django，作为一个功能强大且成熟的 Python Web 框架，在构建稳健的后端 API 方面表现出色，尤其是与 Django REST framework (DRF) 结合使用时。
什么是前后端分离 (What is Frontend-Backend Separation?)
前后端分离是一种软件架构模式，其中应用程序被划分为两个主要部分：
前端 (Frontend)：通常运行在用户的浏览器或移动设备上，负责用户界面的展示、用户交互的处理以及与后端 API 的通信。常用的前端技术栈包括 React, Vue.js, Angular, Swift, Kotlin 等。
后端 (Backend)：运行在服务器上，负责处理业务逻辑、数据存储与检索、API 接口的提供、用户认证与授权等。
在这种模式下，前端和后端通过定义好的 API (通常是 RESTful API 或 GraphQL API) 进行通信。后端不再负责渲染 HTML 页面给浏览器（传统 MVC 模式中的 V 层），而是提供结构化的数据（如 JSON 或 XML）给前端，前端再根据这些数据动态构建和渲染用户界面。
前后端分离的优势：
职责分离 (Separation of Concerns)：前端专注于用户体验和界面展示，后端专注于业务逻辑和数据处理。这种分离使得团队成员可以专注于各自擅长的领域。
独立开发与部署 (Independent Development and Deployment)：前端和后端可以独立开发、测试和部署，互不干扰，加快了开发迭代速度。
技术选型灵活 (Flexible Technology Choices)：前端和后端可以根据各自的需求选择最合适的技术栈，例如前端可以使用 React/Vue，后端可以使用 Python/Django、Java/Spring、Node.js/Express 等。
更好的可扩展性 (Improved Scalability)：前端和后端可以根据各自的负载情况独立进行扩展。例如，如果 API 请求量大，可以单独增加后端服务器数量。
支持多端应用 (Support for Multiple Clients)：一套后端 API 可以同时服务于 Web 应用、移动 App (iOS, Android)、桌面应用，甚至第三方应用，提高了代码复用率。
提升用户体验 (Enhanced User Experience)：前端可以通过异步加载数据、局部刷新等技术，提供更流畅、更快速的用户体验，接近原生应用的感受。
为什么选择 Django 进行前后端分离 (Why Choose Django for Frontend-Backend Separation?)
Django 是一个高级 Python Web 框架，鼓励快速开发和简洁、实用的设计。它遵循 “DRY” (Don’t Repeat Yourself) 原则，并提供了许多开箱即用的功能，使其成为构建后端 API 的理想选择：
成熟稳定 (Mature and Stable)：Django 拥有悠久的历史和庞大的社区，经过了大量项目的检验，非常稳定可靠。
强大的 ORM (Object-Relational Mapper)：Django 的 ORM 使得与数据库的交互变得简单直观，开发者可以用 Python 代码操作数据库，而无需编写复杂的 SQL 语句。它支持多种数据库后端。
内置管理后台 (Built-in Admin Interface)：Django 自动生成的 Admin 后台功能强大，可以方便地管理应用数据，即使在前后端分离的场景下，Admin 后台依然可以用于内部数据管理和调试。
安全性 (Security)：Django 内置了许多安全防护机制，如防止常见的 Web 攻击 (XSS, CSRF, SQL 注入等)。虽然在 API 场景下某些机制（如 CSRF）可能需要调整，但其安全基础依然稳固。
可扩展性 (Scalability)：Django 本身设计良好，结合缓存、数据库优化等策略，可以构建高并发、可扩展的应用。
丰富的第三方库 (Rich Third-party Libraries)：Python 和 Django 拥有庞大的生态系统，有大量的第三方库可以用于各种功能，如认证、支付、任务队列等。
Django REST framework (DRF)：这是 Django 最重要的加分项。DRF 是一个强大且灵活的工具包，专门用于构建 Web API。它简化了 API 开发的许多方面，如序列化、认证、权限、路由、视图等。
Django REST framework (DRF) 简介 (Introduction to Django REST framework)
Django REST framework (DRF) 是构建 Web API 的黄金标准，它与 Django 无缝集成，并提供了构建 RESTful API 所需的一切。DRF 的核心理念是：
提供一个简单、灵活且功能强大的方式来序列化和反序列化数据。
提供一套通用的视图类和混合类，用于处理常见的 API 逻辑。
提供灵活的认证和权限系统。
支持 API 版本控制、内容协商、分页、过滤等高级功能。
自动生成可浏览的 API 文档。
使用 DRF，开发者可以快速高效地构建出符合 RESTful 设计原则的 API 接口，极大地简化了前后端分离的开发过程。
本指南的目标与受众 (Goals and Target Audience of This Guide)
本指南旨在深入探讨使用 Django 和 DRF 进行前后端分离开发的方方面面，从基础概念到高级应用，再到部署运维和真实案例分析。目标是：
深度解析核心机制：不仅告诉读者“怎么做”，更要解释“为什么这么做”，深入理解其内部工作原理。
提供详尽的代码示例：每个知识点都将辅以可运行的代码示例，并对关键代码行进行中文解释。
覆盖广泛的知识领域：包括认证授权、数据校验、性能优化、API 设计、测试、部署等全链路知识。
结合真实场景：通过案例分析，展示如何在复杂的实际项目中应用所学知识。
本指南的受众包括：
希望从传统 Django 开发转向前后端分离的 Django 开发者。
有一定 Python 和 Web 开发基础，希望学习如何使用 Django 构建强大 API 的开发者。
希望深入理解 DRF 内部机制和高级特性的中高级开发者。
对 API 设计、安全、性能和部署有要求的架构师和技术负责人。
我们将力求内容的详尽和深入，确保读者能够通过本指南全面掌握 Django 前后端分离开发的精髓。
Django 基础回顾 (Django Fundamentals Review – Focused on API Development)
在深入学习 Django REST framework 之前，回顾一些 Django 的核心概念至关重要。虽然我们的目标是前后端分离，后端主要提供 API，但这些基础知识是构建健壮 API 的基石。我们将侧重于那些与 API 开发紧密相关的部分。
模型 (Models) – 数据层核心
Django 的模型是数据的唯一、最终的来源。每个模型都映射到数据库中的一张表，模型类的每个属性代表表中的一个字段。
定义模型 (Defining Models)
模型定义在应用的 models.py 文件中，继承自 django.db.models.Model。
# myapp/models.py
from django.db import models
from django.utils import timezone
class Category(models.Model):
name = models.CharField(max_length=100, unique=True) # 定义分类名称，字符型，最大长度100，唯一
description = models.TextField(blank=True, null=True) # 定义分类描述，文本型，可为空
def __str__(self):
return self.name # 定义模型的字符串表示，方便在Admin后台或调试时查看
class Meta:
verbose_name = "产品分类" # 定义模型在Admin后台的单数可读名称
verbose_name_plural = "产品分类" # 定义模型在Admin后台的复数可读名称
class Product(models.Model):
name = models.CharField(max_length=200) # 定义产品名称，字符型，最大长度200
description = models.TextField() # 定义产品描述，文本型
price = models.DecimalField(max_digits=10, decimal_places=2) # 定义价格，十进制数，总共10位，小数点后2位
stock = models.PositiveIntegerField(default=0) # 定义库存，正整型，默认为0
available = models.BooleanField(default=True) # 定义是否上架，布尔型，默认为True
created_at = models.DateTimeField(auto_now_add=True) # 定义创建时间，日期时间型，在对象首次创建时自动设置为当前时间
updated_at = models.DateTimeField(auto_now=True) # 定义更新时间，日期时间型，在对象每次保存时自动设置为当前时间
category = models.ForeignKey(Category, related_name='products', on_delete=models.CASCADE) # 定义外键关联到Category模型，CASCADE表示级联删除
image = models.ImageField(upload_to='products/%Y/%m/%d/', blank=True, null=True) # 定义图片字段，上传路径，可为空
def __str__(self):
return self.name # 定义模型的字符串表示
class Meta:
ordering = ['-created_at'] # 定义默认排序方式，按创建时间降序
verbose_name = "产品信息"
verbose_name_plural = "产品信息"
indexes = [
models.Index(fields=['name']), # 为name字段创建索引，提升查询效率
]
代码解释:
from django.db import models: 导入 Django 模型模块。
class Category(models.Model):: 定义一个名为 Category 的模型，它继承自 models.Model。
name = models.CharField(...): 定义一个字符型字段 name，用于存储分类名称。
max_length=100: 指定最大长度为100个字符。
unique=True: 确保分类名称是唯一的。
description = models.TextField(...): 定义一个文本型字段 description，用于存储分类的详细描述。
blank=True: 表示在表单验证时该字段可以为空。
null=True: 表示在数据库中该字段可以为 NULL。
def __str__(self):: 定义当模型实例被转换为字符串时的行为，通常返回一个具有代表性的字段值。
class Meta:: 用于定义模型的元数据。
verbose_name: 模型在 Admin 界面中显示的单数名称。
verbose_name_plural: 模型在 Admin 界面中显示的复数名称。
class Product(models.Model):: 定义一个名为 Product 的模型。
price = models.DecimalField(...): 定义一个十进制数字段 price。
max_digits=10: 最大位数（不包括小数点）。
decimal_places=2: 小数点后的位数。
stock = models.PositiveIntegerField(...): 定义一个正整数字段 stock。
default=0: 设置默认值为0。
available = models.BooleanField(...): 定义一个布尔型字段 available。
default=True: 默认值为 True。
created_at = models.DateTimeField(auto_now_add=True): 定义一个日期时间字段，当记录第一次创建时，自动设置为当前时间。
updated_at = models.DateTimeField(auto_now=True): 定义一个日期时间字段，每当记录保存（更新）时，自动设置为当前时间。
category = models.ForeignKey(Category, ...): 定义一个外键字段，关联到 Category 模型。
related_name='products': 允许从 Category 对象反向查询其所有关联的 Product 对象，例如 category_instance.products.all()。
on_delete=models.CASCADE: 指定当关联的 Category 对象被删除时，所有相关的 Product 对象也将被级联删除。
image = models.ImageField(...): 定义一个图片字段。
upload_to='products/%Y/%m/%d/': 指定图片上传的路径，%Y, %m, %d 会被替换为当前的年、月、日。
ordering = ['-created_at']: 指定查询该模型数据时的默认排序规则，- 表示降序。
indexes = [models.Index(fields=['name'])]: 为 name 字段创建一个数据库索引，可以加快基于 name 字段的查询速度。
字段类型详解 (Detailed Field Types)
Django 提供了丰富的字段类型来满足各种数据存储需求。除了上述示例中用到的，还有：
AutoField: 自动递增的整型字段，通常用作主键。如果模型没有显式定义主键，Django 会自动添加一个名为 id 的 AutoField。
BigAutoField: 类似 AutoField，但存储 64 位整数。
BinaryField: 存储原始二进制数据。
DateField: 日期字段。常用参数：
auto_now: 每次保存对象时自动设置为当前日期。
auto_now_add: 对象首次创建时自动设置为当前日期。
DateTimeField: 日期时间字段，参数同 DateField。
DurationField: 用于存储时间段，Python 中用 timedelta 表示。
EmailField: 字符串字段，使用 EmailValidator 验证其格式。
FileField: 文件上传字段。
upload_to: 文件上传的路径。
FilePathField: 字段值限定为文件系统上特定目录中的文件名。
FloatField: 浮点数字段。
GenericIPAddressField: IPv4 或 IPv6 地址字符串。
IntegerField: 整数字段。
JSONField: (Django 3.1+ for most databases) 存储 JSON 编码的数据。
NullBooleanField: (Deprecated in Django 4.0, use BooleanField(null=True)) 可以接受 True, False, None (SQL NULL)。
PositiveSmallIntegerField: 类似 PositiveIntegerField，但范围更小。
SlugField: 通常用于存储 URL slug，即包含字母、数字、下划线或连字符的短标签。通常基于某个其他值预填充。
db_index=True 通常是好的实践。
SmallAutoField: 类似 AutoField，但存储范围较小的整数。
SmallIntegerField: 类似 IntegerField，但范围更小。
TimeField: 时间字段。参数同 DateField。
URLField: 字符串字段，使用 URLValidator 验证其格式。
UUIDField: 存储通用唯一标识符 (UUID)。
通用字段选项 (Common Field Options):
null: (布尔型) 如果为 True，Django 将在数据库中将空值存储为 NULL。默认为 False。对于字符串类型字段，如 CharField 和 TextField，避免使用 null=True，因为空字符串 '' 通常是表示空数据的更 Pythonic 的方式。
blank: (布尔型) 如果为 True，该字段在表单验证时允许为空。默认为 False。这与数据库层面的 null 不同。
choices: 一个可迭代对象 (例如列表或元组)，由二元组构成，用作此字段的可选值。如果给出，Django Admin 会使用选择框代替标准的文本字段。
# myapp/models.py
# ...
class Order(models.Model):
STATUS_PENDING = 'P'
STATUS_COMPLETED = 'C'
STATUS_CANCELLED = 'X'
STATUS_CHOICES = [
(STATUS_PENDING, '待处理'), # (数据库存储值, 人类可读名称)
(STATUS_COMPLETED, '已完成'),
(STATUS_CANCELLED, '已取消'),
]
status = models.CharField(
max_length=1,
choices=STATUS_CHOICES,
default=STATUS_PENDING,
) # 定义订单状态，使用choices提供选项
# ...
default: 字段的默认值。可以是一个值或一个可调用对象。
editable: (布尔型) 如果为 False，该字段不会显示在 Admin 后台或任何其他 ModelForm 中。默认为 True。
error_messages: 覆盖字段引发的默认错误消息。
help_text: 在 Admin 表单部件旁边显示的额外帮助文本。
primary_key: (布尔型) 如果为 True，则此字段是模型的主键。
unique: (布尔型) 如果为 True，则此字段在整个表中必须是唯一的。
unique_for_date, unique_for_month, unique_for_year: 确保字段值对于指定的日期字段是唯一的。
verbose_name: 字段的人类可读名称。如果未指定，Django 会自动从字段的属性名创建它。
validators: 一个包含验证函数的列表，用于对字段值进行额外验证。
模型关系 (Model Relationships)
Django 支持三种常见的数据库关系类型：一对一 (OneToOne)，一对多 (ForeignKey)，多对多 (ManyToMany)。
ForeignKey (一对多):
这是最常用的关系类型。例如，一个产品属于一个分类，但一个分类可以有多个产品。我们在 Product 模型中使用了 ForeignKey 指向 Category。
# myapp/models.py
# (已在上面 Product 模型中展示)
# category = models.ForeignKey(Category, related_name='products', on_delete=models.CASCADE)
# on_delete 选项详解:
# models.CASCADE: 级联删除。删除主对象时，也删除所有引用它的从对象。 (例如，删除分类，该分类下的所有产品也删除)
# models.PROTECT: 保护模式。如果从对象存在，则阻止删除主对象，并引发 ProtectedError 异常。
# models.SET_NULL: 设置为空。删除主对象时，将从对象中的外键字段设置为 NULL。前提是该外键字段必须允许 null=True。
# models.SET_DEFAULT: 设置为默认值。删除主对象时，将从对象中的外键字段设置为其默认值。前提是该外键字段必须有 default 值。
# models.SET(value_or_callable): 设置为指定值或可调用对象的返回值。
# models.DO_NOTHING: 不做任何操作。这通常会导致数据库层面的完整性错误，除非数据库本身有相应的约束。
反向访问：从 Category 实例访问其所有产品：category_instance.products.all() (这里的 products 来自 related_name 参数)。如果未设置 related_name，则默认为 modelname_set (例如 product_set)。
ManyToManyField (多对多):
例如，一个产品可以有多个标签，一个标签也可以应用于多个产品。
# myapp/models.py
# ...
class Tag(models.Model):
name = models.CharField(max_length=50, unique=True) # 定义标签名称
def __str__(self):
return self.name
class Product(models.Model):
# ... (其他字段) ...
tags = models.ManyToManyField(Tag, related_name='products', blank=True) # 定义多对多关系到Tag模型，blank=True表示产品可以没有标签
# ...
Django 会自动创建一个中间表来管理这种关系。
访问关系：
product_instance.tags.all(): 获取一个产品的所有标签。
tag_instance.products.all(): 获取一个标签关联的所有产品。
product_instance.tags.add(tag_instance): 为产品添加标签。
product_instance.tags.remove(tag_instance): 移除产品的标签。
product_instance.tags.clear(): 清除产品的所有标签。
product_instance.tags.set([tag1, tag2]): 设置产品的标签集合。
使用 through 指定中间表:
如果需要在中间表上存储额外的数据 (例如，一个学生选修多门课程，中间表可以存储选课的成绩)，可以自定义中间表：
# myapp/models.py
# ...
class Student(models.Model):
name = models.CharField(max_length=100)
courses = models.ManyToManyField('Course', through='Enrollment', related_name='students') # 指定通过Enrollment模型建立多对多关系
def __str__(self):
return self.name
class Course(models.Model):
title = models.CharField(max_length=150)
def __str__(self):
return self.title
class Enrollment(models.Model): # 自定义的中间表
student = models.ForeignKey(Student, on_delete=models.CASCADE) # 外键关联到Student
course = models.ForeignKey(Course, on_delete=models.CASCADE) # 外键关联到Course
enrollment_date = models.DateField(auto_now_add=True) # 选课日期，额外信息
grade = models.CharField(max_length=2, blank=True, null=True) # 成绩，额外信息
class Meta:
unique_together = [['student', 'course']] # 确保学生和课程的组合是唯一的
OneToOneField (一对一):
例如，一个用户可能有一个用户资料 (Profile)，每个用户只有一个 Profile，每个 Profile 也只对应一个用户。
# myapp/models.py
from django.contrib.auth.models import User # 导入Django内置的User模型
class UserProfile(models.Model):
user = models.OneToOneField(User, on_delete=models.CASCADE, primary_key=True, related_name='profile') # 定义一对一关系到User模型，并将此字段设为主键
bio = models.TextField(blank=True) # 个人简介
location = models.CharField(max_length=100, blank=True) # 所在地
birth_date = models.DateField(null=True, blank=True) # 生日
def __str__(self):
return self.user.username # 返回关联用户的用户名
OneToOneField 实际上是 ForeignKey 的一个特例，并添加了 unique=True 的约束。
访问关系：
user_instance.profile: 从用户实例访问其 Profile。
profile_instance.user: 从 Profile 实例访问其用户。
通常，OneToOneField 会放在“从属”模型中，例如 UserProfile 从属于 User。
Meta 选项 (Meta Options)
模型内部的 class Meta 用于提供模型的元数据。一些常用的选项：
abstract: (布尔型) 如果为 True，则该模型是一个抽象基类，不会在数据库中创建表。它的字段会被子类继承。
app_label: 如果模型在 INSTALLED_APPS 之外定义，必须声明它属于哪个应用。
db_table: 指定在数据库中使用的表名。默认是 applabel_modelname。
# myapp/models.py
class MyCustomTable(models.Model):
# ... fields ...
class Meta:
db_table = 'custom_table_name' # 指定数据库表名为 'custom_table_name'
get_latest_by: 指定一个 DateField 或 DateTimeField 字段的名称。模型管理器的 latest() 和 earliest() 方法将默认使用此字段。
managed: (布尔型) 默认为 True，表示 Django 会管理该表的创建、修改和删除 (通过 migrate 命令)。如果为 False，则不会对该表执行数据库操作，这对于使用未受 Django 管理的现有数据库表或视图很有用。
order_with_respect_to: 将此模型标记为相对于指定字段“可排序”。通常用于 ForeignKey，表示“子”对象相对于“父”对象是有序的。
ordering: 字符串列表或元组，指定模型的默认排序方式。例如 ordering = ['-created_at', 'name'] (按创建时间降序，再按名称升序)。
permissions: 额外的权限元组，用于在模型创建时添加到权限表中。
default_permissions: (默认为 ('add', 'change', 'delete', 'view'))。可以自定义模型默认创建的权限。
proxy: (布尔型) 如果为 True，则继承自另一个模型的模型将被视为代理模型。代理模型不会创建新的数据库表，它操作父模型的数据，但可以有不同的 Python 行为 (如不同的管理器、Meta 选项或方法)。
# myapp/models.py
class Person(models.Model):
first_name = models.CharField(max_length=30)
last_name = models.CharField(max_length=30)
def say_hi(self):
return "Hi"
class MyPerson(Person): # MyPerson 是 Person 的代理模型
class Meta:
proxy = True # 声明为代理模型
ordering = ['last_name'] # 可以有不同的默认排序
def do_something_else(self): # 可以有额外的方法
return "Something else"
select_on_save: (布尔型) 决定 Django ORM 在保存具有 AutoField (或 BigAutoField 等) 的新对象后是否使用 SELECT 语句来检索数据库分配的 ID。对于某些数据库后端（如 PostgreSQL），如果 pk 是 AutoField，则默认为 False（使用 RETURNING 子句）。对于其他后端，默认为 True。
unique_together: 元组的元组，每个内部元组中的字段组合在数据库中必须是唯一的。例如 unique_together = (('field1', 'field2'),)。在 Django 3.0+ 中，更推荐使用 Meta.constraints 中的 UniqueConstraint。
index_together: 类似 unique_together，但创建的是非唯一索引。在 Django 3.0+ 中，更推荐使用 Meta.indexes 中的 Index。
verbose_name: 模型的人类可读单数名称。
verbose_name_plural: 模型的人类可读复数名称。
constraints: (Django 2.2+) 一个 Constraint 对象的列表，用于定义数据库约束。
# myapp/models.py
from django.db.models import UniqueConstraint, CheckConstraint, Q
class ProductReview(models.Model):
product = models.ForeignKey(Product, on_delete=models.CASCADE)
user = models.ForeignKey(User, on_delete=models.CASCADE)
rating = models.IntegerField()
review_text = models.TextField()
class Meta:
constraints = [
UniqueConstraint(fields=['product', 'user'], name='unique_product_user_review'), # 确保一个用户对一个产品只能评价一次
CheckConstraint(check=Q(rating__gte=1) & Q(rating__lte=5), name='check_rating_range') # 确保评分在1到5之间
]
indexes: (Django 2.2+) 一个 Index 对象的列表，用于在模型上创建数据库索引。
# myapp/models.py
from django.db.models import Index
class LogEntry(models.Model):
timestamp = models.DateTimeField()
message = models.TextField()
level = models.CharField(max_length=10)
class Meta:
indexes = [
Index(fields=['timestamp', 'level'], name='log_timestamp_level_idx'), # 为 timestamp 和 level 字段创建复合索引
Index(fields=['level'], name='log_level_idx'), # 为 level 字段创建索引
]
模型管理器 (Model Managers)
每个 Django 模型至少有一个管理器 (Manager)。默认情况下，它名为 objects (YourModel.objects)。管理器是模型进行数据库查询操作的接口。
默认管理器:
Product.objects.all(): 获取所有产品。
Product.objects.filter(available=True): 获取所有上架的产品。
Product.objects.get(id=1): 获取 ID 为 1 的产品。
自定义管理器:
可以创建自定义管理器来添加额外的模型级别的方法，或者修改管理器返回的初始查询集 (QuerySet)。
# myapp/models.py
# ... (Product 和 Category 模型定义) ...
class AvailableProductManager(models.Manager): # 自定义一个管理器
def get_queryset(self):
# 重写 get_queryset 方法，使其默认只返回上架 (available=True) 的产品
return super().get_queryset().filter(available=True)
class Product(models.Model):
# ... (字段定义) ...
name = models.CharField(max_length=200)
description = models.TextField()
price = models.DecimalField(max_digits=10, decimal_places=2)
stock = models.PositiveIntegerField(default=0)
available = models.BooleanField(default=True)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
category = models.ForeignKey(Category, related_name='products', on_delete=models.CASCADE)
image = models.ImageField(upload_to='products/%Y/%m/%d/', blank=True, null=True)
objects = models.Manager() # 默认的管理器，可以访问所有产品
available_products = AvailableProductManager() # 自定义的管理器，只访问上架的产品
def __str__(self):
return self.name
class Meta:
ordering = ['-created_at']
verbose_name = "产品信息"
verbose_name_plural = "产品信息"
# 使用示例:
# all_products = Product.objects.all() # 获取所有产品，包括未上架的
# only_available = Product.available_products.all() # 只获取上架的产品
为管理器添加自定义方法:
# myapp/managers.py (可以将管理器代码放到单独的文件)
from django.db import models
from django.db.models import Count
class CategoryManager(models.Manager):
def with_product_counts(self):
# 返回一个查询集，其中每个分类都注解了其产品数量
return self.annotate(num_products=Count('products'))
# myapp/models.py
# from .managers import CategoryManager # 如果管理器在单独文件
class Category(models.Model):
name = models.CharField(max_length=100, unique=True)
description = models.TextField(blank=True, null=True)
objects = CategoryManager() # 使用自定义的管理器
def __str__(self):
return self.name
class Meta:
verbose_name = "产品分类"
verbose_name_plural = "产品分类"
# 使用示例:
# categories_with_counts = Category.objects.with_product_counts()
# for category in categories_with_counts:
# print(f"{category.name}: {category.num_products} products")
在 DRF 中，视图（尤其是通用视图和视图集）通常会使用模型的默认管理器。如果需要特定的查询逻辑，可以通过重写视图的 get_queryset() 方法或在序列化器中进行处理，但自定义管理器也是一种封装常用查询的有效方式。
数据库迁移 (Database Migrations)
当模型发生更改 (例如添加字段、删除模型、更改字段类型) 时，需要将这些更改应用到数据库模式。Django 的迁移系统用于处理这个问题。
核心命令：
python manage.py makemigrations <app_label>:
此命令会检测模型文件的更改，并生成新的迁移文件。这些文件位于应用目录下的 migrations 文件夹中。
python manage.py makemigrations myapp # 为 myapp 应用创建迁移文件
生成的迁移文件（例如 0002_auto_xxxx.py）包含了将模型更改应用到数据库所需的 Python 代码。
python manage.py migrate <app_label> <migration_name>:
此命令会将尚未应用的迁移应用到数据库，即实际修改数据库表结构。
python manage.py migrate # 应用所有应用中所有未应用的迁移
python manage.py migrate myapp # 只应用 myapp 应用的迁移
python manage.py migrate myapp 0001_initial # 将 myapp 应用迁移到 0001_initial 状态 (可以用于回滚)
python manage.py showmigrations:
显示项目中所有应用的迁移及其状态 (是否已应用)。
python manage.py sqlmigrate <app_label> <migration_name>:
显示特定迁移将执行的 SQL 语句，而不会实际执行它们。这对于调试或理解迁移操作很有用。
python manage.py sqlmigrate myapp 0002_auto_xxxx # 查看 myapp 应用的 0002 号迁移对应的 SQL
迁移的最佳实践:
频繁创建小迁移: 每次对模型做少量更改后就运行 makemigrations，而不是一次性进行大量更改。这样更容易管理和回滚。
检视迁移文件: 在运行 migrate 之前，最好打开生成的迁移文件看一下，确保它符合预期。
避免手动编辑迁移文件: 除非你非常清楚自己在做什么，否则不要手动修改迁移文件。
在版本控制中跟踪迁移文件: 迁移文件是项目代码的一部分，应提交到 Git 等版本控制系统中。
数据迁移 (Data Migrations): 有时不仅需要更改表结构，还需要迁移数据 (例如，将一个字段的数据转换格式后存到新字段)。可以使用 migrations.RunPython 操作来实现数据迁移。
# myapp/migrations/0003_populate_fullname.py
from django.db import migrations
def combine_names(apps, schema_editor):
# apps.get_model('myapp', 'Author') 获取迁移发生时的 Author 模型状态
Author = apps.get_model('myapp', 'Author')
for author in Author.objects.all():
author.full_name = f"{
author.first_name} {
author.last_name}" # 假设 Author 模型之前有 first_name, last_name，现在添加了 full_name
author.save()
def uncombine_names(apps, schema_editor):
# 反向操作，如果需要回滚
Author = apps.get_model('myapp', 'Author')
for author in Author.objects.all():
author.full_name = "" # 清空 full_name
author.save()
class Migration(migrations.Migration):
dependencies = [
('myapp', '0002_add_author_fullname_field'), # 依赖于添加 full_name 字段的迁移
]
operations = [
migrations.RunPython(combine_names, reverse_code=uncombine_names), # 执行数据迁移函数
]
处理复杂模式更改: 对于重命名字段、更改字段类型等可能导致数据丢失的操作，Django 的迁移系统可能需要更仔细的处理，有时需要分多步迁移。
理解并熟练使用 Django 的模型和迁移系统是构建任何 Django 应用（包括 API 后端）的基础。这些模型将直接通过 DRF 的序列化器暴露给前端。
视图 (Views) – 逻辑处理 (transitioning to APIViews)
在传统的 Django MVC (MTV – Model-Template-View) 架构中，视图负责接收 Web 请求，处理业务逻辑，并返回一个 Web 响应 (通常是渲染后的 HTML 页面)。在前后端分离的 API 开发中，视图的职责类似，但返回的通常是 JSON 或 XML 格式的数据，而不是 HTML。DRF 提供了专门的视图类来简化 API 的创建。
函数视图 (Function-Based Views – FBV)
最简单的视图是 Python 函数。它接收一个 HttpRequest 对象作为参数，并返回一个 HttpResponse 对象。
# myapp/views.py
from django.http import JsonResponse, HttpResponseBadRequest, Http404
from .models import Product
import json
def product_list_fbv(request): # 定义一个函数视图，用于列出产品
if request.method == 'GET': # 只处理GET请求
products = Product.objects.all() # 获取所有产品对象
data = {
'products': [ # 构建产品数据列表
{
'id': product.id,
'name': product.name,
'price': str(product.price), # Decimal 需要转为字符串以进行JSON序列化
'category': product.category.name if product.category else None,
} for product in products
]
}
return JsonResponse(data) # 返回JSON响应
return HttpResponseBadRequest("Only GET method is allowed") # 如果不是GET请求，返回错误
def product_detail_fbv(request, pk): # 定义一个函数视图，用于获取单个产品详情
try:
product = Product.objects.get(pk=pk) # 根据主键pk获取产品
except Product.DoesNotExist:
raise Http404("Product does not exist") # 如果产品不存在，抛出404错误
if request.method == 'GET': # 只处理GET请求
data = {
# 构建产品详情数据
'id': product.id,
'name': product.name,
'description': product.description,
'price': str(product.price),
'stock': product.stock,
'available': product.available,
'category': product.category.name if product.category else None,
}
return JsonResponse(data) # 返回JSON响应
return HttpResponseBadRequest("Only GET method is allowed")
虽然函数视图简单直观，但随着 API 逻辑变复杂，它们可能会变得臃肿且难以维护。DRF 更推荐使用类视图。
类视图 (Class-Based Views – CBV)
Django 内置的类视图 (如 View, TemplateView, ListView, DetailView) 提供了更好的结构和可重用性。它们通过将 HTTP 方法 (GET, POST, PUT, DELETE 等) 分派给类中的同名方法 (如 get(), post(), put(), delete()) 来处理请求。
# myapp/views.py
from django.views import View
from django.http import JsonResponse, HttpResponseBadRequest
from .models import Product
import json
class ProductListView(View): # 定义一个继承自django.views.View的类视图
def get(self, request, *args, **kwargs): # 处理GET请求的方法
products = Product.objects.all()
data = {
'products': [
{
'id': product.id,
'name': product.name,
'price': str(product.price),
'category': product.category.name if product.category else None,
} for product in products
]
}
return JsonResponse(data)
def post(self, request, *args, **kwargs): # 处理POST请求的方法 (示例，实际创建逻辑会更复杂)
# 假设请求体是 JSON: {"name": "New Product", "price": "19.99", "category_id": 1}
try:
payload = json.loads(request.body) # 解析请求体中的JSON数据
# 此处应有数据验证逻辑
# ... 创建 Product 对象的逻辑 ...
# product = Product.objects.create(name=payload['name'], ...)
return JsonResponse({
'message': 'Product created (simulated)'}, status=201) # 返回创建成功的响应
except json.JSONDecodeError:
return JsonResponse({
'error': 'Invalid JSON'}, status=400) # 返回JSON解析错误
except Exception as e:
return JsonResponse({
'error': str(e)}, status=400) # 返回其他错误
# ... (类似地可以为 product_detail 实现一个类视图) ...
DRF 的 APIView 是 Django View 类的子类，专门为构建 API 进行了扩展，提供了请求解析、内容协商、认证、权限等功能。这是我们后续将重点使用的基类。
URL 配置 (URL Configuration) – API 路由设计
URL 配置 (通常在 urls.py 文件中) 定义了 URL 模式与视图之间的映射关系。对于 API，URL 设计应遵循 RESTful 原则，使用名词表示资源，HTTP 方法表示操作。
# myproject/urls.py (项目级 urls.py)
from django.contrib import admin
from django.urls import path, include # 导入 include
urlpatterns = [
path('admin/', admin.site.urls), # Admin后台的URL
path('api/v1/', include('myapp.urls')), # 将所有以 'api/v1/' 开头的URL路由到 myapp 应用的urls.py
]
# myapp/urls.py (应用级 urls.py)
from django.urls import path
from . import views # 从当前目录导入 views.py
from .views_fbv import product_list_fbv, product_detail_fbv # 假设之前的函数视图在views_fbv.py中
from .views_cbv import ProductListViewCBV, ProductDetailViewCBV # 假设之前的类视图在views_cbv.py中
urlpatterns = [
# 使用函数视图
path('products-fbv/', product_list_fbv, name='product-list-fbv'), # 'products-fbv/' 路径映射到 product_list_fbv 函数
path('products-fbv/<int:pk>/', product_detail_fbv, name='product-detail-fbv'), # '<int:pk>/' 捕获路径中的整数作为参数pk
# 使用 Django 内置类视图
path('products-cbv/', ProductListViewCBV.as_view(), name='product-list-cbv'), # 类视图需要调用 .as_view() 方法
path('products-cbv/<int:pk>/', ProductDetailViewCBV.as_view(), name='product-detail-cbv'),
# 后续我们将使用 DRF 的视图和路由器来简化 API URL 配置
]
代码解释 (myapp/urls.py):
from django.urls import path: 导入 path 函数用于定义 URL 模式。
from . import views: 导入当前应用（myapp）的 views.py 模块。
path('products-fbv/', views.product_list_fbv, name='product-list-fbv'):
第一个参数是 URL 模式字符串。
第二个参数是当 URL 匹配时调用的视图函数或类视图的 as_view() 方法。
name='product-list-fbv': 为该 URL 模式命名，方便在代码中（如模板、视图重定向）通过名称反向解析 URL。
path('products-fbv/<int:pk>/', views.product_detail_fbv, name='product-detail-fbv'):
<int:pk>: 这是一个路径转换器 (path converter)。它匹配一个整数，并将其值作为名为 pk 的关键字参数传递给视图函数 product_detail_fbv(request, pk).
DRF 提供了 Routers，可以自动为 ViewSet 生成 URL 配置，进一步简化 API 路由管理。
模板 (Templates) – (Brief mention)
在纯粹的前后端分离架构中，Django 后端通常不负责渲染 HTML 模板给最终用户。前端应用 (如 React/Vue) 会自己处理视图渲染。
然而，Django 的模板系统在以下场景仍可能有用：
Admin 后台: Admin 后台本身就是用 Django 模板构建的。
邮件模板: 发送 HTML 格式的邮件时，可以使用 Django 模板。
某些辅助页面: 例如，API 文档页面 (DRF 的可浏览 API 就是一个例子)，或者一些简单的服务端渲染页面。
服务器端渲染 (SSR) 的初始页面: 某些情况下，为了 SEO 或首屏加载速度，可能会让 Django 渲染一个包含基本结构和数据的初始 HTML 页面，然后前端接管。
如果需要使用，Django 模板语言 (DTL) 提供了变量、标签、过滤器等功能。
# settings.py 中配置模板目录
# TEMPLATES = [
# {
# 'BACKEND': 'django.template.backends.django.DjangoTemplates',
# 'DIRS': [BASE_DIR / 'templates'], # 项目级模板目录
# 'APP_DIRS': True, # 允许 Django 在应用目录下查找模板
# # ...
# },
# ]
表单 (Forms) – (Brief mention, transitioning to serializers)
Django 的 forms 模块用于处理 HTML 表单的创建、验证和数据清洗。在传统 Django 应用中非常核心。
# myapp/forms.py
from django import forms
from .models import Product
class ProductForm(forms.ModelForm): # ModelForm 可以直接从模型生成表单字段
class Meta:
model = Product # 指定表单关联的模型
fields = ['name', 'description', 'price', 'stock', 'category', 'available'] # 指定表单包含的字段
# exclude = ['created_at', 'updated_at'] # 或者排除某些字段
在前后端分离的 API 开发中，前端通常会自己构建表单 UI，并通过 API 将数据（通常是 JSON）提交到后端。后端不再直接处理 HTML 表单的 POST 请求。数据的验证和转换工作将主要由 DRF 的 Serializers (序列化器) 来完成。序列化器扮演了类似 Django Forms 的角色，但更侧重于数据的序列化 (将复杂数据类型如模型实例转换为原生 Python 数据类型，再渲染为 JSON/XML) 和反序列化 (将解析后的请求数据转换为复杂数据类型，并进行验证)。
因此，虽然 Django Forms 的概念 (特别是数据验证和清洗) 与 DRF Serializers 有相似之处，但在 API 场景下，我们将主要已关注和使用 Serializers。
Admin 后台 (Admin Site) – (How it can still be useful)
Django 自动生成的 Admin 后台是一个非常强大的功能，即使在前后端分离项目中，它也极具价值：
数据管理: 快速方便地查看、创建、编辑和删除数据库中的记录，无需编写任何额外代码。
内部运营: 对于运营人员或内部用户，Admin 后台可以作为一个现成的数据管理工具。
开发调试: 开发者可以通过 Admin 后台快速检查数据状态，验证 API 操作是否正确影响了数据。
快速原型: 在项目初期，可以利用 Admin 后台快速搭建数据模型并进行操作，验证业务逻辑。
要使用 Admin 后台，首先需要确保 django.contrib.admin 在 INSTALLED_APPS 中，并且在项目 urls.py 中配置了 Admin 的 URL。
然后，在应用的 admin.py 文件中注册模型：
# myapp/admin.py
from django.contrib import admin
from .models import Category, Product, Tag, UserProfile, Student, Course, Enrollment # 导入需要注册到Admin的模型
@admin.register(Category) # 使用装饰器注册 Category 模型
class CategoryAdmin(admin.ModelAdmin):
list_display = ('name', 'description') # 在列表页显示的字段
search_fields = ('name',) # 允许按名称搜索
@admin.register(Product) # 注册 Product 模型
class ProductAdmin(admin.ModelAdmin):
list_display = ('name', 'category', 'price', 'stock', 'available', 'created_at') # 列表页显示字段
list_filter = ('available', 'category', 'created_at') # 侧边栏过滤器
search_fields = ('name', 'description') # 搜索字段
list_editable = ('price', 'stock', 'available') # 允许在列表页直接编辑的字段
raw_id_fields = ('category',) # 对于外键字段，使用ID输入框而不是下拉选择框 (当关联对象很多时有用)
# filter_horizontal = ('tags',) # 对于 ManyToManyField，可以使用更友好的水平过滤器
@admin.register(Tag)
class TagAdmin(admin.ModelAdmin):
list_display = ('name',)
search_fields = ('name',)
# 简单注册 (使用默认配置)
admin.site.register(UserProfile)
admin.site.register(Student)
admin.site.register(Course)
admin.site.register(Enrollment)
代码解释 (myapp/admin.py):
from django.contrib import admin: 导入 Admin 模块。
from .models import ...: 导入你的模型。
@admin.register(Category): 这是一个方便的装饰器，等同于 admin.site.register(Category, CategoryAdmin)。
class CategoryAdmin(admin.ModelAdmin):: 自定义模型在 Admin 界面的显示和行为。
list_display: 一个元组或列表，指定在模型的更改列表页面上显示的字段。
search_fields: 一个元组或列表，指定可以通过哪些字段进行搜索。Django 会在后台使用 LIKE 查询。
list_filter: 一个元组或列表，指定可以在更改列表页右侧边栏创建过滤器的字段。Django 会根据字段类型提供合适的过滤选项 (例如日期范围、选项)。
list_editable: 一个元组或列表，指定可以在更改列表页面上直接编辑的字段。这些字段也必须出现在 list_display 中。
raw_id_fields: 一个元组或列表，指定哪些 ForeignKey 或 ManyToManyField 字段应该显示为一个简单的 ID 输入框，而不是下拉选择框或多选框。这对于关联对象非常多的情况可以提高性能。
filter_horizontal: (用于 ManyToManyField) 提供一个更友好的双向选择界面。
通过这些基础知识的回顾，我们为学习 Django REST framework 打下了坚实的基础。接下来，我们将深入 DRF 的世界。
Django REST framework (DRF) 深度剖析 (In-depth Analysis of DRF)
Django REST framework (DRF) 是一个构建 Web API 的强大且灵活的工具包。它旨在简化序列化、视图编写、身份验证、权限控制等常见 API 开发任务。
核心组件 (Core Components)
DRF 的设计围绕几个核心组件构建，理解这些组件及其交互方式是掌握 DRF 的关键。
Serializers (序列化器)
序列化器允许将诸如查询集和模型实例之类的复杂数据转换为可以轻松呈现为 JSON、XML 或其他内容类型的原生 Python 数据类型。序列化器还提供反序列化功能，允许在验证传入数据之后将解析的数据转换回复杂类型。
1. 什么是序列化与反序列化 (What is Serialization and Deserialization?)
序列化 (Serialization): 将程序中的数据结构或对象状态转换为可以存储（例如，在文件或内存缓冲区中）或传输（例如，通过网络连接链路）并稍后在相同或另一个计算机环境中重建的格式的过程。在 Web API 的上下文中，这通常意味着将 Django 模型实例或查询集转换为 JSON 字符串。
Model Instance -> Python dict -> JSON string
反序列化 (Deserialization): 序列化的逆过程，即从一系列字节中提取数据结构。在 Web API 中，这通常意味着将传入的请求数据 (如 JSON) 解析并验证，然后转换为 Python 对象或用于更新/创建 Django 模型实例。
JSON string (from request) -> Python dict -> Validated Data -> Model Instance (for create/update)
2. Serializer 类 (The Serializer Class)
这是 DRF 中所有序列化器的基类。它类似于 Django 的 Form 和 ModelForm 类，通过声明字段来定义数据的表示形式。
# myapp/serializers.py
from rest_framework import serializers
from datetime import datetime
class CommentSerializer(serializers.Serializer):
email = serializers.EmailField() # 定义 email 字段，类型为 EmailField，会自动进行邮箱格式验证
content = serializers.CharField(max_length=200) # 定义 content 字段，字符型，最大长度200
created = serializers.DateTimeField(read_only=True, default=serializers.CreateOnlyDefault(datetime.now)) # 定义 created 字段，日期时间型
# read_only=True 表示该字段只用于序列化输出，不用于反序列化输入
# default=serializers.CreateOnlyDefault(datetime.now) 表示仅在创建时使用默认值
# 字段级别的验证方法 (以 validate_<field_name> 命名)
def validate_content(self, value): # 验证 content 字段
if "spam" in value.lower(): # 如果内容包含 "spam"
raise serializers.ValidationError("Content cannot contain 'spam'.") # 抛出验证错误
return value # 验证通过，返回处理后的值
# 对象级别的验证方法 (名为 validate)
def validate(self, data): # 验证整个数据对象
# 假设有一个需求：如果邮件是 example.com 域名，则内容不能为空
# 'data' 是一个包含所有字段有效值的字典
if "example.com" in data.get('email', '') and not data.get('content'):
raise serializers.ValidationError("Content is required for example.com emails.") # 抛出验证错误
return data # 验证通过，返回数据
# 控制对象的创建和更新
def create(self, validated_data):
# validated_data 是验证通过后的数据字典
# 在这里实现创建对象的逻辑，例如保存到数据库或调用其他服务
print("Creating comment with data:", validated_data)
# return Comment(**validated_data) # 假设 Comment 是一个普通 Python 类或数据结构
return validated_data # 简单返回，实际应用中会创建并返回实例
def update(self, instance, validated_data):
# instance 是要更新的对象实例
# validated_data 是验证通过后的数据字典
# 在这里实现更新对象的逻辑
print(f"Updating instance {
instance} with data:", validated_data)
# instance.email = validated_data.get('email', instance.email)
# instance.content = validated_data.get('content', instance.content)
# instance.save()
# return instance
instance.update(validated_data) # 假设 instance 是一个字典，简单更新
return instance
# 使用示例：
# 序列化 (对象 -> JSON)
# comment_obj = {'email': 'test@example.com', 'content': 'Hello DRF!', 'created': datetime.now()}
# serializer = CommentSerializer(comment_obj)
# print(serializer.data) # 输出: {'email': 'test@example.com', 'content': 'Hello DRF!', 'created': '2023-10-27T10:00:00Z'}
# 反序列化与验证 (JSON -> 对象/数据)
# incoming_data_valid = {'email': 'new@user.com', 'content': 'A new comment.'}
# serializer_valid = CommentSerializer(data=incoming_data_valid)
# if serializer_valid.is_valid():
# print("Valid data:", serializer_valid.validated_data)
# # new_comment = serializer_valid.save() # 调用 create 或 update 方法
# else:
# print("Invalid data:", serializer_valid.errors)
# incoming_data_invalid = {'email': 'bademail', 'content': 'This is spam content.'}
# serializer_invalid = CommentSerializer(data=incoming_data_invalid)
# if serializer_invalid.is_valid():
# print("Valid data:", serializer_invalid.validated_data)
# else:
# print("Invalid data:", serializer_invalid.errors) # 输出错误信息
# # {'email': ['Enter a valid email address.'], 'content': [ErrorDetail(string="Content cannot contain 'spam'.", code='invalid')]}
代码解释 (CommentSerializer):
email = serializers.EmailField(): 定义一个名为 email 的字段，DRF 会使用 EmailValidator 来验证其格式。
content = serializers.CharField(max_length=200): 定义一个字符字段，最大长度为 200。
created = serializers.DateTimeField(read_only=True, ...):
read_only=True: 表示此字段仅用于序列化（输出），不会在反序列化（输入）时被期望或处理。通常用于像创建时间、ID 这类由服务器生成或不可修改的字段。
default=serializers.CreateOnlyDefault(datetime.now): CreateOnlyDefault 是一个特殊的默认值标记，表示这个默认值只在创建操作 (即 serializer.save() 且没有传入实例时) 中使用。datetime.now 是一个可调用对象，它将在需要时被调用以获取当前时间。
def validate_content(self, value): 这是一个字段级别的验证方法。方法名必须是 validate_<field_name>。它接收字段的原始值 value 作为参数。如果验证失败，应抛出 serializers.ValidationError。如果成功，必须返回验证或清洗后的值。
def validate(self, data): 这是一个对象级别的验证方法。它在所有字段级别的验证通过后执行。它接收一个包含所有字段值的字典 data 作为参数。用于需要跨多个字段进行验证的场景。同样，验证失败抛出 serializers.ValidationError，成功则返回 data。
def create(self, validated_data): 当调用 serializer.save() 并且序列化器没有被传入一个现有实例 (即创建新对象) 时，此方法被调用。validated_data 是经过所有验证后的数据字典。此方法需要实现创建对象的逻辑并返回创建的对象实例。
def update(self, instance, validated_data): 当调用 serializer.save() 并且序列化器被传入了一个现有实例 (即更新对象) 时，此方法被调用。instance 是要更新的现有对象，validated_data 是验证后的数据。此方法需要实现更新对象的逻辑并返回更新后的对象实例。
3. ModelSerializer 类 (The ModelSerializer Class)
ModelSerializer 是 Serializer 的一个子类，它可以根据 Django 模型自动生成字段和验证器，并自动实现 create() 和 update() 方法。这是 DRF 中最常用和最强大的序列化器类型。
# myapp/models.py (假设已有 Product 和 Category 模型)
# from django.db import models
# class Category(models.Model):
# name = models.CharField(max_length=100, unique=True)
# def __str__(self): return self.name
# class Product(models.Model):
# name = models.CharField(max_length=200)
# description = models.TextField()
# price = models.DecimalField(max_digits=10, decimal_places=2)
# category = models.ForeignKey(Category, related_name='products', on_delete=models.SET_NULL, null=True, blank=True)
# # ... 其他字段
# myapp/serializers.py
from rest_framework import serializers
from .models import Product, Category # 导入模型
class CategorySerializer(serializers.ModelSerializer):
class Meta:
model = Category # 指定关联的 Category 模型
fields = ['id', 'name'] # 指定序列化器包含的字段 ('id' 是主键，会自动包含)
# fields = '__all__' # 或者包含所有模型字段
# exclude = ['description'] # 或者排除某些字段
class ProductSerializer(serializers.ModelSerializer):
# 可以显式声明模型中已有的字段，以覆盖默认行为或添加额外选项
name = serializers.CharField(max_length=200, help_text="产品名称") # 添加 help_text，用于 API 文档
price = serializers.DecimalField(max_digits=10, decimal_places=2, min_value=0) # 添加 min_value 验证
# 也可以添加不属于模型的额外字段
discounted_price = serializers.SerializerMethodField(read_only=True) # 自定义方法字段，只读
# 对于外键关系，默认会使用 PrimaryKeyRelatedField (即只返回外键的ID)
# category = serializers.PrimaryKeyRelatedField(queryset=Category.objects.all(), allow_null=True) # 这是默认行为之一
# 如果想嵌套显示关联对象的信息，可以使用嵌套序列化器或 StringRelatedField 等
# 选项1: 使用 StringRelatedField 显示关联对象的 __str__ 方法的输出
# category_name = serializers.StringRelatedField(source='category', read_only=True) # source='category' 指定数据来源
# 选项2: 嵌套另一个序列化器 (CategorySerializer)
category_details = CategorySerializer(source='category', read_only=True, allow_null=True) # source='category' 指向 Product 模型的 category 字段
# read_only=True 因为通常不通过产品接口直接创建/更新分类的详细信息
# allow_null=True 如果 category 字段本身允许为空
class Meta:
model = Product # 指定关联的 Product 模型
fields = [
'id', 'name', 'description', 'price', 'discounted_price',
'category', # 这是 category 的 ID (PrimaryKeyRelatedField)
# 'category_name', # 如果使用 StringRelatedField
'category_details', # 如果使用嵌套序列化器
# ... 其他你希望包含的 Product 字段 ...
]
# read_only_fields = ('created_at', 'updated_at') # 指定只读字段
# extra_kwargs = { # 为特定字段提供额外参数
# 'description': {'required': False, 'allow_blank': True} # 例如，将 description 设置为非必填
# }
def get_discounted_price(self, obj): # obj 是 Product 实例
# 自定义方法字段 get_<field_name> 的实现
# 假设打九折
if obj.price is not None:
return obj.price * 0.9
return None
# 可以在 ModelSerializer 中覆盖 validate_<field_name> 和 validate 方法
def validate_name(self, value):
if len(value) < 3:
raise serializers.ValidationError("Product name must be at least 3 characters long.")
return value
def validate(self, data):
# 假设库存 stock 和价格 price 字段都存在于序列化器中 (这里未显式列出，但如果 fields = '__all__' 就会有)
# if 'stock' in data and 'price' in data:
# if data['stock'] < 0 and data['price'] > 1000:
# raise serializers.ValidationError("High-value products cannot have negative stock.")
return data
# 使用 ModelSerializer:
# product = Product.objects.first()
# serializer = ProductSerializer(product)
# print(serializer.data)
# # 输出可能包含：
# # {
# # 'id': 1,
# # 'name': 'Awesome Laptop',
# # 'description': 'A very powerful laptop.',
# # 'price': '1200.00',
# # 'discounted_price': '1080.00',
# # 'category': 1, // category ID
# # 'category_details': {'id': 1, 'name': 'Electronics'} // 嵌套的分类信息
# # }
# 创建新产品:
# new_product_data = {
# 'name': 'New Mouse',
# 'description': 'A comfortable mouse.',
# 'price': '25.00',
# 'category': 1 # 指向一个已存在的 Category ID
# }
# create_serializer = ProductSerializer(data=new_product_data)
# if create_serializer.is_valid():
# new_product = create_serializer.save() # 调用 ModelSerializer 内置的 create() 方法
# print(f"Created product: {new_product.name}")
# else:
# print(create_serializer.errors)
代码解释 (ProductSerializer):
class Meta::
model = Product: 核心配置，告诉 ModelSerializer 要为哪个模型工作。
fields = [...]: 一个字段名列表，指定哪些模型字段应该包含在序列化器中。'id' 通常会自动包含。
可以使用 fields = '__all__' 来包含模型的所有字段。
可以使用 exclude = ['field_to_exclude'] 来指定排除哪些字段。
read_only_fields = ('created_at',): 一个元组，指定哪些字段是只读的。这些字段将包含在序列化输出中，但在反序列化（创建/更新）时将被忽略。
extra_kwargs = {'description': {'required': False}}: 允许为 ModelSerializer 自动生成的字段提供额外的关键字参数。例如，将 description 字段的 required 属性设置为 False。
name = serializers.CharField(...): 即使 name 字段已在 Product 模型中定义，也可以在序列化器中显式声明它。这允许你覆盖默认行为，例如添加 help_text (用于 API 文档) 或更严格的验证规则。
discounted_price = serializers.SerializerMethodField(read_only=True):
SerializerMethodField 是一种只读字段，其值由序列化器类中一个名为 get_<field_name> 的方法计算得出。
def get_discounted_price(self, obj): 这个方法接收模型实例 obj 作为参数，并返回 discounted_price 字段的值。
category_details = CategorySerializer(source='category', read_only=True):
这是一个嵌套序列化器的例子。它使用 CategorySerializer 来序列化 Product 模型的 category 字段。
source='category': 指明这个嵌套序列化器的数据应该从 Product 实例的 category 属性获取。
read_only=True: 通常，对于嵌套表示，我们不希望通过主对象的端点（例如产品API）来创建或更新关联对象（例如分类）的完整细节。这些关联对象通常有自己的独立 API 端点。如果需要可写的嵌套序列化器，DRF 也支持，但会更复杂。
ModelSerializer 会自动处理 create() 和 update() 方法的实现，基于 Meta.model。
4. 字段类型与选项 (Serializer Field Types and Options)
DRF 的序列化器字段与 Django 的模型字段和表单字段有很多相似之处，但它们是专门为序列化/反序列化数据设计的。
常用字段类型：
数值型: IntegerField, FloatField, DecimalField
布尔型: BooleanField, NullBooleanField
字符串型: CharField, EmailField, RegexField, SlugField, URLField, UUIDField, FilePathField, IPAddressField
日期时间型: DateField, TimeField, DateTimeField, DurationField
选择型: ChoiceField (类似 Django 表单的 ChoiceField)
文件型: FileField, ImageField (用于处理文件上传)
复合型: ListField (输入/输出一个值列表), DictField (输入/输出一个字典)
关系型:
PrimaryKeyRelatedField: 将关系表示为其目标的主键。默认。
HyperlinkedRelatedField: 将关系表示为一个超链接。
StringRelatedField: 将关系表示为其目标的 __str__ 方法的输出 (只读)。
SlugRelatedField: 将关系表示为其目标的某个 slug 字段的值。
嵌套序列化器 (直接使用另一个序列化器类作为字段)。
只读型: ReadOnlyField (简单显示字段值，不用于输入)
自定义方法型: SerializerMethodField (值由自定义方法提供)
隐藏型: HiddenField (不从输入数据中取值，而是使用默认值，但在 validated_data 中可用)
通用字段选项：
read_only: (布尔型) 如果为 True，该字段仅用于序列化输出，不用于反序列化输入。
write_only: (布尔型) 如果为 True，该字段仅用于反序列化输入 (例如密码字段)，不用于序列化输出。
required: (布尔型) 如果为 True (默认)，该字段在反序列化时必须提供。如果为 False，则在输入中可以省略该字段。
default: 如果字段在输入数据中未提供，则使用此默认值。不能与 required=True 同时使用。
allow_null: (布尔型) 如果为 True，则该字段接受 None (JSON null) 作为有效值。
allow_blank: (布尔型, 仅用于字符串类型字段) 如果为 True，则该字段接受空字符串 "" 作为有效值。通常与 required=False 结合使用。
source: (字符串) 用于填充此字段的模型属性或字典键的名称。例如，如果模型字段名为 product_name，但你想在 API 中将其公开为 name，则可以设置 source='product_name'。source='*' 可用于将整个对象传递给自定义字段。
validators: 一个验证器函数列表。
error_messages: 一个字典，覆盖默认的错误消息。
label: 字段的简短描述，用于 API 文档或可浏览 API。
help_text: 字段的详细描述。
5. 验证 (Validation)
DRF 的验证过程与 Django Forms 类似，有几个层次：
字段特定验证 (Field-specific validation):
通过在字段上设置参数 (如 max_length, min_value, required=True)。
通过在序列化器中定义 validate_<field_name>(self, value) 方法。
对象级别验证 (Object-level validation):
通过在序列化器中定义 validate(self, attrs) 方法。attrs 是所有字段值的字典。
验证器 (Validators):
可以在字段上使用 validators=[...] 选项，传入可重用的验证器函数或类。DRF 和 Django 都提供了一些内置验证器。
当调用 serializer.is_valid() 时：
传入的数据首先被反序列化为原生 Python 数据类型。
执行字段特定的验证。
如果所有字段都有效，则执行对象级别的 validate() 方法。
如果任何验证步骤失败，is_valid() 返回 False，并且 serializer.errors 字典会包含描述错误的详细信息。
如果所有验证都成功，is_valid() 返回 True，并且验证后的数据可以在 serializer.validated_data 中访问。
如果 is_valid() 抛出异常 (例如，在 validate() 方法中 raise serializers.ValidationError(...)），则 DRF 会捕获它并将其添加到 serializer.errors。
# myapp/serializers.py
from rest_framework import serializers
from .models import Product
def validate_positive_stock(value): # 一个可重用的验证器函数
if value < 0:
raise serializers.ValidationError("Stock cannot be negative.")
class ProductStockUpdateSerializer(serializers.Serializer):
stock = serializers.IntegerField(validators=[validate_positive_stock]) # 使用自定义验证器
last_checked_by = serializers.CharField(required=False, allow_blank=True)
def validate_stock(self, value): # 字段级验证
if value > 10000:
# 假设我们不希望一次性更新超过10000的库存
raise serializers.ValidationError("Stock update cannot exceed 10,000 units at a time.")
print(f"Validated stock: {
value}")
return value # 必须返回处理后的值
def validate(self, data): # 对象级验证
# 'data' 包含通过字段级验证的 'stock' 和可能的 'last_checked_by'
# 假设如果库存大于5000，则必须提供 last_checked_by
if data.get('stock', 0) > 5000 and not data.get('last_checked_by'):
raise serializers.ValidationError({
'last_checked_by': 'Must be specified if stock is greater than 5000.'
}) # 可以为特定字段引发错误，或引发一个通用错误
print(f"Validated data object: {
data}")
return data
# 使用示例
# valid_payload = {'stock': 100, 'last_checked_by': 'admin'}
# serializer = ProductStockUpdateSerializer(data=valid_payload)
# if serializer.is_valid(raise_exception=True): # raise_exception=True 会在验证失败时直接抛出 ValidationError
# print("Stock update data is valid:", serializer.validated_data)
# # serializer.save() # 如果有 create/update 方法
# invalid_payload_field_level = {'stock': -5}
# serializer_field_fail = ProductStockUpdateSerializer(data=invalid_payload_field_level)
# print(serializer_field_fail.is_valid()) # False
# print(serializer_field_fail.errors) # {'stock': [ErrorDetail(string='Stock cannot be negative.', code='invalid')]}
# invalid_payload_object_level = {'stock': 6000}
# serializer_object_fail = ProductStockUpdateSerializer(data=invalid_payload_object_level)
# print(serializer_object_fail.is_valid()) # False
# print(serializer_object_fail.errors) # {'last_checked_by': [ErrorDetail(string='Must be specified if stock is greater than 5000.', code='invalid')]}
6. 嵌套序列化器 (Nested Serializers)
如前所述，可以在一个序列化器中嵌套另一个序列化器来表示关系。
只读嵌套 (Read-only nested representation):
# myapp/serializers.py
# class CategorySerializer(serializers.ModelSerializer): ... (已定义)
class ProductWithNestedCategorySerializer(serializers.ModelSerializer):
category = CategorySerializer(read_only=True) # 嵌套 CategorySerializer，只读
class Meta:
model = Product
fields = ['id', 'name', 'price', 'category']
当序列化 Product 时，category 字段会包含 CategorySerializer 序列化后的完整分类信息。
可写嵌套 (Writable nested representation):
DRF 支持可写的嵌套序列化器，这意味着你可以通过主对象的端点同时创建或更新关联的对象。这需要你在主序列化器中重写 .create() 和/或 .update() 方法来处理嵌套数据的保存。
# myapp/serializers.py
# class TagSerializer(serializers.ModelSerializer):
# class Meta:
# model = Tag
# fields = ['id', 'name']
#
# class ProductWithWritableTagsSerializer(serializers.ModelSerializer):
# tags = TagSerializer(many=True, required=False) # many=True 因为一个产品可以有多个标签
# # required=False 表示标签是可选的
#
# class Meta:
# model = Product
# fields = ['id', 'name', 'price', 'category', 'tags']
#
# def create(self, validated_data):
# tags_data = validated_data.pop('tags', []) # 弹出标签数据，如果没有提供则为空列表
# product = Product.objects.create(**validated_data) # 创建产品实例
# for tag_data in tags_data:
# tag, created = Tag.objects.get_or_create(name=tag_data['name']) # 获取或创建标签
# product.tags.add(tag) # 将标签添加到产品
# return product
#
# def update(self, instance, validated_data):
# tags_data = validated_data.pop('tags', None) # 弹出标签数据
#
# # 更新产品实例的普通字段
# instance.name = validated_data.get('name', instance.name)
# instance.price = validated_data.get('price', instance.price)
# instance.category = validated_data.get('category', instance.category)
# # ... 其他字段更新 ...
# instance.save()
#
# if tags_data is not None: # 如果请求中提供了标签数据
# instance.tags.clear() # 先清除旧的标签关系 (或者可以做更复杂的 diff 更新)
# for tag_data in tags_data:
# tag, created = Tag.objects.get_or_create(name=tag_data['name'])
# instance.tags.add(tag)
# return instance
注意: 可写嵌套序列化器虽然强大，但也可能使逻辑变得复杂，特别是在处理深层嵌套或多对多关系时。有时，为关联资源提供独立的 API 端点是更清晰、更 RESTful 的做法。例如，可以有一个 /api/products/ 端点和一个 /api/tags/ 端点，以及一个 /api/products/<pk>/tags/ 端点来管理特定产品的标签关系。
7. 处理关联关系 (Handling Relationships)
除了嵌套序列化器，DRF 还提供了其他方式来表示模型之间的关系：
PrimaryKeyRelatedField: 这是 ModelSerializer 对 ForeignKey 和 ManyToManyField 的默认处理方式。它将关联对象表示为其主键 ID。
# myapp/serializers.py
class ProductSimpleSerializer(serializers.ModelSerializer):
# category 字段会自动被处理为 PrimaryKeyRelatedField
# category = serializers.PrimaryKeyRelatedField(queryset=Category.objects.all()) # 可以显式指定
class Meta:
model = Product
fields = ['id', 'name', 'category'] # category 会输出 category_id
在反序列化时，你需要提供关联对象的 ID。queryset 参数是必需的，用于在反序列化时查找关联对象。对于 ModelSerializer，它通常会自动从关系中推断出来。
HyperlinkedModelSerializer 和 HyperlinkedRelatedField:
这种方式将关系表示为指向关联资源的 API 端点的超链接，而不是 ID。这有助于构建更具可发现性的 API。
# myapp/serializers.py
class CategoryHyperlinkedSerializer(serializers.HyperlinkedModelSerializer):
class Meta:
model = Category
fields = ['url', 'id', 'name'] # 'url' 是自动生成的超链接字段
# extra_kwargs 用于为自动生成的 'url' 字段指定 view_name 和 lookup_field
extra_kwargs = {
'url': {
'view_name': 'category-detail', 'lookup_field': 'pk'} # 'category-detail' 是 URL 名称
}
class ProductHyperlinkedSerializer(serializers.HyperlinkedModelSerializer):
# category 会被自动处理为 HyperlinkedRelatedField
category = serializers.HyperlinkedRelatedField(
view_name='category-detail', # 指向分类详情视图的 URL 名称
read_only=True # 或者 queryset=Category.objects.all() 如果需要可写
)
# 如果 Product 也有自己的详情视图，HyperlinkedModelSerializer 会自动添加 'url' 字段
# url = serializers.HyperlinkedIdentityField(view_name='product-detail', lookup_field='pk') # 这是自动添加的
class Meta:
model = Product
fields = ['url', 'id', 'name', 'price', 'category']
extra_kwargs = {
'url': {
'view_name': 'product-detail', 'lookup_field': 'pk'}
}
要使用超链接序列化器，你需要：
在 URL 配置中为你的 API 视图命名。
确保请求上下文中包含 request 对象，以便序列化器可以构建完整的 URL。DRF 的 APIView 和 ViewSet 会自动处理。
在 Meta 的 extra_kwargs 中或直接在字段上指定 view_name 和可选的 lookup_field。
StringRelatedField: 将关联对象表示为其 __str__() 方法的输出。这是只读的。
# myapp/serializers.py
class ProductWithStringCategorySerializer(serializers.ModelSerializer):
category_name = serializers.StringRelatedField(source='category', read_only=True) # source='category' 很重要
class Meta:
model = Product
fields = ['id', 'name', 'price', 'category_name']
SlugRelatedField: 将关联对象表示为其某个 slug 字段的值。可以用于读写。
# myapp/models.py
# class Category(models.Model):
# name = models.CharField(max_length=100, unique=True)
# slug = models.SlugField(max_length=100, unique=True) # 分类有一个 slug 字段
# # ...
# myapp/serializers.py
class ProductWithSlugCategorySerializer(serializers.ModelSerializer):
category = serializers.SlugRelatedField(
slug_field='slug', # 指定 Category 模型中用作 slug 的字段名
queryset=Category.objects.all() # 反序列化时需要 queryset
)
class Meta:
model = Product
fields = ['id', 'name', 'price', 'category'] # category 会输出或接收 category slug
当反序列化时，客户端需要提供 slug 值。序列化器会使用 queryset 和 slug_field 来查找对应的 Category 对象。
8. 动态修改字段 (Dynamically Modifying Fields)
有时，你可能希望根据上下文（例如请求用户、请求方法或传入的参数）动态地修改序列化器包含哪些字段，或者字段的属性。
在 __init__ 方法中修改 fields:
# myapp/serializers.py
class DynamicFieldsProductSerializer(serializers.ModelSerializer):
class Meta:
model = Product
fields = ['id', 'name', 'description', 'price', 'stock', 'category'] # 定义所有可能的字段
def __init__(self, *args, **kwargs):
# 从 kwargs 中弹出 'fields' 参数，如果调用者提供了它
# 'fields' 应该是一个包含所需字段名的元组或列表
fields_to_include = kwargs.pop('fields', None)
# 调用父类的 __init__ 方法
super().__init__(*args, **kwargs)
if fields_to_include is not None:
# 如果提供了 'fields' 参数，则只保留这些字段
allowed = set(fields_to_include)
existing = set(self.fields.keys())
for field_name in existing - allowed:
self.fields.pop(field_name) # 移除不在 'fields_to_include' 中的字段
# 在视图中使用:
# user = request.user
# if user.is_staff:
# # 管理员可以看到所有字段
# serializer = DynamicFieldsProductSerializer(products, many=True)
# else:
# #普通用户只能看到部分字段
# serializer = DynamicFieldsProductSerializer(products, many=True, fields=('id', 'name', 'price'))
使用 context 传递信息:
序列化器在实例化时可以接收一个 context 字典。这个字典可以在序列化器的任何方法中 (如 SerializerMethodField 的方法、validate 方法等) 通过 self.context 访问。
# myapp/serializers.py
class ProductContextSerializer(serializers.ModelSerializer):
is_on_sale = serializers.SerializerMethodField() # 根据上下文判断是否在促销
class Meta:
model = Product
fields = ['id', 'name', 'price', 'is_on_sale']
def get_is_on_sale(self, obj):
request = self.context.get('request') # 从上下文中获取 request 对象
# 假设我们可以从 request 或其他上下文信息判断是否促销
if request and request.user.is_authenticated and request.user.groups.filter(name='VIP').exists():
return True # VIP 用户看到促销标记
# 也可以根据传入的特定上下文参数
if self.context.get('campaign_active', False):
return True # 如果活动激活
return False
# 在视图中使用:
# serializer_context = {'request': request, 'campaign_active': True}
# serializer = ProductContextSerializer(product, context=serializer_context)
9. ListSerializer
当你将 many=True 传递给序列化器实例时，DRF 实际上会创建一个 ListSerializer 实例，该实例的 child 是你定义的序列化器。ListSerializer 负责处理对象列表的序列化和验证。
你可以通过在 ModelSerializer 的 Meta 中指定 list_serializer_class 来自定义用于 many=True 情况的 ListSerializer 行为，例如，进行批量创建或更新的优化。
# myapp/serializers.py
class ProductListSerializer(serializers.ListSerializer): # 自定义 ListSerializer
def create(self, validated_data_list): # validated_data_list 是一个包含多个产品数据的列表
# 实现批量创建逻辑
# 注意: Product.objects.bulk_create() 不会调用模型的 save() 方法，也不会发送 pre/post_save 信号
products = [Product(**item) for item in validated_data_list]
return Product.objects.bulk_create(products)
# 也可以重写 update, validate 等方法
class ProductBulkSerializer(serializers.ModelSerializer): # 这个序列化器用于单个产品
class Meta:
model = Product
fields = ['name', 'price', 'category'] # 假设这些是创建时需要的字段
list_serializer_class = ProductListSerializer # 指定当 many=True 时使用自定义的 ListSerializer
然后，当你在视图中像这样使用 ProductBulkSerializer 时：
serializer = ProductBulkSerializer(data=multiple_product_data, many=True)
如果 is_valid() 通过，调用 serializer.save() 实际上会调用 ProductListSerializer 的 create() 方法。
10. 编写自定义字段 (Writing Custom Serializer Fields)
如果 DRF 内置的字段类型不满足需求，你可以通过继承 serializers.Field 来创建自定义字段。你需要重写以下一个或多个方法：
to_representation(self, value): 将 Python 对象转换为用于序列化输出的原生表示 (例如字符串、整数、字典)。value 是要序列化的对象属性或字典值。
to_internal_value(self, data): 将传入的原生数据 (例如来自 JSON 解析后的字符串或数字) 转换为 Python 对象。如果数据无效，应抛出 serializers.ValidationError。
run_validation(self, data=serializers.empty): (可选) 如果需要更复杂的验证逻辑，可以重写此方法。
__init__(self, ...): (可选) 如果字段需要额外的参数。
# myapp/fields.py (自定义字段可以放在单独文件)
from rest_framework import serializers
import re
class RGBAColorField(serializers.Field): # 自定义一个 RGBA 颜色字段
default_error_messages = {
'invalid_format': 'Invalid RGBA format. Expected "R,G,B,A" (e.g., "255,0,0,0.5").',
'invalid_value': 'Invalid RGBA value. R,G,B must be 0-255, A must be 0.0-1.0.'
}
def to_representation(self, value): # 将 Python 对象 (假设是元组 (R,G,B,A)) 转换为字符串
if not isinstance(value, (list, tuple)) or len(value) != 4:
return None # 或者根据需要处理错误
r, g, b, a = value
return f"{
r},{
g},{
b},{
a}"
def to_internal_value(self, data): # 将字符串 "R,G,B,A" 转换为 Python 元组
if not isinstance(data, str):
self.fail('invalid_format') # 使用预定义的错误消息
match = re.fullmatch(r"(d{1,3}),(d{1,3}),(d{1,3}),([01](?:.d+)?)", data.strip())
if not match:
self.fail('invalid_format')
try:
r, g, b = [int(x) for x in match.groups()[:3]]
a = float(match.groups()[3])
except ValueError:
self.fail('invalid_value') # 如果转换失败
if not (0 <= r <= 255 and 0 <= g <= 255 and 0 <= b <= 255 and 0.0 <= a <= 1.0):
self.fail('invalid_value')
return (r, g, b, a) # 返回内部 Python 表示
# myapp/serializers.py
# from .fields import RGBAColorField
class ProductDisplayOptionsSerializer(serializers.Serializer):
background_color = RGBAColorField(required=False, allow_null=True) # 使用自定义字段
font_size = serializers.IntegerField(min_value=8, max_value=72, default=12)
# 使用:
# data_valid = {'background_color': "100,150,200,0.8", 'font_size': 16}
# serializer = ProductDisplayOptionsSerializer(data=data_valid)
# if serializer.is_valid():
# print(serializer.validated_data) # {'background_color': (100, 150, 200, 0.8), 'font_size': 16}
# obj = {'background_color': (50,50,50,1.0), 'font_size': 10}
# output_serializer = ProductDisplayOptionsSerializer(obj)
# print(output_serializer.data) # {'background_color': '50,50,50,1.0', 'font_size': 10}
11. 序列化器继承 (Serializer Inheritance)
序列化器可以像普通 Python 类一样相互继承。这对于重用通用字段或逻辑很有用。
# myapp/serializers.py
class BaseAuditSerializer(serializers.Serializer): # 定义一个基础序列化器，包含审计字段
created_by = serializers.CharField(read_only=True)
created_at = serializers.DateTimeField(read_only=True)
updated_by = serializers.CharField(read_only=True, required=False)
updated_at = serializers.DateTimeField(read_only=True, required=False)
class LogEntrySerializer(BaseAuditSerializer): # LogEntrySerializer 继承自 BaseAuditSerializer
message = serializers.CharField()
level = serializers.ChoiceField(choices=['INFO', 'WARNING', 'ERROR'])
# 它将自动拥有 created_by, created_at 等字段
# 如果与 ModelSerializer 结合:
class AuditedProductSerializer(ProductSerializer, BaseAuditSerializer): # 多重继承
# ProductSerializer 提供了 Product 模型的字段
# BaseAuditSerializer 提供了审计字段
# 需要确保字段名不冲突，或者显式声明解决
class Meta(ProductSerializer.Meta): # 继承 ProductSerializer 的 Meta
fields = ProductSerializer.Meta.fields + ['created_by', 'created_at', 'updated_by', 'updated_at'] # 合并字段
如果使用多重继承，特别是当基类包含 Meta 类时 (如 ModelSerializer)，需要注意 MRO (Method Resolution Order) 和 Meta 属性的继承与覆盖。通常，将非 ModelSerializer 的基类放在前面，或者显式合并 Meta 中的属性。
序列化器是 DRF 的核心，它们在 API 的数据输入和输出中扮演着至关重要的角色。熟练掌握序列化器的各种特性是构建高质量 DRF API 的基础。
*(因内容长度限制，后续部分将在下一个响应中继续。当前已生成大量关于序列化器的内容，接下来将是 Request 和 Response 对象。)*好的，我们继续深入 Django REST framework (DRF) 的核心组件。
Request 对象 (Request Object)
DRF 的 Request 对象扩展了 Django 标准的 HttpRequest 对象，为处理 API 请求提供了更方便的功能。当 DRF 的视图 (如 APIView 或 ViewSet 的子类) 处理请求时，传入视图方法的 request 参数将是 DRF 的 Request 实例。
1. DRF Request vs Django HttpRequest
Django HttpRequest:
request.GET: 一个类字典对象，包含所有 HTTP GET 参数。
request.POST: 一个类字典对象，包含所有 HTTP POST 参数，前提是请求的 Content-Type 是 application/x-www-form-urlencoded 或 multipart/form-data。对于其他类型的请求体 (如 JSON)，request.POST 会是空的。
request.body: 包含原始 HTTP 请求体的字节字符串。对于 JSON 等数据，你需要手动解析，例如 json.loads(request.body)。
request.FILES: 包含所有上传的文件。
request.user: 如果使用了 Django 的认证中间件，并且用户已认证，则为 User 对象实例；否则为 AnonymousUser 实例。
request.session: 如果启用了会话中间件，则为可读写的类字典对象。
DRF Request:
request.data: 这是 DRF Request 对象最重要的属性之一。它返回请求体的解析内容，支持多种内容类型。DRF 会根据请求的 Content-Type header 自动选择合适的解析器 (Parser) 来解析请求体。
对于 application/json，request.data 会是解析后的 Python 字典或列表。
对于 application/x-www-form-urlencoded 或 multipart/form-data，request.data 的行为类似于 Django 的 request.POST，但也包含了 request.FILES 的内容。
它统一了对不同类型请求体的访问方式。
request.query_params: 类似于 Django request.GET 的别名，用于获取 URL 查询参数。它是一个 QueryDict 实例。
# URL: /api/items/?category=electronics&page=2
# request.query_params['category'] -> 'electronics'
# request.query_params.get('page') -> '2'
request.user: 与 Django 的 request.user 类似，但其值取决于 DRF 配置的认证类 (Authentication classes)。
如果认证成功，request.user 将是认证后的用户对象 (通常是 Django User 实例)。
如果认证失败或未提供凭证，request.user 通常会是 django.contrib.auth.models.AnonymousUser 的实例。
request.auth: 如果认证成功，并且认证类设置了此属性，request.auth 会包含额外的认证信息。
例如，对于 TokenAuthentication，request.auth 会是成功验证的 Token 实例。
对于 JWT 认证，它可能是解码后的 token payload 或相关信息。
如果认证失败或凭证无效，request.auth 通常是 None。
request.authenticators: 一个列表，包含在处理此请求时尝试进行身份验证的认证器实例。
request.parser_context: 一个包含解析器额外上下文的字典，例如视图、请求、参数等。
request.content_type: 请求的 Content-Type header 的值。
request.stream: 一个可以读取请求体内容的类文件流。request.data 就是通过解析这个流得到的。
2. request.data 详解
request.data 是处理 API 输入数据的核心。DRF 的解析器 (Parsers) 负责填充 request.data。默认启用的解析器通常包括：
JSONParser: 解析 JSON 请求体。
FormParser: 解析 HTML 表单数据 (application/x-www-form-urlencoded)。
MultiPartParser: 解析多部分 HTML 表单数据 (multipart/form-data)，支持文件上传。
# myapp/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from rest_framework.parsers import JSONParser, FormParser # 导入解析器
class DataTestView(APIView):
# 可以为特定视图配置解析器，覆盖全局设置
# parser_classes = [JSONParser, FormParser] # 如果未指定，则使用 settings.py 中的全局默认值
def post(self, request, *args, **kwargs): # request 是 DRF 的 Request 对象
print(f"Request Content-Type: {
request.content_type}") # 打印请求的内容类型
print(f"Request Data: {
request.data}") # 打印解析后的请求数据
# request.data 可以直接传递给序列化器
# serializer = YourSerializer(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)
name = request.data.get('name') # 从 request.data 中获取 'name' 字段
age = request.data.get('age') # 获取 'age' 字段
if not name:
return Response({
'error': 'Name is required.'}, status=status.HTTP_400_BAD_REQUEST) # 返回错误响应
return Response({
# 返回成功响应
'message': 'Data received successfully.',
'name_received': name,
'age_received': age
}, status=status.HTTP_200_OK)
def get(self, request, *args, **kwargs): # 处理 GET 请求
# GET 请求通常没有请求体，参数在 URL 查询字符串中
search_term = request.query_params.get('search', None) # 从查询参数中获取 'search'
page = request.query_params.get('page', 1) # 获取 'page'，默认为 1
response_data = {
'message': 'GET request processed.',
'search_term': search_term,
'page': page
}
# 模拟数据查询
# items = YourModel.objects.filter(name__icontains=search_term) if search_term else YourModel.objects.all()
# ... 分页逻辑 ...
return Response(response_data, status=status.HTTP_200_OK)
使用示例 (假设上述视图配置在 /api/data-test/)
发送 JSON POST 请求:
curl -X POST http://localhost:8000/api/data-test/
-H "Content-Type: application/json"
-d '{"name": "Alice", "age": 30}'
服务器端 request.data 将是 {'name': 'Alice', 'age': 30}。
发送 Form POST 请求:
curl -X POST http://localhost:8000/api/data-test/
-d "name=Bob&age=25"
服务器端 request.data 将是 QueryDict({'name': ['Bob'], 'age': ['25']}) (类似字典，但值是列表)。
发送 GET 请求:
curl http://localhost:8000/api/data-test/?search=productX&page=3
服务器端 request.query_params 将是 QueryDict({'search': ['productX'], 'page': ['3']})。
3. request.query_params
这是 request.GET 的一个更明确的别名，用于访问 URL 中的查询参数 (query string)。它是一个 django.http.QueryDict 实例，这意味着如果一个参数在 URL 中出现多次，query_params.getlist('param_name') 会返回一个包含所有值的列表。
# URL: /api/items?tags=python&tags=django&status=active
# request.query_params.get('tags') -> 'django' (只获取最后一个)
# request.query_params.getlist('tags') -> ['python', 'django'] (获取所有同名参数的值列表)
# request.query_params.get('status') -> 'active'
4. request.user 和 request.auth
这两个属性与 DRF 的认证系统紧密相关。
request.user:
在 DRF 的 APIView 中，会依次调用 settings.DEFAULT_AUTHENTICATION_CLASSES 中定义的认证类来尝试认证用户。
第一个成功认证的认证类会设置 request.user 和 request.auth。
如果所有认证类都失败，或者请求未提供认证凭证，request.user 通常是 AnonymousUser 的实例。
request.auth:
存储与成功认证相关的令牌或其他凭证信息。
例如，使用 TokenAuthentication 时，如果请求头中提供了有效的 Authorization: Token <your_token>，则 request.user 是对应的用户对象，request.auth 是该用户的 Token 模型实例。
如果认证失败，request.auth 通常是 None。
这些属性在权限检查 (Permissions) 中非常重要，因为权限类通常会检查 request.user 是否已认证，或者是否具有特定权限。
# myapp/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.permissions import IsAuthenticated # 导入权限类
class ProfileView(APIView):
permission_classes = [IsAuthenticated] # 要求用户必须已认证才能访问此视图
def get(self, request, *args, **kwargs):
user = request.user # 获取当前认证的用户对象
auth_token = request.auth # 获取与认证相关的 token 或其他信息 (如果认证类设置了它)
return Response({
'username': user.username,
'email': user.email,
'is_staff': user.is_staff,
'auth_info': str(auth_token) # 将 auth_token 转为字符串以便显示
})
如果未认证的用户尝试访问 /api/profile/，他们会收到 401 Unauthorized 或 403 Forbidden 响应 (取决于认证和权限的具体配置)。
5. 内容协商 (Content Negotiation)
DRF 的 Request 对象也参与内容协商过程的一部分，主要是通过 request.content_type 属性。内容协商决定了如何解析请求体 (由 Parsers 处理) 以及如何格式化响应体 (由 Renderers 处理)。
请求解析 (Request Parsing):
客户端在请求的 Content-Type header 中指明请求体的媒体类型 (如 application/json, multipart/form-data)。
DRF 的 APIView (或其子类) 会遍历其 parser_classes 列表。
它会找到第一个能够处理 request.content_type 的解析器，并用它来解析 request.stream (原始请求体) 并填充 request.data。
如果没有解析器能处理该 Content-Type，或者解析失败，会引发 UnsupportedMediaType (415) 或 ParseError (400) 异常。
DRF 的 Request 对象为 API 视图提供了一个统一且强大的接口来处理传入的请求数据和认证信息，极大地简化了 API 逻辑的编写。
Response 对象 (Response Object)
DRF 的 Response 对象是 Django HttpResponse 的子类，但它允许你在返回响应之前不立即渲染内容。相反，它接收原生 Python 数据 (如字典、列表、模型实例等)，并使用内容协商来确定如何将其渲染为最终的响应内容 (如 JSON、XML)。
1. DRF Response 的特点
数据驱动 (Data-driven): 你传递给 Response 的是 Python 数据，而不是预先渲染好的字符串。
# 错误的方式 (直接传递渲染后的 JSON 字符串给 Django HttpResponse)
# from django.http import HttpResponse
# import json
# data = {'message': 'Hello'}
# return HttpResponse(json.dumps(data), content_type='application/json')
# 正确的方式 (使用 DRF Response)
from rest_framework.response import Response
data = {
'message': 'Hello'}
return Response(data) # DRF 会负责内容协商和渲染
内容协商 (Content Negotiation):
Response 对象会根据客户端请求的 Accept header 和视图配置的 renderer_classes 来选择合适的渲染器 (Renderer)。
渲染器负责将 Python 数据转换为特定媒体类型的字节流 (如 JSON 字符串)。
这允许同一个 API 端点根据客户端的需求返回不同格式的数据。
状态码 (Status Codes):
可以方便地通过 status 参数指定 HTTP 状态码。DRF 在 rest_framework.status 模块中提供了一系列常用的状态码常量 (如 status.HTTP_200_OK, status.HTTP_201_CREATED, status.HTTP_400_BAD_REQUEST 等)。
from rest_framework import status
return Response({
'error': 'Not found'}, status=status.HTTP_404_NOT_FOUND)
自定义 Headers (Custom Headers):
可以像 Django HttpResponse 一样设置自定义 HTTP 头部。
response = Response(data, status=status.HTTP_200_OK)
response['X-Custom-Header'] = 'MyValue'
response['Cache-Control'] = 'no-cache'
return response
# 或者在初始化时传入 headers 字典
# return Response(data, status=status.HTTP_200_OK, headers={'X-Custom-Header': 'MyValue'})
2. Response 的参数
Response(data=None, status=None, template_name=None, headers=None, exception=False, content_type=None)
data: 要序列化并包含在响应体中的数据。通常是序列化器 serializer.data 的输出，或者一个 Python 字典/列表。如果为 None，响应体将为空 (例如对于 204 No Content 响应)。
status: HTTP 状态码。例如 status.HTTP_201_CREATED。如果未提供，默认为 200 OK (除非 data 为 None 且未指定状态码，则默认为 204 No Content)。
template_name: 如果使用了 HTMLRenderer (例如 DRF 的可浏览 API)，可以指定用于渲染 HTML 的模板名称。
headers: 一个包含额外 HTTP 头部的字典。
exception: (布尔型) 如果为 True，并且 data 是一个 Exception 实例，DRF 会尝试使用其异常处理机制来格式化错误响应。通常由 DRF 内部使用。
content_type: 覆盖内容协商，强制使用此内容类型。通常应避免使用，让内容协商机制自动处理。
3. 使用示例
# myapp/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from .models import Product
from .serializers import ProductSerializer # 假设已有 ProductSerializer
class ProductListCreateView(APIView):
def get(self, request, *args, **kwargs): # 处理 GET 请求，列出产品
products = Product.objects.all() # 获取所有产品对象
serializer = ProductSerializer(products, many=True, context={
'request': request}) # 序列化产品列表，传入 request 上下文用于超链接等
return Response(serializer.data, status=status.HTTP_200_OK) # 返回序列化后的数据和 200 OK 状态
def post(self, request, *args, **kwargs): # 处理 POST 请求，创建新产品
serializer = ProductSerializer(data=request.data, context={
'request': request}) # 使用请求数据初始化序列化器
if serializer.is_valid(): # 验证数据
serializer.save() # 如果有效，保存数据 (调用序列化器的 create 方法)
return Response(serializer.data, status=status.HTTP_201_CREATED) # 返回新创建的产品数据和 201 Created 状态
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST) # 如果无效，返回错误信息和 400 Bad Request 状态
class ProductDetailView(APIView):
def get_object(self, pk): # 辅助方法，获取单个产品对象
try:
return Product.objects.get(pk=pk)
except Product.DoesNotExist:
return None
def get(self, request, pk, *args, **kwargs): # 处理 GET 请求，获取单个产品详情
product = self.get_object(pk)
if product is None:
return Response({
'error': 'Product not found.'}, status=status.HTTP_404_NOT_FOUND) # 产品不存在，返回 404
serializer = ProductSerializer(product, context={
'request': request})
return Response(serializer.data, status=status.HTTP_200_OK)
def put(self, request, pk, *args, **kwargs): # 处理 PUT 请求，完整更新产品
product = self.get_object(pk)
if product is None:
return Response({
'error': 'Product not found.'}, status=status.HTTP_404_NOT_FOUND)
serializer = ProductSerializer(product, data=request.data, context={
'request': request}) # 使用实例和新数据初始化序列化器
if serializer.is_valid():
serializer.save() # 调用序列化器的 update 方法
return Response(serializer.data, status=status.HTTP_200_OK)
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
def patch(self, request, pk, *args, **kwargs): # 处理 PATCH 请求，部分更新产品
product = self.get_object(pk)
if product is None:
return Response({
'error': 'Product not found.'}, status=status.HTTP_404_NOT_FOUND)
# partial=True 允许部分更新，序列化器不会要求所有字段都存在于 request.data 中
serializer = ProductSerializer(product, data=request.data, partial=True, context={
'request': request})
if serializer.is_valid():
serializer.save()
return Response(serializer.data, status=status.HTTP_200_OK)
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
def delete(self, request, pk, *args, **kwargs): # 处理 DELETE 请求，删除产品
product = self.get_object(pk)
if product is None:
return Response({
'error': 'Product not found.'}, status=status.HTTP_404_NOT_FOUND)
product.delete() # 删除产品对象
return Response(status=status.HTTP_204_NO_CONTENT) # 删除成功，返回 204 No Content 状态 (响应体为空)
4. 内容协商与 Renderers
当 Response 对象在视图方法中被返回时，DRF 的 APIView 会执行以下步骤来渲染响应：
选择渲染器 (Renderer Selection):
视图会检查其 renderer_classes 属性 (或全局默认的 DEFAULT_RENDERER_CLASSES)。
同时，它会查看客户端请求的 Accept HTTP header。这个 header 表明客户端可以理解哪些媒体类型，通常会带有一个优先级列表 (q-factors)。例如: Accept: application/json; q=0.9, application/xml; q=0.8, */*; q=0.1。
DRF 会尝试在 renderer_classes 中找到一个与 Accept header 匹配的、且优先级最高的渲染器。
如果 Accept header 未提供或不匹配任何可用渲染器，通常会使用 renderer_classes 中的第一个渲染器作为默认。
常见的内置渲染器有 JSONRenderer (默认), BrowsableAPIRenderer (用于生成可浏览的 HTML API 界面), XMLRenderer (需要额外安装 djangorestframework-xml)等。
渲染数据 (Data Rendering):
选定的渲染器会调用其 render(data, accepted_media_type, renderer_context) 方法。
data 是你传递给 Response 对象的 Python 数据。
accepted_media_type 是协商后确定的媒体类型 (例如 'application/json')。
renderer_context 是一个包含视图、请求、响应等信息的字典。
render() 方法负责将 data 转换为该媒体类型的字节串，并设置响应的 Content-Type header。
例如，如果 JSONRenderer 被选中，它会使用 json.dumps() (或一个可配置的 JSON 编码器) 将数据转换为 JSON 字符串。如果 BrowsableAPIRenderer 被选中 (通常当浏览器直接访问 API 时，其 Accept header 会包含 text/html)，它会使用 Django 模板将数据渲染成一个用户友好的 HTML 页面。
你可以通过在 settings.py 中配置 REST_FRAMEWORK 来设置全局默认的渲染器和解析器：
# settings.py
REST_FRAMEWORK = {
'DEFAULT_RENDERER_CLASSES': [
'rest_framework.renderers.JSONRenderer', # 默认返回 JSON
'rest_framework.renderers.BrowsableAPIRenderer', # 如果浏览器请求，则显示可浏览API
],
'DEFAULT_PARSER_CLASSES': [
'rest_framework.parsers.JSONParser',
'rest_framework.parsers.FormParser',
'rest_framework.parsers.MultiPartParser',
],
# ... 其他 DRF 设置 ...
}
也可以在单个视图或视图集上覆盖这些设置：
# myapp/views.py
from rest_framework.renderers import JSONRenderer, XMLRenderer # 假设已安装 djangorestframework-xml
from rest_framework.parsers import JSONParser
class MyCustomView(APIView):
renderer_classes = [JSONRenderer, XMLRenderer] # 此视图支持 JSON 和 XML 输出
parser_classes = [JSONParser] # 此视图只接受 JSON 输入
# ...
DRF 的 Response 对象与内容协商机制的结合，使得构建能够适应不同客户端需求的灵活 API 变得简单。
APIView 与视图集 (APIView and ViewSets)
DRF 提供了不同级别的视图抽象，用于处理 API 请求和构建响应。
1. APIView (基类)
APIView 是 DRF 中所有视图的基类，它继承自 Django 的 View 类，并为其添加了 API 特有的行为：
请求对象: 传入视图方法的 request 不再是 Django 的 HttpRequest，而是 DRF 的 Request 实例。
响应对象: 视图方法应返回 DRF 的 Response 实例，而不是 Django 的 HttpResponse。
认证 (Authentication): APIView 会在分发到处理方法 (如 get(), post()) 之前执行认证检查。
权限 (Permissions): 在认证之后、分发到处理方法之前执行权限检查。
限流 (Throttling): 在认证和权限检查之后、分发到处理方法之前执行限流检查。
内容协商 (Content Negotiation): 自动处理请求解析 (Parsers) 和响应渲染 (Renderers)。
异常处理 (Exception Handling): 捕获在视图中抛出的特定异常 (如 Http404, DRF 的 APIException 子类等)，并返回合适的错误 Response。
核心属性和方法:
authentication_classes: 一个类元组或列表，定义了用于此视图的认证方案。默认为 settings.DEFAULT_AUTHENTICATION_CLASSES。
permission_classes: 一个类元组或列表，定义了用于此视图的权限检查。默认为 settings.DEFAULT_PERMISSION_CLASSES。
throttle_classes: 一个类元组或列表，定义了用于此视图的限流策略。默认为 settings.DEFAULT_THROTTLE_CLASSES。
parser_classes: 定义可接受的请求媒体类型。
renderer_classes: 定义可生成的响应媒体类型。
HTTP 方法处理: APIView 通过将请求分派给与 HTTP 方法同名的处理函数来工作，例如：
def get(self, request, *args, **kwargs): ...
def post(self, request, *args, **kwargs): ...
def put(self, request, *args, **kwargs): ...
def patch(self, request, *args, **kwargs): ...
def delete(self, request, *args, **kwargs): ...
def head(self, request, *args, **kwargs): ...
def options(self, request, *args, **kwargs): ...
def trace(self, request, *args, **kwargs): ...
我们在前面的 ProductListCreateView 和 ProductDetailView 示例中已经看到了 APIView 的用法。它为构建独立的、具有特定行为的 API 端点提供了坚实的基础。
# myapp/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from rest_framework.permissions import IsAuthenticated
from .serializers import ProductSerializer # 假设存在
from .models import Product # 假设存在
class ProductRudView(APIView): # RUD = Retrieve, Update, Delete
permission_classes = [IsAuthenticated] # 示例：需要认证
def get_object(self, pk):
try:
return Product.objects.get(pk=pk)
except Product.DoesNotExist:
# from django.http import Http404 # 可以直接抛出 Django 的 Http404
# raise Http404
return None # 或者返回 None，在调用处处理
def get(self, request, pk, format=None): # format 参数由 DRF 自动处理，用于内容协商后缀 (如 .json)
product = self.get_object(pk)
if product is None:
return Response({
'detail': 'Not found.'}, status=status.HTTP_404_NOT_FOUND)
serializer = ProductSerializer(product, context={
'request': request})
return Response(serializer.data)
def put(self, request, pk, format=None):
product = self.get_object(pk)
if product is None:
return Response({
'detail': 'Not found.'}, status=status.HTTP_404_NOT_FOUND)
serializer = ProductSerializer(product, data=request.data, context={
'request': request})
if serializer.is_valid():
serializer.save()
return Response(serializer.data)
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
def delete(self, request, pk, format=None):
product = self.get_object(pk)
if product is None:
return Response({
'detail': 'Not found.'}, status=status.HTTP_404_NOT_FOUND)
product.delete()
return Response(status=status.HTTP_204_NO_CONTENT)
# myapp/urls.py
# from django.urls import path
# from .views import ProductRudView
# urlpatterns = [
# path('products/<int:pk>/', ProductRudView.as_view(), name='product-rud'),
# ]
2. GenericAPIView (通用视图)
GenericAPIView 继承自 APIView，并添加了处理单个模型实例列表和详情的常用行为。它本身不提供任何 HTTP 方法处理函数 (如 get, post)，而是提供了构建这些方法所需的核心功能和属性，通常与一个或多个 Mixin 类 结合使用。
核心属性:
queryset: 此视图将用于返回对象的查询集。必须设置，或者重写 get_queryset() 方法。
serializer_class: 用于验证和反序列化输入以及序列化输出的序列化器类。必须设置，或者重写 get_serializer_class() 方法。
lookup_field: 用于执行单个模型实例查找的模型字段。默认为 'pk'。
lookup_url_kwarg: 用于对象查找的 URL 关键字参数。如果未设置，则默认为与 lookup_field相同的值。
filter_backends: 一个过滤后端类列表，用于过滤查询集 (例如搜索、排序)。
pagination_class: 一个分页类，用于对列表结果进行分页。
核心方法:
get_queryset(): 返回用于视图的查询集。默认返回 self.queryset。
get_object(): 返回用于详情视图的单个对象实例。默认使用 self.lookup_field 从 get_queryset() 的结果中查找。如果找不到对象，会抛出 Http404。
get_serializer_class(): 返回用于实例化序列化器的类。默认返回 self.serializer_class。
get_serializer_context(): 返回应传递给序列化器的额外上下文。默认包含 request, format, view。
get_serializer(*args, **kwargs): 返回一个序列化器实例。
filter_queryset(queryset): 给定一个查询集，使用配置的过滤后端对其进行过滤，并返回一个新的查询集。
paginate_queryset(queryset): 对查询集进行分页，并返回一个页面对象，或者如果未配置分页则返回 None。
get_paginated_response(data): 接收序列化后的页面数据，并返回一个 Response 对象。
GenericAPIView 单独使用时，你需要自己实现 get(), post() 等方法，并在其中调用上述辅助方法。
# myapp/views.py
from rest_framework.generics import GenericAPIView
# ... (其他导入与 ProductRudView 类似) ...
class ProductDetailGenericView(GenericAPIView):
queryset = Product.objects.all() # 指定查询集
serializer_class = ProductSerializer # 指定序列化器类
# lookup_field = 'pk' # 默认为 'pk'
def get(self, request, pk, *args, **kwargs): # 实现 GET 方法
instance = self.get_object() # 调用 GenericAPIView 的 get_object() 获取对象
serializer = self.get_serializer(instance) # 调用 get_serializer() 获取序列化器实例
return Response(serializer.data)
def put(self, request, pk, *args, **kwargs): # 实现 PUT 方法
instance = self.get_object()
serializer = self.get_serializer(instance, data=request.data)
serializer.is_valid(raise_exception=True) # is_valid() 可以抛出异常，会被 DRF 捕获并返回错误响应
serializer.save()
return Response(serializer.data)
# myapp/urls.py
# from django.urls import path
# from .views import ProductDetailGenericView
# urlpatterns = [
# path('products-generic/<int:pk>/', ProductDetailGenericView.as_view(), name='product-detail-generic'),
# ]
3. Mixins (混合类)
Mixin 类提供了实现基本视图行为的动作 (actions)。它们与 GenericAPIView 结合使用，可以快速构建出具有标准 CRUD (Create, Retrieve, Update, Delete) 功能的视图。
主要的 Mixin 类：
CreateModelMixin:
提供 .create(request, *args, **kwargs) 方法。
实现了创建和保存新模型实例的逻辑。
通常映射到 HTTP POST 方法。
ListModelMixin:
提供 .list(request, *args, **kwargs) 方法。
实现了列出查询集的逻辑 (支持分页和过滤)。
通常映射到 HTTP GET 方法 (用于列表)。
RetrieveModelMixin:
提供 .retrieve(request, *args, **kwargs) 方法。
实现了检索单个模型实例的逻辑。
通常映射到 HTTP GET 方法 (用于详情)。
UpdateModelMixin:
提供 .update(request, *args, **kwargs) 方法。
实现了更新和保存现有模型实例的逻辑。支持完整更新 (PUT) 和部分更新 (PATCH)。
需要重写 perform_update(serializer) (可选) 来自定义更新行为。
通常映射到 HTTP PUT 和 PATCH 方法。
DestroyModelMixin:
提供 .destroy(request, *args, **kwargs) 方法。
实现了删除现有模型实例的逻辑。
需要重写 perform_destroy(instance) (可选) 来自定义删除行为。
通常映射到 HTTP DELETE 方法。
通过组合 GenericAPIView 和这些 Mixin，可以轻松创建视图：
# myapp/views.py
from rest_framework import mixins
from rest_framework.generics import GenericAPIView
# ... (其他导入) ...
class ProductListCreateWithMixinsView(mixins.ListModelMixin, # 提供 list 行为
mixins.CreateModelMixin, # 提供 create 行为
GenericAPIView): # 基础通用视图
queryset = Product.objects.all()
serializer_class = ProductSerializer
def get(self, request, *args, **kwargs): # 将 GET 请求映射到 ListModelMixin 的 list 方法
return self.list(request, *args, **kwargs)
def post(self, request, *args, **kwargs): # 将 POST 请求映射到 CreateModelMixin 的 create 方法
return self.create(request, *args, **kwargs)
class ProductRetrieveUpdateDestroyWithMixinsView(mixins.RetrieveModelMixin, # 检索
mixins.UpdateModelMixin, # 更新 (PUT, PATCH)
mixins.DestroyModelMixin, # 删除
GenericAPIView):
queryset = Product.objects.all()
serializer_class = ProductSerializer
# lookup_field = 'pk' # 默认
def get(self, request, *args, **kwargs): # GET (详情) -> retrieve
return self.retrieve(request, *args, **kwargs)
def put(self, request, *args, **kwargs): # PUT -> update (完整)
return self.update(request, *args, **kwargs)
def patch(self, request, *args, **kwargs): # PATCH -> update (部分)
# UpdateModelMixin 的 update 方法会自动处理 partial=True
return self.partial_update(request, *args, **kwargs)
def delete(self, request, *args, **kwargs): # DELETE -> destroy
return self.destroy(request, *args, **kwargs)
# myapp/urls.py
# from django.urls import path
# from .views import ProductListCreateWithMixinsView, ProductRetrieveUpdateDestroyWithMixinsView
# urlpatterns = [
# path('mixin-products/', ProductListCreateWithMixinsView.as_view(), name='mixin-product-list-create'),
# path('mixin-products/<int:pk>/', ProductRetrieveUpdateDestroyWithMixinsView.as_view(), name='mixin-product-rud'),
# ]
4. 具体通用视图 (Concrete Generic Views)
DRF 提供了一系列预先组合好的具体通用视图，它们直接继承自 GenericAPIView 和相应的 Mixin 类。这使得创建标准 CRUD 端点更加简洁。
CreateAPIView: 用于只创建实例的端点 (继承 GenericAPIView, CreateModelMixin)。提供 post 方法。
ListAPIView: 用于只读的实例列表端点 (继承 GenericAPIView, ListModelMixin)。提供 get 方法。
RetrieveAPIView: 用于只读的单个实例端点 (继承 GenericAPIView, RetrieveModelMixin)。提供 get 方法。
DestroyAPIView: 用于只删除单个实例的端点 (继承 GenericAPIView, DestroyModelMixin)。提供 delete 方法。
UpdateAPIView: 用于只更新单个实例的端点 (继承 GenericAPIView, UpdateModelMixin)。提供 put 和 patch 方法。
ListCreateAPIView: 用于读写实例列表的端点 (继承 GenericAPIView, ListModelMixin, CreateModelMixin)。提供 get 和 post 方法。
RetrieveUpdateAPIView: 用于读或更新单个实例的端点 (继承 GenericAPIView, RetrieveModelMixin, UpdateModelMixin)。提供 get, put, patch 方法。
RetrieveDestroyAPIView: 用于读或删除单个实例的端点 (继承 GenericAPIView, RetrieveModelMixin, DestroyModelMixin)。提供 get, delete 方法。
RetrieveUpdateDestroyAPIView: 用于读、写、删单个实例的端点 (继承 GenericAPIView, RetrieveModelMixin, UpdateModelMixin, DestroyModelMixin)。提供 get, put, patch, delete 方法。
使用具体通用视图非常简单，通常只需要设置 queryset 和 serializer_class：
# myapp/views.py
from rest_framework import generics # 导入具体通用视图模块
# ... (Product, ProductSerializer 导入) ...
class ProductListCreateConcreteView(generics.ListCreateAPIView): # 直接使用 ListCreateAPIView
queryset = Product.objects.all()
serializer_class = ProductSerializer
# permission_classes = [...] # 可以在这里添加权限等
class ProductRetrieveUpdateDestroyConcreteView(generics.RetrieveUpdateDestroyAPIView): # 直接使用 RetrieveUpdateDestroyAPIView
queryset = Product.objects.all()
serializer_class = ProductSerializer
# lookup_field = 'pk' # 默认
# permission_classes = [...]
# myapp/urls.py
# from django.urls import path
# from .views import ProductListCreateConcreteView, ProductRetrieveUpdateDestroyConcreteView
# urlpatterns = [
# path('concrete-products/', ProductListCreateConcreteView.as_view(), name='concrete-product-list-create'),
# path('concrete-products/<int:pk>/', ProductRetrieveUpdateDestroyConcreteView.as_view(), name='concrete-product-rud'),
# ]
这是构建标准 CRUD API 端点最常用和推荐的方式之一，因为它非常简洁且遵循 DRY 原则。
5. ViewSet (视图集)
ViewSet 允许开发者将一组相关的视图逻辑组织到一个类中。它不再像 APIView 那样直接将 HTTP 方法 (如 get, post) 映射到方法，而是映射到更具表述性的动作名称 (如 list, create, retrieve, update, partial_update, destroy)。
ViewSet 通常与 Router 类结合使用，Router 可以自动为 ViewSet 生成 URL 配置。
ViewSet 基类:
继承自 APIView。
不提供任何默认的动作实现。你需要自己实现动作方法，或者通过混入 Mixin 类来提供。
在 URL 绑定时，HTTP 方法会映射到动作。例如，GET 请求可以映射到 list (列表) 或 retrieve (详情) 动作。
GenericViewSet:
继承自 ViewSet 和 GenericAPIView。
提供了 GenericAPIView 的所有基础行为 (如 get_queryset(), get_object(), get_serializer() 等)，但本身不包含任何动作的实现。
需要与 Mixin 类结合使用来提供 list, create 等动作。
# myapp/views.py
from rest_framework import viewsets
from rest_framework import mixins
# ... (Product, ProductSerializer 导入) ...
class ProductGenericViewSet(mixins.ListModelMixin,
mixins.RetrieveModelMixin,
viewsets.GenericViewSet): # 继承 GenericViewSet 和所需的 Mixins
queryset = Product.objects.all()
serializer_class = ProductSerializer
# lookup_field = 'pk'
# GenericViewSet 配合 Mixins 后，list 和 retrieve 动作就自动可用了
# 无需再写 get 方法并手动调用 self.list() 或 self.retrieve()
ModelViewSet (重点):
继承自 GenericViewSet 和所有 CRUD Mixin (CreateModelMixin, RetrieveModelMixin, UpdateModelMixin, ListModelMixin, DestroyModelMixin)。
提供了一整套标准的读写操作 (list, create, retrieve, update, partial_update, destroy) 的完整实现。
这是构建标准 CRUD API 最便捷的方式，通常只需要设置 queryset 和 serializer_class。
# myapp/views.py
from rest_framework import viewsets
# ... (Product, ProductSerializer 导入) ...
class ProductModelViewSet(viewsets.ModelViewSet): # 直接继承 ModelViewSet
queryset = Product.objects.all().order_by('-created_at') # 可以自定义查询集，例如排序
serializer_class = ProductSerializer
# permission_classes = [IsAuthenticatedOrReadOnly] # 示例：设置权限
# filter_backends = [DjangoFilterBackend, filters.SearchFilter, filters.OrderingFilter] # 示例：配置过滤后端
# filterset_fields = ['category', 'available'] # 用于 DjangoFilterBackend
# search_fields = ['name', 'description'] # 用于 SearchFilter
# ordering_fields = ['price', 'created_at'] # 用于 OrderingFilter
# pagination_class = PageNumberPagination # 示例：设置分页
ReadOnlyModelViewSet:
继承自 GenericViewSet, ListModelMixin, RetrieveModelMixin。
提供只读操作 (list, retrieve)。
# myapp/views.py
class CategoryReadOnlyViewSet(viewsets.ReadOnlyModelViewSet): # 只读视图集
queryset = Category.objects.all() # 假设 Category 模型存在
serializer_class = CategorySerializer # 假设 CategorySerializer 存在
自定义 ViewSet 动作 (Custom ViewSet Actions)
除了标准的 CRUD 动作，你还可以使用 @action 装饰器向 ViewSet 添加自定义的路由端点。
# myapp/views.py
from rest_framework import viewsets, status
from rest_framework.decorators import action # 导入 action 装饰器
from rest_framework.response import Response
from django.shortcuts import get_object_or_404
# ... (Product, ProductSerializer 导入) ...
class ProductModelViewSetWithActions(viewsets.ModelViewSet):
queryset = Product.objects.all()
serializer_class = ProductSerializer
# detail=True 表示这个动作是针对单个实例的 (URL 会包含 pk)
# URL 将是 /products/{pk}/publish/
# methods=['post'] 指定允许的 HTTP 方法
@action(detail=True, methods=['post'], url_path='publish', url_name='product-publish')
def publish(self, request, pk=None): # pk 会被传入
product = self.get_object() # get_object() 是 ModelViewSet 提供的
# ... 实现发布的逻辑 ...
product.available = True
product.save()
return Response({
'status': 'product published'}, status=status.HTTP_200_OK)
# detail=False 表示这个动作是针对列表的 (URL 不包含 pk)
# URL 将是 /products/inventory-report/
@action(detail=False, methods=['get'], url_path='inventory-report', url_name='product-inventory-report')
def inventory_report(self, request):
# ... 实现生成库存报告的逻辑 ...
total_stock = Product.objects.aggregate(total=models.Sum('stock'))['total']
return Response({
'total_stock': total_stock})
# 也可以有更复杂的自定义动作，使用不同的序列化器等
@action(detail=True, methods=['put'], serializer_class=ProductStockUpdateSerializer, url_path='update-stock') # 使用不同的序列化器
def update_stock_custom(self, request, pk=None):
product = self.get_object()
serializer = self.get_serializer(data=request.data) # get_serializer 会使用 action 中指定的 serializer_class
if serializer.is_valid():
product.stock = serializer.validated_data['stock']
# ... 其他更新逻辑 ...
product.save(update_fields=['stock'])
return Response(ProductSerializer(product, context={
'request':request}).data) # 返回用主序列化器格式化的产品
else:
return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)
@action 的参数：
detail: (布尔型) True 表示动作作用于单个实例，False 表示作用于列表。
methods: 一个 HTTP 方法字符串列表 (例如 ['get', 'post'])。
url_path: (可选) URL 中此动作的路径片段。默认为方法名。
url_name: (可选) 为此动作生成的 URL 的名称。默认为 <basename>-<methodname>。
permission_classes, serializer_class, parser_classes, renderer_classes, throttle_classes 等: 可以为特定动作覆盖视图集的默认设置。
ViewSets 结合 Routers 是 DRF 中组织和构建 API 的非常强大和高效的方式。
Routers (路由器)
路由器与 ViewSet 配合使用，可以自动生成 URL 配置。这大大减少了为每个视图手动编写 path() 条目的需要。
1. SimpleRouter
SimpleRouter 为标准的 list, create, retrieve, update, partial_update, destroy 动作生成 URL 模式。它不包含 API 根视图。
# myproject/urls.py (或 myapp/urls.py)
from django.urls import path, include
from rest_framework.routers import SimpleRouter # 导入 SimpleRouter
from myapp import views # 假设视图集在 myapp.views 中
# 1. 创建一个路由器实例
router = SimpleRouter()
# 2. 注册 ViewSet
# router.register(r'prefix', ViewSetClass, basename='basename_prefix')
# 'prefix' 是此组 URL 的前缀 (例如 'products')
# 'ViewSetClass' 是你的视图集类 (例如 views.ProductModelViewSet)
# 'basename' (可选) 用于生成 URL 名称的前缀。如果 ViewSet 定义了 queryset，则通常可以省略，DRF 会从模型名推断。
router.register(r'products-simple', views.ProductModelViewSet, basename='product-simple')
# 如果 ProductModelViewSetWithActions 也注册了:
router.register(r'products-actions', views.ProductModelViewSetWithActions, basename='product-actions')
router.register(r'categories-readonly', views.CategoryReadOnlyViewSet, basename='category-readonly')
# 3. 将路由器生成的 URL 添加到 urlpatterns
# urlpatterns 通常在项目级 urls.py 中
# urlpatterns = [
# path('admin/', admin.site.urls),
# path('api/', include(router.urls)), # 将路由器生成的 URL 包含在 'api/' 前缀下
# ]
# 如果在应用级 urls.py 中使用：
# app_name = 'myapp' # 最好定义 app_name 以便 URL 反向解析
# urlpatterns = [
# # ... 其他应用内 URL ...
# ]
# urlpatterns += router.urls # 直接追加
# 或者
# urlpatterns = [
# path('', include(router.urls)), # 如果整个应用都由这个 router 管理
# ]
对于 ProductModelViewSet (假设 basename='product')，SimpleRouter 会生成类似以下的 URL 模式：
/products-simple/
GET: list (列出所有产品)
POST: create (创建新产品)
/products-simple/{pk}/
GET: retrieve (获取 ID 为 pk 的产品)
PUT: update (完整更新 ID 为 pk 的产品)
PATCH: partial_update (部分更新 ID 为 pk 的产品)
DELETE: destroy (删除 ID 为 pk 的产品)
对于 ProductModelViewSetWithActions 中的自定义动作：
/products-actions/{pk}/publish/ (POST)
/products-actions/inventory-report/ (GET)
2. DefaultRouter
DefaultRouter 与 SimpleRouter 类似，但额外增加了一些功能：
API 根视图: 自动创建一个 API 根视图 (通常在路由前缀的根路径，例如 /api/)，它会列出所有已注册的视图集的超链接。这使得 API 更具可发现性。
.json 格式后缀支持: 自动为生成的 URL 添加对格式后缀的支持 (例如 /products.json/)，允许客户端通过 URL 请求特定格式的响应。
使用方法与 SimpleRouter 完全相同，只需替换类名：
# myproject/urls.py
from django.urls import path, include
from rest_framework.routers import DefaultRouter # 导入 DefaultRouter
from myapp import views
router = DefaultRouter() # 使用 DefaultRouter
router.register(r'products', views.ProductModelViewSet, basename='product') # 使用更简洁的 'products' 前缀
router.register(r'categories', views.CategoryReadOnlyViewSet, basename='category')
# ... 其他注册 ...
urlpatterns = [
path('admin/', admin.site.urls),
path('api/v1/', include(router.urls)), # 路由器 URL 包含在 'api/v1/' 下
# API 根视图将在 /api/v1/
]
当访问 /api/v1/ 时，如果使用了 DefaultRouter 并且视图中配置了 BrowsableAPIRenderer，你将看到一个列出 “products” 和 “categories” 端点链接的页面。
3. 路由器注册 (Registering ViewSets)
router.register(prefix, viewset, basename=None)
prefix: 此视图集 URL 模式的 URL 前缀。
viewset: ViewSet 类。
basename: 用于创建 URL 名称的基础。
如果 ViewSet 有一个 queryset 属性，basename 通常是可选的，路由器会根据 queryset.model._meta.model_name 自动生成它。例如，如果模型是 Product，basename 会是 product。
如果 ViewSet 没有 queryset 属性 (例如，它不是基于模型的，或者你想覆盖默认名称)，则必须提供 basename。
4. URL 命名与反向解析 (URL Naming and Reverse Resolution)
路由器会自动为生成的 URL 命名。名称通常遵循以下模式：
列表视图: {basename}-list (例如 product-list)
详情视图: {basename}-detail (例如 product-detail)
自定义动作 (使用 @action):
如果 @action 中指定了 url_name，则使用该名称。
否则，使用 {basename}-{action_method_name} (例如 product-publish)。
你可以使用 Django 的 reverse() 函数或模板中的 {% url %} 标签来反向解析这些 URL，就像处理普通命名的 URL 一样。
# 在视图或测试中:
from django.urls import reverse
list_url = reverse('product-list') # 假设 basename 是 'product'
# list_url 会是类似 '/api/v1/products/' (取决于路由配置)
detail_url = reverse('product-detail', kwargs={
'pk': 1})
# detail_url 会是类似 '/api/v1/products/1/'
publish_action_url = reverse('product-publish', kwargs={
'pk': 1}) # 假设 action url_name 是 'product-publish'
# publish_action_url 会是类似 '/api/v1/products/1/publish/'
# 在模板中 (例如用于可浏览 API 或邮件模板):
# <a href="{% url 'product-list' %}">View all products</a>
# <a href="{% url 'product-detail' pk=product.id %}">View {
{ product.name }}</a>
如果你的路由嵌套在应用命名空间或实例命名空间下，反向解析时需要包含它们：
# 项目 urls.py: path('api/', include(('myapp.urls', 'myapp_ns'), namespace='myapp_api_ns'))
# 应用 urls.py (myapp.urls): router.register(...)
# 反向解析: reverse('myapp_api_ns:myapp_ns:product-list')
# 或者更常见的是在应用 urls.py 中定义 app_name:
# myapp/urls.py
# app_name = 'myapp'
# router = DefaultRouter()
# router.register(r'products', ProductModelViewSet, basename='product')
# urlpatterns = [path('', include(router.urls))]
# 项目 urls.py
# path('api/myapp/', include('myapp.urls', namespace='myapp-api'))
# 反向解析: reverse('myapp-api:product-list')
路由器是 DRF 中一个非常强大的工具，它极大地简化了 URL 配置，并鼓励使用 ViewSet 来组织相关的 API 逻辑，从而使代码更清晰、更易于维护。
DRF 的这些核心组件——序列化器、请求/响应对象、视图 (APIView, GenericAPIView, ViewSets) 和路由器——共同构成了一个灵活而全面的框架，用于高效构建健壮的 Web API。
![[20220214已更新]鼠标定时点击器1.2 - 宋马](https://bbs.songma.com/song/img/moren.svg)
暂无评论内容