<!--
译者：Github@wizardforcel
-->
# 管理器 #
**class Manager**
管理器是一个接口，数据库查询操作通过它提供给django的模型。django应用的每个模型至少拥有一个 管理器。
管理器类的工作方式在 执行查询文档中阐述，而这篇文档涉及了自定义管理器行为的模型选项。
## 管理器的名字 ##
通常，django为每个模型类添加一个名为objects的管理器。然而，如果你想将objects用于字段名称，或者你想使用其它名称而不是objects访问管理器，你可以在每个模型类中重命名它。在模型中定义一个值为models.Manager()的属性，来重命名管理器。例如：
```
from django.db import models
class Person(models.Model):
#...
people = models.Manager()
```
使用例子中的模型， Person.objects会抛出AttributeError异常，而Person.people.all()会返回一个包含所有Person对象的列表。
## 自定义管理器 ##
在一个特定的模型中，你可以通过继承管理器类来构建一个自定义的管理器，以及实例化你的自定义管理器。
你有两个原因可能会自己定义管理器：向器类中添加额外的方法，或者修改管理器最初返回的查询集。
### 添加额外的管理器方法 ###
为你的模型添加表级(table-level)功能时，采用添加额外的管理器方法是更好的处理方式。如果要添加行级功能－－就是说该功能只对某个模型的实例对象起作用。在这种情况下，使用 模型方法 比使用自定义的管理器方法要更好。）
自定义的管理器 方法可以返回你想要的任何数据，而不只是查询集。
例如，下面这个自定义的 管理器提供了一个 with_counts() 方法，它返回所有 OpinionPoll 对象的列表，而且列表中的每个对象都多了一个名为 num_responses的属性，这个属性保存一个聚合查询(COUNT*)的结果：
```
from django.db import models
class PollManager(models.Manager):
def with_counts(self):
from django.db import connection
cursor = connection.cursor()
cursor.execute("""
SELECT p.id, p.question, p.poll_date, COUNT(*)
FROM polls_opinionpoll p, polls_response r
WHERE p.id = r.poll_id
GROUP BY p.id, p.question, p.poll_date
ORDER BY p.poll_date DESC""")
result_list = []
for row in cursor.fetchall():
p = self.model(id=row[0], question=row[1], poll_date=row[2])
p.num_responses = row[3]
result_list.append(p)
return result_list
class OpinionPoll(models.Model):
question = models.CharField(max_length=200)
poll_date = models.DateField()
objects = PollManager()
class Response(models.Model):
poll = models.ForeignKey(OpinionPoll)
person_name = models.CharField(max_length=50)
response = models.TextField()
```
在这个例子中，你已经可以使用 OpinionPoll.objects.with_counts() 得到所有含有 num_responses属性的 OpinionPoll对象。
这个例子要注意的一点是： 管理器方法可以访问 self.model来得到它所用到的模型类。
### 修改管理器初始的查询集 ###
管理器自带的 查询集返回系统中所有的对象。例如，使用下面这个模型：
```
from django.db import models
class Book(models.Model):
title = models.CharField(max_length=100)
author = models.CharField(max_length=50)
```
... Book.objects.all() 语句将返回数据库中所有的 Book 对象。
你可以通过重写 Manager.get_queryset() 的方法来覆盖 管理器自带的 查询集。get_queryset() 会根据你所需要的属性返回 查询集。
例如，下面的模型有两个 管理器，一个返回所有的对象，另一个则只返回作者是 Roald Dahl 的对象：
```
# First, define the Manager subclass.
class DahlBookManager(models.Manager):
def get_queryset(self):
return super(DahlBookManager, self).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() 返回的是一个 查询集 对象，所以你仍可以对它使用 filter(), exclude()和其他 查询集的方法。所以下面这些例子都是可用的：
```
Book.dahl_objects.all()
Book.dahl_objects.filter(title='Matilda')
Book.dahl_objects.count()
```
这个例子还展示了另外一个很有意思的技巧：在同一个模型中使用多个管理器。你可以随你所意在一个模型里面添加多个 Manager() 实例。下面就用很简单的方法，给模型添加通用过滤器：
例如：
```
class AuthorManager(models.Manager):
def get_queryset(self):
return super(AuthorManager, self).get_queryset().filter(role='A')
class EditorManager(models.Manager):
def get_queryset(self):
return super(EditorManager, self).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(), 都会得到和名称相符的结果。
#### 默认管理器 ####
如果你使用了自定义 管理器对象，要注意 Django 中的第一个 管理器 (按照模型中出现的顺序而定) 拥有特殊的地位。Django 会将模型中定义的管理器解释为默认的 管理器，并且 Django 中的一部分应用(包括数据备份)会使用默认的管理器，除了前面那个模型。因此，要决定默认的管理器时，要小心谨慎，仔细考量，这样才能避免重写 get_queryset() 导致无法正确地获得数据。
#### 使用管理器访问关联对象 ####
默认情况下，在访问相关对象时（例如choice.poll），Django 并不使用相关对象的默认管理器，而是使用一个"朴素"管理器类的实例来访问。这是因为 Django 要能从关联对象中获得数据，但这些数据有可能被默认管理器过滤掉，或是无法进行访问。
如果普通的朴素管理器类(django.db.models.Manager)并不适用于你的应用，那么你可以通过在管理器类中设置 use_for_related_fields ，强制 Django 在你的模型中使用默认的管理器。这部分内容在 下面有 详细介绍。
### 调用自定义的查询集 ###
虽然大多数标准查询集的方法可以从管理器中直接访问到，但是这是一个例子，访问了定义在自定义 查询集上的额外方法，如果你也在管理器上面实现了它们：
```
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()。
### 创建管理器 ###
** django 1.7 中新增 **
对于上面的例子，同一个方法需要在查询集 和 管理器上创建两份副本，作为替代，QuerySet.as_manager()可以创建一个管理器的实例，它拥有自定义查询集的方法：
```
class Person(models.Model):
...
people = PersonQuerySet.as_manager()
```
通过QuerySet.as_manager()创建的管理器 实例，实际上等价于上面例子中的PersonManager。
并不是每个查询集的方法都在管理器层面上有意义。比如 QuerySet.delete()，我们有意防止它复制到管理器 中。
方法按照以下规则进行复制：
+ 公共方法默认被复制。
+ 私有方法（前面带一个下划线）默认不被复制。
+ 带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.from_queryset()，它会返回管理器的一个子类，带有自定义查询集所有方法的副本：
```
class BaseManager(models.Manager):
def manager_only_method(self):
return
class CustomQuerySet(models.QuerySet):
def manager_and_queryset_method(self):
return
class MyModel(models.Model):
objects = BaseManager.from_queryset(CustomQueryset)()
```
你也可以在一个变量中储存生成的类：
```
CustomManager = BaseManager.from_queryset(CustomQueryset)
class MyModel(models.Model):
objects = CustomManager()
```
### 自定义管理器和模型继承 ###
类继承和模型管理器两者之间配合得并不是很好。 管理器一般只对其定义所在的类起作用，在子类中对其继承绝对不是一个好主意。 而且，因为第一个 管理器会被 Djange 声明为默认的管理器，所以对默认的管理器 进行控制是非常必要的。下面就是 Django 如何处理自定义管理器和模型继承(model inheritance)的：
+ 定义在非抽象基类中的管理器是 不会 被子类继承的。如果你想从一个非抽象基类中重用管理器，只能在子类中重定义管理器。 这是因为这种管理器与定义它的模型 绑定得非常紧密，所以继承它们经常会导致异常的结果（特别是默认管理器运行的时候）。 因此，它们不应继承给子类。
+ 定义在抽象基类中的管理器总是被子类继续的，是按 Python 的命名解析顺序解析的（首先是子类中的命名覆盖所有的，然后是第一个父类的，以此类推）。 抽象类用来提取子类中的公共信息和行为，定义公共管理器也是公共信息的一部分。
+ 如果类当中显示定义了默认管理器，Django 就会以此做为默认管理器；否则就会从第一个抽象基类中继承默认管理器； 如果没有显式声明默认管理器，那么 Django 就会自动添加默认管理器。
如果你想在一组模型上安装一系列自定义管理器，上面提到的这些规则就已经为你的实现提供了必要的灵活性。你可以继承一个抽象基类，但仍要自定义默认的管理器。例如，假设你的基类是这样的：
```
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()
```
会抛出一个异常。这是因为，管理器被设计用来封装对象集合管理的逻辑。由于抽象的对象中并没有一个集合，管理它们是毫无意义的。如果你写了应用在抽象模型上的功能，你应该把功能放到抽象模型的静态方法，或者类的方法中。
### 实现上的注意事项 ###
无论你向自定义管理器中添加了什么功能，都必须可以得到 管理器实例的一个浅表副本：例如，下面的代码必须正常运行：
```
>>> import copy
>>> manager = MyManager()
>>> my_copy = copy.copy(manager)
```
Django 在一些查询中会创建管理器的浅表副本；如果你的管理器不能被复制，查询就会失败。
这对于大多数自定义管理器不是什么大问题。如果你只是添加一些简单的方法到你的管理器中，不太可能会把你的管理器实例变为不可复制的。但是，如果你覆盖了\_\_getattr\_\_，或者其它管理器中控制对象状态的私有方法，你应该确保不会影响到管理器的复制。
## 控制自动管理器的类型 ##
这篇文档已经提到了Django创建管理器类的一些位置：默认管理器和用于访问关联对象的“朴素” 管理器。在 Django 的实现中也有很多地方用到了临时的朴素管理器。 正常情况下，django.db.models.Manager 类的实例会自动创建管理器。
在整个这一节中，我们将那种由 Django 为你创建的管理器称之为 "自动管理器"，既有因为没有管理器而被 Django 自动添加的默认管理器， 也包括在访问关联模型时使用的临时管理器。
有时，默认管理器也并非是自动管理器。 一个例子就是 Django 自带的django.contrib.gis 应用，所有 gis模型都必须使用一个特殊的管理器类(GeoManager)，因为它们需要运行特殊的查询集(GeoQuerySet)与数据库进行交互。这表明无论自动管理器是否被创建，那些要使用特殊的管理器的模型仍要使用这个特殊的管理器类。
Django 为自定义管理器的开发者提供了一种方式：无论开发的管理器类是不是默认的管理器，它都应该可以用做自动管理器。 可以通过在管理器类中设置 use_for_related_fields 属性来做到这点：
```
class MyManager(models.Manager):
use_for_related_fields = True
# ...
```
如果在模型中的默认 管理器(在这些情况中仅考虑默认管理器)中设置了这个属性，那么无论它是否需要被自动创建，Django 都会自动使用它。否则 Django 就会使用 django.db.models.Manager.
> 历史回顾
>
> 从它使用目的来看，这个属性的名称(use_for_related_fields)好象有点古怪。原本，这个属性仅仅是用来控制访问关联字段的管理器的类型，这就是它名字的由来。 后来它的作用更加拓宽了，但是名称一直未变。 因为要保证现在的代码在 Django 以后的版本中仍可以正常工作(continue to work)，这就是它名称不变的原因。
### 在自动管理器实例中编写正确的管理器 ###
在上面的django.contrib.gis 已经提到了， use_for_related_fields这个特性是在需要返回一个自定义查询集子类的管理器中使用的。要在你的管理器中提供这个功能，要注意以下几点。
#### 不要在这种类型的管理器子类中过滤掉任何结果 ####
一个原因是自动管理器是用来访问关联模型 的对象。 在这种情况下，Django 必须要能看到相关模型的所有对象，所以才能根据关联关系得到任何数据 。
如果你重写了 get_queryset() 方法并且过滤掉了一些行数据，Django 将返回不正确的结果。不要这么做！ 在 get_queryset()方法中过滤掉数据，会使得它所在的管理器不适于用做自动管理器。
#### 设置 use_for_related_fields ####
use_for_related_fields属性必须在管理器类中设置，而不是在类的 实例中设置。上面已经有例子展示如何正确地设置，下面这个例子就是一个错误的示范：
```
# BAD: Incorrect code
class MyManager(models.Manager):
# ...
pass
# Sets the attribute on an instance of MyManager. Django will
# ignore this setting.
mgr = MyManager()
mgr.use_for_related_fields = True
class MyModel(models.Model):
# ...
objects = mgr
# End of incorrect code.
```
你也不应该在模型中使用这个属性之后，在类上改变它。这是因为在模型类被创建时，这个属性值马上就会被处理，而且随后不会再读取这个属性值。 这节的第一个例子就是在第一次定义的时候在管理器上设置use_for_related_fields属性，所有的代码就工作得很好。
- 新手入门
- 从零开始
- 概览
- 安装
- 教程
- 第1部分：模型
- 第2部分：管理站点
- 第3部分：视图和模板
- 第4部分：表单和通用视图
- 第5部分：测试
- 第6部分：静态文件
- 高级教程
- 如何编写可重用的应用
- 为Django编写首个补丁
- 模型层
- 模型
- 模型语法
- 元选项
- 模型类
- 查询集
- 执行查询
- 查找表达式
- 模型的实例
- 实例方法
- 访问关联对象
- 迁移
- 模式编辑器
- 编写迁移
- 高级
- 管理器
- 原始的SQL查询
- 聚合
- 多数据库
- 自定义查找
- 条件表达式
- 数据库函数
- 其它
- 遗留的数据库
- 提供初始数据
- 优化数据库访问
- 视图层
- 基础
- URL配置
- 视图函数
- 快捷函数
- 装饰器
- 参考
- 内建的视图
- TemplateResponse 对象
- 文件上传
- 概览
- File 对象
- 储存API
- 管理文件
- 自定义存储
- 基于类的视图
- 概览
- 内建显示视图
- 内建编辑视图
- API参考
- 分类索引
- 高级
- 生成 CSV
- 生成 PDF
- 中间件
- 概览
- 内建的中间件类
- 模板层
- 基础
- 面向设计师
- 语言概览
- 人性化
- 面向程序员
- 表单
- 基础
- 概览
- 表单API
- 内建的Widget
- 高级
- 整合媒体
- 开发过程
- 设置
- 概览
- 应用程序
- 异常
- 概览
- django-admin 和 manage.py
- 添加自定义的命令
- 测试
- 介绍
- 部署
- 概述
- WSGI服务器
- 部署静态文件
- 通过email追踪代码错误
- Admin
- 管理操作
- 管理文档生成器
- 安全
- 安全概述
- 说明Django中的安全问题
- 点击劫持保护
- 加密签名
- 国际化和本地化
- 概述
- 本地化WEB UI格式化输入
- “本地特色”
- 常见的网站应用工具
- 认证
- 概览
- 使用认证系统
- 密码管理
- 日志
- 分页
- 会话
- 数据验证
- 其它核心功能
- 按需内容处理
- 重定向
- 信号
- 系统检查框架