如何用Django REST Framework的ModelSerializer添加顶级JSON字段

我明白你现在的需求：原本用ModelSerializer返回的是纯数据列表，现在要把这个列表放到一个子字段里，同时在根JSON里加一些自定义字段（比如状态码、总数、提示信息这类）。下面给你两种最常用的实现方式，都是DRF里很常规的操作：

方法一：在视图层直接构造响应结构（最直观简单） #

这种方法不需要修改你的Serializer，直接在View里把序列化后的列表包装到新的字典结构里，同时添加自定义字段。

假设你原来的views.py是这样的：

from rest_framework import generics
from .models import YourModel
from .serializer import YourModelSerializer

class YourModelListView(generics.ListAPIView):
    queryset = YourModel.objects.all()
    serializer_class = YourModelSerializer

修改后变成：

from rest_framework import generics, status
from rest_framework.response import Response
from .models import YourModel
from .serializer import YourModelSerializer

class YourModelListView(generics.ListAPIView):
    queryset = YourModel.objects.all()
    serializer_class = YourModelSerializer

    def list(self, request, *args, **kwargs):
        # 先获取原本的序列化数据
        queryset = self.filter_queryset(self.get_queryset())
        page = self.paginate_queryset(queryset)
        if page is not None:
            serializer = self.get_serializer(page, many=True)
            return self.get_paginated_response(
                {
                    "code": status.HTTP_200_OK,
                    "message": "数据获取成功",
                    "data": serializer.data
                }
            )
        
        serializer = self.get_serializer(queryset, many=True)
        # 构造自定义的响应结构
        return Response({
            "code": status.HTTP_200_OK,
            "message": "数据获取成功",
            "count": queryset.count(),  # 额外添加总数字段
            "data": serializer.data  # 把原本的列表放到data子字段里
        })

这种方式的好处是不用改动序列化器，适合快速调整响应格式，尤其是多个视图需要统一格式时，还可以把这个包装逻辑抽成一个混合类（Mixin）复用。

方法二：在序列化器层修改输出结构（适合需要复用格式的场景） #

如果你的多个序列化器都需要输出这种带根字段的结构，可以在Serializer里重写to_representation方法，或者创建一个通用的包装序列化器。

方式A：重写ListSerializer的to_representation #

默认情况下，当many=True时，DRF会使用ListSerializer来处理批量数据，我们可以自定义这个类：

在serializer.py中：

from rest_framework import serializers
from .models import YourModel

class CustomListSerializer(serializers.ListSerializer):
    def to_representation(self, data):
        # 这里构造根层级的结构
        return {
            "code": 200,
            "message": "success",
            "count": len(data),
            "results": super().to_representation(data)  # 原列表数据放到results字段
        }

class YourModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = YourModel
        fields = "__all__"
        # 指定使用我们自定义的ListSerializer
        list_serializer_class = CustomListSerializer

然后在视图里正常使用这个序列化器即可，当你序列化多个对象时，就会自动输出带根字段的结构。

方式B：用嵌套序列化器包装结果 #

如果你需要更灵活的控制，可以创建一个专门的包装序列化器，把数据列表作为它的一个字段：

serializer.py：

from rest_framework import serializers
from .models import YourModel

class YourModelSerializer(serializers.ModelSerializer):
    class Meta:
        model = YourModel
        fields = "__all__"

class ResponseWrapperSerializer(serializers.Serializer):
    code = serializers.IntegerField(default=200)
    message = serializers.CharField(default="数据获取成功")
    data = YourModelSerializer(many=True)  # 嵌套我们的模型序列化器

然后在视图里使用这个包装序列化器：

from rest_framework import generics
from rest_framework.response import Response
from .models import YourModel
from .serializer import ResponseWrapperSerializer

class YourModelListView(generics.ListAPIView):
    queryset = YourModel.objects.all()

    def list(self, request, *args, **kwargs):
        queryset = self.filter_queryset(self.get_queryset())
        # 使用包装序列化器
        serializer = ResponseWrapperSerializer({
            "data": queryset,
            "message": "自定义提示信息"  # 可以动态传参
        })
        return Response(serializer.data)

总结 #

• 如果只是单个视图需要调整格式，方法一最快捷；
• 如果多个视图或序列化器需要统一格式，方法二更适合复用；
• 要是需要分页的话，记得在分页响应里也同步调整结构（方法一里已经包含了分页的处理）。

内容的提问来源于stack exchange，提问作者ni9e