管理器

class Manager[source]

Manager 是一种接口，它赋予了 Django 模型操作数据库的能力。Django 应用中每个模型拥有至少一个 Manager。

Manager 类的文档介绍位于 执行查询；本页着重介绍自定义 Manager 行为的模型选项。

管理器名称

默认情况下，Django 为每个模型类添加了一个名为 objects 的 Manager。不过，若你想将 objects 用作字段名，或想使用 objects 以外的 Manager 名字，就要在模型基类中重命名。要为指定类重命名 Manager，在该模型中定义一个类型为 models.Manager 的属性。例如:

from django.db import models


class Person(models.Model):
    # ...
    people = models.Manager()

使用这个实例模型时， Person.objects 会产生一个 AttributeError 异常，而 Person.people.all() 会返回包含所有 Person 对象的列表。

自定义管理器

继承基类 Manager，在模型中实例化自定义 Manager，你就可以在该模型中使用自定义的 Manager。

有两种原因可能使你想要自定义 Manager：添加额外的 Manager 方法，修改 Manager 返回的原始 QuerySet。

添加额外的管理器方法

添加额外的 Manager 方法一般是为模型添加 “表级” 功能的更好方法。（对于 “行级” 功能 —— 即，只操作单个模型对象 —— 通过 模型方法，而不是自定义 Manager 的方法。）

例如，这个自定义的 Manager 添加了一个方法 with_counts()：

from django.db import models
from django.db.models.functions import Coalesce


class PollManager(models.Manager):
    def with_counts(self):
        return self.annotate(num_responses=Coalesce(models.Count("response"), 0))


class OpinionPoll(models.Model):
    question = models.CharField(max_length=200)
    objects = PollManager()


class Response(models.Model):
    poll = models.ForeignKey(OpinionPoll, on_delete=models.CASCADE)
    # ...

通过这个示例，你可以使用 OpinionPoll.objects.with_counts() 来获取带有额外的 num_responses 属性附加的 OpinionPoll 对象的 QuerySet。

自定义 Manager 方法能返回任何东西，没有强制它必须返回一个 QuerySet。

另一个需要注意的是，Manager 方法可以访问 self.model 来获取它们附加的模型类。

修改管理器的初始 QuerySet

Manager 的基础 QuerySet 会返回系统中所有的对象。例如，使用以下模型:

from django.db import models


class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)

……语句 Book.objects.all() 会返回数据库中所有的书。

你可以通过重写 Manager.get_queryset() 方法来覆盖 Manager 的基础 QuerySet。 get_queryset() 返回的 QuerySet 应该包含你需要的属性。

例如，以下模型有 两个 Manager —— 一个返回所有对象，另一个仅返回 Roald Dahl 写的书:

# First, define the Manager subclass.
class DahlBookManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(author="Roald Dahl")


# Then hook it into the Book model explicitly.
class Book(models.Model):
    title = models.CharField(max_length=100)
    author = models.CharField(max_length=50)

    objects = models.Manager()  # The default manager.
    dahl_objects = DahlBookManager()  # The Dahl-specific manager.

使用这个实例模型时， Book.objects.all() 会返回数据库中所有的书，而 Book.dahl_objects.all() 仅返回 Roald Dahl 写的书。

因为 get_queryset() 返回一个 QuerySet 对象，你可以在上面调用 filter()， exclude() 和其它的 QuerySet 方法。所以，以下语句是等效的:

Book.dahl_objects.all()
Book.dahl_objects.filter(title="Matilda")
Book.dahl_objects.count()

本例同时介绍了另一个有趣的技巧：在一个模型中使用多个管理器。你可以为一个模型添加任意多个 Manager()。为模型定义通用 "filters" 的非重复方式。

例如：

class AuthorManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(role="A")


class EditorManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(role="E")


class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    role = models.CharField(max_length=1, choices={"A": _("Author"), "E": _("Editor")})
    people = models.Manager()
    authors = AuthorManager()
    editors = EditorManager()

本例允许你调用 Person.authors.all()， Person.editors.all() 和 Person.people.all()，返回符合期望的结果。

默认管理器

Model._default_manager

若你使用自定义 Manager 对象，注意 Django 遇到的第一个 Manager （按照你在模型中定义的顺序）会拥有一个独特的状态。Django 将类定义中的第一个 Manager 视作 “默认” Manager，Django 的几个组件（包括 dumpdata）在用到该模型时会独立地调用该 Manager。故此，选择默认管理器时要万分小心，避免遇到重写的 get_queryset() 无法获取期望的结果这种情况。

你可以通过 Meta.default_manager_name 指定一个自定义的默认管理器。

若你正在编写的代码必须处理未知模型，例如，在实现了通用视图的第三方应用中使用这个管理器（或 _base_manager），而不是假定该模型有一个名为 objects 的管理器。

基础管理器

Model._base_manager

用于访问关联对象的管理器

By default, Django uses an instance of the Model._base_manager manager class when accessing related objects (e.g. choice.question), not the _default_manager on the related object. This is because Django needs to be able to retrieve the related object, even if it would otherwise be filtered out (and hence be inaccessible) by the default manager.

若基本管理器类 (django.db.models.Manager) 无法满足需求，你可以通过设置 Meta.base_manager_name 告诉 Django 使用哪个类。

在关联模型上执行查询时不会使用基础管理器，或者当访问一对多或多对多关系( accessing a one-to-many or many-to-many relationship )。例如，若 来自教程 的模型 Question 有个 deleted 字段，还有一个基础管理器，用于过滤掉 deleted=True 的实例。由 Choice.objects.filter(question__name__startswith='What') 返回的查询结果集会包含关联至已删除的问题的选项。

不要在这类管理器子类中过滤掉任何结果

该管理器用于访问由其它模型关联过来的对象。这些情况下，Django 要能访问待获取模型的全部对象，这样就能检索出其指向的 任何东西。

因此，你不应该覆盖 get_queryset() 来过滤任何rows。如果你这么做，Django 会返回不完整的结果。

管理器调用自定义 QuerySet 方法

因为大部分的标准 QuerySet 方法能直接从 Manager 访问，这个实例仅适用于你在自定义 QuerySet 中定义了额外方法，且在 Manager 中实现了它们:

class PersonQuerySet(models.QuerySet):
    def authors(self):
        return self.filter(role="A")

    def editors(self):
        return self.filter(role="E")


class PersonManager(models.Manager):
    def get_queryset(self):
        return PersonQuerySet(self.model, using=self._db)

    def authors(self):
        return self.get_queryset().authors()

    def editors(self):
        return self.get_queryset().editors()


class Person(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    role = models.CharField(max_length=1, choices={"A": _("Author"), "E": _("Editor")})
    people = PersonManager()

本例允许你从管理器 Person.people 直接调用 authors() 和 editors()。

创建带有 QuerySet 方法的管理器

要替换前面的要求复制 QuerySet 和 Manager 方法的方案， 可以用 QuerySet.as_manager() 创建一个 Manager 实例，拷贝了自定义 QuerySet 的方法:

class Person(models.Model):
    ...
    people = PersonQuerySet.as_manager()

由 QuerySet.as_manager() 创建的 Manager 实例实质上等价于前面例子中的 PersonManager。

不是每个 QuerySet 方法在 Manager 层都是有意义的；例如，我们故意阻止 QuerySet.delete() 被拷贝进 Manager 类中。

方法拷贝规则如下：

• 公开方法默认会被拷贝。

• 私有方法（以下划线打头）默认不会被复制。

• queryset_only 属性值为 False 的方法总是会被复制。

• queryset_only 属性值为 True 的方法永远不会被复制。

例如：

class CustomQuerySet(models.QuerySet):
    # Available on both Manager and QuerySet.
    def public_method(self):
        return

    # Available only on QuerySet.
    def _private_method(self):
        return

    # Available only on QuerySet.
    def opted_out_public_method(self):
        return

    opted_out_public_method.queryset_only = True

    # Available on both Manager and QuerySet.
    def _opted_in_private_method(self):
        return

    _opted_in_private_method.queryset_only = False

from_queryset()

classmethod from_queryset(queryset_class)

对于进阶用法，你可能同时要一个自定义 Manager 和一个自定义 QuerySet。你可以通过调用 Manager.from_queryset() 达成目的，这将会返回一个自定义基础 Manager 的子类，带有一份自定义 QuerySet 方法的拷贝:

class CustomManager(models.Manager):
    def manager_only_method(self):
        return


class CustomQuerySet(models.QuerySet):
    def manager_and_queryset_method(self):
        return


class MyModel(models.Model):
    objects = CustomManager.from_queryset(CustomQuerySet)()

还可以将生成的类存储到变量中：

MyManager = CustomManager.from_queryset(CustomQuerySet)


class MyModel(models.Model):
    objects = MyManager()

自定义管理器和模型继承

下面是 Django 如何处理自定义管理器和 模型继承：

1. 基类的管理器总是被子类以 Python 的普通名称解析顺序继承（子类上的属性会覆盖所有父类上的同名属性；直接父类会覆盖更上一级的，以此类推）。

2. 如果没有在模型或其父类申明管理器，Django 会自动创建 objects 管理器。

3. 一个类的默认管理器要么由 Meta.default_manager_name 指定，要么是模型中申明的第一个管理器，或者是直接父模型的默认管理器。

如果您想通过抽象基类在一组模型上安装自定义管理器，但仍能自定义默认管理器，这些规则提供了必要的灵活性。例如，假设有此基类:

class AbstractBase(models.Model):
    # ...
    objects = CustomManager()

    class Meta:
        abstract = True

如果你在子类中直接使用这个，如果你在子类中没有声明任何管理器，那么 objects 将是默认的管理器：

class ChildA(AbstractBase):
    # ...
    # This class has CustomManager as the default manager.
    pass

如果您想继承 AbstractBase，但提供不同的默认管理器，则可以在子类上提供该默认管理器:

class ChildB(AbstractBase):
    # ...
    # An explicit default manager.
    default_manager = OtherManager()

这里的 default_manager 是默认的。 objects 管理器仍然可用，因为它是继承的，但没有被当做默认管理器。

最后，对于这个示例，假设您想要向子类中添加额外的管理器，但是仍然使用来自 AbstractBase 的默认管理器。您不能直接在子类中添加新的管理器，因为这将覆盖默认管理器，并且您还必须显式地申明来自抽象基类的所有管理器。解决方案是将这个管理器放到另一个基类中，并在默认管理器 之后 将其引入继承层次结构:

class ExtraManager(models.Model):
    extra_manager = OtherManager()

    class Meta:
        abstract = True


class ChildC(AbstractBase, ExtraManager):
    # ...
    # Default manager is CustomManager, but OtherManager is
    # also available via the "extra_manager" attribute.
    pass

请注意，虽然可以在抽象模型上 定义 自定义管理器，但不能使用抽象模型 调用 任何方法。即:

ClassA.objects.do_something()

是合法的，但:

AbstractBase.objects.do_something()

会引发一个异常。这是因为管理器意在封装管理映射对象集合的逻辑。因为您不能拥有抽象对象的集合，所以管理抽象对象是没有意义的。如果您有适用于抽象模型的功能，则应该将该功能放在抽象模型的 静态方法 或 类方法 中。

执行关系

无论你向自定义的 Manager 添加了什么特性，都必须能够对 Manager 实例进行浅拷贝；也就是说，以下代码必须可以正常工作：

>>> import copy
>>> manager = MyManager()
>>> my_copy = copy.copy(manager)

Django 在某些查询期间对管理器对象进行浅拷贝；如果您的管理器无法被复制，那么这些查询将失败。

对于大多数的资源管理器来说，这不是问题。若你只是为 Manager 添加简单的方法，一般不会疏忽地把 Manager 变的不可拷贝。但是，若重写了 Manager 对象用于控制对象状态的 __getattr__ 或其它私有方法，你需要确认你的修改不会影响 Manager 被复制。