Django REST Framework 渲染器(Renderers)深度解析-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00722/article/details/148360318

Django REST Framework 渲染器(Renderers)深度解析

django-rest-framework 项目地址: https://gitcode.com/gh_mirrors/dja/django-rest-framework

什么是渲染器？

在Web开发中，渲染器负责将数据转换为特定格式的响应内容。Django REST Framework中的渲染器组件，能够将Python数据结构转换为JSON、XML、HTML等多种格式的响应。

简单来说，渲染器就是数据格式转换器，它决定了API返回数据的呈现形式。

渲染器的工作原理

内容协商机制

Django REST Framework通过内容协商(Content Negotiation)机制自动选择最合适的渲染器，主要依据以下两个因素：

请求头中的Accept字段：客户端通过这个字段声明它希望接收的数据格式
URL中的格式后缀：如.json或.api等显式指定的格式

渲染器优先级

当客户端没有明确指定接受格式时，框架会按照renderer_classes列表中定义的顺序使用第一个匹配的渲染器。这个设计非常重要，因为它决定了默认的响应格式。

内置渲染器详解

Django REST Framework提供了一系列开箱即用的渲染器：

JSONRenderer

这是最常用的渲染器，特点包括：

默认使用UTF-8编码
输出紧凑格式，无多余空格
支持通过indent参数控制缩进
可通过配置调整编码风格

# 配置示例
REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',
    ],
    'UNICODE_JSON': False,  # 禁用Unicode字符转义
    'COMPACT_JSON': False   # 启用美化输出
}

TemplateHTMLRenderer

专为HTML响应设计的渲染器，特点包括：

使用Django模板系统渲染
响应数据不需要预先序列化
需要指定模板名称
自动创建RequestContext

class UserProfileView(APIView):
    renderer_classes = [TemplateHTMLRenderer]
    
    def get(self, request):
        user = get_object_or_404(User, pk=request.user.pk)
        return Response({'user': user}, template_name='user_profile.html')

BrowsableAPIRenderer

这个渲染器提供了强大的Web浏览界面：

自动生成API文档
支持交互式测试
显示其他可用渲染器的输出
可自定义默认渲染行为

class CustomBrowsableRenderer(BrowsableAPIRenderer):
    def get_default_renderer(self, view):
        return JSONRenderer()  # 在浏览界面默认使用JSON

AdminRenderer

仿照Django Admin风格的渲染器：

适合数据管理类API
提供类似Admin的界面
需要正确配置URL字段

class AccountViewSet(ModelViewSet):
    renderer_classes = [AdminRenderer, JSONRenderer]
    queryset = Account.objects.all()
    serializer_class = AccountSerializer

自定义渲染器开发指南

创建自定义渲染器只需继承BaseRenderer并实现几个关键属性和方法：

class ExcelRenderer(renderers.BaseRenderer):
    media_type = 'application/vnd.ms-excel'
    format = 'xls'
    charset = None
    render_style = 'binary'

    def render(self, data, accepted_media_type=None, renderer_context=None):
        # 使用第三方库如openpyxl生成Excel文件
        output = io.BytesIO()
        workbook = openpyxl.Workbook()
        # ...填充数据逻辑...
        workbook.save(output)
        return output.getvalue()

关键注意事项

字符编码：默认UTF-8，可覆盖charset属性
二进制内容：设置charset=None和render_style='binary'
上下文访问：通过renderer_context获取请求、视图等信息

高级应用场景

多格式支持

单个端点支持多种响应格式：

@api_view(['GET'])
@renderer_classes([JSONRenderer, TemplateHTMLRenderer])
def user_list(request):
    users = User.objects.all()
    if request.accepted_renderer.format == 'html':
        return Response({'users': users}, template_name='user_list.html')
    serializer = UserSerializer(users, many=True)
    return Response(serializer.data)

媒体类型通配

处理一类媒体类型：

class ImageRenderer(renderers.BaseRenderer):
    media_type = 'image/*'  # 匹配所有图片类型
    
    def render(self, data, context):
        # 根据Accept头返回不同图片格式
        accept = context['request'].accepted_media_type
        if accept == 'image/png':
            return generate_png(data)
        elif accept == 'image/jpeg':
            return generate_jpeg(data)