本文档描述了 Model API 的细节。它建立在 模型 和 数据库查询 指南中所介绍的材料基础上，因此，在阅读本文档之前，你可能需要阅读并理解这些文档。
在整个参考资料中，我们将使用在 数据库查询指南 中提出的 示例博客模型。
\n要创建一个新的模型实例，像其他 Python 类一样实例化它。
\n关键字参数是你在模型上定义的字段名。请注意，实例化一个模型不会触及你的数据库；为此，你需要 save()。
from_db() 方法可以在数据库加载时用于自定义模型实例创建。
db 参数包含模型从数据库加载的数据库别名，field_names 包含所有加载字段的名称，values 包含 field_names 中每个字段的加载值。field_names 和 values 的顺序相同。如果模型的所有字段都存在，那么 values 就必须按照 __init__() 预期的顺序。也就是说，实例可以通过 cls(*values) 来创建。如果有任何字段被推迟，它们将不会出现在 field_names 中。在这种情况下，给每个缺失的字段分配一个 django.db.models.DEFERRED 的值。
除了创建新的模型外，from_db() 方法必须在新实例的 _state 属性中设置 adding 和 db 标志。
下面是一个例子，说明如何记录从数据库中加载字段的初始值：
\nfrom django.db.models import DEFERRED\n\n@classmethod\ndef from_db(cls, db, field_names, values):\n # Default implementation of from_db() (subject to change and could\n # be replaced with super()).\n if len(values) != len(cls._meta.concrete_fields):\n values = list(values)\n values.reverse()\n values = [\n values.pop() if f.attname in field_names else DEFERRED\n for f in cls._meta.concrete_fields\n ]\n instance = cls(*values)\n instance._state.adding = False\n instance._state.db = db\n # customization to store the original field values on the instance\n instance._loaded_values = dict(\n zip(field_names, (value for value in values if value is not DEFERRED))\n )\n return instance\n\ndef save(self, *args, **kwargs):\n # Check how the current values differ from ._loaded_values. For example,\n # prevent changing the creator_id of the model. (This example doesn't\n # support cases where 'creator_id' is deferred).\n if not self._state.adding and (\n self.creator_id != self._loaded_values['creator_id']):\n raise ValueError("Updating the value of creator isn't allowed")\n super().save(*args, **kwargs)\n上面的例子显示了一个完整的 from_db() 实现，以说明如何做到这一点。在这种情况下，可以在 from_db() 方法中使用 super() 调用。
如果你从模型实例中删除了一个字段，再次访问它就会从数据库中重新加载该值：
\n>>> obj = MyModel.objects.first()\n>>> del obj.field\n>>> obj.field # Loads the field from the database\n如果你需要从数据库中重新加载一个模型的值，你可以使用 refresh_from_db() 方法。当这个方法被调用时，没有参数时，会做以下工作：
模型的所有非递延字段都更新为数据库中当前的值。
任何缓存的关系都会从重新加载的实例中清除。
只有模型的字段会从数据库中重载。其他依赖于数据库的值，如注释，不会被重载。任何 @cached_property 属性也不会被清除。
重载发生在实例被加载的数据库中，如果实例不是从数据库中加载的，则从默认数据库中加载。using 参数可以用来强制使用数据库进行重载。
可以通过使用 fields 参数强制加载一组字段。
例如，为了测试 update() 的调用是否导致了预期的更新，你可以写一个类似这样的测试：
def test_update_result(self):\n obj = MyModel.objects.create(val=1)\n MyModel.objects.filter(pk=obj.pk).update(val=F('val') + 1)\n # At this point obj.val is still 1, but the value in the database\n # was updated to 2. The object's updated value needs to be reloaded\n # from the database.\n obj.refresh_from_db()\n self.assertEqual(obj.val, 2)\n请注意，当访问递延字段时，递延字段的值的加载是通过这个方法发生的。因此，可以自定义递延加载的发生方式。下面的例子显示了当一个递延字段被重载时，如何重载实例的所有字段：
\nclass ExampleModel(models.Model):\n def refresh_from_db(self, using=None, fields=None, **kwargs):\n # fields contains the name of the deferred field to be\n # loaded.\n if fields is not None:\n fields = set(fields)\n deferred_fields = self.get_deferred_fields()\n # If any deferred field is going to be loaded\n if fields.intersection(deferred_fields):\n # then load all of them\n fields = fields.union(deferred_fields)\n super().refresh_from_db(using, fields, **kwargs)\n一个辅助方法，返回一个包含当前这个模型的所有这些字段的属性名的集合。
\nThere are four steps involved in validating a model:
\n验证模型字段—— Model.clean_fields()
验证整个模型—— Model.clean()
验证字段的唯一性—— Model.validate_unique()
Validate the constraints - Model.validate_constraints()
All four steps are performed when you call a model's full_clean()\nmethod.
当你使用一个 ModelForm 时，调用 is_valid() 将对表单中包含的所有字段执行这些验证步骤。更多信息请参见 模型表单文档。只有当你打算自己处理验证错误，或者你从 ModelForm 中排除了需要验证的字段时，才需要调用模型的 full_clean() 方法。
This method calls Model.clean_fields(), Model.clean(),\nModel.validate_unique() (if validate_unique is True), and\nModel.validate_constraints() (if validate_constraints is True)\nin that order and raises a ValidationError that\nhas a message_dict attribute containing errors from all four stages.
The optional exclude argument can be used to provide a set of field\nnames that can be excluded from validation and cleaning.\nModelForm uses this argument to exclude fields that\naren't present on your form from being validated since any errors raised could\nnot be corrected by the user.
请注意，当您调用模型的 save() 方法时，full_clean() 不会 自动调用。当你想为自己手动创建的模型运行一步模型验证时，你需要手动调用它。例如：
from django.core.exceptions import ValidationError\ntry:\n article.full_clean()\nexcept ValidationError as e:\n # Do something based on the errors contained in e.message_dict.\n # Display them to a user, or handle them programmatically.\n pass\nfull_clean() 执行的第一步是清理每个单独的字段。
This method will validate all fields on your model. The optional exclude\nargument lets you provide a set of field names to exclude from validation.\nIt will raise a ValidationError if any fields\nfail validation.
full_clean() 执行的第二步是调用 Model.clean()。这个方法应该被重写，以便对你的模型进行自定义验证。
这个方法应该用来提供自定义模型验证，如果需要的话，还可以修改模型上的属性。例如，你可以使用它来自动为一个字段提供一个值，或进行需要访问多个字段的验证：
\nimport datetime\nfrom django.core.exceptions import ValidationError\nfrom django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\nclass Article(models.Model):\n ...\n def clean(self):\n # Don't allow draft entries to have a pub_date.\n if self.status == 'draft' and self.pub_date is not None:\n raise ValidationError(_('Draft entries may not have a publication date.'))\n # Set the pub_date for published items if it hasn't been set already.\n if self.status == 'published' and self.pub_date is None:\n self.pub_date = datetime.date.today()\n但请注意，像 Model.full_clean() 一样，当你调用你的模型的 save() 方法时，模型的 clean() 方法不会被调用。
在上面的例子中，由 Model.clean() 引发的 ValidationError 异常是用字符串实例化的，所以它将被存储在一个特殊的错误字典键中， NON_FIELD_ERRORS。这个键用于与整个模型相关的错误，而不是与某个特定字段相关的错误：
from django.core.exceptions import NON_FIELD_ERRORS, ValidationError\ntry:\n article.full_clean()\nexcept ValidationError as e:\n non_field_errors = e.message_dict[NON_FIELD_ERRORS]\n要将异常分配给一个特定的字段，用一个字典实例化 ValidationError，其中键是字段名。我们可以更新前面的例子，将错误分配给 pub_date 字段：
class Article(models.Model):\n ...\n def clean(self):\n # Don't allow draft entries to have a pub_date.\n if self.status == 'draft' and self.pub_date is not None:\n raise ValidationError({'pub_date': _('Draft entries may not have a publication date.')})\n ...\n如果你在 Model.clean() 期间检测到多个字段的错误，你也可以传递一个字段名与错误映射的字典：
raise ValidationError({\n 'title': ValidationError(_('Missing title.'), code='required'),\n 'pub_date': ValidationError(_('Invalid date.'), code='invalid'),\n})\nThen, full_clean() will check unique constraints on your model.
This method is similar to clean_fields(), but validates\nuniqueness constraints defined via Field.unique,\nField.unique_for_date, Field.unique_for_month,\nField.unique_for_year, or Meta.unique_together on your model instead of individual\nfield values. The optional exclude argument allows you to provide a set\nof field names to exclude from validation. It will raise a\nValidationError if any fields fail validation.
UniqueConstraints defined in the\nMeta.constraints are validated\nby Model.validate_constraints().
请注意，如果你为 validate_unique() 提供了一个 exclude 参数，任何涉及你提供的一个字段的 unique_together 约束将不会被检查。
Finally, full_clean() will check any other constraints on your model.
This method validates all constraints defined in\nMeta.constraints. The\noptional exclude argument allows you to provide a set of field names to\nexclude from validation. It will raise a\nValidationError if any constraints fail\nvalidation.
要将对象保存回数据库，调用 save()：
关于使用 force_insert 和 force_update 参数的细节，见 强制执行 INSERT 或 UPDATE 。关于 update_fields 参数的细节可以在 指定要保存的字段 部分找到。
如果你想自定义保存行为，你可以覆盖这个 save() 方法。更多细节请参见 重写之前定义的模型方法。
模型保存过程也有一些微妙的地方，请看下面的章节。
\n如果一个模型有一个 AutoField——一个自动递增的主键，那么当你第一次调用 save() 时，这个自动递增的值就会被计算出来并保存为你的对象的一个属性：
>>> b2 = Blog(name='Cheddar Talk', tagline='Thoughts on cheese.')\n>>> b2.id # Returns None, because b2 doesn't have an ID yet.\n>>> b2.save()\n>>> b2.id # Returns the ID of your new object.\n在你调用 save() 之前，没有办法知道一个 ID 的值是多少，因为这个值是由你的数据库计算出来的，而不是由 Django 计算出来的。
为了方便起见，每个模型都有一个 AutoField 默认命名为 id，除非你在模型中的字段上明确指定 primary_key=True。更多细节请参见 AutoField 的文档。
pk 属性Link to this heading#无论你是自己定义一个主键字段，还是让 Django 为你提供一个主键字段，每个模型都会有一个叫做 pk 的属性。它的行为就像模型上的一个普通属性，但实际上是模型主键字段属性的别名。您可以像读取和设置任何其他属性一样读取和设置这个值，它将更新模型中的正确字段。
如果一个模型有一个 AutoField，但你想在保存时显式地定义一个新对象的 ID，就在保存前显式地定义它，而不是依赖 ID 的自动分配：
>>> b3 = Blog(id=3, name='Cheddar Talk', tagline='Thoughts on cheese.')\n>>> b3.id # Returns 3.\n>>> b3.save()\n>>> b3.id # Returns 3.\n如果你手动分配自动主键值，请确保不要使用一个已经存在的主键值！如果你创建一个新的对象，并使用一个已经存在于数据库中的显式主键值，Django 会认为你是在改变现有的记录，而不是创建一个新的记录。
\n考虑到上面的 'Cheddar Talk' 博客的例子，这个例子将覆盖数据库中以前的记录：
b4 = Blog(id=3, name='Not Cheddar', tagline='Anything but cheese.')\nb4.save() # Overrides the previous blog with ID=3!\n发生这种情况的原因，请看下面 How Django knows to UPDATE vs. INSERT 。
\n明确指定自动主键值主要用于批量保存对象，当你确信不会发生主键碰撞时。
\n如果你使用的是 PostgreSQL，与主键相关的序列可能需要更新；参见 手动指定自增主键的值。。
\n当你保存一个对象时，Django 会执行以下步骤：
\n发送一个预保存信号。 pre_save 信号被发送，允许任何监听该信号的函数做一些事情。
预处理数据。 每个字段的 pre_save() 方法被调用来执行任何需要的自动数据修改。例如，日期／时间字段重写了 pre_save() 来实现 auto_now_add 和 auto_now。
为数据库准备数据。 要求每个字段的 get_db_prep_save() 方法提供其当前的值，数据类型可以写入数据库。
大多数字段不需要数据准备。简单的数据类型，如整数和字符串，作为一个 Python 对象是“可以写入”的。然而，更复杂的数据类型通常需要一些修改。
\n例如，DateField 字段使用 Python datetime 对象来存储数据。数据库不存储 datetime 对象，所以字段值必须转换成符合 ISO 标准的日期字符串才能插入数据库。
将数据插入数据库。 将预先处理、准备好的数据组成 SQL 语句，以便插入数据库。
发送一个保存后的信号。 post_save 信号被发送，允许任何监听该信号的函数做一些事情。
你可能已经注意到 Django 数据库对象使用相同的 save() 方法来创建和更改对象。Django 抽象了需要使用 INSERT 或 UPDATE 的 SQL 语句。具体来说，当你调用 save()，而对象的主键属性 没有 定义一个 default 时，Django 会遵循这个算法。
如果对象的主键属性被设置为值为 True （即，一个不是 None 或空字符串的值），Django 会执行 UPDATE。
如果对象的主键属性没有设置，或者 UPDATE 没有更新任何东西（例如主键被设置为数据库中不存在的值），Django 会执行 INSERT。
如果对象的主键属性定义了一个 default，那么如果它是一个现有的模型实例，并且主键被设置为数据库中存在的值，Django 就会执行一个 UPDATE。否则，Django 会执行一个 INSERT。
这里的一个问题是，如果你不能保证主键值未被使用，那么在保存新对象时，你应该注意不要显式地指定一个主键值。关于这个细微的差别，请看上面的 Explicitly specifying auto-primary-key values 和下面的 Forcing an INSERT or UPDATE 。
\n在 Django 1.5 和更早的版本中，当主键属性被设置时，Django 执行 SELECT。如果 SELECT 找到了一条记录，那么 Django 就会进行 UPDATE，否则就会进行 INSERT。老算法的结果是在 UPDATE 的情况下多了一个查询。在一些罕见的情况下，即使数据库中包含了一条对象主键值的记录，数据库也不会报告某行被更新。一个例子是 PostgreSQL 的 ON UPDATE 触发器，它返回 NULL。在这种情况下，可以通过将 select_on_save 选项设置为 True 来恢复到旧算法。
在一些罕见的情况下，有必要强制 save() 方法执行 SQL INSERT，而不是回到 UPDATE。或者反过来说：如果可能的话，更新，但不插入新的记录。在这些情况下，你可以将 force_insert=True 或 force_update=True 参数传递给 save() 方法。一起传递这两个参数是一个错误：你不能同时插入 和 更新！
你应该很少需要使用这些参数。Django 几乎总是会做正确的事情，试图覆盖会导致难以追踪的错误。这个功能只适合进阶使用。
\n使用 update_fields 将强制更新，类似于 force_update。
有时你需要在一个字段上执行一个简单的算术任务，比如递增或递减当前值。一种方法是在 Python 中进行运算，比如：
\n>>> product = Product.objects.get(name='Venezuelan Beaver Cheese')\n>>> product.number_sold += 1\n>>> product.save()\n如果从数据库中检索到的 number_sold 旧值是 10，那么 11 的值将被写回数据库。
这个过程可以变得更健壮， 避免竞争条件，以及通过表达相对于原始字段值的更新，而不是作为一个新值的显式赋值来稍微加快。Django 提供了 F 表达式 来执行这种相对更新。使用 F 表达式，前面的例子表示为：
>>> from django.db.models import F\n>>> product = Product.objects.get(name='Venezuelan Beaver Cheese')\n>>> product.number_sold = F('number_sold') + 1\n>>> product.save()\n如果 save() 在关键字参数 update_fields 中传递了一个字段名列表，那么只有列表中命名的字段才会被更新。如果你只想更新一个对象上的一个或几个字段，这可能是可取的。防止数据库中所有的模型字段被更新会有轻微的性能优势。例如：
product.name = 'Name changed again'\nproduct.save(update_fields=['name'])\nupdate_fields 参数可以是任何包含字符串的可迭代对象。一个空的 update_fields 可迭代对象将跳过保存。值为 None 将对所有字段进行更新。
指定 update_fields 将强制更新。
当保存一个通过延迟模型加载获取的模型时（only() 或 defer()），只有从数据库加载的字段会被更新。实际上，在这种情况下有一个自动的 update_fields。如果你分配或改变任何延迟字段的值，该字段将被添加到更新的字段中。
Issues an SQL DELETE for the object. This only deletes the object in the\ndatabase; the Python instance will still exist and will still have data in\nits fields, except for the primary key set to None. This method returns the\nnumber of objects deleted and a dictionary with the number of deletions per\nobject type.
更多细节，包括如何批量删除对象，请参见 删除对象。
\n如果你想自定义删除行为，你可以覆盖 delete() 方法。更多细节请参见 重写之前定义的模型方法。
有时，在 多表继承 中，你可能只想删除子模型的数据，指定 keep_parents=True 将保留父模型的数据。指定 keep_parents=True 将保留父模型的数据。
当你 pickle 一个模型时，它的当前状态被序列化。当你反序列化时，它将包含它被序列化时的模型实例，而不是当前数据库中的数据。
有几个对象方法有特殊用途。
\n__str__()Link to this heading#每当你对一个对象调用 str() 时，就会调用 __str__() 方法。Django 在很多地方使用了 str(obj) 方法。最主要的是，在 Django 管理站点中显示一个对象，以及作为模板显示对象时插入的值。因此，你应该总是从 __str__() 方法中返回一个漂亮的、人类可读的模型表示。
例子：
\nfrom django.db import models\n\nclass Person(models.Model):\n first_name = models.CharField(max_length=50)\n last_name = models.CharField(max_length=50)\n\n def __str__(self):\n return '%s %s' % (self.first_name, self.last_name)\n__eq__()Link to this heading#相等方法的定义是，具有相同主键值和相同具体类的实例被认为是相等的，但主键值为 None 的实例除自身外对任何事物都不相等。对于代理模型，具体类被定义为模型的第一个非代理父类；对于所有其他模型，它只是模型的类。
例子：
\nfrom django.db import models\n\nclass MyModel(models.Model):\n id = models.AutoField(primary_key=True)\n\nclass MyProxyModel(MyModel):\n class Meta:\n proxy = True\n\nclass MultitableInherited(MyModel):\n pass\n\n# Primary keys compared\nMyModel(id=1) == MyModel(id=1)\nMyModel(id=1) != MyModel(id=2)\n# Primary keys are None\nMyModel(id=None) != MyModel(id=None)\n# Same instance\ninstance = MyModel(id=None)\ninstance == instance\n# Proxy model\nMyModel(id=1) == MyProxyModel(id=1)\n# Multi-table inheritance\nMyModel(id=1) != MultitableInherited(id=1)\n__hash__()Link to this heading#__hash__() 方法是基于实例的主键值。它实际上是 hash(obj.pk)。如果实例没有主键值，那么将引发一个 TypeError （否则 __hash__() 方法会在保存实例之前和之后返回不同的值，但是在 Python 中禁止改变实例的 __hash__() 值。
get_absolute_url()Link to this heading#定义一个 get_absolute_url() 方法来告诉 Django 如何计算一个对象的标准 URL。对于调用者来说，这个方法应该返回一个字符串，可以通过 HTTP 引用对象。
例子：
\ndef get_absolute_url(self):\n return "/people/%i/" % self.id\n虽然这段代码正确且简单，但它可能不是写这种方法的最可移植的方式。reverse() 函数通常是最好的方法。
例子：
\ndef get_absolute_url(self):\n from django.urls import reverse\n return reverse('people-detail', kwargs={'pk' : self.pk})\nDjango 使用 get_absolute_url() 的一个地方就是在管理应用中。如果一个对象定义了这个方法，那么对象编辑页面会有一个“View on site”的链接，直接跳转到对象的公开视图，就像 get_absolute_url() 给出的那样。
类似的，Django 的其他几个部分，比如 联合供稿框架，当定义了 get_absolute_url() 时，也会使用 get_absolute_url()。如果你的模型的每个实例都有一个唯一的 URL，你应该定义 get_absolute_url()。
在模板中使用 get_absolute_url()，而不是硬编码你的对象的 URL，这是一个很好的做法。例如，这个模板代码就很糟糕：
<!-- BAD template code. Avoid! -->\n<a href="/people/{{ object.id }}/">{{ object.name }}</a>\n这个模板代码就好多了：
\n<a href="{{ object.get_absolute_url }}">{{ object.name }}</a>\n这里的逻辑是，如果你改变了你的对象的 URL 结构，即使是为了纠正拼写错误这样的小事，你也不想追踪 URL 可能被创建的每个地方。在 get_absolute_url() 中指定一次，然后让你的其他代码调用那个地方。
除了 save()、 delete() 之外，一个模型对象还可能有以下一些方法：
对于每一个设置了 choice 的字段，该对象将有一个 get_FOO_display() 方法，其中 FOO 是字段的名称。该方法返回字段的“人类可读”值。
例子：
\nfrom django.db import models\n\nclass Person(models.Model):\n SHIRT_SIZES = (\n ('S', 'Small'),\n ('M', 'Medium'),\n ('L', 'Large'),\n )\n name = models.CharField(max_length=60)\n shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES)\n>>> p = Person(name="Fred Flintstone", shirt_size="L")\n>>> p.save()\n>>> p.shirt_size\n'L'\n>>> p.get_shirt_size_display()\n'Large'\n对于每一个 DateField 和 DateTimeField 没有 null=True，该对象将有 get_next_by_FOO() 和 get_previous_by_FOO() 方法，其中 FOO 是字段名。这将返回与日期字段相关的下一个和上一个对象，适当时引发一个 DoesNotExist 异常。
这两种方法都将使用模型的默认管理器执行查询。如果你需要模拟自定义管理器使用的过滤，或者想要执行一次性的自定义过滤，这两种方法也都接受可选的关键字参数，其格式应该是 字段查找 中描述的格式。
\n请注意，在日期值相同的情况下，这些方法将使用主键作为比较。这保证了没有记录被跳过或重复。这也意味着你不能对未保存的对象使用这些方法。
\n\n_stateLink to this heading#_state 属性指的是一个 ModelState 对象，它跟踪模型实例的生命周期。
ModelState 对象有两个属性。adding 是一个标志，如果模型尚未保存到数据库，则为 True；db 是一个字符串，指的是实例从数据库加载或保存到的别名。
新实例有 adding=True 和 db=None，因为它们尚未被保存。从 QuerySet 获取的实例将有 adding=False 和 db 设置为相关数据库的别名。