当前位置：首页 > news >正文

如何使用Django REST Framework渲染器：JSON/XML/HTML多格式输出完整指南

news 2026/4/27 20:42:18

如何使用Django REST Framework渲染器：JSON/XML/HTML多格式输出完整指南

【免费下载链接】django-rest-frameworkWeb APIs for Django. 🎸项目地址: https://gitcode.com/gh_mirrors/dj/django-rest-framework

Django REST Framework（DRF）是一个强大的工具集，用于构建Web API。它提供了灵活的渲染器系统，让开发者能够轻松地为API支持多种输出格式，如JSON、XML和HTML等。本文将详细介绍DRF渲染器的核心概念、常用类型以及如何配置和使用它们，帮助你快速掌握多格式API输出的实现方法。

什么是DRF渲染器？

DRF渲染器是负责将API响应数据转换为特定格式的组件。它们根据客户端请求的Accept头信息，自动选择合适的格式进行响应。这意味着同一个API端点可以同时支持多种数据格式，极大地提高了API的灵活性和兼容性。

DRF的渲染器系统在rest_framework/renderers.py中实现，提供了一系列内置渲染器，同时也支持自定义渲染器的开发。

常用DRF渲染器类型

JSON渲染器

JSON是API开发中最常用的数据格式。DRF提供了JSONRenderer作为默认渲染器，能够将Python数据结构转换为JSON格式。

# settings.py REST_FRAMEWORK = { 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework.renderers.JSONRenderer', ] }

可浏览API渲染器

DRF的一大特色是其可浏览的API界面，这得益于BrowsableAPIRenderer。它提供了一个美观的HTML界面，方便开发者测试和调试API。

上图展示了DRF的可浏览API界面，它不仅显示了API的响应数据，还提供了交互功能，让开发者可以直接在浏览器中测试API端点。

XML渲染器

对于需要支持XML格式的API，DRF提供了XMLRenderer。使用前需要安装defusedxml库：

pip install defusedxml

然后在设置中添加XML渲染器：

# settings.py REST_FRAMEWORK = { 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.XMLRenderer', ] }

其他渲染器

DRF还提供了其他一些有用的渲染器，如：

TemplateHTMLRenderer：使用Django模板生成HTML响应
StaticHTMLRenderer：返回预定义的HTML内容
JSONPRenderer：支持JSONP格式，方便跨域请求

如何配置渲染器

全局配置

在Django的settings.py中配置DEFAULT_RENDERER_CLASSES可以为整个项目设置默认渲染器：

# settings.py REST_FRAMEWORK = { 'DEFAULT_RENDERER_CLASSES': [ 'rest_framework.renderers.JSONRenderer', 'rest_framework.renderers.BrowsableAPIRenderer', ] }

视图级别配置

你也可以在单个视图或视图集上覆盖全局渲染器配置：

from rest_framework.renderers import JSONRenderer, XMLRenderer from rest_framework.viewsets import ModelViewSet from .models import Book from .serializers import BookSerializer class BookViewSet(ModelViewSet): queryset = Book.objects.all() serializer_class = BookSerializer renderer_classes = [JSONRenderer, XMLRenderer]

函数视图配置

对于基于函数的视图，可以使用@api_view装饰器的renderer_classes参数：

from rest_framework.decorators import api_view, renderer_classes from rest_framework.renderers import JSONRenderer, XMLRenderer from rest_framework.response import Response @api_view(['GET']) @renderer_classes([JSONRenderer, XMLRenderer]) def book_list(request): books = Book.objects.all() serializer = BookSerializer(books, many=True) return Response(serializer.data)

如何测试不同的渲染格式

客户端可以通过设置Accept请求头来指定所需的响应格式。例如：

对于JSON格式：Accept: application/json
对于XML格式：Accept: application/xml
对于HTML格式：Accept: text/html

在DRF的可浏览API中，你可以通过界面右上角的格式选择器轻松切换不同的渲染格式：

上图显示了DRF API响应中的Content-Type头信息，表明当前响应使用的是HTML格式。

自定义渲染器

如果DRF提供的内置渲染器不能满足你的需求，你可以创建自定义渲染器。自定义渲染器需要继承BaseRenderer并实现render()方法。

例如，创建一个CSV渲染器：

from rest_framework.renderers import BaseRenderer import csv from io import StringIO class CSVRenderer(BaseRenderer): media_type = 'text/csv' format = 'csv' def render(self, data, media_type=None, renderer_context=None): renderer_context = renderer_context or {} response = renderer_context.get('response') if response and response.exception: return self.render_error(data) csv_buffer = StringIO() writer = csv.writer(csv_buffer) # 写入表头 if data and isinstance(data, list): writer.writerow(data[0].keys()) # 写入数据行 for item in data: writer.writerow(item.values()) return csv_buffer.getvalue()

然后在视图中使用这个自定义渲染器：

class BookViewSet(ModelViewSet): queryset = Book.objects.all() serializer_class = BookSerializer renderer_classes = [JSONRenderer, XMLRenderer, CSVRenderer]

渲染器的高级用法

条件渲染

你可以根据请求的某些条件动态选择渲染器。例如，只为管理员用户提供HTML渲染：

from rest_framework.renderers import JSONRenderer, BrowsableAPIRenderer class ConditionalBrowsableAPIRenderer(BrowsableAPIRenderer): def allow(self, renderer_context): request = renderer_context['request'] return request.user.is_staff class BookViewSet(ModelViewSet): queryset = Book.objects.all() serializer_class = BookSerializer renderer_classes = [JSONRenderer, ConditionalBrowsableAPIRenderer]

渲染器链

DRF允许你定义一个渲染器链，它会按顺序尝试每个渲染器，直到找到一个可以处理请求的渲染器。这在处理复杂的内容协商时非常有用。

实际应用示例

下面是一个完整的示例，展示如何在DRF中使用多种渲染器：

# serializers.py from rest_framework import serializers from .models import User class UserSerializer(serializers.ModelSerializer): class Meta: model = User fields = ['id', 'username', 'email', 'is_active', 'is_staff'] # views.py from rest_framework.renderers import JSONRenderer, XMLRenderer, BrowsableAPIRenderer from rest_framework.viewsets import ModelViewSet from .models import User from .serializers import UserSerializer class UserViewSet(ModelViewSet): queryset = User.objects.all() serializer_class = UserSerializer renderer_classes = [JSONRenderer, XMLRenderer, BrowsableAPIRenderer]

这个视图集将支持JSON、XML和HTML三种格式的响应。当你在浏览器中访问这个API时，会看到友好的HTML界面：