一，Requests：请求
request.user：请求身份验证的用户， AnonymousUser:游客
request.auth：请求通过身份验证的令牌实例
request.data：返回请求主体的解析内容
request.method: 返回请求的HTTP方法的大写字符串表示形式。
request.content_type: 返回表示HTTP请求正文的媒体类型的字符串对象，如果没有提供媒体类型，则返回空字符串。
request.stream: 返回表示请求主体内容的流。
二，Response: 响应
Response(data, status=None, template_name=None, headers=None, content_type=None)
data：响应的序列化数据。
status：响应的状态码。默认为200.另请参阅状态代码。
template_name：HTMLRenderer选择要使用的模板名称。
headers：在响应中使用的HTTP标头字典。
content_type：响应的内容类型。通常情况下，渲染器会根据内容协商的结果自动设置，但有些情况下需要明确指定内容类型。
三，Views: 视图
API策略属性:
.renderer_classes
.parser_classes
.authentication_classes
.throttle_classes
.permission_classes
.content_negotiation_class
API策略实例化方法:
.get_renderers(self)
.get_parsers(self)
.get_authenticators(self)
.get_throttles(self)
.get_permissions(self)
.get_content_negotiator(self)
.get_exception_handler(self)
API政策实施方法:
.check_permissions(self, request)
.check_throttles(self, request)
.perform_content_negotiation(self, request, force=False)
调度方法: .dispatch()方法直接调用 .get()，.post()，put()，patch()和.delete()
.initial（self，request，* args，** kwargs）
执行处理器方法被调用之前需要发生的任何操作。此方法用于强制执行权限和限制，并执行内容协商。
您通常不需要重写此方法。
.handle_exception（self，exc）
处理程序方法抛出的任何异常都将传递给此方法，该方法返回一个Response实例，或者重新引发异常。
默认实现处理rest_framework.exceptions.APIExceptionDjango Http404和PermissionDenied异常的任何子类，并返回相应的错误响应。
如果您需要自定义API返回的错误响应，您应该子类化此方法。
.initialize_request（self，request，* args，** kwargs）
确保传递给处理程序方法的请求对象是一个实例Request，而不是通常的Django HttpRequest。
您通常不需要重写此方法。
.finalize_response（self，request，response，* args，** kwargs）
确保Response从处理程序方法返回的任何对象将被呈现为正确的内容类型，由内容协商确定。
您通常不需要重写此方法。
API策略装饰器:
@api_view(['GET', 'POST'])
@renderer_classes(...)
@parser_classes(...)
@authentication_classes(...)
@throttle_classes(...)
@permission_classes(...)
每个装饰器都有一个参数，它必须是一个列表或者一个类的元组。
depth: 设置深度
url中.as_view() 调用dispatch根据请求类型执行对应的函数。
四，Generic views: 通用视图
API参考：
GenericAPIView：
属性：
基本设置：
queryset - 应该用于从此视图返回对象的查询集。通常，您必须设置该属性，或覆盖该get_queryset()方法。如果你重写一个视图方法，重要的是你调用get_queryset()而不是直接访问这个属性，
因为它queryset会被评估一次，并且这些结果将被缓存所有后续请求。
serializer_class - 应该用于验证和反序列化输入以及序列化输出的序列化程序类。通常，您必须设置该属性，或覆盖该get_serializer_class()方法。
lookup_field - 应该用于执行各个模型实例的对象查找的模型字段。默认为'pk'。请注意，使用超链接的API时，您需要确保双方的API意见和串行类设置查找字段，如果你需要使用一个自定义值。
lookup_url_kwarg - 应该用于对象查找的URL关键字参数。URL conf应该包含与此值相对应的关键字参数。如果未设置，则默认使用与之相同的值lookup_field。
分页：
与列表视图一起使用时，以下属性用于控制分页。
pagination_class - 分页列表结果时应使用的分页类。默认值与DEFAULT_PAGINATION_CLASS设置值相同，即'rest_framework.pagination.PageNumberPagination'。设置pagination_class=None将禁用此视图的分页。
过滤：
filter_backends - 应该用于过滤查询集的过滤后端类列表。默认值与DEFAULT_FILTER_BACKENDS设置相同。
方法
基本方法：
get_queryset(self)： 返回应该用于列表视图的查询集，并应将其用作查看详细视图的基础。默认返回queryset属性指定的查询集。
get_object(self)： 返回应该用于详细视图的对象实例。默认使用lookup_field参数来过滤基本查询集。
filter_queryset(self, queryset): 给定一个查询集，使用任何后端过滤器进行过滤，返回一个新的查询集
get_serializer_class(self): 返回应该用于序列化程序的类。默认返回serializer_class属性。 可为不同类型的用户提供不同的序列化器
保持和删除挂钩：
mixin类提供了一下方法，并提供了对象保持或删除行为的轻松覆盖。
perform_create(self, serializer) - CreateModelMixin 保存新对象实例时调用。
perfrom_update(self, serializer) - UpdateModelMixin 保存现有对象实例时调用。
perfrom_destroy(self, instance) - DestroyModelMixin 在删除对象实例时调用。
这些钩子对设置请求中隐含的但不属于请求数据的属性特别有用。例如，您可以根据请求用户或基于URL关键字参数在对象上设置属性。
其他方法：
get_serializer_context(self) - 返回包含任何应提供给序列化程序的额外上下文的字典。默认为包括'request'，'view'和'format'钥匙。
get_serializer(self, instance=None, data=None, many=False, partial=False) - 返回一个序列化器实例。
get_paginated_response(self, data)- 返回分页样式Response对象。
paginate_queryset(self, queryset)- 根据需要为查询集分页，或者返回一个页面对象，或者None没有为该视图配置分页。
filter_queryset(self, queryset) - 给定一个查询集，使用任何正在使用的后端过滤器，返回一个新的查询集。
Mixins:mixin类提供用于提供基本视图行为的操作, mixin类可以从中导入rest_framework.mixins
ListModelMixin: 提供一个.list(request, *args, **kwargs)实现列出查询集的方法
CreateModelMixin: 提供一种.create(request, *args, **kwargs) 方法，实现创建和保存新的模型实例。
RetrieveModelMixin: 提供一种.retrieve(request, *args, **kwargs)方法，实现在响应中返回现有的模型实例。
UpdateModelMixin: 提供一种.update(request, *args, **kwargs)实现更新和保存现有模型实例的方法。
DestroyModelMixin: 提供一种.destroy(request, *args, **kwargs)方法，实现现有模型实例的删除。
具体视图类: 从中导入rest_framework.generics
CreateAPIView
用于创建专用端点。
提供post方法处理程序。
扩展：GenericAPIView，CreateModelMixin
ListAPIView
用于只读端点来表示模型实例的集合。
提供get方法处理程序。
扩展：GenericAPIView，ListModelMixin
RetrieveAPIView
用于只读端点来表示单个模型实例。
提供get方法处理程序。
扩展：GenericAPIView，RetrieveModelMixin
DestroyAPIView
用于单个模型实例的仅删除端点。
提供delete方法处理程序
扩展：GenericAPIView，DestroyModelMixin
UpdateAPIView
用于单个模型实例的仅更新端点。
提供put和patch方法处理程序。
扩展：GenericAPIView，UpdateModelMixin
ListCreateAPIView
用于读写端点以表示模型实例的集合。
提供get和post方法处理程序。
扩展：GenericAPIView，ListModelMixin，CreateModelMixin
RetrieveUpdateAPIView
用于读取或更新端点以表示单个模型实例。
提供get，put并且patch方法处理。
扩展：GenericAPIView，RetrieveModelMixin，UpdateModelMixin
RetrieveDestroyAPIView
用于读取或删除端点以表示单个模型实例。
提供get和delete方法处理程序。
扩展：GenericAPIView，RetrieveModelMixin，DestroyModelMixin
RetrieveUpdateDestroyAPIView
用于读写 - 删除端点以表示单个模型实例。
提供get，put，patch和delete方法处理。
扩展：GenericAPIView，RetrieveModelMixin，UpdateModelMixin，DestroyModelMixin
五，Viewsets: 视图集
from rest_framnework import ViewSet
一个ViewSet类只是一种基于类的View，它不提供任何方法处理程序（如.get()or）.post()，而是提供诸如.list()and之类的操作.create()
使用ViewSet类比使用View类有两个主要优点。
重复的逻辑可以合并成一个类。在上面的例子中，我们只需要指定queryset一次，它将用于多个视图。
通过使用路由器，我们不再需要处理自己的URL配置。
在发送过程中，以下属性可用ViewSet。
basename - 用于创建的URL名称的基础。
action- 当前动作的名称（例如list，create）。
detail - 布尔值，指示当前操作是否为列表或详细视图配置。
suffix- 视图类型的显示后缀 - 镜像detail属性。
APL参考:
ViewSet:
将ViewSet类从继承APIView。您可以使用任何标准属性，例如permission_classes，authentication_classes以便控制视图上的API策略。
本ViewSet类不提供任何操作实现。为了使用ViewSet类，您将重写该类并明确定义动作实现。
GenericViewSet
该GenericViewSet班由继承GenericAPIView，并提供了默认设置get_object，get_queryset方法及其他通用视图基地的行为，但不包括默认情况下，任何动作。
为了使用GenericViewSet类，您将覆盖该类并混合所需的混合类，或者明确定义操作实现。
ModelViewSet
的ModelViewSet类所继承GenericAPIView，并包括用于各种动作实现方式中，通过在各种混入类的行为混合。
由提供的动作ModelViewSet类是.list()，.retrieve()， .create()，.update()，.partial_update()，和.destroy()。
例: 因为ModelViewSet扩展GenericAPIView，你通常需要提供至少queryset和serializer_class属性。例如：
class AccountViewSet(viewsets.ModelViewSet):
"""
A simple ViewSet for viewing and editing accounts.
"""
queryset = Account.objects.all()
serializer_class = AccountSerializer
permission_classes = [IsAccountAdminOrReadOnly]
ReadOnlyModelViewSet
该ReadOnlyModelViewSet班也继承GenericAPIView。与ModelViewSet它一样，它还包括各种操作的实现，但不同于ModelViewSet只提供“只读”操作，.list()而且.retrieve()。
例: 与之相同ModelViewSet，您通常需要提供至少the queryset和serializer_class属性。例如：
class AccountViewSet(viewsets.ReadOnlyModelViewSet):
"""
A simple ViewSet for viewing accounts.
"""
queryset = Account.objects.all()
serializer_class = AccountSerializer
六，Routers: 路由器
用法: 这是一个简单的URL配置的例子，它使用SimpleRouter。
from rest_framework import routers
router = routers.SimpleRouter()
router.register(r'users', UserViewSet)
router.register(r'accounts', AccountViewSet)
urlpatterns = router.urls
该方法有两个强制参数register()：
prefix - 用于这组路线的URL前缀。
viewset - 视图类。
或者，您也可以指定一个附加参数：
base_name - 用于创建的URL名称的基础。如果未设置，基本名称将根据queryset视图集的属性自动生成，如果有的话。请注意，如果视图集不包含queryset属性，则必须base_name在注册视图集时进行设置。
上面的例子会生成以下URL模式：
网址格式：^users/$ 名称：'user-list'
网址格式：^users/{pk}/$ 名称：'user-detail'
网址格式：^accounts/$ 名称：'account-list'
网址格式：^accounts/{pk}/$ 名称：'account-detail'
APL指南:
SimpleRouter:
该路由器包括一套标准的途径list，create，retrieve，update，partial_update和destroy行动。该视图还可以使用@action装饰器标记要路由的其他方法。
默认情况下，由创建的URL SimpleRouter附加了尾部斜线。通过在实例化路由器时将trailing_slash参数设置为可以修改此行为False。例如：
router = SimpleRouter(trailing_slash=False)
路由器将匹配包含除斜杠和句点字符以外的任何字符的查找值。对于更严格（或宽松）的查找模式，请lookup_value_regex在视图集上设置属性。例如，您可以将查找限制为有效的UUID：
class MyModelViewSet(mixins.RetrieveModelMixin, viewsets.GenericViewSet):
lookup_field = 'my_model_id'
lookup_value_regex = '[0-9a-f]{32}'
DefaultRouter:
此路由器与SimpleRouter上述类似，但还包含一个默认API根视图，该视图返回包含指向所有列表视图的超链接的响应。它还为可选的.json样式格式后缀生成路由。
Custom Routers:
Route命名元组的参数是：
url：表示要路由的URL的字符串。可能包含以下格式字符串：
{prefix} - 用于这组路线的URL前缀。
{lookup} - 用于匹配单个实例的查找字段。
{trailing_slash}- 根据trailing_slash参数，可以是'/'或空字符串。
映射：HTTP方法名称与视图方法的映射
name：reverse呼叫中使用的URL的名称。可能包含以下格式字符串：
{basename} - 用于创建的URL名称的基础。
initkwargs：实例化视图时应传递的任何其他参数的字典。需要注意的是detail，basename和suffix参数保留给视图集中内省和也使用可浏览的API生成视图名称和面包屑链接
Customizing dynamic routes:
url：表示要路由的URL的字符串。可能包含与之相同的格式字符串Route，并且还接受{url_path}格式字符串。
name：reverse呼叫中使用的URL的名称。可能包含以下格式字符串：
{basename} - 用于创建的URL名称的基础。
{url_name}- url_name提供给@action。
initkwargs：实例化视图时应传递的任何其他参数的字典。
七，Parsers: 解析器
解析器如何确定:
当 request.data被访问时，REST框架将检查Content-Type传入请求上的头，并确定使用哪个解析器来解析请求内容。
设置解析器:
REST_FRAMEWORK = {
'DEFAULT_PARSER_CLASSES': (
'rest_framework.parsers.JSONParser',
)
}
API参考:
JSONParser:
分析JSON请求内容。
.media_type: application/json
FormParser:
解析HTML表单内容。request.data将填充QueryDict一些数据
您通常会希望同时使用FormParser，并MultiPartParser以完全支持HTML表单数据一起。
.media_type：application/x-www-form-urlencoded
MultiPartParser:
分析支持文件上传的多部分HTML表单内容。两者都request.data将填充一个QueryDict。
您通常会希望同时使用FormParser，并MultiPartParser以完全支持HTML表单数据一起。
.media_type：multipart/form-data
FileUploadParser:
分析原始文件上传内容。该request.data属性将是一个'file'包含上传文件的单个密钥的字典。
如果使用的视图FileUploadParser是使用filenameURL关键字参数调用的，则该参数将用作文件名。
如果在没有filenameURL关键字参数的情况下调用它，则客户端必须在Content-DispositionHTTP标头中设置文件名。例如Content-Disposition: attachment; filename=upload.jpg。
.media_type：*/*
笔记：
的FileUploadParser是与本地客户端的使用，可以将文件上传的原始数据请求。对于基于Web的上传，或者对于具有分段上传支持的本地客户端，您应该使用MultiPartParser解析器。
由于此解析器media_type匹配任何内容类型，FileUploadParser通常应该是在API视图上设置的唯一解析器。
FileUploadParser尊重Django的标准FILE_UPLOAD_HANDLERS设置和request.upload_handlers属性。有关更多详细信息，请参阅Django文档。
parser_context
可选的。如果提供，则该参数将是一个包含解析请求内容可能需要的任何其他上下文的字典。
默认情况下，这将包括以下键：view，request，args，kwargs。
八，Renderers: 渲染器
渲染器如何确定:
当输入视图时，REST框架将对传入请求执行内容协商，并确定最合适的渲染器以满足请求
设置渲染器:
REST_FRAMEWORK = {
'DEFAULT_RENDERER_CLASSES': (
'rest_framework.renderers.JSONRenderer',
'rest_framework.renderers.BrowsableAPIRenderer',
)
}
API参考：
JSONRenderer：
JSON使用utf-8编码将请求数据提交到。
使用UNICODE_JSON和COMPACT_JSON设置键可以更改默认的JSON编码样式。
.media_type：application/json
.format：'.json'
.charset：None
TemplateHTMLRenderer：
模板名称由（按优先顺序）确定：
template_name 传递给响应的明确参数。
.template_name 在此类上设置显式属性。
调用的返回结果 view.get_template_names()。
使用TemplateHTMLRenderer以下内容的视图示例：
class UserDetail(generics.RetrieveAPIView):
"""
A view that returns a templated HTML representation of a given user.
"""
queryset = User.objects.all()
renderer_classes = (TemplateHTMLRenderer,)
def get(self, request, *args, **kwargs):
self.object = self.get_object()
return Response({'user': self.object}, template_name='user_detail.html')
StaticHTMLReanderer:
一个简单的渲染器，它只是返回预渲染的HTML。与其他渲染器不同，传递给响应对象的数据应该是表示要返回的内容的字符串。
使用StaticHTMLRenderer以下内容的视图示例：
@api_view(('GET',))
@renderer_classes((StaticHTMLRenderer,))
def simple_html_view(request):
data = '<html><body><h1>Hello, world</h1></body></html>'
return Response(data)
您可以使用StaticHTMLRendererREST框架返回常规HTML页面，也可以从单个端点返回HTML和API响应。
.media_type：text/html
.format：'.html'
.charset：utf-8
也可以看看： TemplateHTMLRenderer
BrowsableAPIRenderer:
该渲染器将确定哪个其他渲染器被赋予最高优先级，并使用该渲染器在HTML页面中显示API样式响应。
.media_type：text/html
.format：'.api'
.charset：utf-8
模板：'rest_framework/api.html'
AdminRenderer:
将数据呈现为HTML以显示类似管理员的显示内容：
HTMLFormRenderer:
将序列化程序返回的数据呈现为HTML表单。此渲染器的输出不包含封闭<form>标签，隐藏的CSRF输入或任何提交按钮。
MultiPartRenderer:
该渲染器用于呈现HTML多部分表单数据。 它不适合作为响应渲染器，而是用于创建测试请求，使用REST框架的测试客户端和测试请求工厂。
.media_type：multipart/form-data; boundary=BoUnDaRyStRiNg
.format：'.multipart'
.charset：utf-8
Custom renderers: 自定义渲染器
要实现自定义渲染器，您应该重写BaseRenderer，设置.media_type和.format属性并实现该.render(self, data, media_type=None, renderer_context=None)方法。
九，Serializers: 串行器
序列化对象：
from rest_framework import serializers
class CommentSerializer(serializers.Serializer):
email = serializers.EmailField()
content = serializers.CharField(max_length=200)
created = serializers.DateTimeField()
serializer = CommentSerializer(comment)
serializer.data
此时我们已经将模型实例转换为Python本地数据类型。为了完成序列化过程，我们将数据渲染到json。
from rest_framework.renderers import JSONRenderer
json = JSONRenderer().render(serializer.data)
json
反序列化对象:
from django.utils.six import BytesIO
from rest_framework.parsers import JSONParser
stream = BytesIO(json)
data = JSONParser().parse(stream)
serializer = CommentSerializer(data=data)
serializer.is_valid()
# True
serializer.validated_data
当反序列化数据时，我们可以调用.save()返回基于验证数据的对象实例。
comment = serializer.save()
该.is_valid()方法采用可选raise_exception标志，serializers.ValidationError如果存在验证错误，将导致它引发异常。
这些异常会由REST框架提供的默认异常处理程序自动处理，并会HTTP 400 Bad Request默认返回响应。
serializer.is_valid(raise_exception=True)
部分更新
默认情况下，序列化程序必须为所有必填字段传递值，否则会引发验证错误。您可以使用partial参数以允许部分更新。
serializer = CommentSerializer(comment, data={'content': u'foo bar'}, partial=True)
ModelSerializer:
该ModelSerializer课程与普通Serializer课程相同，不同之处在于：
它会根据模型自动为您生成一组字段。
它会自动为串行器生成验证器，例如unique_together验证器。
它包括简单的默认实现.create()和.update()。
指定要包含的字段:
class AccountSerializer(serializers.ModelSerializer):
class Meta:
model = Account
fields = ('id', 'account_name', 'users', 'created')
您还可以将该fields属性设置为特殊值'__all__'以指示应该使用模型中的所有字段。
您可以将该exclude属性设置为从序列化程序中排除的字段列表。
例如：
class AccountSerializer(serializers.ModelSerializer):
class Meta:
model = Account
exclude = ('users',)
指定嵌套序列化
默认情况下ModelSerializer使用主键进行关系，但您也可以使用以下depth选项轻松生成嵌套表示：
class AccountSerializer(serializers.ModelSerializer):
class Meta:
model = Account
fields = ('id', 'account_name', 'users', 'created')
depth = 1
显式指定字段
您可以ModelSerializer通过在类上声明字段来为其添加额外的字段或覆盖默认字段，就像您对Serializer类所做的那样。
class AccountSerializer(serializers.ModelSerializer):
url = serializers.CharField(source='get_absolute_url', read_only=True)
groups = serializers.PrimaryKeyRelatedField(many=True)
class Meta:
model = Account
指定只读字段
您可能希望将多个字段指定为只读。read_only=True您可以使用快捷方式Meta选项，而不是使用该属性明确添加每个字段read_only_fields。
该选项应该是字段名称的列表或元组，并声明如下：
class AccountSerializer(serializers.ModelSerializer):
class Meta:
model = Account
fields = ('id', 'account_name', 'users', 'created')
read_only_fields = ('account_name',)
HyperlinkedModelSerializer:
HyperlinkedModelSerializer类是类似于ModelSerializer不同之处在于它使用的超链接来表示的关系，而不是主键类。
ListSerializer:
本ListSerializer类提供了序列化和一次验证多个对象的行为。您通常不需要ListSerializer直接使用，而应该many=True在实例化序列化程序时通过
自定义ListSerializer行为
这里是一些使用情况下，您可能希望定制的ListSerializer行为。例如：
您希望提供对列表的特定验证，例如检查一个元素是否与列表中的另一个元素不冲突。
您想要自定义多个对象的创建或更新行为。
对于这些情况，您可以many=True使用list_serializer_class序列化程序Meta类上的选项来修改传递时使用的类。
例如：
class CustomListSerializer(serializers.ListSerializer):
...
class CustomSerializer(serializers.Serializer):
...
class Meta:
list_serializer_class = CustomListSerializer
BaseSerializer:
BaseSerializer 类可以用来轻松地支持替代序列化和反序列化样式。
该类实现与该类相同的基本API Serializer
.data - 返回传出的原始数据。
.is_valid() - 反序列化并验证传入的数据。
.validated_data - 返回验证的传入数据。
.errors - 在验证过程中返回任何错误。
.save() - 将验证的数据保存到对象实例中。
有四种方法可以被覆盖，具体取决于你希望序列化类支持的功能：
.to_representation() - 覆盖此以支持序列化，用于读取操作。
.to_internal_value() - 重写这个以支持反序列化，用于写入操作。
.create()和.update()-覆盖的这些一个或两个支持节能实例。
创建用于将HighScore实例转换为基本数据类型的只读序列化器非常简单。
class HighScoreSerializer(serializers.BaseSerializer):
def to_representation(self, obj):
return {
'score': obj.score,
'player_name': obj.player_name
}
serializer.is_valid(raise_exception=True)
通用视图使用raise_exception=True标志，这意味着您可以在API中全局覆盖验证错误响应的样式
十，Serializer fields: 序列化字段
处理原始值和内部数据类型之间的转换。他们还处理验证输入值，以及从其父对象中检索和设置值
read_only: 将其设置True为确保在序列化表示时使用该字段，但在反序列化期间创建或更新实例时不使用该字段。默认为False
write_only: 将其设置True为确保在更新或创建实例时可以使用该字段，但在序列化表示时不包括该字段。默认为 False
required: 如果在反序列化过程中没有提供字段，通常会出现错误。如果在反序列化过程中不需要此字段，则设置为false
default: 如果设置，则会给出默认值，如果没有提供输入值，将使用该字段的默认值。如果未设置，则默认行为是根本不填充该属性
allow_null: 通常情况下，如果None传递到序列化程序字段会引发错误。将此关键字参数设置为Trueif None应被视为有效值。
source: 将用于填充字段的属性的名称。可能是只接受self参数的方法，例如URLField(source='get_absolute_url')，或者可能使用虚线符号来遍历属性，例如EmailField(source='user.email')。
validators: 应该应用于传入字段输入的验证程序函数列表，其中可能引发验证错误或仅返回
error_messages: 错误消息的错误代码字典。
label: 一个简短的文本字符串，可用作HTML表单字段或其他描述性元素中字段的名称。
help_text: 一个文本字符串，可用作HTML表单字段或其他描述性元素中字段的描述。
initial: 应该用于预填充HTML表单字段的值的值。您可能会传递一个可调用对象，就像您对任何常规Django可能做的一样Field：
import datetime
from rest_framework import serializers
class ExampleSerializer(serializers.Serializer):
day = serializers.DateField(initial=datetime.date.today)
style: 可用于控制渲染器渲染字段的键值对的字典。
这里的两个例子是'input_type'和'base_template'：
# Use <input type="password"> for the input.
password = serializers.CharField(
style={'input_type': 'password'}
)
# Use a radio input instead of a select input.
color_channel = serializers.ChoiceField(
choices=['red', 'green', 'blue'],
style={'base_template': 'radio.html'}
)
布尔字段
BooleanField:
默认BooleanField实例将生成一个required=False选项（因为Django models.BooleanField总是blank=True）
NullBooleanField:
字符串字段
CharField: 文本表示。可以选择验证文本是短于max_length还是长于min_length
签名： CharField(max_length=None, min_length=None, allow_blank=False, trim_whitespace=True)
allow_blank- 如果设置为，True则空字符串应被视为有效值。如果设置为False那么空字符串被认为是无效的并会引发验证错误。默认为False。
trim_whitespace- 如果设置为，True则前导和尾随空白被修剪。默认为True
EmailField: 文本表示形式，将文本验证为有效的电子邮件地址。
签名： EmailField(max_length=None, min_length=None, allow_blank=False)
RegexField: 一个文本表示，用于验证给定的值是否与某个正则表达式匹配。
签名： RegexField(regex, max_length=None, min_length=None, allow_blank=False)
强制regex参数可以是字符串，也可以是已编译的python正则表达式对象
SlugField: RegexField根据模式验证输入[a-zA-Z0-9_-]+
签名： SlugField(max_length=50, min_length=None, allow_blank=False)
URLField: RegexField根据URL匹配模式验证输入。预计表单的完全限定URL http://<host>/<path>
签名： URLField(max_length=200, min_length=None, allow_blank=False)
UUIDField: 确保输入的字段是有效的UUID字符串。该to_internal_value方法将返回一个uuid.UUID实例。在输出时，字段将以规范的连字符格式返回一个字符串，例如：
"de305d54-75b4-431b-adb2-eb6b9e546013"
签名： UUIDField(format='hex_verbose')
format：确定uuid值的表示格式
'hex_verbose' - cannoncical十六进制表示，包括连字符： "5ce0e9a5-5ffa-654b-cee0-1238041fb31a"
'hex' - UUID的紧凑十六进制表示，不包括连字符： "5ce0e9a55ffa654bcee01238041fb31a"
'int' - UUID的128位整数表示： "123456789012312313134124512351145145114"
'urn'- UUID的RFC 4122 URN表示："urn:uuid:5ce0e9a5-5ffa-654b-cee0-1238041fb31a" 更改format参数仅影响表示值。所有格式都被接受to_internal_value
FilePathField: 一个字段，其选项仅限于文件系统上某个目录中的文件名
签名： FilePathField(path, match=None, recursive=False, allow_files=True, allow_folders=False, required=None, **kwargs)
path - FilePathField应该从中选择的目录的绝对文件系统路径。
match - FilePathField将用来过滤文件名的正则表达式，作为字符串。
recursive - 指定是否应包含路径的所有子目录。默认是False。
allow_files - 指定是否应包含指定位置中的文件。默认是True。无论是这个还是allow_folders必须的True。
allow_folders - 指定是否应包含指定位置的文件夹。默认是False。无论是这个还是allow_files必须的True。
IPAddressField: 确保输入是有效的IPv4或IPv6字符串的字段。
签名：IPAddressField(protocol='both', unpack_ipv4=False, **options)
protocol限制有效输入到指定的协议。接受的值是'both'（默认），'IPv4'或'IPv6'。匹配不区分大小写。
unpack_ipv4解压IPv4映射的地址，如:: ffff：192.0.2.1。如果启用此选项，则该地址将解压到192.0.2.1。默认是禁用的。只能在协议设置为'both'时使用。
数字字段:
IntegerField: 整数表示。
签名：IntegerField(max_value=None, min_value=None)
max_value 验证提供的数字不大于此值。
min_value 验证提供的数字是否不小于此值。
FloatField: 浮点表示。
签名：FloatField(max_value=None, min_value=None)
max_value 验证提供的数字不大于此值。
min_value 验证提供的数字是否不小于此值。
DecimalField: 由Python Decimal实例表示的十进制表示。
签名：DecimalField(max_digits, decimal_places, coerce_to_string=None, max_value=None, min_value=None)
max_digits数字中允许的最大位数。它必须是或者None大于或等于的整数decimal_places。
decimal_places 与号码一起存储的小数位数。
coerce_to_string设置为True如果字符串值应为表示被退回，或者False如果Decimal对象应返回。默认值与COERCE_DECIMAL_TO_STRING设置键的值相同，True除非被覆盖。如果Decimal对象由序列化程序返回，则最终的输出格式将由渲染器确定。请注意，设置localize会强制该值True。
max_value 验证提供的数字不大于此值。
min_value 验证提供的数字是否不小于此值。
localize设置为True启用基于当前语言环境的输入和输出本地化。这也将迫使coerce_to_string到True。默认为False。请注意，如果您已USE_L10N=True在设置文件中设置了数据格式，则会启用数据格式。
rounding设置量化到配置精度时使用的舍入模式。有效值是decimal模块舍入模式。默认为None。
日期和时间字段:
DateTimeField: 日期和时间表示。
签名： DateTimeField(format=api_settings.DATETIME_FORMAT, input_formats=None)
format - 表示输出格式的字符串。如果未指定，则默认为与DATETIME_FORMAT设置键相同的值，'iso-8601'除非设置，否则该设置键将被设置。设置为格式字符串表示to_representation应将返回值强制为字符串输出。格式字符串如下所述。将此值设置为None指示datetime应由Python 返回Python 对象to_representation。在这种情况下，日期时间编码将由渲染器确定。
input_formats - 表示可用于解析日期的输入格式的字符串列表。如果未指定，DATETIME_INPUT_FORMATS则将使用该设置，默认为['iso-8601']。
auto_now, auto_now_add
DateField: 日期表示。
签名： DateField(format=api_settings.DATE_FORMAT, input_formats=None)
format - 表示输出格式的字符串。如果未指定，则默认为与DATE_FORMAT设置键相同的值，'iso-8601'除非设置，否则该设置键将被设置。设置为格式字符串表示to_representation应将返回值强制为字符串输出。格式字符串如下所述。将此值设置为None指示date应由Python 返回Python 对象to_representation。在这种情况下，日期编码将由渲染器决定。
input_formats - 表示可用于解析日期的输入格式的字符串列表。如果未指定，DATE_INPUT_FORMATS则将使用该设置，默认为['iso-8601']。
auto_now, auto_now_add
TimeField: 时间表示。
签名： TimeField(format=api_settings.TIME_FORMAT, input_formats=None)
format - 表示输出格式的字符串。如果未指定，则默认为与TIME_FORMAT设置键相同的值，'iso-8601'除非设置，否则该设置键将被设置。设置为格式字符串表示to_representation应将返回值强制为字符串输出。格式字符串如下所述。将此值设置为None指示time应由Python 返回Python 对象to_representation。在这种情况下，时间编码将由渲染器确定。
input_formats - 表示可用于解析日期的输入格式的字符串列表。如果未指定，TIME_INPUT_FORMATS则将使用该设置，默认为['iso-8601']。
DurationField: 持续时间表示
选择选择字段:
ChoiceField: 可以接受有限选项集中的值的字段。
ModelSerializer如果相应的模型字段包含choices=…参数，则由其用于自动生成字段。
签名： ChoiceField(choices)
choices- 有效值列表或(key, display_name)元组列表。
allow_blank- 如果设置为，True则空字符串应被视为有效值。如果设置为False那么空字符串被认为是无效的并会引发验证错误。默认为False。
html_cutoff - 如果设置，这将是HTML选择下拉菜单中显示的选项的最大数量。可以用来确保自动生成的具有非常大可能选择的ChoiceFields不会阻止模板渲染。默认为None。
html_cutoff_text - 如果设置，如果在HTML选择下拉菜单中已经截断了最大数量的项目，将显示文本指示符。默认为"More than {count} items…"
MultipleChoiceField: 一个字段，可以接受一组零个，一个或多个值，从一组有限的选项中选择。采取一个强制性的论据。to_internal_value返回一个set包含选定值的a。
签名： MultipleChoiceField(choices)
choices- 有效值列表或(key, display_name)元组列表。
allow_blank- 如果设置为，True则空字符串应被视为有效值。如果设置为False那么空字符串被认为是无效的并会引发验证错误。默认为False。
html_cutoff - 如果设置，这将是HTML选择下拉菜单中显示的选项的最大数量。可以用来确保自动生成的具有非常大可能选择的ChoiceFields不会阻止模板渲染。默认为None。
html_cutoff_text - 如果设置，如果在HTML选择下拉菜单中已经截断了最大数量的项目，将显示文本指示符。默认为"More than {count} items…"
文件上传字段:
FileField: 文件表示。执行Django的标准FileField验证
签名： FileField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)
max_length - 指定文件名的最大长度。
allow_empty_file - 指定是否允许空文件。
use_url- 如果设置为True那么URL字符串值将用于输出表示。如果设置为，False则文件名字符串值将用于输出表示。默认为UPLOADED_FILES_USE_URL设置键的值，True除非另有设置。
ImageField: 图像表示。验证上传的文件内容是否匹配已知的图像格式。
签名： ImageField(max_length=None, allow_empty_file=False, use_url=UPLOADED_FILES_USE_URL)
max_length - 指定文件名的最大长度。
allow_empty_file - 指定是否允许空文件。
use_url- 如果设置为True那么URL字符串值将用于输出表示。如果设置为，False则文件名字符串值将用于输出表示。默认为UPLOADED_FILES_USE_URL设置键的值，True除非另有设置。
复合领域:
ListField: 验证对象列表的字段类。
签名：ListField(child=<A_FIELD_INSTANCE>, min_length=None, max_length=None)
child - 应该用于验证列表中的对象的字段实例。如果未提供此参数，则列表中的对象将不会被验证。
min_length - 确认列表中包含的元素数量不少于此数量。
max_length - 验证列表中包含的元素数量不超过此数量。
例如，要验证整数列表，可以使用类似下面的内容：
scores = serializers.ListField(
child=serializers.IntegerField(min_value=0, max_value=100)
)
DictField: 验证对象字典的字段类。键入内容DictField始终假定为字符串值。
签名：DictField(child=<A_FIELD_INSTANCE>)
child - 应该用于验证字典中的值的字段实例。如果未提供此参数，则映射中的值将不会被验证。
例如，要创建一个验证字符串到字符串映射的字段，可以这样写：
document = DictField(child=CharField())
HStoreField: DictField与Django的postgres兼容的预配置HStoreField。
签名：HStoreField(child=<A_FIELD_INSTANCE>)
child - 用于验证字典中的值的字段实例。默认的子字段接受空字符串和空值。
请注意，子字段必须是实例CharField，因为hstore扩展将值存储为字符串。
JSONField: 验证传入数据结构由有效JSON基元组成的字段类。在其替代二进制模式下，它将表示并验证JSON编码的二进制字符串。
签名：JSONField(binary)
binary- 如果设置为True那么该字段将输出并验证JSON编码的字符串，而不是原始数据结构。默认为False。
杂项领域:
ReadOnlyField: 只是简单地返回字段的值而不进行修改的字段类。
签名：ReadOnlyField()
HiddenField: 不根据用户输入获取值的字段类，而是从默认值或可调用值中获取值。
签名：HiddenField()
例如，要包含始终提供当前时间的字段作为序列化器验证数据的一部分，则可以使用以下内容：
modified = serializers.HiddenField(default=timezone.now)
ModelField: 可以绑定到任意模型字段的通用字段。该ModelField级代表序列化/反序列化到其关联的模型领域的任务。该字段可用于为自定义模型字段创建序列化程序字段，而无需创建新的自定义序列化程序字段。
签名： ModelField(model_field=<Django ModelField instance>)
SerializerMethodField: 这是一个只读字段。它通过调用它所连接的序列化器类的方法来获得它的值。它可用于将任何类型的数据添加到对象的序列化表示中。
签名：SerializerMethodField(method_name=None)
method_name - 要调用序列化程序的方法的名称。如果不包含，则默认为get_<field_name>。
运用 source='*'
x = serializers.IntegerField(source='x_coordinate')
每个实例都source 指向相关字段
十一，Serializer relations: 串行器关系
关系字段用于表示模型关系。它们可以应用到ForeignKey，ManyToManyField和OneToOneField关系，以及扭转的关系，以及自定义关系等GenericForeignKey
API参考:
StringRelatedField: StringRelatedField可以用来用它的__unicode__方法来表示关系的目标。
例如，下面的序列化程序。
class AlbumSerializer(serializers.ModelSerializer):
tracks = serializers.StringRelatedField(many=True)
class Meta:
model = Album
fields = ('album_name', 'artist', 'tracks')
参数：
many- 如果应用于多对多关系，则应将此参数设置为True。
PrimaryKeyRelatedField: PrimaryKeyRelatedField 可用于使用其主键来表示关系的目标。
例如，以下序列化程序：
class AlbumSerializer(serializers.ModelSerializer):
tracks = serializers.PrimaryKeyRelatedField(many=True, read_only=True)
class Meta:
model = Album
fields = ('album_name', 'artist', 'tracks')
参数：
queryset - 验证字段输入时用于模型实例查找的查询集。关系必须明确地设置查询集，或者设置read_only=True。
many- 如果应用于多对多关系，则应将此参数设置为True。
allow_null- 如果设置为True，该字段将接受None可为空的关系的值或空字符串。默认为False。
pk_field - 设置为一个字段来控制主键值的序列化/反序列化。例如，pk_field=UUIDField(format='hex')会将UUID主键序列化为其紧凑的十六进制表示形式。
HyperlinkedRelatedField: HyperlinkedRelatedField 可用于使用超链接来表示关系的目标。
例如，以下序列化程序：
class AlbumSerializer(serializers.ModelSerializer):
tracks = serializers.HyperlinkedRelatedField(
many=True,
read_only=True,
view_name='track-detail'
)
class Meta:
model = Album
fields = ('album_name', 'artist', 'tracks')
参数：
view_name - 应该用作关系目标的视图名称。如果你使用的是标准路由器类，这将是一个格式的字符串<modelname>-detail。需要。
queryset - 验证字段输入时用于模型实例查找的查询集。关系必须明确地设置查询集，或者设置read_only=True。
many- 如果应用于多对多关系，则应将此参数设置为True。
allow_null- 如果设置为True，该字段将接受None可为空的关系的值或空字符串。默认为False。
lookup_field - 应该用于查找的目标字段。应该对应于引用视图上的URL关键字参数。默认是'pk'。
lookup_url_kwarg - 与查找字段对应的URL conf中定义的关键字参数的名称。默认使用与。相同的值lookup_field。
format- 如果使用格式后缀，则超链接字段将使用与目标相同的格式后缀，除非使用format参数进行覆盖。
SlugRelatedField: SlugRelatedField 可以用来表示使用目标上的字段的关系的目标。
例如，以下序列化程序：
class AlbumSerializer(serializers.ModelSerializer):
tracks = serializers.SlugRelatedField(
many=True,
read_only=True,
slug_field='title'
)
class Meta:
model = Album
fields = ('album_name', 'artist', 'tracks')
参数：
slug_field - 应该用来表示目标的字段。这应该是唯一标识任何给定实例的字段。例如，username。 需要
queryset - 验证字段输入时用于模型实例查找的查询集。关系必须明确地设置查询集，或者设置read_only=True。
many- 如果应用于多对多关系，则应将此参数设置为True。
allow_null- 如果设置为True，该字段将接受None可为空的关系的值或空字符串。默认为False。
HyperlinkedIdentityField: 该字段可以作为身份关系应用，例如'url'HyperlinkedModelSerializer上的字段。它也可以用于对象的属性。例如，以下序列化程序：
class AlbumSerializer(serializers.HyperlinkedModelSerializer):
track_listing = serializers.HyperlinkedIdentityField(view_name='track-list')
class Meta:
model = Album
fields = ('album_name', 'artist', 'track_listing')
参数：
view_name - 应该用作关系目标的视图名称。如果你使用的是标准路由器类，这将是一个格式的字符串<model_name>-detail。 需要。
lookup_field - 应该用于查找的目标字段。应该对应于引用视图上的URL关键字参数。默认是'pk'。
lookup_url_kwarg - 与查找字段对应的URL conf中定义的关键字参数的名称。默认使用与。相同的值lookup_field。
format- 如果使用格式后缀，则超链接字段将使用与目标相同的格式后缀，除非使用format参数进行覆盖。
自定义超链接字段:
在某些情况下，您可能需要自定义超链接字段的行为，以表示需要多个查询字段的URL。
你可以通过覆盖来实现这一点HyperlinkedRelatedField。有两种可能被覆盖的方法：
get_url（self，obj，view_name，request，format）: 该get_url方法用于将对象实例映射到其URL表示。
NoReverseMatch如果view_name和lookup_field 属性未配置为正确匹配URL conf，可能会引发一次
get_object（self，queryset，view_name，view_args，view_kwargs）: 如果您想支持可写的超链接字段，那么您还需要重写get_object，以便将传入的URL映射回其代表的对象。对于只读超链接字段，不需要重写此方法。
十二，Validators: 验证器
大多数情况下，您在REST框架中处理验证时，只需依赖缺省字段验证，或者在序列化程序或字段类上编写显式验证方法。
UniqueValidator: 这个验证器可以用来强制unique=True模型字段的约束。它需要一个必需的参数和一个可选的messages参数：
queryset 必需 - 这是查询集应对其执行唯一性。
message - 验证失败时应使用的错误消息。
lookup - 用于查找具有正在验证的值的现有实例的查找。默认为'exact'
这个验证器应该应用于序列化程序字段，如下所示：
from rest_framework.validators import UniqueValidator
slug = SlugField(
max_length=100,
validators=[UniqueValidator(queryset=BlogPost.objects.all())]
)
UniqueTogetherValidator: 这个验证器可以用来强制unique_together对模型实例进行约束。它有两个必需的参数和一个可选messages参数：
queryset 必需 - 这是查询集应对其执行唯一性。
fields 必需 - 应该创建唯一集合的字段名称列表或元组。这些必须作为序列化程序类中的字段存在。
message - 验证失败时应使用的错误消息。
验证器应该应用于序列化器类，如下所示：
from rest_framework.validators import UniqueTogetherValidator
class ExampleSerializer(serializers.Serializer):
class Meta:
# ToDo items belong to a parent list, and have an ordering defined
# by the 'position' field. No two items in a given list may share
# the same position.
validators = [
UniqueTogetherValidator(
queryset=ToDoItem.objects.all(),
fields=('list', 'position')
)
]
UniqueForDateValidator:
UniqueForMonthValidator:
UniqueForYearValidator:
这些验证器可用于强制实施模型实例unique_for_date，unique_for_month并unique_for_year约束模型实例。他们采取以下论点：
queryset 必需 - 这是查询集应对其执行唯一性。
field 必需 - 在给定日期范围内唯一性将被验证的字段名称。这必须作为序列化程序类中的字段存在。
date_field required - 将用于确定唯一性约束的日期范围的字段名称。这必须作为序列化程序类中的字段存在。
message - 验证失败时应使用的错误消息。
验证器应该应用于序列化器类，如下所示：
from rest_framework.validators import UniqueForYearValidator
class ExampleSerializer(serializers.Serializer):
class Meta:
# Blog posts should have a slug that is unique for the current year.
validators = [
UniqueForYearValidator(
queryset=BlogPostItem.objects.all(),
field='slug',
date_field='published'
)
]
与可写日期字段一起使用。
如果您希望日期字段是可写的，唯一值得注意的是您应确保它始终可用于输入数据中，可以通过设置default参数或通过设置required=True。
published = serializers.DateTimeField(required=True)
与只读日期字段一起使用。
如果您希望日期字段可见，但用户无法编辑，请设置read_only=True并另外设置default=...参数。
published = serializers.DateTimeField(read_only=True, default=timezone.now)
与隐藏的日期字段一起使用。
如果您希望日期字段对用户完全隐藏，请使用HiddenField。该字段类型不接受用户输入，而是始终将其默认值返回给validated_data序列化程序。
published = serializers.HiddenField(default=timezone.now)
高级字段默认值:
CurrentUserDefault
可用于表示当前用户的默认类。为了使用它，在实例化序列化程序时，'request'必须作为上下文字典的一部分提供。
owner = serializers.HiddenField(
default=serializers.CurrentUserDefault()
)
CreateOnlyDefault
可用于在创建操作期间仅设置默认参数的默认类。在更新期间，该字段被省略。
它采用一个参数，这是在创建操作期间应该使用的默认值或可调用参数。
created_at = serializers.DateTimeField(
default=serializers.CreateOnlyDefault(timezone.now)
)
验证器的限制:
有一些不明确的情况，您需要明确处理验证，而不是依赖ModelSerializer生成的默认序列化程序类 。
您通常需要从序列化程序类中排除验证程序，而是在.validate()方法中或在视图中显式编写任何验证逻辑。
例如：
class BillingRecordSerializer(serializers.ModelSerializer):
def validate(self, data):
# Apply custom validation either here, or in the view.
class Meta:
fields = ('client', 'date', 'amount')
extra_kwargs = {'client': {'required': False}}
validators = [] # Remove a default "unique together" constraint.
更新嵌套序列化器:
你可能想要从序列化类中明确地移除验证器，并将验证约束的代码明确地写入.validate()方法或视图中。
十三，Authentication: 认证
身份验证是将传入请求与一组识别凭证（例如请求来自的用户或其签名的令牌）相关联的机制。然后，权限和限制策略可以使用这些凭据来确定请求是否应该被允许。
如何确定身份验证：
认证成功，request.user属性通常会被设置为contrib.auth包的User类的实例。 认证不成功为AnonymousUser
认证成功，request.auth属性用于任何其他身份验证信息，例如，它可以用来表示请求已签名的身份验证令牌。 认证不成功为None
设置认证方案： 全局
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'rest_framework.authentication.BasicAuthentication',
'rest_framework.authentication.SessionAuthentication',
)
}
局部： authentication_classes = (SessionAuthentication, BasicAuthentication)
未经授权和禁止的回复：
HTTP 401未经授权
HTTP 403权限被拒绝
API参考
BasicAuthentication: 此认证方案使用HTTP基本认证，并根据用户的用户名和密码进行签名。基本认证通常只适用于测试。
如果成功通过身份验证，则BasicAuthentication提供以下凭据。
request.user将是一个Django User实例。
request.auth将会None。
TokenAuthentication: 此认证方案使用简单的基于令牌的HTTP认证方案。令牌身份验证适用于客户端 - 服务器设置，例如本机桌面和移动客户端。
要使用该TokenAuthentication方案，您需要配置要包含的认证类TokenAuthentication，并rest_framework.authtoken在您的INSTALLED_APPS设置中另外包含：
INSTALLED_APPS = (
...
'rest_framework.authtoken'
)
注意：确保manage.py migrate在更改设置后运行。该rest_framework.authtoken应用程序提供了Django数据库迁移。
您还需要为您的用户创建令牌。
from rest_framework.authtoken.models import Token
token = Token.objects.create(user=...)
print token.key
如果您已经创建了一些用户，则可以为所有现有用户生成令牌，例如：
from django.contrib.auth.models import User
from rest_framework.authtoken.models import Token
for user in User.objects.all():
Token.objects.get_or_create(user=user)
SessionAuthentication: 此认证方案使用Django的默认会话后端进行认证。会话身份验证适用于与您的网站在同一会话环境中运行的AJAX客户端。
如果成功通过身份验证，则SessionAuthentication提供以下凭据。
request.user将是一个Django User实例。
request.auth将会None
RemoteUserAuthentication: 这种身份验证方案允许您将身份验证委托给设置REMOTE_USER 环境变量的Web服务器。
自定义认证:
要实现自定义身份验证方案，请创建子类BaseAuthentication并覆盖该.authenticate(self, request)方法。(user, auth)如果认证成功，该方法应返回一个二元组，否则返回None。
例
以下示例将以名为'X_USERNAME'的自定义请求标头中的用户名给出的用户身份验证任何传入请求。
from django.contrib.auth.models import User
from rest_framework import authentication
from rest_framework import exceptions
class ExampleAuthentication(authentication.BaseAuthentication):
def authenticate(self, request):
username = request.META.get('X_USERNAME')
if not username:
return None
try:
user = User.objects.get(username=username)
except User.DoesNotExist:
raise exceptions.AuthenticationFailed('No such user')
return (user, None)
十四，Permissions: 权限
与身份验证和限制一起，权限决定是应该授予还是拒绝访问请求。
如何确定权限:
如果有任何权限检查失败的情况exceptions.PermissionDenied或exceptions.NotAuthenticated将引发异常，并且视图的主体将无法运行。
当权限检查失败时，根据以下规则，将返回“403 Forbidden”或“401 Unauthorized”响应：
该请求已成功通过身份验证，但权限被拒绝。 - 将返回HTTP 403 Forbidden响应。
该请求未成功通过身份验证，并且最高优先级的身份验证类不使用WWW-Authenticate标头。 - 将返回HTTP 403 Forbidden响应。
请求未成功验证，并且最高优先级认证类不使用WWW-Authenticate头。- HTTP 401未经授权的响应，并WWW-Authenticate返回一个适当的头文件。
设置权限策略: 全局
REST_FRAMEWORK = {
'DEFAULT_PERMISSION_CLASSES': (
'rest_framework.permissions.IsAuthenticated',
)
}
局部： permission_classes = (IsAuthenticated,)
API参考
AllowAny
该AllowAny许可类将允许不受限制的访问，不管请求被认证或未认证的。
此权限并非严格要求，因为您可以通过为权限设置使用空列表或元组来获得相同的结果，但是您可能会发现指定此类是有用的，因为它会使意图变得明确。
IsAuthenticated
该IsAuthenticated许可类将拒绝允许任何未认证用户，并允许许可，否则。
如果您希望您的API只能由注册用户访问，则此权限是适合的。
IsAdminUser
所述IsAdminUser许可类将拒绝许可给任何用户，除非user.is_staff是True在这种情况下的许可将被允许。
如果您希望您的API只能被部分受信任的管理员访问，则此权限是适合的。
IsAuthenticatedOrReadOnly
在IsAuthenticatedOrReadOnly将允许被授权的用户进行任何请求。只有当请求方法是“安全”方法之一时，才允许未经授权的用户请求; GET，HEAD或者OPTIONS。
如果您希望您的API允许匿名用户读取权限，并且只允许对已通过身份验证的用户进行写入权限，则此权限是适合的。
DjangoModelPermissions
此权限类与Django的标准django.contrib.auth 模型权限相关联。此权限只能应用于具有.queryset属性设置的视图。只有在用户通过身份验证并分配了相关模型权限的情况下，授权才会被授予。
POST请求要求用户拥有add模型的权限。
PUT并且PATCH请求要求用户change获得模型的许可。
DELETE请求要求用户拥有delete模型的权限。
要使用自定义模型权限，请覆盖DjangoModelPermissions并设置.perms_map属性。有关详细信息，请参阅源代码
DjangoModelPermissionsOrAnonReadOnly
与此类似DjangoModelPermissions，但也允许未经身份验证的用户拥有对该API的只读访问权限。
DjangoObjectPermissions
此权限类绑定到Django的标准对象权限框架中，该框架允许对模型执行每对象权限。为了使用此权限类，您还需要添加支持对象级权限的权限后端，例如django-guardian。
同样DjangoModelPermissions，此权限只能应用于具有.queryset属性或.get_queryset()方法的视图。只有在用户通过身份验证并且具有相关的每个对象权限和相关的模型权限后，授权才会被授予。
POST请求要求用户拥有add模型实例的权限。
PUT并且PATCH请求要求用户拥有change模型实例的权限。
DELETE请求要求用户拥有delete模型实例的权限。
请注意，DjangoObjectPermissions 不要求django-guardian包，并且应该支持其他对象级后端同样出色。
与DjangoModelPermissions您一样，您可以通过覆盖DjangoObjectPermissions和设置.perms_map属性来使用自定义模型权限。有关详细信息，请参阅源代码。
自定义权限:
要实现自定义权限，请覆盖BasePermission并实现以下方法之一或两者：
.has_permission(self, request, view)
.has_object_permission(self, request, view, obj)
如果请求应该被授予访问权限，则方法应该返回True，否则返回False。
请注意，为了运行实例级检查，视图代码应该显式调用.check_object_permissions(request, obj)
PermissionDenied如果测试失败，自定义权限将引发异常。要更改与异常相关的错误消息，请message直接在您的自定义权限上实施属性。否则default_detail，PermissionDenied将使用来自该属性的属性。
from rest_framework import permissions
class CustomerAccessPermission(permissions.BasePermission):
message = 'Adding customers not allowed.'
def has_permission(self, request, view):
...
十五，Throttling: 节流
节流与权限类似，因为它确定是否应该授权请求。节流阀指示临时状态，并用于控制客户端可以对API进行的请求速率。
如何确定节流
与权限和身份验证一样，REST框架中的限制通常定义为类的列表。
设置限制策略: 全局
REST_FRAMEWORK = {
'DEFAULT_THROTTLE_CLASSES': (
'rest_framework.throttling.AnonRateThrottle',
'rest_framework.throttling.UserRateThrottle'
),
'DEFAULT_THROTTLE_RATES': {
'anon': '100/day', # 游客一天访问100次
'user': '1000/day' # 注册用户一天访问1000次
}
}
局部：throttle_classes = (UserRateThrottle,)
APL参考
AnonRateThrottle
将AnonRateThrottle仅会扼杀未经授权的用户。传入请求的IP地址用于生成一个唯一的密钥来进行抑制。
允许的请求率由以下之一决定（按优先顺序）。
rate班上的财产，可以通过重写AnonRateThrottle和设置财产来提供。
该DEFAULT_THROTTLE_RATES['anon']设置。
UserRateThrottle
该UserRateThrottleAPI会将用户限制在整个API中给定的请求速率。用户标识用于生成一个唯一的密钥来加以抑制。未经身份验证的请求将回退到使用传入请求的IP地址生成一个唯一的密钥来进行抑制。
允许的请求率由以下之一决定（按优先顺序）。
rate班上的财产，可以通过重写UserRateThrottle和设置财产来提供。
该DEFAULT_THROTTLE_RATES['user']设置。
ScopedRateThrottle
的ScopedRateThrottle类可用于限制访问API的特定部分。只有当正在访问的视图包含.throttle_scope属性时才会应用此节流阀。然后通过将请求的“范围”与唯一的用户标识或IP地址连接起来形成唯一的节制密钥。
允许的请求速率由DEFAULT_THROTTLE_RATES使用来自请求“范围”的键的设置确定。
自定义节流：
要创建自定义节流阀，请覆盖BaseThrottle并执行.allow_request(self, request, view)。如果请求被允许，该方法应该返回True，否则返回False。
或者，您也可以重写该.wait()方法。如果已实施，.wait()则应在尝试下一个请求之前返回建议的等待秒数，或者None。该.wait()方法只会在.allow_request()以前返回时调用False。
如果该.wait()方法已实现并且请求受到限制，则会Retry-After在响应中包含一个标头。
例：
以下是速率限制的一个示例，每10次请求会随机调节一次。
import random
class RandomRateThrottle(throttling.BaseThrottle):
def allow_request(self, request, view):
return random.randint(1, 10) != 1
十六，Filtering: 过滤
REST框架的通用列表视图的默认行为是返回模型管理器的整个查询集。通常您会希望您的API限制查询集返回的项目。
过滤任何视图的子集的查询集的最简单方法GenericAPIView是重写该.get_queryset()方法。
设置过滤器; 全局
REST_FRAMEWORK = {
'DEFAULT_FILTER_BACKENDS': ('django_filters.rest_framework.DjangoFilterBackend',)
}
局部： filter_backends = (django_filters.rest_framework.DjangoFilterBackend,)
API指南
DjangoFilterBackend
该django-filter库包含一个DjangoFilterBackend支持REST框架的高度可自定义字段过滤的类。
filter_fields在视图或视图集上设置一个属性，列出您要过滤的一组字段
例:
filter_fields = ('category', 'in_stock')
SearchFilter:
该SearchFilter级支持简单单的查询参数基于搜索和基于该admin界面的搜索功能。
所述SearchFilter如果视图有一类将只应用于search_fields属性集。该search_fields属性应该是模型上文本类型字段的名称列表，例如CharField或TextField。
class UserListView(generics.ListAPIView):
queryset = User.objects.all()
serializer_class = UserSerializer
filter_backends = (filters.SearchFilter,)
search_fields = ('username', 'email')
搜索行为可能受到各种字符预先限制search_fields。
'^'开始 - 搜索。
'='完全匹配。
'@'全文搜索。（目前只支持Django的MySQL后端。）
'$'正则表达式搜索。
例如：bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1dWlkIjoiNjNjZGRhYWFjOTIwNGUyNDhmNmEyOWQ4YTkwZDViZjAiLCJuaWNrIjoiYWRtaW4iLCJ0eXBlIjoxLCJleHAiOjE1MjY2OTE3NDR9.j9UL0QQU0JtulkR1JBG0cF0nJWf9N636pnU-BL_mI7Q
search_fields = ('=username', '=email')
OrderingFilter
本OrderingFilter类支持控制结果的排序简单的查询参数。
默认情况下，查询参数是命名的'ordering'，但这可能会被ORDERING_PARAM设置覆盖。
例如，要通过用户名来订购用户：
http://example.com/api/users?ordering=username
通过ordering_fields在视图上设置属性来完成针对哪些字段进行排序:
ordering_fields = ('username', 'email')
DjangoObjectPermissionsFilter
该软件DjangoObjectPermissionsFilter旨在与django-guardian软件包一起使用，并'view'添加了自定义权限。过滤器将确保查询集仅返回用户具有适当查看权限的对象。
自定义通用筛选
您还可以提供自己的通用过滤后端，或者编写一个可供其他开发人员使用的可安装应用程序。
这样做覆盖BaseFilterBackend，并覆盖该.filter_queryset(self, request, queryset, view)方法。该方法应该返回一个新的，过滤的查询集。
例:
例如，您可能需要限制用户只能看到他们创建的对象。
class IsOwnerFilterBackend(filters.BaseFilterBackend):
"""
Filter that only allows users to see their own objects.
"""
def filter_queryset(self, request, queryset, view):
return queryset.filter(owner=request.user)
定制界面
通用过滤器也可以在可浏览的API中呈现接口。为此，您应该实现一个to_html()返回过滤器的呈现HTML表示形式的方法。此方法应具有以下签名：
to_html(self, request, queryset, view)
该方法应该返回一个呈现的HTML字符串。
分页和模式
通过实现一个get_schema_fields()方法，您还可以使过滤器控件可用于REST框架提供的模式自动生成。此方法应具有以下签名：
get_schema_fields(self, view)
该方法应该返回一个coreapi.Field实例列表。
十七，Pagination: 分页
REST框架包含对可定制分页样式的支持。这允许您修改多大的结果集被分成单独的数据页面。
设置分页样式: 全局
REST_FRAMEWORK = {
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.LimitOffsetPagination',
'PAGE_SIZE': 100
}
局部：
class LargeResultsSetPagination(PageNumberPagination):
page_size = 1000
page_size_query_param = 'page_size'
max_page_size = 10000
然后，您可以使用.pagination_class属性将新样式应用于视图
API参考
PageNumberPagination
此分页样式在请求查询参数中接受单个号码页码
要求：
GET https://api.example.org/accounts/?page=4
要设置这些属性，您应该重写PageNumberPagination该类，然后像上面那样启用您的自定义分页类。
django_paginator_class - 要使用的Django Paginator类。默认值是django.core.paginator.Paginator，对大多数用例来说应该没问题。
page_size - 指示页面大小的数值。如果设置，则会覆盖PAGE_SIZE设置。默认值与PAGE_SIZE设置键相同。
page_query_param - 一个字符串值，指示用于分页控件的查询参数的名称。
page_size_query_param - 如果设置，这是一个字符串值，指示查询参数的名称，允许客户端根据每个请求设置页面大小。默认为None，表示客户端可能无法控制所请求的页面大小。
max_page_size - 如果设置，这是一个数字值，表示允许的最大页面大小。该属性仅在page_size_query_param设置时才有效。
last_page_strings- 字符串值的列表或元组值，指示可用于page_query_param请求集合中最终页面的值。默认为('last',)
template - 在可浏览API中呈现分页控件时使用的模板的名称。可能会被覆盖以修改渲染样式，或者设置为None完全禁用HTML分页控件。默认为"rest_framework/pagination/numbers.html"
LimitOffsetPagination
这种分页样式反映了查找多个数据库记录时使用的语法。
要求：
GET https://api.example.org/accounts/?limit=100&offset=400
要设置这些属性，您应该重写LimitOffsetPagination该类，然后像上面那样启用您的自定义分页类。
default_limit - 一个数字值，指示客户端在查询参数中未提供的限制。默认值与PAGE_SIZE设置键相同。
limit_query_param - 一个字符串值，指示“限制”查询参数的名称。默认为'limit'。
offset_query_param - 一个字符串值，指示“偏移量”查询参数的名称。默认为'offset'。
max_limit - 如果设置，这是一个数字值，表示客户可能要求的最大允许限制。默认为None。
template - 在可浏览API中呈现分页控件时使用的模板的名称。可能会被覆盖以修改渲染样式，或者设置为None完全禁用HTML分页控件。默认为"rest_framework/pagination/numbers.html"。
CursorPagination
基于光标的分页提供了一个不透明的“光标”指示器，客户端可以使用该指示器来遍历结果集
自定义分页样式
要创建自定义分页序列化程序类，您应该继承pagination.BasePagination并覆盖paginate_queryset(self, queryset, request, view=None)和get_paginated_response(self, data)方法：
该paginate_queryset方法传递给初始查询集，并返回一个只包含请求页面中数据的可迭代对象。
该get_paginated_response方法传递序列化的页面数据并返回一个Response实例。
请注意，该paginate_queryset方法可能会在分页实例上设置状态，稍后可能会使用该get_paginated_response方法。
十八，Versioning: 版本
API版本控制允许您更改不同客户端之间的行为。
配置版本控制方案: 全局
REST_FRAMEWORK = {
'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.NamespaceVersioning'
}
局部: versioning_class = versioning.QueryParameterVersioning
以下设置键也用于控制版本控制：
DEFAULT_VERSION。request.version当没有版本信息存在时应该使用的值。默认为None。
ALLOWED_VERSIONS。如果设置，则此值将限制版本控制方案可能返回的版本集，并且如果提供的版本不在此集中，则会引发错误。请注意，用于DEFAULT_VERSION设置的值始终被认为是该ALLOWED_VERSIONS组的一部分（除非是这样None）。默认为None。
VERSION_PARAM。应该用于任何版本控制参数的字符串，例如媒体类型或URL查询参数。默认为'version'。
API参考：
AcceptHeaderVersioning
该方案要求客户端指定版本作为Accept标题中媒体类型的一部分。该版本作为媒体类型参数包含在内，它补充了主要媒体类型。
这是一个使用accept头版本风格的示例HTTP请求。
GET /bookings/ HTTP/1.1
Host: example.com
Accept: application/json; version=1.0
URLPathVersioning
该方案要求客户端将版本指定为URL路径的一部分。
GET /v1/bookings/ HTTP/1.1
Host: example.com
Accept: application/json
您的URL conf必须包含一个与带有'version'关键字参数的版本匹配的模式，以便版本控制方案可以使用此信息。
urlpatterns = [
url(
r'^(?P<version>(v1|v2))/bookings/$',
bookings_list,
name='bookings-list'
),
url(
r'^(?P<version>(v1|v2))/bookings/(?P<pk>[0-9]+)/$',
bookings_detail,
name='bookings-detail'
)
]
NamespaceVersioning
对于客户来说，这个方案与之相同URLPathVersioning。唯一的区别是它在Django应用程序中的配置方式，因为它使用URL命名空间而不是URL关键字参数。
GET /v1/something/ HTTP/1.1
Host: example.com
Accept: application/json
HostNameVersioning
主机名版本控制方案要求客户端将请求的版本指定为URL中主机名的一部分。
例如，以下是对http://v1.example.com/bookings/URL 的HTTP请求：
GET /bookings/ HTTP/1.1
Host: v1.example.com
Accept: application/json
QueryParameterVersioning
该方案是一种简单的样式，其中包含版本作为URL中的查询参数。例如：
GET /something/?version=0.1 HTTP/1.1
Host: example.com
Accept: application/json
自定义版本控制方案
要实现自定义版本控制方案，请创建子类BaseVersioning并覆盖该.determine_version方法。
例:
以下示例使用自定义X-API-Version标题来确定所请求的版本。
class XAPIVersionScheme(versioning.BaseVersioning):
def determine_version(self, request, *args, **kwargs):
return request.META.get('HTTP_X_API_VERSION', None)
十九，Content negotiation: 内里协商
内容协商是基于客户端或服务器偏好选择多种可能的表示之一以返回客户端的过程。
设置内容协商: 全局
REST_FRAMEWORK = {
'DEFAULT_CONTENT_NEGOTIATION_CLASS': 'myapp.negotiation.IgnoreClientContentNegotiation',
}bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1dWlkIjoiNjNjZGRhYWFjOTIwNGUyNDhmNmEyOWQ4YTkwZDViZjAiLCJuaWNrIjoiYWRtaW4iLCJ0eXBlIjoxLCJleHAiOjE1MjY2OTE3NDR9.j9UL0QQU0JtulkR1JBG0cF0nJWf9N636pnU-BL_mI7Q
局部: content_negotiation_class = IgnoreClientContentNegotiation
自定义内容协商
您不太可能希望为REST框架提供自定义内容协商方案，但如果需要，您可以这样做。实施自定义内容协商方案覆盖BaseContentNegotiation。
REST框架的内容协商类处理选择适当的请求解析器和适当的响应渲染器，所以你应该实现.select_parser(request, parsers)和.select_renderer(request, renderers, format_suffix)方法。
该select_parser()方法应该从可用解析器列表中返回一个解析器实例，或者None如果没有解析器可以处理传入的请求。
该select_renderer()方法应返回（渲染器实例，媒体类型）的二元组，或引发NotAcceptable异常。
例：
以下是定制内容协商类，它在选择适当的解析器或渲染器时会忽略客户端请求。
from rest_framework.negotiation import BaseContentNegotiation
class IgnoreClientContentNegotiation(BaseContentNegotiation):
def select_parser(self, request, parsers):
"""
Select the first parser in the `.parser_classes` list.
"""
return parsers[0]
def select_renderer(self, request, renderers, format_suffix):
"""
Select the first renderer in the `.renderer_classes` list.
"""
return (renderers[0], renderers[0].media_type)
二十，Metadata: 元数据
REST框架包含一个可配置的机制，用于确定API如何响应OPTIONS请求。这使您可以返回API模式或其他资源信息。
设置元数据方案: 全局
REST_FRAMEWORK = {
'DEFAULT_METADATA_CLASS': 'rest_framework.metadata.SimpleMetadata'
}
局部: metadata_class = APIRootMetadata
自定义元数据类
如果你想提供一个自定义的元数据类，你应该覆盖BaseMetadata和实现该determine_metadata(self, request, view)方法。
您可能想要做的有用事情可能包括返回模式信息，使用诸如JSON模式之类的格式，或将调试信息返回给管理员用户。
例:
以下类可用于限制返回OPTIONS请求的信息。
class MinimalMetadata(BaseMetadata):
"""
Don't include field and other information for `OPTIONS` requests.
Just return the name and description.
"""
def determine_metadata(self, request, view):
return {
'name': view.get_view_name(),
'description': view.get_view_description()
}
二一，Schemas: 架构
API模式是一个非常有用的工具，它允许一系列用例，包括生成参考文档，或者驱动可以与API交互的动态客户端库。
get_schema_view快捷方式
在您的项目中包含模式的最简单方法是使用该 get_schema_view()函数。
from rest_framework.schemas import get_schema_view
schema_view = get_schema_view(title="Server Monitoring API")
urlpatterns = [
url('^$', schema_view),
...
]
API参考
SchemaGenerator
一个遍历路由URL模式列表的类，为每个视图请求模式并整理生成的CoreAPI文档。
通常你会SchemaGenerator用一个参数实例化，如下所示：
generator = SchemaGenerator(title='Stock Prices API')
参数：
title 必需 - API的名称。
url - API模式的根URL。除非模式包含在路径前缀下，否则此选项不是必需的。
patterns - 生成模式时要检查的URL列表。默认为项目的URL conf。
urlconf - 生成模式时使用的URL配置模块名称。默认为settings.ROOT_URLCONF。
get_schema（self，request）
返回coreapi.Document表示API模式的实例。
get_links（self，request）
返回一个嵌套的字典，其中包含应包含在API模式中的所有链接。
AutoSchema
一个处理模式生成的个人视图反思的类。
AutoSchemaAPIView通过schema属性附加到。
该AutoSchema构造函数使用单个关键字参数 manual_fields。
以下方法可用于覆盖。
get_link（self，path，method，base_url）
返回coreapi.Link与给定视图相对应的实例。
这是主要的入口点。如果您需要为特定视图提供自定义行为，则可以覆盖此内容。
get_description（(self, path, method)）
返回用作链接描述的字符串。默认情况下，这基于上面的“作为文档的模式”部分中描述的视图文档字符串。
get_encoding（(self, path, method)）
与给定视图交互时返回一个字符串，以指示任何请求主体的编码。例如。'application/json'。可能会返回一个空字符串用于不期望请求主体的视图。
get_path_fields（self，path，method）：
返回coreapi.Link()实例列表。一个用于URL中的每个路径参数。
get_serializer_fields（(self, path, method)）
返回coreapi.Link()实例列表。一个用于视图使用的序列化器类中的每个字段。
get_pagination_fields（(self, path, method)）
返回由该视图使用的任何分页类上coreapi.Link()的get_schema_fields()方法返回的实例列表。
get_filter_fields（(self, path, method)）
返回由视图使用的任何过滤器类coreapi.Link()的get_schema_fields()方法返回的实例列表。
get_manual_fields（(self, path, method)）
返回coreapi.Field()要添加或替换生成的字段的实例列表。默认为（可选）manual_fields传递给AutoSchema构造函数。
update_fields（fields，update_with）
效用staticmethod。封装逻辑以通过添加或替换列表中的字段Field.name。可能会被覆盖以调整替换标准。
ManualSchema
允许手动提供coreapi.Field模式的实例列表，以及可选的描述。
class MyView(APIView):
schema = ManualSchema(fields=[
coreapi.Field(
"first_field",
required=True,
location="path",
schema=coreschema.String()
),
coreapi.Field(
"second_field",
required=True,
location="path",
schema=coreschema.String()
),
]
)
该ManualSchema构造函数有两个参数：
fields：coreapi.Field实例列表。需要。
description：一个字符串描述。可选的。
encoding：默认None。字符串编码，例如application/json。可选的。
二二，Format suffixes: 格式后缀
format_suffix_patterns
签名：format_suffix_patterns（urlpatterns，suffix_required = False，allowed=None）
返回一个URL模式列表，其中包含附加到提供的每个URL模式的格式后缀模式
参数：
urlpatterns：必需。一个URL模式列表。
suffix_required：可选。一个布尔值，表示URL中的后缀是否可选或强制。默认为False，意味着后缀默认是可选的。
allowed：可选。有效格式后缀的列表或元组。如果没有提供，将使用通配符格式后缀模式。
例：
from rest_framework.urlpatterns import format_suffix_patterns
from blog import views
urlpatterns = [
url(r'^/$', views.apt_root),
url(r'^comments/$', views.comment_list),
url(r'^comments/(?P<pk>[0-9]+)/$', views.comment_detail)
]
urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
二三，Returning URLs: 返回网址
通常，从Web API返回绝对URI可能是更好的做法，例如http://example.com/foobar，而不是返回相对URI，例如/foobar。
这样做的好处是：
它更明确。
它为您的API客户端留下更少的工作。
在没有原生URI类型的JSON等表示中找到该字符串的含义时，不存在歧义。
它使得使用超链接来完成标记HTML表示等事情变得很容易。
reverse # from rest_framework.reverse import reverse
签名： reverse(viewname, *args, **kwargs)
django.urls.reverse除了返回完全限定的URL之外，其行为与使用该请求确定主机和端口的行为相同。
您应该将该请求作为关键字参数包含在该函数中，例如：
from rest_framework.reverse import reverse
from rest_framework.views import APIView
from django.utils.timezone import now
class APIRootView(APIView):
def get(self, request):
year = now().year
data = {
...
'year-summary-url': reverse('year-summary', args=[year], request=request)
}
return Response(data)
reverse_lazy
签名： reverse_lazy(viewname, *args, **kwargs)
django.urls.reverse_lazy除了返回完全限定的URL之外，其行为与使用该请求确定主机和端口的行为相同。
与reverse函数一样，您应该将请求作为关键字参数包含在函数中，例如：
api_root = reverse_lazy('api-root', request=request)
二四，Exceptions: 异常
REST框架的视图处理各种异常，并处理返回适当的错误响应。
自定义异常处理:
{"status_code": 405, "detail": "Method 'DELETE' not allowed."}
异常配置: 全局配置
REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'rest_framework.views.exception_handler'
}
API参考
APIException
签名： APIException()
为了提供一个自定义异常，子类APIException和设置.status_code，.default_detail以及default_code对类属性。
例如，如果您的API依赖于可能无法访问的第三方服务，则可能需要为“503服务不可用”HTTP响应代码实施例外。你可以这样做：
from rest_framework.exceptions import APIException
class ServiceUnavailable(APIException):
status_code = 503
default_detail = 'Service temporarily unavailable, try again later.'
default_code = 'service_unavailable'
可用的属性和方法是：
.detail - 返回错误的文本描述。
.get_codes() - 返回错误的代码标识符。
.get_full_details() - 返回文本描述和代码标识符。
ParseError
签名： ParseError(detail=None, code=None)
如果请求在访问时包含格式错误的数据则引发request.data。
默认情况下，此异常会导致HTTP状态码“400错误请求”的响应。
AuthenticationFailed
签名： AuthenticationFailed(detail=None, code=None)
当传入的请求包含不正确的身份验证时引发。
NotAuthenticated
签名： NotAuthenticated(detail=None, code=None)
当未经身份验证的请求未通过权限检查时引发。
PermissionDenied
签名： PermissionDenied(detail=None, code=None)
当经过身份验证的请求未通过权限检查时引发。
默认情况下，此异常会导致HTTP状态码“403 Forbidden”的响应。
NotFound
签名： NotFound(detail=None, code=None)
当资源不存在于给定的URL时引发。这个异常相当于标准的Http404Django异常。
默认情况下，此异常会导致HTTP状态码为“404 Not Found”的响应。
MethodNotAllowed
签名： MethodNotAllowed(method, detail=None, code=None)
当传入的请求发生时没有映射到视图上的处理程序方法时引发。
默认情况下，此异常会导致HTTP状态码为“405方法不允许”的响应。
NotAcceptable
签名： NotAcceptable(detail=None, code=None)
当传入的请求发生时，引发Accept任何可用渲染器无法满足的标头时引发。
默认情况下，此异常会导致HTTP状态码为“406不可接受”的响应。
UnsupportedMediaType
签名： UnsupportedMediaType(media_type, detail=None, code=None)
如果在访问时没有解析器可以处理请求数据的内容类型，就会引发此问题request.data。
默认情况下，此异常会导致HTTP状态码“415 Unsupported Media Type”不响应。
Throttled
签名： Throttled(wait=None, detail=None, code=None)
传入的请求未通过限制检查时引发。
默认情况下，此异常会导致HTTP状态码“429太多请求”的响应。
ValidationError
签名： ValidationError(detail, code=None)
这个ValidationError例外与其他APIException类稍有不同：
该detail参数是强制性的，不是可选的。
所述detail参数可以是错误的详细信息列表或字典，并且还可以是嵌套的数据结构。
按照惯例，您应该导入序列化模块并使用完全合格的ValidationError样式，以区别于Django内置的验证错误。例如。raise serializers.ValidationError('This field must be an integer value.')
serializer.is_valid(raise_exception=True)
通用视图使用raise_exception=True标志，这意味着您可以在API中全局覆盖验证错误响应的样式
二五，Status codes: 状态码
不建议在您的响应中使用裸露的状态码。REST框架包含一组命名常量，您可以使用它们使代码更加明显易读。
from rest_framework import status
from rest_framework.response import Response
def empty_view(self):
content = {'please move along': 'nothing to see here'}
return Response(content, status=status.HTTP_404_NOT_FOUND)
Informational - 1xx ：临时响应。
HTTP_100_CONTINUE
HTTP_101_SWITCHING_PROTOCOLS
Successful - 2xx ：这类状态码表明客户的请求已被成功接收，理解和接受。
HTTP_200_OK
HTTP_201_CREATED ：已创建
HTTP_202_ACCEPTED ：已接受
HTTP_203_NON_AUTHORITATIVE_INFORMATION ：非授权信息
HTTP_204_NO_CONTENT ：无内容
HTTP_205_RESET_CONTENT ：重置内容
HTTP_206_PARTIAL_CONTENT ：部分内容
HTTP_207_MULTI_STATUS ：多状态
Redirection - 3xx ：表明用户代理需要采取进一步行动来完成请求。
HTTP_300_MULTIPLE_CHOICES ：多种选择
HTTP_301_MOVED_PERMANENTLY ：永久移动
HTTP_302_FOUND ：找到
HTTP_303_SEE_OTHER ：参见其他
HTTP_304_NOT_MODIFIED ：未修改
HTTP_305_USE_PROXY ：使用代理
HTTP_306_RESERVED ：保留
HTTP_307_TEMPORARY_REDIRECT ：临时重定向
Client Error - 4xx ：用于客户端出现错误的情况。
HTTP_400_BAD_REQUEST ：错误的请求
HTTP_401_UNAUTHORIZED ：未经授权
HTTP_402_PAYMENT_REQUIRED ：付款需要
HTTP_403_FORBIDDEN ：被禁止的
HTTP_404_NOT_FOUND ：未找到
HTTP_405_METHOD_NOT_ALLOWED ：不允许的方法
HTTP_406_NOT_ACCEPTABLE ：不能接受的
HTTP_407_PROXY_AUTHENTICATION_REQUIRED ：需要代理认证
HTTP_408_REQUEST_TIMEOUT ：请求超时
HTTP_409_CONFLICT ：冲突
HTTP_410_GONE ：跑了
HTTP_411_LENGTH_REQUIRED ：长度要求
HTTP_412_PRECONDITION_FAILED ：前提条件失败
HTTP_413_REQUEST_ENTITY_TOO_LARGE ：请求实体太大
HTTP_414_REQUEST_URI_TOO_LONG ：请求URI太长
HTTP_415_UNSUPPORTED_MEDIA_TYPE ：不支持的媒体类型
HTTP_416_REQUESTED_RANGE_NOT_SATISFIABLE ：请求范围不满足
HTTP_417_EXPECTATION_FAILED ：期望失败
HTTP_422_UNPROCESSABLE_ENTITY ：无法处理的实体
HTTP_423_LOCKED ：已锁定
HTTP_424_FAILED_DEPENDENCY ：失败的依赖
HTTP_428_PRECONDITION_REQUIRED ：预先要求
HTTP_429_TOO_MANY_REQUESTS ：太多的要求
HTTP_431_REQUEST_HEADER_FIELDS_TOO_LARGE ：请求标题栏太大
HTTP_451_UNAVAILABLE_FOR_LEGAL_REASONS ：因法律原因不可用
Server Error - 5xx ：指示服务器意识到其发生错误或无法执行请求的情况。
HTTP_500_INTERNAL_SERVER_ERROR ：内部服务器错误
HTTP_501_NOT_IMPLEMENTED ：未实现
HTTP_502_BAD_GATEWAY ：错误的网关
HTTP_503_SERVICE_UNAVAILABLE ：暂停服务
HTTP_504_GATEWAY_TIMEOUT ：网关超时
HTTP_505_HTTP_VERSION_NOT_SUPPORTED ：HTTP版本不支持
HTTP_507_INSUFFICIENT_STORAGE ：存储空间不足
HTTP_511_NETWORK_AUTHENTICATION_REQUIRED ：网络认证要求
以下帮助函数可用于识别响应代码的类别。
- is_informational() # 1xx
- is_success() # 2xx
- is_redirect() # 3xx
- is_client_error() # 4xx
- is_server_error() # 5xx
二六，Testing: 测试
APIRequestFactory
扩展了Django的现有RequestFactory类。
创建测试请求
本APIRequestFactory类支持几乎相同的API来Django的标准RequestFactory类。这意味着，标准.get()，.post()，.put()，.patch()，.delete()，.head()和.options()方法都是可用的。
from rest_framework.test import APIRequestFactory
# Using the standard RequestFactory API to create a form POST request
factory = APIRequestFactory()
request = factory.post('/notes/', {'title': 'new idea'})
强制认证
当使用请求工厂直接测试视图时，能够直接验证请求通常很方便，而不必构造正确的验证凭证。
要强制验证请求，请使用该force_authenticate()方法。
签名: force_authenticate(request, user=None, token=None)
from rest_framework.test import force_authenticate
factory = APIRequestFactory()
user = User.objects.get(username='olivia')
view = AccountDetail.as_view()
# Make an authenticated request to the view...
request = factory.get('/accounts/django-superstars/')
force_authenticate(request, user=user)
response = view(request)
强制CSRF验证
默认情况下，创建的请求APIRequestFactory在传递到REST框架视图时将不会应用CSRF验证。如果您需要明确打开CSRF验证，则可以通过enforce_csrf_checks在实例化工厂时设置标志来实现。
factory = APIRequestFactory(enforce_csrf_checks=True)
APIClient
发出请求
本APIClient类支持相同的请求接口Django的标准Client类。这意味着这一标准.get()，.post()，.put()，.patch()，.delete()，.head()和.options()方法都是可用的。例如：
from rest_framework.test import APIClient
client = APIClient()
client.post('/notes/', {'title': 'new idea'}, format='json')
二七，Settings: 设置
REST框架的配置是在单个Django设置中命名的REST_FRAMEWORK。