Django - Filter 源码解析（一）

在 Django 开发中，Filter 是一个非常重要的概念，它用于对数据库查询结果进行筛选。深入理解 Filter 的源码，有助于我们更好地掌握 Django 的查询机制，写出更高效、更灵活的代码。本文将从基础开始，逐步解析 Filter 的源码。

目录#

  1. Filter 的基本概念
  2. Filter 的核心类
  3. Filter 的查询构建过程
  4. 示例用法
  5. 最佳实践
  6. 参考

1. Filter 的基本概念#

在 Django 中，当我们使用 Model.objects.filter() 方法时，实际上是在构建一个查询集（QuerySet）。Filter 就是用于定义查询条件的方式。它可以根据模型的字段、关系等进行各种条件的组合。

2. Filter 的核心类#

QuerySet 类#

QuerySet 是 Django 中表示数据库查询结果的类。它的 filter 方法是我们使用的入口。在 django/db/models/query.py 中可以找到其定义。

class QuerySet:
    def filter(self, *args, **kwargs):
        # 这里进行了一系列的处理
        clone = self._clone()
        if kwargs:
            clone.add_q(Q(*args, **kwargs))
        return clone

Q 类#

Q 类用于构建复杂的查询条件。它可以进行逻辑与（&）、逻辑或（|）等操作。在 django/db/models/query.py 中定义。

class Q:
    def __init__(self, *args, **kwargs):
        self.children = []
        self.connector = AND
        self.negated = False
        if args or kwargs:
            self.add(args, kwargs)
 
    def add(self, args, kwargs):
        # 处理传入的参数，构建查询条件
        if args:
            if len(args) == 1 and isinstance(args[0], (Q, str)):
                obj = args[0]
                if isinstance(obj, Q):
                    self.children.append(obj)
                else:
                    self.children.append(...)  # 省略部分代码
            else:
                self.children.append(...)  # 省略部分代码
        if kwargs:
            self.children.append(...)  # 省略部分代码

3. Filter 的查询构建过程#

当我们调用 Model.objects.filter(field=value) 时：

  1. 首先创建一个 QuerySet 的克隆（_clone 方法）。
  2. 然后将传入的关键字参数（**kwargs）转换为 Q 对象（通过 Q(*args, **kwargs)）。
  3. 接着将这个 Q 对象添加到克隆的 QuerySet 的查询条件中（add_q 方法）。
  4. 最后返回这个新的 QuerySet。

例如，对于 Book.objects.filter(title="Python 入门")：

  • 会创建一个新的 QuerySet 克隆。
  • 构建 Q(title="Python 入门")。
  • 将其添加到查询条件。
  • 返回包含筛选后结果的 QuerySet。

4. 示例用法#

简单字段筛选#

from myapp.models import Book
 
# 筛选标题为 "Django 实战" 的书籍
books = Book.objects.filter(title="Django 实战")

多条件筛选（逻辑与）#

# 筛选标题为 "Django 实战" 且价格大于 50 的书籍
books = Book.objects.filter(title="Django 实战", price__gt=50)

复杂条件（使用 Q 类）#

from django.db.models import Q
 
# 筛选标题包含 "Django" 或者价格小于 30 的书籍
books = Book.objects.filter(Q(title__icontains="Django") | Q(price__lt=30))

5. 最佳实践#

  • 使用索引：对于经常用于筛选的字段，添加数据库索引可以提高查询效率。
  • 避免过度复杂的条件：过于复杂的 Q 组合可能会使查询性能下降，尽量优化条件逻辑。
  • 缓存查询结果：如果某些查询结果不经常变化，可以考虑使用缓存（如 django.core.cache）。

6. 参考#

通过以上对 Filter 源码的解析，我们对 Django 的查询机制有了更深入的理解，能够更好地运用 Filter 进行高效的数据库查询操作。

2026-08