Django REST framework API 指南&＃xff08;1&＃xff09;&＃xff1a;请求
Django REST framework API 指南&＃xff08;2&＃xff09;&＃xff1a;响应
Django REST framework API 指南&＃xff08;3&＃xff09;&＃xff1a;视图
Django REST framework API 指南&＃xff08;4&＃xff09;&＃xff1a;通用视图
Django REST framework API 指南&＃xff08;5&＃xff09;&＃xff1a;视图集
Django REST framework API 指南&＃xff08;6&＃xff09;&＃xff1a;路由
Django REST framework API 指南&＃xff08;7&＃xff09;&＃xff1a;解析
Django REST framework API 指南&＃xff08;8&＃xff09;&＃xff1a;渲染

官方原文链接

渲染

REST framework 包含许多内置的渲染器类&＃xff0c;允许您使用各种 media type 返回响应。同时也支持自定义渲染器。

如何确定使用哪个渲染器

视图的渲染器集合始终被定义为类列表。当调用视图时&＃xff0c;REST framework 将对请求内容进行分析&＃xff0c;并确定最合适的渲染器以满足请求。内容分析的基本过程包括检查请求的 Accept header&＃xff0c;以确定它在响应中期望的 media type。或者&＃xff0c;用 URL 上的格式后缀明确表示。例如&＃xff0c;URL http://example.com/api/users_count.json 可能始终返回 JSON 数据。

设置渲染器

可以使用 DEFAULT_RENDERER_CLASSES 设置全局的默认渲染器集。例如&＃xff0c;以下设置将使用JSON作为主要 media type&＃xff0c;并且还包含自描述 API。

REST_FRAMEWORK &＃61; {&＃39;DEFAULT_RENDERER_CLASSES&＃39;: (&＃39;rest_framework.renderers.JSONRenderer&＃39;,&＃39;rest_framework.renderers.BrowsableAPIRenderer&＃39;,) }

还可以使用基于 APIView 的视图类来设置单个视图或视图集的渲染器。

from django.contrib.auth.models import User from rest_framework.renderers import JSONRenderer from rest_framework.response import Response from rest_framework.views import APIViewclass UserCountView(APIView):"""A view that returns the count of active users in JSON."""renderer_classes &＃61; (JSONRenderer, )def get(self, request, format&＃61;None):user_count &＃61; User.objects.filter(active&＃61;True).count()content &＃61; {&＃39;user_count&＃39;: user_count}return Response(content)

或者是在基于 &＃64;api_view 装饰器的函数视图上设置。

&＃64;api_view([&＃39;GET&＃39;]) &＃64;renderer_classes((JSONRenderer,)) def user_count_view(request, format&＃61;None):"""A view that returns the count of active users in JSON."""user_count &＃61; User.objects.filter(active&＃61;True).count()content &＃61; {&＃39;user_count&＃39;: user_count}return Response(content)

渲染器类的优先级

在为 API 指定渲染器类时&＃xff0c;需要考虑它们处理每种媒体类型时的优先级&＃xff0c;这点很重要。如果客户端没有指定接受数据的表现形式&＃xff0c;例如发送 Accept&＃xff1a;*/* header&＃xff0c;或者根本不包含 Accept header&＃xff0c;则 REST framework 将选择列表中的第一个渲染器用于响应。

例如&＃xff0c;如果你的 API 提供 JSON 响应和可浏览的 HTML API&＃xff0c;则可能需要将 JSONRenderer 作为默认渲染器&＃xff0c;以便将 JSON 响应发送给未指定 Accept header 的客户端。

如果你的 API 包含可根据请求同时处理常规网页和 API 响应的视图&＃xff0c;那么你可以考虑将 TemplateHTMLRenderer 设置为默认渲染器&＃xff0c;以便与发送 broken accept headers 的老式浏览器很好地配合使用。

API 参考

JSONRenderer

使用 utf-8 编码将请求数据呈现为 JSON。

请注意&＃xff0c;默认风格包含 unicode 字符&＃xff0c;并使用紧凑风格呈现&＃xff08;没有多余的空白&＃xff09;响应&＃xff1a;

{"unicode black star":"★","value":999}

客户端可能还会包含 “缩进” media type 参数&＃xff0c;在这种情况下&＃xff0c;返回的 JSON 将会缩进。

比如&＃xff1a; Accept: application/json; indent&＃61;4。

{"unicode black star": "★","value": 999 }

使用 UNICODE_JSON 和 COMPACT_JSON 设置键可以更改默认的 JSON 编码风格。

.media_type&＃xff1a; application/json

.format&＃xff1a; &＃39;.json&＃39;

.charset&＃xff1a; None

TemplateHTMLRenderer

使用 Django 的标准模板将数据呈现为 HTML。与其他渲染器不同&＃xff0c;传递给 Response 的数据不需要序列化。另外&＃xff0c;创建 Response 时可能需要包含 template_name 参数。

TemplateHTMLRenderer 将创建一个 RequestContext&＃xff0c;使用 response.data 作为上下文字典&＃xff0c;并确定用于呈现上下文的模板名称。

模板名称由&＃xff08;按优先顺序&＃xff09;确定&＃xff1a;

传递给 response 的显式 template_name 参数。
在此类上设置明确的 .template_name 属性。
调用 view.get_template_names() 的返回结果。

使用 TemplateHTMLRenderer 的视图示例&＃xff1a;

class UserDetail(generics.RetrieveAPIView):"""A view that returns a templated HTML representation of a given user."""queryset &＃61; User.objects.all()renderer_classes &＃61; (TemplateHTMLRenderer,)def get(self, request, *args, **kwargs):self.object &＃61; self.get_object()return Response({&＃39;user&＃39;: self.object}, template_name&＃61;&＃39;user_detail.html&＃39;)

你可以使用 TemplateHTMLRenderer 来使 REST framework 返回常规 HTML 页面&＃xff0c;或者从单个端点&＃xff08;a single endpoint&＃xff09;返回 HTML 和 API 响应。

如果你正在构建使用 TemplateHTMLRenderer 以及其他渲染器类的网站&＃xff0c;则应考虑将 TemplateHTMLRenderer 列为 renderer_classes 列表中的第一个类&＃xff0c;以便即使对于发送格式错误的 ACCEPT: header 的浏览器&＃xff0c;也会优先考虑它。

.media_type&＃xff1a; text/html

.format&＃xff1a; &＃39;.html&＃39;

.charset&＃xff1a; utf-8

StaticHTMLRenderer

一个简单的渲染器&＃xff0c;它只是返回预渲染的 HTML。与其他渲染器不同&＃xff0c;传递给响应对象的数据应该是表示要返回的内容的字符串。

使用 StaticHTMLRenderer 的视图示例&＃xff1a;

&＃64;api_view((&＃39;GET&＃39;,)) &＃64;renderer_classes((StaticHTMLRenderer,)) def simple_html_view(request):data &＃61; &＃39;

`Hello, world`

&＃39;return Response(data)

你可以使用 StaticHTMLRenderer 来使 REST framework 返回常规 HTML 页面&＃xff0c;或者从单个端点&＃xff08;a single endpoint&＃xff09;返回 HTML 和 API 响应。

.media_type&＃xff1a; text/html

.format&＃xff1a; &＃39;.html&＃39;

.charset&＃xff1a; utf-8

BrowsableAPIRenderer

将数据呈现为可浏览的 HTML API&＃xff1a;

该渲染器将确定哪个其他渲染器被赋予最高优先级&＃xff0c;并使用该渲染器在 HTML 页面中显示 API 风格响应。

.media_type&＃xff1a; text/html

.format&＃xff1a; &＃39;.api&＃39;

.charset&＃xff1a; utf-8

.template&＃xff1a; &＃39;rest_framework/api.html&＃39;

自定义 BrowsableAPIRenderer

默认情况下&＃xff0c;除 BrowsableAPIRenderer 之外&＃xff0c;响应内容将使用最高优先级的渲染器渲染。如果你需要自定义此行为&＃xff0c;例如&＃xff0c;将 HTML 用作默认返回格式&＃xff0c;但在可浏览的 API 中使用 JSON&＃xff0c;则可以通过覆盖 get_default_renderer() 方法来实现。

例如&＃xff1a;

class CustomBrowsableAPIRenderer(BrowsableAPIRenderer):def get_default_renderer(self, view):return JSONRenderer()

AdminRenderer

将数据呈现为 HTML&＃xff0c;以显示类似管理员的内容&＃xff1a;

该渲染器适用于 CRUD 风格的 Web API&＃xff0c;该 API 还应提供用于管理数据的用户友好界面。

请注意&＃xff0c; AdminRenderer 对于嵌套或列出序列化输入的视图不起作用&＃xff0c;因为 HTML 表单无法正确支持它们。

注意&＃xff1a;当数据中存在正确配置的 URL_FIELD_NAME &＃xff08;默认为 url&＃xff09;属性时&＃xff0c; AdminRenderer 仅能够包含指向详细页面的链接。对于 HyperlinkedModelSerializer &＃xff0c;情况就是这样&＃xff0c;但对于 ModelSerializer 类或普通 Serializer 类&＃xff0c;你需要确保明确包含该字段。例如&＃xff0c;在这里我们使用模型 get_absolute_url 方法&＃xff1a;

class AccountSerializer(serializers.ModelSerializer):url &＃61; serializers.CharField(source&＃61;&＃39;get_absolute_url&＃39;, read_only&＃61;True)class Meta:model &＃61; Account

.media_type&＃xff1a; text/html

.format&＃xff1a; &＃39;.admin&＃39;

.charset&＃xff1a; utf-8

.template&＃xff1a; &＃39;rest_framework/admin.html&＃39;

HTMLFormRenderer

将序列化返回的数据呈现为 HTML 表单。该渲染器的输出不包含封闭的标签&＃xff0c;隐藏的 CSRF 输入或任何提交按钮。

这个渲染器不是直接使用&＃xff0c;而是可以通过将一个序列化器实例传递给 render_form 模板标签来在模板中使用。

{% load rest_framework %}{% csrf_token %}{% render_form serializer %}

.media_type&＃xff1a; text/html

.format&＃xff1a; &＃39;.form&＃39;

.charset&＃xff1a; utf-8

.template&＃xff1a; &＃39;rest_framework/horizontal/form.html&＃39;

MultiPartRenderer

该渲染器用于呈现 HTML multipart form 数据。它不适合作为响应渲染器&＃xff0c;而是用于创建测试请求&＃xff0c;使用REST framework 的测试客户端和测试请求工厂。

.media_type&＃xff1a; multipart/form-data; boundary&＃61;BoUnDaRyStRiNg

.format&＃xff1a; &＃39;.multipart&＃39;

.charset&＃xff1a; utf-8

自定义渲染器

要实现自定义渲染器&＃xff0c;您应该继承 BaseRenderer &＃xff0c;设置 .media_type 和 .format 属性&＃xff0c;并实现 .render(self, data, media_type&＃61;None, renderer_context&＃61;None) 方法。

该方法应返回一个字符串&＃xff0c;它将用作 HTTP 响应的主体。

传递给 .render() 方法的参数是&＃xff1a;

`data`

请求数据&＃xff0c;由 Response() 实例化时设置。

`media_type&＃61;None`

可选的。如果提供&＃xff0c;这是接受的媒体类型&＃xff0c;由内容协商&＃xff08;content negotiation&＃xff09;阶段确定。

依赖于客户端的 Accept: header&＃xff0c;它可以比渲染器的 media_type 属性更具体&＃xff0c;并且可能包含媒体类型参数。比如 "application/json; nested&＃61;true" 。

`renderer_context&＃61;None`

可选的。如果提供&＃xff0c;它是视图提供的上下文信息字典。

默认情况下&＃xff0c;这将包括以下键&＃xff1a;view , request , response , args , kwargs 。

举个栗子

以下是一个示例纯文本渲染器&＃xff0c;它将返回带有数据参数的响应作为响应的内容。

from django.utils.encoding import smart_unicode from rest_framework import renderersclass PlainTextRenderer(renderers.BaseRenderer):media_type &＃61; &＃39;text/plain&＃39;format &＃61; &＃39;txt&＃39;def render(self, data, media_type&＃61;None, renderer_context&＃61;None):return data.encode(self.charset)

设置 charset

默认情况下&＃xff0c;渲染器类被假定为使用 UTF-8 编码。要使用不同的编码&＃xff0c;请在渲染器上设置 charset 属性。

class PlainTextRenderer(renderers.BaseRenderer):media_type &＃61; &＃39;text/plain&＃39;format &＃61; &＃39;txt&＃39;charset &＃61; &＃39;iso-8859-1&＃39;def render(self, data, media_type&＃61;None, renderer_context&＃61;None):return data.encode(self.charset)

请注意&＃xff0c;如果渲染器类返回一个 unicode 字符串&＃xff0c;则响应内容将被 Response 类强制为一个 bytestring&＃xff0c;请在渲染器上设置 charset 属性用于确定编码。

如果渲染器返回代表原始二进制内容的字符串&＃xff0c;则应将 charset 值设置为 None&＃xff0c;这将确保响应的 Content-Type header 不会设置 charset 值。

在某些情况下&＃xff0c;你可能还想将 render_style 属性设置为 &＃39;binary&＃39;。这样做也将确保可浏览的 API 不会尝试将二进制内容显示为字符串。

class JPEGRenderer(renderers.BaseRenderer):media_type &＃61; &＃39;image/jpeg&＃39;format &＃61; &＃39;jpg&＃39;charset &＃61; Nonerender_style &＃61; &＃39;binary&＃39;def render(self, data, media_type&＃61;None, renderer_context&＃61;None):return data

渲染器的高级用法

你可以使用 REST framework 的渲染器来做一些非常灵活的事情。例如...

根据请求的 media type&＃xff0c;提供来自同一端点的平面或嵌套&＃xff08;flat or nested&＃xff09;表示。
同时处理常规 HTML 网页和来自相同端点的基于 JSON 的 API 响应。
指定 API 客户端使用的多种 HTML 表示形式。
不用明确指定渲染器的 media type&＃xff0c;例如使用 media_type &＃61;&＃39;image/*&＃39;&＃xff0c;并使用 Accept header 改变响应的编码。

media type 的变化

在某些情况下&＃xff0c;可能希望视图根据接受的 media type 使用不同的序列化风格。如果需要这样做&＃xff0c;可以访问 request.accepted_renderer 以确定将用于响应的协商&＃xff08;negotiate&＃xff09;渲染器。

例如&＃xff1a;

&＃64;api_view((&＃39;GET&＃39;,)) &＃64;renderer_classes((TemplateHTMLRenderer, JSONRenderer)) def list_users(request):"""A view that can return JSON or HTML representationsof the users in the system."""queryset &＃61; Users.objects.filter(active&＃61;True)if request.accepted_renderer.format &＃61;&＃61; &＃39;html&＃39;:# TemplateHTMLRenderer takes a context dict,# and additionally requires a &＃39;template_name&＃39;.# It does not require serialization.data &＃61; {&＃39;users&＃39;: queryset}return Response(data, template_name&＃61;&＃39;list_users.html&＃39;)# JSONRenderer requires serialized data as normal.serializer &＃61; UserSerializer(instance&＃61;queryset)data &＃61; serializer.datareturn Response(data)