如何通过Django/Python API向前端返回复杂嵌套字典对象？

一、直接使用JsonResponse（推荐） #

Django的JsonResponse是专门为返回JSON响应设计的工具，默认就能处理多层嵌套的列表/字典——只要数据里的元素是Python原生可序列化类型：字符串、数字、列表、字典、布尔值、None。

• 基础用法：

  from django.http import JsonResponse
  
  def nested_data_view(request):
      # 示例多层嵌套数据结构
      nested_data = {
          "status": "success",
          "data": {
              "user_info": {
                  "id": 23,
                  "username": "Rafael",
                  "tags": ["backend", "api", "django"]
              },
              "recent_posts": [
                  {"id": 1001, "title": "Django入门笔记", "views": 120},
                  {"id": 1002, "title": "嵌套JSON返回踩坑", "views": 87}
              ]
          }
      }
      # 直接传入数据即可，自动设置content-type为application/json
      return JsonResponse(nested_data)
  

• 处理非原生可序列化类型：
  如果数据里包含datetime、date或Django模型实例这类特殊对象，需要指定Django内置的编码器：

  from django.http import JsonResponse
  from django.core.serializers.json import DjangoJSONEncoder
  from datetime import datetime
  
  def nested_data_with_datetime(request):
      nested_data = {
          "status": "success",
          "created_at": datetime.now(),
          "data": {"user_id": 23, "login_records": ["2024-05-01", "2024-05-02"]}
      }
      # 用DjangoJSONEncoder处理datetime等特殊类型
      return JsonResponse(nested_data, encoder=DjangoJSONEncoder)
  

• 直接返回列表的特殊处理：
  如果要返回的顶层数据是列表而非字典，必须设置safe=False：

  return JsonResponse([{"name": "item1"}, {"name": "item2"}], safe=False)
  

二、使用HttpResponse手动构造JSON #

如果一定要用HttpResponse，需要手动将数据序列化为JSON字符串，并设置正确的响应头：

from django.http import HttpResponse
import json
from django.core.serializers.json import DjangoJSONEncoder

def manual_json_response(request):
    nested_data = {
        "status": "success",
        "data": {"user": {"id":23}, "items": [1,2,3]}
    }
    # 序列化数据，指定编码器处理特殊类型
    json_str = json.dumps(nested_data, cls=DjangoJSONEncoder)
    # 显式设置content-type，确保前端识别为JSON
    return HttpResponse(json_str, content_type="application/json")

三、常见问题排查 #

• 报错TypeError: Object of type X is not JSON serializable：
  数据中包含JSON无法直接序列化的类型（比如自定义类实例、Django模型对象）。解决方式要么用DjangoJSONEncoder，要么手动将对象转换为可序列化的字典（比如模型实例可以用Model.objects.values()获取字典格式数据）。
• 返回结果显示为纯字符串而非JSON：
  没有设置正确的content-type，前端无法识别。用JsonResponse会自动处理，用HttpResponse则必须显式指定content_type="application/json"。

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