如何在Django Admin中实现JSON字段的搜索与过滤功能

Django Admin默认的search_fields、list_filter配置不直接支持JSON字段的嵌套键匹配，针对MongoDB（通常搭配djongo驱动）的场景，可按以下方式实现：

一、JSON字段搜索实现 #

不要直接将JSON键传入默认的search_fields配置，原生逻辑会将传入值识别为普通字段名抛出异常，通过重写get_search_results方法自定义搜索逻辑即可，支持灵活配置要搜索的JSON键：

from django.contrib import admin
from django.db.models import Q
from .models import YourTargetModel

class YourModelAdmin(admin.ModelAdmin):
    # 常规非JSON字段可正常写入search_fields
    search_fields = ['id', 'name']
    # 单独配置需要搜索的JSON键，支持嵌套键写法
    json_search_keys = ['username', 'contact.email', 'profile.age']
    # 替换为你模型中实际的JSONField字段名
    json_field_name = 'extra_info'

    def get_search_results(self, request, queryset, search_term):
        queryset, use_distinct = super().get_search_results(request, queryset, search_term)
        if not search_term:
            return queryset, use_distinct
        # 拼接JSON字段查询条件
        json_query = Q()
        for key in self.json_search_keys:
            # 嵌套键的点号替换为双下划线，适配Django ORM查询语法
            lookup_path = f"{self.json_field_name}__{key.replace('.', '__')}__icontains"
            json_query |= Q(**{lookup_path: search_term})
        queryset = queryset.filter(json_query)
        return queryset, use_distinct

注意：djongo驱动对MongoDB的JSON字段查询做了原生适配，上述双下划线拼接键路径的写法不需要额外做JSON格式转换，查询效率和普通字段一致。后续要新增/删除搜索的JSON键，只需要修改json_search_keys列表即可。

Django Admin JSON字段功能参考效果

二、JSON字段过滤实现 #

针对JSON字段的过滤，通过自定义SimpleListFilter实现即可，支持固定选项过滤、自定义输入过滤两类场景：

固定选项过滤示例 #

比如要过滤JSON字段中存储的用户状态：

from django.contrib.admin import SimpleListFilter

class JsonUserStatusFilter(SimpleListFilter):
    title = '用户状态' # 过滤栏显示的名称
    parameter_name = 'user_status' # 地址栏传参标识

    def lookups(self, request, model_admin):
        # 定义过滤选项：(JSON中存储的实际值, 页面显示文本)
        return (
            ('active', '正常账号'),
            ('banned', '封禁账号'),
            ('unverified', '未实名认证'),
        )

    def queryset(self, request, queryset):
        if self.value():
            # 同样用双下划线拼接JSON键路径做匹配
            return queryset.filter(extra_info__status=self.value())
        return queryset

写完过滤器后，将其加入Admin类的list_filter配置即可生效：

class YourModelAdmin(admin.ModelAdmin):
    # ...其他配置
    list_filter = [JsonUserStatusFilter]

如果需要实现输入关键词/数值范围的动态过滤，只需要在自定义过滤器中增加表单渲染逻辑，查询部分的写法和上述逻辑完全一致。

三、常见踩坑说明 #

• 不要尝试直接把extra_info__username这类JSON键路径写入默认search_fields，原生搜索逻辑不会做JSON键解析，会直接报字段不存在错误。
• 嵌套JSON键查询时，必须将键路径中的.替换为__，比如profile.contact.city对应的查询路径是extra_info__profile__contact__city，和Django跨关联表查询语法一致。
• 如果JSON字段存在值为null的情况，可在查询条件中增加__isnull=False的判断，避免匹配到空值条目。

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