Django REST framework 一个强大灵活的Django工具包，提供了便捷的 REST API 开发框架

我们用传统的django也可以实现REST风格的api，但是顶不住Django REST framework实现起来太简单了

什么REST API风格

主要需要注意这几个：

1. api部署的域名, 主域名或者专有域名
2. 版本, 通过url地址或者请求头accept
3. 路径, 只能有名词, 不能有动词
4. http请求动词, get, post, update, delete
5. 状态, 200, 201, 204, 400, 401, 403, 404
6. 返回json格式数据

例子（仅作参考）：

功能

路径

请求方式

响应状态码（成功）

响应体（成功）

获取所有的书籍

/books

get

200 OK

全部书籍

创建书籍

/books

post

201 Created

已经创建的书籍

获取单个书籍

/books/{id}

get

200 OK

单个书籍

修改书籍

/books/{id}

put

201 Created

已经修改的单个书籍

删除书籍

/books/{id}

delete

204 No Content

无

详细的可以看这里：RESTful 架构详解

关于返回什么，可以看这里：通用设计规则

简单使用流程

在我看来，Django RST framework的主要工作就是对传统django中的view和form在进行了通用性设计。由于使用REST API，我们可以统一使用一样的请求方式，请求参数和请求体，而响应体和状态码也是确定。所以Django RST framework的复用性极高，而且Django RST framework提供了从简单到复杂的封装类，我们只需要直接使用这些类或继承这些类重写部分方法，就可以享受到便利性和可扩展性。

为了显示Django RST framework简单易用，用展示封装程度比较高的类实现一个五个基本功能（get一个、get全部、post创建、put修改单个、delete删除单个）

1. 安装Django RST framework

   $pip install djangorestframework

2. 修改setting文件

   在settings.INSTALLED_APPS中添加rest_framework

   注：添加这个app可以为我们提供测试页面, 假如是使用postman等工具进行测试的话可以不用添加

3. 创建model

   from django.db import models
   
   class Author(models.Model):
       aid = models.AutoField(primary_key=True)
       name = models.CharField(max_length=32, verbose_name="姓名")
       phone = models.CharField(max_length=11, verbose_name="手机号码")
       address = models.CharField(max_length=63, verbose_name="地址")
       def __str__(self):
           return self.name

4. 执行迁移命令

   $python manage.py makemigrations
   $python manage.py migrate

5. 定义序列化器

   在app目录下创建一个serializers.py，在里面定义序列化器：

   from rest_framework.serializers import ModelSerializer
   from rest_test.models import Author
   
   class AuthorSerialize(ModelSerializer):
       class Meta:
           model = Author
           fields = "__all__"

6. 使用视图集

   在views.py中，导入并使用之前的模型和序列化器：

   from rest_framework.viewsets import ModelViewSet
   
   from rest_test.serializers import AuthorSerialize
   from rest_test.models import Author
   
   class AuthorModelViewSet(ModelViewSet):
       queryset = Author.objects.all()
       serializer_class = AuthorSerialize

7. 定义路由规则

   在根路由中定义urlpatterns:

   """djangotest URL Configuration
   """
   from django.contrib import admin
   from django.urls import path
   from rest_test import views
   from rest_framework.routers import SimpleRouter
   
   urlpatterns = [
       path('admin/', admin.site.urls),
   
   ]
   
   router = SimpleRouter()
   
   # 添加自己的url
   router.register('authors', views.AuthorModelViewSet, basename="authors")
   urlpatterns += router.urls

8. 启动django，并访问/authors

   我们就可以看到这样的页面，可以对数据进行增删改查了：

序列化器

序列化器的主要作用就是进行数据转换，即序列化（python的数据类型转换为json等数据类型）和反序列化（json等数据类型转换为python的数据类型）

在反序列化的过程中我们还可以手动验证数据是否合法, 可以与model相结合，完成对数据库的操作

所以说，序列化器和django的Form非常像，所以假如会django的 Form的话，应该很好理解

在定程度上可以类比dango.forms.Form

定义起来非常简单，字段名称对应的是model中的字段名，字段类型和model中的字段有一定的对应关系，参数是一些约束条件和描述信息, 见: 字段和参数

from rest_framework import serializers

class AuthorSerialize(serializers.Serializer):
    aid = serializers.IntegerField(read_only=True,label="作者id")
    name = serializers.CharField(max_length=32, label="姓名")
    phone = serializers.CharField(min_length=11, max_length=11, label="手机号码")
    address = serializers.CharField(max_length=63, label="地址")

字段

这里的参数指的是字段自带的参数，不是像required这样都可以用的参数

仅列出常用的

全部字段都是rest_framework.serializers下的

字段名称

描述

参数

备注

BooleanField

布尔值

无

无论有无指定，默认值都为False, NullBooleanField可以接收None的值

CharField

文本

max_length min_length allow_blank（空字符串是否为有效值）trim_whitespace（True时修剪前后的空白，默认为True

EmailField

电子邮箱

max_length min_length allow_blank（默认为False）

RegexField

文本，通过正则匹配

regex（正则表达式） max_length min_length allow_blank（默认为False）

SlugField

regex为[a-zA-Z0-9_-]+的RegexField字段

就比RegexField少了regex参数

URLField

http://<host>/<path>格式的RegexField

同SlugField

UUIDField

uuid字段

format

该字段的format参数指定的是uuid的格式，见UUIDField

IntegerField

整数

max_value min_value

FloatField

小数

max_value min_value

DateTimeField

时间 年月日时分秒

format（序列化的时间格式） input_formats（反序列化的时间格式） default_timezone（时区）

参数

和form一样，这里指的是通用的参数，不是字段自带的参数

参数

描述

read_only

只读，不能反序列化，如主键，默认是False

Write_only

只写，不能序列化，只在更新和创建数据时使用，默认是False

required

反序列化必须提供的字段，默认为True

default

默认值，在没有提供值时使用，默认不设置

allow_null

允许值为None（一般情况下，如果向序列化字段传递None是会抛出异常的），默认是False

validators

指定验证器列表

error_message

错误代码到错误消息的字典

label

提供可读性高的字段名称

help_text

对字段进行详细描述

全部字段和参数可以查看官方文档：Serializer fields （中文）、Serializer fields （英文）

书接上回，我们已经在serializers.py中定义了一个AuthorSerialize，下面就利用该序列化器进行序列化，即python的转换为json等数据。

序列化一个

步骤：

1. 导入AuthorSerialize和Author模型
2. 使用get获取Author的数据
3. 将数据传给AuthorSerialize的instance参数
4. 使用.data属性（是一个静态属性）获得序列化后的数据

注意：假如你的数据库中没有数据，应该提前将数据创建好，可以用SQL命令也可以用django ORM或借助其他工具

使用django shell执行命令：

$ python manage.py shell
Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from rest_test.serializers import AuthorSerialize
>>> from rest_test.models import Author
>>>
>>> a = Author.objects.get(pk=4)
>>> t = AuthorSerialize(instance=a)
>>> t.data
{'aid': 4, 'name': '张三', 'phone': '1388888888', 'address': '广东省广州市xxxxx'}
>>>

暂时用命令行的方式序列化

序列化多个

序列化器一般是不能序列化多个数据的，需要我们指定参数many=True。同样的，我们先使用django shell执行命令：

$ python manage.py shell
Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from rest_test.serializers import AuthorSerialize
>>> from rest_test.models import Author
>>>
>>> a = Author.objects.all()
>>> t = AuthorSerialize(instance=a, many=True)
>>>
>>> t.data
[OrderedDict([('aid', 4), ('name', '张三'), ('phone', '138888888888'), ('address', '广东省广州市xxxx')]),
OrderedDict([('aid', 5), ('name', '李四'), ('phone', '1388888888'), ('address', '广东省广州市xxxxx')]),
OrderedDict([('aid', 6),('name', '王五'), ('phone', '1388888888'), ('address', '广东省广州市xxxxx')])]

可以看到，data的值是一个OrderedDict数据类型

外键序列化

由于外键在序列化时不知道是使用主键、__str__或整个主键的数据中的一个，所以需要我们手动指定不同的字段实现。

假如我们添加了一个model：

class Author(models.Model):
    aid = models.AutoField(primary_key=True)
    name = models.CharField(max_length=32, verbose_name="姓名")
    phone = models.CharField(max_length=11, verbose_name="手机号码")
    address = models.CharField(max_length=63, verbose_name="地址")

    def __str__(self):
        return self.name

class Books(models.Model):
    bid = models.AutoField(primary_key=True)
    name = models.CharField(max_length=32, verbose_name="书名")
    description = models.CharField(max_length=128, verbose_name="书籍描述")
    author = models.ForeignKey(Author, on_delete=models.CASCADE)

    def __str__(self):
        return f"{self.author.name}: 《{self.name}》"

子表序列化

子表序列化比较简单，因为字段定义子表哪边，所以可以通过字段，只需要确定返回主表的哪些值即可。

• 返回外键的主键PrimaryKeyRelatedField

  定义序列化器：

      class BookSerialize(serializers.Serializer):
          bid = serializers.IntegerField(read_only=True)
          name = serializers.CharField(max_length=32, label="书名")
          description = serializers.CharField(max_length=128, label="书籍描述")
          author = serializers.PrimaryKeyRelatedField(read_only=True)

  PrimaryKeyRelatedField必须指定read_only为True，或指定queryset=Books.objects.all()，否则会报错

  使用django shell测试：

  $ python manage.py shell
  Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
  Type "help", "copyright", "credits" or "license" for more information.
  (InteractiveConsole)
  >>> from rest_test.serializers import BookSerialize
  >>> from rest_test.models import Books
  >>>
  >>> b = Books.objects.all()
  >>> s = BookSerialize(instance=b, many=True)
  >>> s.data
  [OrderedDict([('bid', 1), ('name', 'book1'), ('description', 'very good'), ('author', 4)]),
  OrderedDict([('bid', 2), ('name', 'book2'), ('description', '好书推荐'), ('author', 4)])]
  >>>

• 返回外键的__str__方法StringRelatedField

  修改author的字段类型，让它返回的是主表的__str__方法：

  class BookSerialize(serializers.Serializer):
      bid = serializers.IntegerField(read_only=True)
      name = serializers.CharField(max_length=32, label="书名")
      description = serializers.CharField(max_length=128, label="书籍描述")
      author = serializers.StringRelatedField(read_only=True)

  可以不设置read_only

  验证：

  $ python manage.py shell
  Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
  Type "help", "copyright", "credits" or "license" for more information.
  (InteractiveConsole)
  >>> from rest_test.serializers import BookSerialize
  >>> from rest_test.models import Books
  >>>
  >>> b = Books.objects.all()
  >>> s = BookSerialize(instance=b, many=True)
  >>> s.data
  [OrderedDict([('bid', 1), ('name', 'book1'), ('description', 'very good'), ('author', '张三')]),
  OrderedDict([('bid', 2), ('name', 'book2'), ('description', '好书推荐'), ('author', '张三')])]

• 返回整个主表的数据

  只需要字段的值改为主表的序列化器即可：

  class AuthorSerialize(serializers.Serializer):
      aid = serializers.IntegerField(read_only=True)
      name = serializers.CharField(max_length=32, label="姓名")
      phone = serializers.CharField(min_length=11, max_length=11, label="手机号码")
      address = serializers.CharField(max_length=63, label="地址")
  
  class BookSerialize(serializers.Serializer):
      bid = serializers.IntegerField(read_only=True)
      name = serializers.CharField(max_length=32, label="书名")
      description = serializers.CharField(max_length=128, label="书籍描述")
      author = AuthorSerialize(read_only=True)

  验证：

  $ python manage.py shell
  Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
  Type "help", "copyright", "credits" or "license" for more information.
  (InteractiveConsole)
  >>> from rest_test.serializers import AuthorSerialize, BookSerialize
  >>> from rest_test.models import Author, Books
  >>>
  >>> b = Books.objects.all()
  >>> s = BookSerialize(instance=b, many=True)
  >>> s.data
  [OrderedDict([('bid', 1), ('name', 'book1'), ('description', 'very good'),
  ('author', OrderedDict([('aid', 4), ('name', '张三'), ('phone', '138888888888'), ('address', '广东省广州市xxxxx')]))]),
  OrderedDict([('bid', 2), ('name', 'book2'), ('description', '好书推荐'),
  ('author', OrderedDict([('aid', 4), ('name', '张三'), ('phone', '138888888888'), ('address', '广东省广州市xxxxx')]))])]

主表序列化

由于主表不能直接访问子表，但是我们知道django为我们提供了表名(小写)_set管理器，这样我们就可以通过该管理器访问子表了。

假如指定了related_name参数的话，该管理器的名称就是related_name的值

如可以改成这样：author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name="author")

另，关于管理器，可以查看django的文档：“反向” 关联和管理器

为了演示，使用默认的管理器

与子表类似，我们需要指定返回什么值（__str__或主键），使用的是相同的字段，但是要指定many参数！！

• __str__ StringRelatedField

  注意many参数

  序列化器：

  class AuthorSerialize(serializers.Serializer):
      aid = serializers.IntegerField(read_only=True)
      name = serializers.CharField(max_length=32, label="姓名")
      phone = serializers.CharField(min_length=11, max_length=11, label="手机号码")
      address = serializers.CharField(max_length=63, label="地址")
      books_set = serializers.StringRelatedField(read_only=True, many=True)

  演示：

  $ python manage.py shell
  Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
  Type "help", "copyright", "credits" or "license" for more information.
  (InteractiveConsole)
  >>> from rest_test.serializers import AuthorSerialize
  >>> from rest_test.models import Author
  >>>
  >>> a = Author.objects.get(pk=4)
  >>> t = AuthorSerialize(instance=a)
  >>> t.data
  {'aid': 4, 'name': '张三', 'phone': '138888888888', 'address': '广东省广州市xxxxx', 'books_set': ['张三: 《book1》', '张三: 《book2》']}

• 主键PrimaryKeyRelatedField

  注意many参数

  序列化器：

  class AuthorSerialize(serializers.Serializer):
      aid = serializers.IntegerField(read_only=True)
      name = serializers.CharField(max_length=32, label="姓名")
      phone = serializers.CharField(min_length=11, max_length=11, label="手机号码")
      address = serializers.CharField(max_length=63, label="地址")
      books_set = serializers.PrimaryKeyRelatedField(read_only=True,many=True)

  演示：

  $ python manage.py shell
  Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
  Type "help", "copyright", "credits" or "license" for more information.
  (InteractiveConsole)
  >>> from rest_test.serializers import AuthorSerialize
  >>> from rest_test.models import Author
  >>>
  >>> a = Author.objects.get(pk=4)
  >>>
  >>> t = AuthorSerialize(instance=a)
  >>> t.data
  {'aid': 4, 'name': '张三', 'phone': '138888888888', 'address': '广东省广州市xxxxx', 'books_set': [1, 2]}
  >>>

上面演示了如何将model序列化成 字符串或OrderedDict，而反序列化化就是将json等数据，变成序列化器中的字段的数据类型，就好比我们使用form处理数据一样。

一般操作

此部分还不涉及将数据保存到数据库

流程：

1. 获得数据
2. 将数据传入到序列化器的data参数中
3. 调用返回对象的is_valid()方法

由于还未讲到视图，所以先用一个字典数据代替从浏览器传过来的数据。

$python manage.py shell
Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from rest_test.serializers import AuthorSerialize, BookSerialize
>>> from rest_test.models import Author, Books
>>>
>>> data = {
...     "name": "龙傲天",
...     "phone": "18888888888",
...     "address": "xxx省xx市",
... }
>>>
>>> result = AuthorSerialize(data=data)
>>> result.is_valid(raise_exception=True)
True

# ################ 这里故意用一个错误的数据 #############################
>>> data = {
...     "name": "龙傲天",
...     "phone": "188888888889",
...     "address": "xxx省xx市",
... }
>>> result = AuthorSerialize(data=data)
>>> result.is_valid(raise_exception=True)
# 报错
rest_framework.exceptions.ValidationError: {'phone': [ErrorDetail(string='Ensure this field has no more than 11 characters.', code='max_length')]}
>>>

• is_valid和django form的is_valid一样，可以检验数据是否符合我们在序列化器中定义的一样，检验成功是返回True，否则返回False。
• 假如指定raise_exception为True，那么当数据不合法时，抛出异常，我们可以通过error_messages参数提示信息（见: 自定义错误信息）。
• 假如不想要抛出异常，我们也可以通过.errors获取错误信息（这是一个OrderedDict的子类对象）如这里的result.errors。

利用序列化器进行创建和更新数据

终于讲到如何将数据保存到数据库了。

用过django ModelForm的都知道，只要将数据传入到form中，假如数据通过，就可以通过.save()方法将数据保存到数据库，指定instance参数可一个更新数据。而序列化器的使用方式样是这样，不过我们现在用的是叫较为低级的序列化器，需要我们自定义创建数据和更新数据的逻辑。

创建数据

使用步骤:

1. 获得数据
2. 将数据传入到序列化器的data参数中
3. 调用返回对象的is_valid()方法
4. 为序列化器定义create方法
5. 调用save方法，执行创建数据的函数(会调用create函数)

这里的create函数需要我们自定义，在序列化器中：

class AuthorSerialize(serializers.Serializer):
    aid = serializers.IntegerField(read_only=True)
    name = serializers.CharField(max_length=32, label="姓名")
    phone = serializers.CharField(min_length=11, max_length=11, label="手机号码")
    address = serializers.CharField(max_length=63, label="地址")
    books_set = serializers.StringRelatedField(read_only=True, many=True)

    def create(self, validated_data):
        """
        创建数据
        :param validated_data: 已经通过验证的数据
        :return: Author instance
        """
        author = Author.objects.create(**validated_data)

        # 不要忘记返回数据了
        return author

可以说非常简单，下面有django shell测试一下：

$python manage.py shell
Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from rest_test.serializers import AuthorSerialize
>>>
>>> data = {
...     "name": "龙傲天",
...     "phone": "18888888888",
...     "address": "xxx省xx市",
... }
>>> result = AuthorSerialize(data=data)
>>> result.is_valid(raise_exception=True)
True
>>> result.save()
<Author: 龙傲天>

用PyCharm自带的Database工具，我们可以看到的确已经保存到了数据库中：

更新数据（全部）

PUT请求方式是更新全部数据

使用步骤:

1. 获得数据
2. 将数据传入到序列化器的data参数中, 要更新的数据传入instance参数
3. 调用返回对象的is_valid()方法
4. 为序列化器定义update方法
5. 调用save方法，执行创建数据的函数(会调用update函数)

只要序列化器中同时传入data和instance参数，它就会调用更新的方法(update)

注意：data参数传入数据，instance参数传入待更新的model对象

class AuthorSerialize(serializers.Serializer):
    aid = serializers.IntegerField(read_only=True)
    name = serializers.CharField(max_length=32, label="姓名")
    phone = serializers.CharField(min_length=11, max_length=11, label="手机号码")
    address = serializers.CharField(max_length=63, label="地址")
    books_set = serializers.StringRelatedField(read_only=True, many=True)

    def update(self, instance, validated_data):
        """
        更新数据
        由于传入的不是QuerySet对象，所以不能用update方法
        :param instance: Author对象
        :param validated_data: 已经验证的数据
        :return: instance
        """
        instance.name = validated_data.get("name")
        instance.phone = validated_data.get("phone")
        instance.address = validated_data.get("address")
        instance.save()  # 不要忘记保存了

        return instance



$ python manage.py shell
Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from rest_test.serializers import AuthorSerialize
>>> from rest_test.models import Author
>>>
>>> author = Author.objects.get(pk=10)
>>>
>>> data = {
...     "name": "龙傲天",
...     "phone": "18888888888",
...     "address": "广东省广州市",
... }
>>> result = AuthorSerialize(data=data, instance=author)
>>> result.is_valid(raise_exception=True)
True
>>> result.save()
<Author: 龙傲天>
>>>

更新数据（部分）

PATCH请求方式是更新部分数据

上面我们只更新了地址的信息，却把其它不用改的信息也一并穿了进去，这显然不是我们预期的，但由于序列化器的字段的required默认为True，除非我们设置read_only=True或指定一个默认值，否则会报错，但设置了这些又会影响到我们正常创建数据的验证。

所以，序列化器提供了一个参数：partial用来说明这是更新部分信息的。在使用时和上面的一样，只是多了个参数而已。不过我们需要修改一下update函数, 因为值可能为None, 会报错，可以指定get的默认值，也可以用反射的方法：

class AuthorSerialize(serializers.Serializer):
    aid = serializers.IntegerField(read_only=True)
    name = serializers.CharField(max_length=32, label="姓名")
    phone = serializers.CharField(min_length=11, max_length=11, label="手机号码")
    address = serializers.CharField(max_length=63, label="地址")
    books_set = serializers.StringRelatedField(read_only=True, many=True)

    def update(self, instance, validated_data):
        """
        更新数据
        :param instance: Author对象
        :param validated_data: 已经验证的数据
        :return: instance
        """
        for field in validated_data:
            if not hasattr(instance, field):
                continue
            setattr(instance, field, validated_data.get(field))

        instance.save()  # 不要忘记保存了
        return instance

来试一下吧：

$ python manage.py shell
Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from rest_test.serializers import AuthorSerialize
>>> from rest_test.models import Author
>>>
>>> data = {
...     "address": "广东省广州市xxxxx",
... }
>>> author = Author.objects.get(pk=10)
>>> result = AuthorSerialize(data=data, instance=author, partial=True)
>>> result.is_valid(raise_exception=True)
True
>>> result.save()
<Author: 龙傲天>

DRF有一个model序列化器: ModelSerializer, 其在一定程度上与dango.forms.ModelForm十分相似

在上面使用的例子就用到了该序列化器

说到底，它就是将干了这几件事：

简单使用

简直是简简单单：

class AuthorModelSerialize(serializers.ModelSerializer):
    class Meta:
        model = Author
        fields = "__all__"

Meta类

从例子中看出，Meta类是关键，它决定着 要序列化的字段、用哪个模型、错误信息、约束条件等重要的参数。

下面我们看看Meta类可以指定什么内容：

还是那句话，真的和ModelForm十分相似

1. model

   指定用哪个Model

2. fields

   使用模型中的哪些字段，推荐利用元组显式指定，但可以将值指定为__all__（表示全部字段）

   不能和exclude一起使用，否则报错：Cannot set both 'fields' and 'exclude' options on serializer xxx.

3. exclude

   不使用模型中的哪些字段

   不能和fields一起使用，否则报错：Cannot set both 'fields' and 'exclude' options on serializer xxx.

4. depth

   指定关联深度，是一个数字

   注意，关联字段默认返回的是主键，即rest_framework.serializers.PrimaryKeyRelatedField

5. read_only_fields

   只读字段，主键默认只读

6. extra_kwargs

   指定额外的参数，该参数可以传给字段

例子：

class AuthorModelSerialize(serializers.ModelSerializer):
    class Meta:
        model = Author      # 指定使用Author这个模型
        # 指定字段，注意：books_set
        fields = ("aid", "name", "phone", "address", "books_set")

        # 不使用模型中的哪些字段
        # 不能一起使用，这里注释掉

        # exclude = ("phone", )

        depth = 1       # 关联深度为1
        # 设置只读字段
        read_only_fields = ("aid", "books_set")

        # 设置额外参数，该参数是给字段的
        # 注意格式
        extra_kwargs = {
            "name": {
                "read_only": True
            }
        }

我们同样用django shell查看：

$ python manage.py shell
Python 3.9.5 (tags/v3.9.5:0a7dcbd, May  3 2021, 17:27:52) [MSC v.1928 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from rest_test.serializers import AuthorModelSerialize
>>> from rest_test.models import Author
>>>
>>> a = Author.objects.all()
>>> res = AuthorModelSerialize(instance=a, many=True)
>>> res
AuthorModelSerialize(instance=<QuerySet [<Author: 张三>, <Author: 李四>, <Author: 王五>, <Author: 龙傲天>]>, many=True):aid = IntegerField(read_only=True) name = CharField(label='姓名', read_only=True) address = CharField(label='地址', max_length=63) books_set = NestedSerializer(many=True, read_only=True): bid = IntegerField(read_only=True) name = CharField(label='书名', max_length=32) description = CharField(label='书籍描述', max_length=128) author = PrimaryKeyRelatedField(queryset=Author.objects.all())

extra_kwargs

由于ModelSerializer直接用model的字段类型，肯定不能很好的做好条件约束

因此DRF提供了extra_kwargs属性, 并且错误信息也通过该参数进行自定制

class AuthorModelSerialize(serializers.ModelSerializer):
    class Meta:
        model = Author  # 指定使用Author这个模型
        # 指定字段，注意：books_set
        fields = ("aid", "name", "phone", "address", "books_set")
        extra_kwargs = {
            "phone": {
                "min_length": 11,
                "max_length": 11
            }
        }

像普通Serialize那样编写

我们可以自定义一些额外的字段或不用extra_kwargs属性而直接model的字段进行定义：

class AuthorModelSerialize(serializers.ModelSerializer):
    phone = serializers.CharField(min_length=11, max_length=11, label="手机号码")
    # write_only只反序列化，不入库
    note = serializers.CharField(max_length=128, label="额外的字段，不入库", write_only=True)    

    class Meta:
        model = Author  # 指定使用Author这个模型
        # 指定字段，注意：books_set
        fields = ("aid", "name", "address", "books_set")

指定外键返回类型

外键默认返回主键，但通过serializer_related_field属性指定：

class AuthorModelSerialize(serializers.ModelSerializer):
    serializer_related_field = serializers.StringRelatedField
    # 返回 __str__

    class Meta:
        model = Author
        fields = ("aid", "name", "address", "books_set")

这部分内容也是和Model一样

验证一个字段

和form一样，只要在序列化器重定义一个validate_xxx方法（xxx指的是字段名）即可验证单个字段，如下面的例子：

class AuthorSerialize(serializers.Serializer):
    aid = serializers.IntegerField(read_only=True)
    name = serializers.CharField(max_length=32, label="姓名")
    phone = serializers.CharField(min_length=11, max_length=11, label="手机号码")
    address = serializers.CharField(max_length=63, label="地址")
    books_set = serializers.StringRelatedField(read_only=True, many=True)

    def validate_name(self, value:str):
        # 1. 判读
        if not value.startswith("lcz"):
            # 抛出ValidationError异常
            raise serializers.ValidationError("必须以lcz开头", "startError")
        # 2.返回结果
        return value

ValidationError是一个异常，有两个参数detail和code，前者接收异常的描述信息，后者接收异常名（默认为"invalid"）

该方法调用is_valid时自动执行

记得返回value

验证一下：

>>> data = {
...     "name": "xxx",
...     "phone": "12345678910",
...     "note": "test",
...     "address": "广东省广州市xxxxx1",
... }
>>> result = AuthorSerialize(data=data)
>>> result.is_valid()
False
>>> result.errors
{'name': [ErrorDetail(string='必须以lcz开头', code='startError')]}

验证多个字段

需要重写validate方法：

class AuthorSerialize(serializers.Serializer):
    aid = serializers.IntegerField(read_only=True)
    name = serializers.CharField(max_length=32, label="姓名")
    phone = serializers.CharField(min_length=11, max_length=11, label="手机号码")
    address = serializers.CharField(max_length=63, label="地址")
    books_set = serializers.StringRelatedField(read_only=True, many=True)

    def validate(self, attrs):
        """
        :param attrs: 外界传入的需要校验的字典
        :return: attrs
        """
        # 1. 判断name和address（随便举个例子）
        if attrs["name"].startswith("lcz") and attrs.startswith("广东省"):
            # 2.返回结果
            return attrs
        # 否则抛出异常
        raise serializers.ValidationError("只有lcz开头且地址是广东省的才能通过验证")

自定义验证器

分两步：

1. 定义

   使用验证器时，传入的数据已经转换为python的数据类型了

   def check_bpub_date(date):
       if date.year < 2015:
           raise serializers.ValidationError("日期不能小于2015年")
   return date</code></pre></li>
   使用  
   通过validators参数指定
   def check_pub_date(date):
       if date.year < 2015:
           raise serializers.ValidationError("日期不能小于2015年")
       return date
   
   class BookSerialize(serializers.Serializer):
       pub_date = serializers.DateTimeField(validators=[check_pub_date]
   

from rest_framework import serializers

class AuthorSerialize(serializers.Serializer):
    aid = serializers.IntegerField(read_only=True)
    name = serializers.CharField(max_length=32, label="姓名")
    phone = serializers.CharField(min_length=11, max_length=11, label="手机号码",
                                  error_messages={"min_length": "号码太短了", "max_length": "号码太长了"})
    address = serializers.CharField(max_length=63, label="地址")
    books_set = serializers.StringRelatedField(read_only=True, many=True)

def check_bpub_date(date):
    if date.year < 2015:
        raise serializers.ValidationError("日期不能小于2015年")
    return date

from django.contrib import admin
from django.urls import path
from rest_test import views

urlpatterns = [
    path('admin/', admin.site.urls),
    # 同样调用.as_view方法
    path("authors/", views.AuthorListView.as_view())
]

from django.contrib import admin
from django.urls import path
from rest_test import views

urlpatterns = [
    path('admin/', admin.site.urls),
    path("authors/", views.AuthorListView.as_view()),
    path("authors/<int:pk>/", views.AuthorDetailView.as_view())
]

from rest_framework.generics import GenericAPIView
from rest_framework import status
from rest_framework.response import Response
from rest_test.serializers import AuthorModelSerialize
from rest_test.models import Author

class AuthorListView(GenericAPIView):
   queryset = Author.objects.all()
   serializer_class = AuthorModelSerialize

   def get(self, request):
       serialize = self.get_serializer(instance=self.get_queryset(), many=True)
       return Response(serialize.data, status=status.HTTP_200_OK)

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

from rest_framework.generics import GenericAPIView
from rest_framework import status
from rest_framework.response import Response
from rest_test.serializers import AuthorModelSerialize
from rest_test.models import Author

class AuthorDetailView(GenericAPIView):
    queryset = Author.objects.all()
    serializer_class = AuthorModelSerialize
    lookup_url_kwarg = "author_id"

    def get(self, request, author_id):
        # 相当于get_object_or_404
        instance = self.get_object()
        serialize = self.get_serializer(instance=instance)
        return Response(serialize.data, status=status.HTTP_200_OK)

    def put(self, request, author_id):
        data = request.data
        instance = self.get_object()
        serialize = self.get_serializer(instance=instance, data=data, partial=True)
        serialize.is_valid(raise_exception=True)
        serialize.save()
        return Response(serialize.data, status.HTTP_201_CREATED)

    def delete(self, request, author_id):
        instance = self.get_object()
        instance.delete()
        return Response(status=status.HTTP_204_NO_CONTENT)

from django.contrib import admin
from django.urls import path
from rest_test import views

urlpatterns = [
    path('admin/', admin.site.urls),
    path("authors/", views.AuthorListView.as_view()),
    path("authors/<int:author_id>/", views.AuthorDetailView.as_view())
]

class DestroyModelMixin:
    """
    Destroy a model instance.
    """
    def destroy(self, request, *args, **kwargs):
        instance = self.get_object()
        self.perform_destroy(instance)
        return Response(status=status.HTTP_204_NO_CONTENT)

    def perform_destroy(self, instance):
        instance.delete()

from rest_framework.generics import CreateAPIView, ListAPIView, RetrieveAPIView, UpdateAPIView, DestroyAPIView
from rest_test.serializers import AuthorModelSerialize
from rest_test.models import Author

class AuthorListView(ListAPIView, CreateAPIView):
    # 列表视图
    queryset = Author.objects.all()
    serializer_class = AuthorModelSerialize

class AuthorDetailView(RetrieveAPIView, UpdateAPIView, DestroyAPIView):
    # 详情视图
    queryset = Author.objects.all()
    serializer_class = AuthorModelSerialize
    lookup_url_kwarg = "author_id"

from rest_framework.viewsets import ReadOnlyModelViewSet
from rest_test.serializers import AuthorModelSerialize
from rest_test.models import Author
from rest_framework.decorators import action

class AuthorReadOnlyViewSet(ReadOnlyModelViewSet):
    queryset = Author.objects.all()
    serializer_class = AuthorModelSerialize
    lookup_url_kwarg = "author_id"

    # 生成路由规则: 前缀/方法名/  detail=True时，需要主键的值且url为：前缀/{pk}/方法名/
    @action(methods=['GET'], detail=False)
    def gt_id(self, request):
        queryset = self.filter_queryset(self.get_queryset())
        authors = queryset.filter(pk__gt=7)
        serialize = self.get_serializer(instance=authors, many=True)
        return Response(serialize.data, status=status.HTTP_200_OK)

from django.contrib import admin
from django.urls import path
from rest_test import views
from rest_framework.routers import DefaultRouter, SimpleRouter

urlpatterns = [
    path('admin/', admin.site.urls),
]

router = DefaultRouter()
router.register("authors", views.AuthorReadOnlyViewSet, basename="authors")

# 是authors不是authors/

urlpatterns += router.urls
print(urlpatterns)
"""
[<URLResolver <URLPattern list> (admin:admin) 'admin/'>,
<URLPattern '^authors/$' [name='authors-list']>,
<URLPattern '^authors\.(?P<format>[a-z0-9]+)/?$' [name='authors-list']>,
<URLPattern '^authors/gt_id/$' [name='authors-gt-id']>,
<URLPattern '^authors/gt_id\.(?P<format>[a-z0-9]+)/?$' [name='authors-gt-id']>,
<URLPattern '^authors/(?P<author_id>[^/.]+)/$' [name='authors-detail']>,
<URLPattern '^authors/(?P<author_id>[^/.]+)\.(?P<format>[a-z0-9]+)/?$' [name='authors-detail']>,
<URLPattern '^authors/$' [name='authors-list']>,
<URLPattern '^authors\.(?P<format>[a-z0-9]+)/?$' [name='authors-list']>,
<URLPattern '^authors/(?P<author_id>[^/.]+)/$' [name='authors-detail']>,
<URLPattern '^authors/(?P<author_id>[^/.]+)\.(?P<format>[a-z0-9]+)/?$' [name='authors-detail']>,
<URLPattern '^$' [name='api-root']>, <URLPattern '^\.(?P<format>[a-z0-9]+)/?$' [name='api-root']>]
"""

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": (
        'rest_framework.authentication.BasicAuthentication',
    ),
    'DEFAULT_PERMISSION_CLASSES': (
        # 'rest_framework.permissions.IsAuthenticated', # 普通用户
        # 'rest_framework.permissions.AllowAny',         # 所有用户
        'rest_framework.permissions.IsAdminUser',          # 管理员户
    )
}

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": (
        'rest_framework.authentication.SessionAuthentication',
    ),
    'DEFAULT_PERMISSION_CLASSES': (
        # 'rest_framework.permissions.IsAuthenticated', #普通用户
        # 'rest_framework.permissions.AllowAny', #所有用户
        'rest_framework.permissions.IsAdminUser',  # 管理员户
    )
}

# views.py
from rest_framework.views import APIView
from rest_framework.permissions import AllowAny
from django.contrib.auth import authenticate, login, logout

class SessionView(APIView):
    permission_classes = (AllowAny, )
    # 必须写AllowAny（即每个人都可以访问），不然连登录的权限都没有！！

    def post(self, request):
        username = request.data.get("username")
        password = request.data.get("password")
        user = authenticate(request, username=username, password=password)

        if user is not None:
            # 登录，写入session信息
            login(request, user)
            return Response({"detail": "success!"}, status=status.HTTP_201_CREATED)
        else:
            return Response({"detail": "password or username error!"}, status=status.HTTP_400_BAD_REQUEST)

    def delete(self, request):
        logout(request)
        return Response({"detail": "logout success!!"}, status=status.HTTP_204_NO_CONTENT)

urlpatterns = [
    path('admin/', admin.site.urls),
    path("session/", views.SessionView.as_view())
]

perms_map = {
    'GET': [],
    'OPTIONS': [],
    'HEAD': [],
    'POST': ['%(app_label)s.add_%(model_name)s'],
    'PUT': ['%(app_label)s.change_%(model_name)s'],
    'PATCH': ['%(app_label)s.change_%(model_name)s'],
    'DELETE': ['%(app_label)s.delete_%(model_name)s'],
}

# views.py
class CustomPermClass(DjangoModelPermissions):
    # GET请求权限, can_publish
    perms_map = {"GET": ['%(app_label)s.can_publish']}

class AuthorViewSet(ModelViewSet):
    queryset = Author.objects.all()
    serializer_class = AuthorModelSerialize
    lookup_url_kwarg = "author_id"
    permission_classes = (CustomPermClass,)

# models.py
class Books(models.Model):
    bid = models.AutoField(primary_key=True)
    name = models.CharField(max_length=32, verbose_name="书名")
    description = models.CharField(max_length=128, verbose_name="书籍描述")
    author = models.ForeignKey(Author, on_delete=models.CASCADE)

    def __str__(self):
        return f"{self.author.name}: 《{self.name}》"

    class Meta:
        permissions = (("can_publish", "能够出版"),)

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
    'PAGE_SIZE': 2,

}

{
    "count": 9,
    "next": "http://127.0.0.1:8000/authors/?limit=2&offset=6",
    "previous": "http://127.0.0.1:8000/authors/?limit=2&offset=2",
    "results": [
        {
            "aid": 8,
            "name": "张三",
            "phone": "13888888888",
            "address": "广东省广州市xxxxx",
            "books_set": []
        },
        {
            "aid": 9,
            "name": "李四",
            "phone": "13888888888",
            "address": "广东省广州市xxxxx",
            "books_set": []
        }
    ]
}

#自定义分页对象
class MyPageNumberPagination(PageNumberPagination):
    #1,默认的大小
    page_size = 3

    #2,前端可以指定页面大小
    page_size_query_param = 'page_size'

    #3,页面的最大大小
    max_page_size = 5

# 视图集
class BookInfoModelViewSet(ModelViewSet):
    # ...
    pagination_class = MyPageNumberPagination
    #  链接可以是，?page=4 或者 ?page=4&page_size=100

from rest_framework.filters import OrderingFilter

class BookInfoModelViewSet(ModelViewSet):
    # ....
    # 局部排序
    filter_backends = (OrderingFilter, ) 

    # 指定排序字段
    ordering_fields = ['id', 'btitle','bread']

    # 查询格式: ?ordering=-bread,id