本文档描述了 Model API 的细节。它建立在 模型 和 数据库查询 指南中所介绍的材料基础上，因此，在阅读本文档之前，你可能需要阅读并理解这些文档。
在整个参考资料中，我们将使用在 数据库查询指南 中提出的 示例博客模型。
\n要创建一个新的模型实例，像其他 Python 类一样实例化它。
\nThe keyword arguments are the names of the fields you've defined on your model.\nNote that instantiating a model in no way touches your database; for that, you\nneed to 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\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\n\ndef save(self, **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 ):\n raise ValueError("Updating the value of creator isn't allowed")\n super().save(**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异步版本: arefresh_from_db()
如果你需要从数据库中重新加载一个模型的值，你可以使用 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)\nWhen a deferred field is loaded on-demand for a single model instance, the\nloading happens through this method. Thus it is possible to customize the way\nthis loading happens. The example below shows how one can reload all of the\ninstance's fields when a deferred field is loaded on-demand:
\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)\nfrom_queryset 参数允许使用不同于从 _base_manager 创建的查询集。它让你对模型的重新加载方式有更多的控制。例如，当你的模型使用软删除时，你可以让 refresh_from_db() 考虑到这一点：
obj.refresh_from_db(from_queryset=MyModel.active_objects.all())\n你可以缓存相关对象，否则这些对象将从重新加载的实例中清除：
\nobj.refresh_from_db(from_queryset=MyModel.objects.select_related("related_field"))\n你可以在重新加载模型值之前锁定该行直到事务结束：
\nobj.refresh_from_db(from_queryset=MyModel.objects.select_for_update())\n一个辅助方法，返回一个包含当前这个模型的所有这些字段的属性名的集合。
\n验证模型涉及四个步骤：
\nValidate the model fields - Model.clean_fields()
Validate the model as a whole - Model.clean()
Validate the field uniqueness - Model.validate_unique()
验证约束 - Model.validate_constraints()
当你调用模型的 full_clean() 方法时，会执行所有四个步骤。
When you use a ModelForm, the call to\nis_valid() will perform these validation steps for\nall the fields that are included on the form. See the ModelForm\ndocumentation for more information. You should only\nneed to call a model's full_clean() method if you plan to handle\nvalidation errors yourself, or if you have excluded fields from the\nModelForm that require validation.
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.
可选的 exclude 参数可以用来提供一个字段名称的 set，可以从验证和清理中排除。 ModelForm 使用这个参数来排除在表单上不存在的字段，因为用户无法纠正引发的任何错误。
Note that full_clean() will not be called automatically when you call\nyour model's save() method. You'll need to call it manually\nwhen you want to run one-step model validation for your own manually created\nmodels. For example:
from django.core.exceptions import ValidationError\n\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() 执行的第一步是清理每个单独的字段。
该方法将验证模型上的所有字段。可选的 exclude 参数允许您提供一个字段名称的 set，以排除验证。如果任何字段未通过验证，它将引发 ValidationError。
The second step full_clean() performs is to call Model.clean().\nThis method should be overridden to perform custom validation on your model.
这个方法应该用来提供自定义模型验证，如果需要的话，还可以修改模型上的属性。例如，你可以使用它来自动为一个字段提供一个值，或进行需要访问多个字段的验证：
\nimport datetime\nfrom django.core.exceptions import ValidationError\nfrom django.db import models\nfrom django.utils.translation import gettext_lazy as _\n\n\nclass Article(models.Model):\n ...\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()\nNote, however, that like Model.full_clean(), a model's clean()\nmethod is not invoked when you call your model's save() method.
在上面的例子中，由 Model.clean() 引发的 ValidationError 异常是用字符串实例化的，所以它将被存储在一个特殊的错误字典键中， NON_FIELD_ERRORS。这个键用于与整个模型相关的错误，而不是与某个特定字段相关的错误：
from django.core.exceptions import NON_FIELD_ERRORS, ValidationError\n\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\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(\n {"pub_date": _("Draft entries may not have a publication date.")}\n )\n ...\n如果你在 Model.clean() 期间检测到多个字段的错误，你也可以传递一个字段名与错误映射的字典：
raise ValidationError(\n {\n "title": ValidationError(_("Missing title."), code="required"),\n "pub_date": ValidationError(_("Invalid date."), code="invalid"),\n }\n)\n接下来，full_clean() 将检查模型上的唯一约束。
这个方法类似于 clean_fields()，但是验证模型上定义的唯一约束，而不是单个字段的值，这些约束通过 Field.unique、Field.unique_for_date、Field.unique_for_month、Field.unique_for_year 或 Meta.unique_together 来定义。可选的 exclude 参数允许您提供一个字段名称的 set，以排除验证。如果任何字段未通过验证，它将引发 ValidationError。
在 Meta.constraints 中定义的 UniqueConstraint 由 Model.validate_constraints() 进行验证。
请注意，如果你为 validate_unique() 提供了一个 exclude 参数，任何涉及你提供的一个字段的 unique_together 约束将不会被检查。
最后，full_clean() 将检查模型上的任何其他约束。
这个方法验证了在 Meta.constraints 中定义的所有约束。可选的 exclude 参数允许您提供一个字段名称的 set，以排除验证。如果任何约束未通过验证，它将引发 ValidationError。
要将对象保存回数据库，调用 save()：
异步版本: asave()
关于使用 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#Regardless of whether you define a primary key field yourself, or let Django\nsupply one for you, each model will have a property called pk. It behaves\nlike a normal attribute on the model, but is actually an alias for whichever\nfield or fields compose the primary key for the model. You can read and set\nthis value, just as you would for any other attribute, and it will update the\ncorrect fields in the model.
如果模型具有 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 或 db_default 时，Django 遵循以下算法：
If the object's primary key attribute is set to anything except None,\nDjango executes an UPDATE.
如果对象的主键属性没有设置，或者 UPDATE 没有更新任何东西（例如主键被设置为数据库中不存在的值），Django 会执行 INSERT。
如果对象的主键属性定义了 default 或 db_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 来恢复到旧算法。
In some rare circumstances, it's necessary to be able to force the\nsave() method to perform an SQL INSERT and not fall back to\ndoing an UPDATE. Or vice-versa: update, if possible, but not insert a new\nrow. In these cases you can pass the force_insert=True or\nforce_update=True parameters to the save() method.\nPassing both parameters is an error: you cannot both insert and update at the\nsame time!
在使用 多表继承 时，也可以提供一个父类的元组给 force_insert，以强制为每个基类执行 INSERT 语句。例如：
Restaurant(pk=1, name="Bob's Cafe").save(force_insert=(Place,))\n\nRestaurant(pk=1, name="Bob's Cafe", rating=4).save(force_insert=(Place, Rating))\n你可以传递 force_insert=(models.Model,) 来强制执行所有父类的 INSERT 语句。默认情况下，force_insert=True 只会强制为当前模型插入新行。
你应该很少需要使用这些参数。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 的值将被写回数据库。
The process can be made robust, avoiding a race condition, as well as slightly faster by expressing\nthe update relative to the original field value, rather than as an explicit\nassignment of a new value. Django provides F() 表达式 for performing\nthis kind of relative update. Using F() 表达式, the previous example\nis expressed as:
\n>>> 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()\nFor more details, see the documentation on F() 表达式 and their\nuse in update queries.
\n如果 save() 在关键字参数 update_fields 中传递了一个字段名列表，那么只有列表中命名的字段才会被更新。如果你只想更新一个对象上的一个或几个字段，这可能是可取的。防止数据库中所有的模型字段被更新会有轻微的性能优势。例如：
product.name = "Name changed again"\nproduct.save(update_fields=["name"])\nupdate_fields 参数可以是任何包含字符串的可迭代对象。一个空的 update_fields 可迭代对象将跳过保存。值为 None 将对所有字段进行更新。
指定 update_fields 将强制更新。
When saving a model fetched through deferred model loading\n(only() or\ndefer()) only the fields loaded\nfrom the DB will get updated. In effect there is an automatic\nupdate_fields in this case. If you assign or change any deferred field\nvalue, the field will be added to the updated fields.
异步版本: adelete()
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. The return value will count instances from related models if\nDjango is emulating cascade behavior via Python on_delete\nvariants. Otherwise, for database variants such as\nDB_CASCADE, the return value will report only\ninstances of the QuerySet's model.
更多细节，包括如何批量删除对象，请参见 删除对象。
\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\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 f"{self.first_name} {self.last_name}"\n__eq__()Link to this heading#相等方法的定义是，具有相同主键值和相同具体类的实例被认为是相等的，但主键值为 None 的实例除自身外对任何事物都不相等。对于代理模型，具体类被定义为模型的第一个非代理父类；对于所有其他模型，它只是模型的类。
例子：
\nfrom django.db import models\n\n\nclass MyModel(models.Model):\n id = models.AutoField(primary_key=True)\n\n\nclass MyProxyModel(MyModel):\n class Meta:\n proxy = True\n\n\nclass MultitableInherited(MyModel):\n pass\n\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#The __hash__() method is based on the instance's primary key value. It\nis effectively hash(obj.pk). If the instance doesn't have a primary key\nvalue then a TypeError will be raised (otherwise the __hash__()\nmethod would return different values before and after the instance is\nsaved), but changing the __hash__() value of an instance is\nforbidden in Python.
get_absolute_url()Link to this heading#定义一个 get_absolute_url() 方法来告诉 Django 如何计算一个对象的标准 URL。对于调用者来说，这个方法应该返回一个字符串，可以通过 HTTP 引用对象。
例子：
\ndef get_absolute_url(self):\n return "/people/%i/" % self.id\nWhile this code is correct and simple, it may not be the most portable way\nto write this kind of method. The reverse() function is\nusually the best approach.
例子：
\ndef get_absolute_url(self):\n from django.urls import reverse\n\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()。
It's good practice to use get_absolute_url() in templates, instead of\nhardcoding your objects' URLs. For example, this template code is bad:
<!-- 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() 中指定一次，然后让你的其他代码调用那个地方。
In addition to save(), delete(), a model object\nmight have some of the following methods:
对于每一个设置了 choice 的字段，该对象将有一个 get_FOO_display() 方法，其中 FOO 是字段的名称。该方法返回字段的“人类可读”值。
例子：
\nfrom django.db import models\n\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 对象，它跟踪模型实例的生命周期。
The ModelState object has three attributes: adding, a flag which is\nTrue if the model has not been saved to the database yet, db, a\nstring referring to the database alias the instance was loaded from or\nsaved to, and fetch_mode, the fetch mode to be used in subsequent field fetches.
Newly instantiated instances have adding=True and db=None,\nsince they are yet to be saved, and fetch_mode=models.FETCH_ONE.\nInstances fetched from a QuerySet will have adding=False, db\nset to the alias of the associated database, and fetch_mode copied\nfrom the queryset's fetch mode.
_is_pk_set()Link to this heading#The _is_pk_set() method returns whether the model instance's pk is\nset. It abstracts the model's primary key definition, ensuring consistent\nbehavior regardless of the specific pk configuration. A\nDatabaseDefault on an unsaved instance is considered unset.