restframework 中 Serializer 和 ViewSet 的 API

1. Serializer

1.1 数据校验

在反序列化数据时，需要对数据的合法性进行校验。这时，可以调用 is_valid() 进行验证，如果发生验证错误，可以在 .errors 属性获取错误提示信息。例如：

1
2
3
4
serializer.is_valid()
# False
serializer.errors
# {'created': [u'This field is required.']}

.is_valid() 方法带有一个可选的 raise_exception 标志，如果存在验证错误，将抛出 serializers.ValidationError 异常。

1
serializer.is_valid(raise_exception=True)

除了使用显示申明式的验证规则，还可以通过向 Serializer 子类添加 .validate_<field_name> 方法来指定自定义字段级验证。这与 Django 表单的 .clean_<field_name> 方法类似。

1
2
3
4
class SnippetSerializer(serializers.Serializer):
    def validate_title(self, value):
	    # do something
        return value

还可以自定义验证器，这里不再详细描述。

1.2 相关方法

Serializer 类继承自 BaseSerializer，有几个方法，可以用于定制序列化行为：

to_internal_value(self, data)，用于反序列化，写入数据
to_representation(self, instance)，用于序列化，读取数据
update(self, instance, validated_data)，用于更新数据
create(self, validated_data)，用于新增数据
save(self, **kwargs)，保存操作

2. APIView

2.1 相关属性

renderer_classes，渲染器类
parser_classes，解释器类
authentication_classes：权限类
throttle_classes：节流类
permission_classes：权限类
content_negotiation_class：内容协商类

2.2 相关方法

get_renderers(self)，获取渲染器方法
get_parsers(self)，获取解释器方法
get_authenticators(self)，获取认证方法
get_throttles(self)，获取节流方法
get_permissions(self)，获取权限方法
get_content_negotiator(self)，获取内容协商方法
check_permissions(self, request)，检查权限
check_throttles(self, request)，检查节流
check_content_negotiation(self, request, force=False)，检查内容协商

2.3 调度方法

initial(self, request, *args, **kwargs)

在处理程序方法之前被调用。这个方法是用来执行权限和节流，并执行内容协商。

handle_exception(self, exc)

抛出的任何异常处理程序方法将被传递给这个方法，而返回响应实例，或者 raises 异常。

initialize_request(self, request, *args, **kwargs)

确保请求对象传递给处理程序方法是 request 的一个实例，而不是 Django 的 HttpRequest。

finalize_response(self, request, response, *args, **kwargs)

确保任何响应处理程序方法返回的对象将被呈现到正确的内容类型。

3. GenericAPIView

3.1 相关属性

queryset

用于返回query对象集合，也可以使用 get_queryset() 方法。

serializer_class

序列化器类，应该用于输入进行验证和反序列化，并用于序列化输出。通常情况下，你必须设置这个属性，或重写 get_serializer_class() 方法。

lookup_field，模型的字段应该用于执行对象查找个别的模型实例
lookup_url_kwarg，URL应该用于对象查找关键字参数
pagination_class

用于返回一个分页列表视图的分页类，默认与 settings 中设置的 DEFAULT_PAGINATION_CLASS 值相同，可以通过rest_framework.pagination.PageNumberPagination 设置分页数
过滤器属性。

filter_backends，过滤 queryset 的类列表，和在 settings 中设置 DEFAULT_FILTER_BACKENDS 一样

3.2 基本方法

get_queryset()，返回queryset
get_object()，获取某一个具体的 Model 实例对象

以下方法是 mixins 类提供，提供简单的对象保存和删除的行为重写：

perform_create(self, serializer)，CreateModelMixin 保存对象时调用
perform_update(self, serializer)，UpdateModelMixin 更新对象时调用
perform_destroy(self, instance)，DestoryModelMixin 删除对象时调用

4 ModelViewSet

GenericViewSet 是对 GenericAPIView 的继承。ModelViewSet 又是对 GenericViewSet 和大量 mixins 的组合。

rest_framework/viewsets.py 定义了 ModelViewSet 类：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
class ModelViewSet(mixins.CreateModelMixin,
                   mixins.RetrieveModelMixin,
                   mixins.UpdateModelMixin,
                   mixins.DestroyModelMixin,
                   mixins.ListModelMixin,
                   GenericViewSet):
    """
    A viewset that provides default `create()`, `retrieve()`, `update()`,
    `partial_update()`, `destroy()` and `list()` actions.
    """
    pass

在使用过程中，通常需要继承 ModelViewSet 实现自己的业务逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
class YourViewSet(viewsets.ModelViewSet):
	def list(self, request):
	    pass
	def create(self, request):
	    pass
	def retrieve(self, request, pk=None):
	    pass
	def update(self, request, pk=None):
	    pass
	def partial_update(self, request, pk=None):
	    pass
	def destroy(self, request, pk=None):
	    pass

下面是前端 URL 请求与 ModelViewSet 方法的对应关系：

list() ，GET 方法，/date-list/
create() ，POST，/date-list/
retrieve() ，GET，/date-list/<id>/
update()，PUT，/date-list/<id>/
partial_update()，PATCH, /date-list/<id>/
destroy()，DELETE，/date-list/<id>/