字段类型¶

模型中的每个字段都应是适当的Field类的实例。Django 使用字段类类型来确定一些事情

• 列类型，它告诉数据库要存储哪种类型的数据（例如 INTEGER、VARCHAR、TEXT）。
• 呈现表单字段时使用的默认 HTML 小部件（例如 <input type="text">、<select>）。
• Django 的管理和自动生成的表单中使用的最小验证要求。

Django 附带数十种内置字段类型；您可以在 模型字段参考 中找到完整列表。如果您觉得 Django 的内置字段类型不够用，您可以轻松编写自己的字段；请参阅 如何创建自定义模型字段。

字段选项¶

每个字段都采用一组特定的字段特定参数（在 模型字段参考 中记录）。例如，CharField（及其子类）需要一个 max_length 参数，该参数指定用于存储数据的 VARCHAR 数据库字段的大小。

还有一组可用于所有字段类型的通用参数。所有参数都是可选的。它们在 参考 中得到了充分解释，但以下是对最常用的参数的快速总结

null

如果为 True，Django 将在数据库中将空值存储为 NULL。默认值为 False。

blank

如果为 True，则允许字段为空。默认值为 False。

请注意，这与 null 不同。 null 纯粹与数据库相关，而 blank 与验证相关。如果某个字段具有 blank=True，则表单验证将允许输入空值。如果某个字段具有 blank=False，则该字段将为必填项。

choices

一个 序列 的 2 值元组、一个 映射、一个 枚举类型 或一个可调用对象（不接受参数并返回任何上述格式），用作此字段的选择项。如果指定了此项，则默认表单小部件将是选择框，而不是标准文本字段，并将选择项限制为给定的选择项。

选择项列表如下所示

YEAR_IN_SCHOOL_CHOICES = [
    ("FR", "Freshman"),
    ("SO", "Sophomore"),
    ("JR", "Junior"),
    ("SR", "Senior"),
    ("GR", "Graduate"),
]

注意

每次 choices 的顺序发生变化时，都会创建一个新的迁移。

每个元组中的第一个元素将存储在数据库中的值。第二个元素由字段的表单小部件显示。

给定一个模型实例，可以使用 get_FOO_display() 方法访问具有 choices 的字段的显示值。例如

from django.db import models


class Person(models.Model):
    SHIRT_SIZES = {
        "S": "Small",
        "M": "Medium",
        "L": "Large",
    }
    name = models.CharField(max_length=60)
    shirt_size = models.CharField(max_length=1, choices=SHIRT_SIZES)

>>> p = Person(name="Fred Flintstone", shirt_size="L")
>>> p.save()
>>> p.shirt_size
'L'
>>> p.get_shirt_size_display()
'Large'

您还可以使用枚举类以简洁的方式定义 choices

from django.db import models


class Runner(models.Model):
    MedalType = models.TextChoices("MedalType", "GOLD SILVER BRONZE")
    name = models.CharField(max_length=60)
    medal = models.CharField(blank=True, choices=MedalType, max_length=10)

更多示例可在 模型字段参考 中找到。

在 Django 5.0 中更改

添加了对映射和可调用对象的的支持。

default

字段的默认值。这可以是一个值或一个可调用对象。如果可调用，它将在每次创建新对象时被调用。

help_text

要与表单小部件一起显示的额外“帮助”文本。即使你的字段没有在表单中使用，它对于文档也很有用。

primary_key

如果 True，此字段是模型的主键。

如果你没有为模型中的任何字段指定 primary_key=True，Django 将自动添加一个 IntegerField 来保存主键，因此你无需在任何字段上设置 primary_key=True，除非你想覆盖默认的主键行为。更多信息，请参阅 自动主键字段。

主键字段是只读的。如果你更改现有对象上的主键值然后保存它，将创建一个新对象与旧对象并存。例如

from django.db import models


class Fruit(models.Model):
    name = models.CharField(max_length=100, primary_key=True)

>>> fruit = Fruit.objects.create(name="Apple")
>>> fruit.name = "Pear"
>>> fruit.save()
>>> Fruit.objects.values_list("name", flat=True)
<QuerySet ['Apple', 'Pear']>

unique

如果 True，此字段在整个表中必须唯一。

同样，这些只是最常见字段选项的简短描述。可以在 通用模型字段选项参考 中找到完整详细信息。

自动主键字段¶

默认情况下，Django 为每个模型提供一个自动递增的主键，其类型在 AppConfig.default_auto_field 中按应用程序指定，或在 DEFAULT_AUTO_FIELD 设置中全局指定。例如

id = models.BigAutoField(primary_key=True)

如果您想指定自定义主键，请在您的一个字段上指定 primary_key=True。如果 Django 看到您已明确设置 Field.primary_key，它将不会添加自动 id 列。

每个模型都需要正好一个字段具有 primary_key=True（明确声明或自动添加）。

详细字段名称¶

除了 ForeignKey、ManyToManyField 和 OneToOneField 以外的每种字段类型，都采用可选的第一个位置参数 - 详细名称。如果未提供详细名称，Django 将使用字段的属性名称自动创建它，并将下划线转换为空格。

在此示例中，详细名称为 "person's first name"

first_name = models.CharField("person's first name", max_length=30)

在此示例中，详细名称为 "first name"

first_name = models.CharField(max_length=30)

ForeignKey、ManyToManyField 和 OneToOneField 要求第一个参数为模型类，因此请使用 verbose_name 关键字参数

poll = models.ForeignKey(
    Poll,
    on_delete=models.CASCADE,
    verbose_name="the related poll",
)
sites = models.ManyToManyField(Site, verbose_name="list of sites")
place = models.OneToOneField(
    Place,
    on_delete=models.CASCADE,
    verbose_name="related place",
)

惯例是不对 verbose_name 的第一个字母大写。Django 将在需要时自动将第一个字母大写。

关系¶

显然，关系型数据库的强大之处在于将表彼此关联起来。Django 提供了定义三种最常见类型的数据库关系的方法：多对一、多对多和一对一。

from django.db import models


class Manufacturer(models.Model):
    # ...
    pass


class Car(models.Model):
    manufacturer = models.ForeignKey(Manufacturer, on_delete=models.CASCADE)
    # ...

class Car(models.Model):
    company_that_makes_it = models.ForeignKey(
        Manufacturer,
        on_delete=models.CASCADE,
    )
    # ...

from django.db import models


class Topping(models.Model):
    # ...
    pass


class Pizza(models.Model):
    # ...
    toppings = models.ManyToManyField(Topping)

from django.db import models


class Person(models.Model):
    name = models.CharField(max_length=128)

    def __str__(self):
        return self.name


class Group(models.Model):
    name = models.CharField(max_length=128)
    members = models.ManyToManyField(Person, through="Membership")

    def __str__(self):
        return self.name


class Membership(models.Model):
    person = models.ForeignKey(Person, on_delete=models.CASCADE)
    group = models.ForeignKey(Group, on_delete=models.CASCADE)
    date_joined = models.DateField()
    invite_reason = models.CharField(max_length=64)

>>> ringo = Person.objects.create(name="Ringo Starr")
>>> paul = Person.objects.create(name="Paul McCartney")
>>> beatles = Group.objects.create(name="The Beatles")
>>> m1 = Membership(
...     person=ringo,
...     group=beatles,
...     date_joined=date(1962, 8, 16),
...     invite_reason="Needed a new drummer.",
... )
>>> m1.save()
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>]>
>>> ringo.group_set.all()
<QuerySet [<Group: The Beatles>]>
>>> m2 = Membership.objects.create(
...     person=paul,
...     group=beatles,
...     date_joined=date(1960, 8, 1),
...     invite_reason="Wanted to form a band.",
... )
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>]>

>>> beatles.members.add(john, through_defaults={"date_joined": date(1960, 8, 1)})
>>> beatles.members.create(
...     name="George Harrison", through_defaults={"date_joined": date(1960, 8, 1)}
... )
>>> beatles.members.set(
...     [john, paul, ringo, george], through_defaults={"date_joined": date(1960, 8, 1)}
... )

>>> Membership.objects.create(
...     person=ringo,
...     group=beatles,
...     date_joined=date(1968, 9, 4),
...     invite_reason="You've been gone for a month and we miss you.",
... )
>>> beatles.members.all()
<QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>, <Person: Ringo Starr>]>
>>> # This deletes both of the intermediate model instances for Ringo Starr
>>> beatles.members.remove(ringo)
>>> beatles.members.all()
<QuerySet [<Person: Paul McCartney>]>

>>> # Beatles have broken up
>>> beatles.members.clear()
>>> # Note that this deletes the intermediate model instances
>>> Membership.objects.all()
<QuerySet []>

# Find all the groups with a member whose name starts with 'Paul'
>>> Group.objects.filter(members__name__startswith="Paul")
<QuerySet [<Group: The Beatles>]>

# Find all the members of the Beatles that joined after 1 Jan 1961
>>> Person.objects.filter(
...     group__name="The Beatles", membership__date_joined__gt=date(1961, 1, 1)
... )
<QuerySet [<Person: Ringo Starr]>

>>> ringos_membership = Membership.objects.get(group=beatles, person=ringo)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'

>>> ringos_membership = ringo.membership_set.get(group=beatles)
>>> ringos_membership.date_joined
datetime.date(1962, 8, 16)
>>> ringos_membership.invite_reason
'Needed a new drummer.'

跨文件模型¶

将模型与另一个应用程序中的模型关联起来完全可以。为此，在定义模型的文件顶部导入相关模型。然后，在需要的地方引用其他模型类。例如

from django.db import models
from geography.models import ZipCode


class Restaurant(models.Model):
    # ...
    zip_code = models.ForeignKey(
        ZipCode,
        on_delete=models.SET_NULL,
        blank=True,
        null=True,
    )

字段名称限制¶

Django 对模型字段名称有一些限制

1. 字段名称不能是 Python 保留字，因为那样会导致 Python 语法错误。例如

   class Example(models.Model):
       pass = models.IntegerField() # 'pass' is a reserved word!
   

2. 由于 Django 的查询查找语法的工作方式，字段名称不能连续包含多个下划线。例如

   class Example(models.Model):
       foo__bar = models.IntegerField()  # 'foo__bar' has two underscores!
   

3. 出于类似的原因，字段名称不能以下划线结尾。

不过，这些限制是可以解决的，因为你的字段名称不一定必须与你的数据库列名称匹配。请参阅 db_column 选项。

SQL 保留字，例如 join、where 或 select，是允许作为模型字段名称的，因为 Django 会在每个底层 SQL 查询中转义所有数据库表名和列名。它使用特定数据库引擎的引用语法。

自定义字段类型¶

如果现有的模型字段之一不能用于满足你的目的，或者如果你希望利用一些不太常见的数据库列类型，你可以创建自己的字段类。在 如何创建自定义模型字段 中提供了创建自己字段的完整说明。

覆盖预定义模型方法¶

还有另一组模型方法，它们封装了一组您需要自定义的数据库行为。尤其是，您通常需要更改save()和delete()的工作方式。

您可以自由地覆盖这些方法（以及任何其他模型方法）来更改行为。

覆盖内置方法的一个经典用例是，如果您希望在每次保存对象时发生某些事情。例如（请参见save()，了解其接受的参数的文档）

from django.db import models


class Blog(models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()

    def save(self, *args, **kwargs):
        do_something()
        super().save(*args, **kwargs)  # Call the "real" save() method.
        do_something_else()

您还可以防止保存

from django.db import models


class Blog(models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()

    def save(self, *args, **kwargs):
        if self.name == "Yoko Ono's blog":
            return  # Yoko shall never have her own blog!
        else:
            super().save(*args, **kwargs)  # Call the "real" save() method.

重要的是要记住调用超类方法，即super().save(*args, **kwargs)业务，以确保对象仍保存到数据库中。如果您忘记调用超类方法，则默认行为不会发生，并且数据库不会受到影响。

同样重要的是，您传递可以传递给模型方法的参数，即*args, **kwargs位的作用。Django 会时不时地扩展内置模型方法的功能，添加新参数。如果您在方法定义中使用*args, **kwargs，则可以保证在添加这些参数时，您的代码会自动支持这些参数。

如果您希望在 save() 方法中更新字段值，您可能还希望将此字段添加到 update_fields 关键字参数中。这将确保在指定 update_fields 时保存该字段。例如

from django.db import models
from django.utils.text import slugify


class Blog(models.Model):
    name = models.CharField(max_length=100)
    slug = models.TextField()

    def save(
        self, force_insert=False, force_update=False, using=None, update_fields=None
    ):
        self.slug = slugify(self.name)
        if update_fields is not None and "name" in update_fields:
            update_fields = {"slug"}.union(update_fields)
        super().save(
            force_insert=force_insert,
            force_update=force_update,
            using=using,
            update_fields=update_fields,
        )

有关更多详细信息，请参见 指定要保存的字段。

执行自定义 SQL¶

另一种常见模式是在模型方法和模块级方法中编写自定义 SQL 语句。有关使用原始 SQL 的更多详细信息，请参阅有关使用原始 SQL的文档。

抽象基类¶

当您想将一些公共信息放入多个其他模型中时，抽象基类非常有用。编写基类并在 Meta 类中放入 abstract=True。然后，此模型将不会用于创建任何数据库表。相反，当它用作其他模型的基类时，它的字段将添加到子类的字段中。

一个示例

from django.db import models


class CommonInfo(models.Model):
    name = models.CharField(max_length=100)
    age = models.PositiveIntegerField()

    class Meta:
        abstract = True


class Student(CommonInfo):
    home_group = models.CharField(max_length=5)

Student 模型将有三个字段：name、age 和 home_group。CommonInfo 模型不能用作普通 Django 模型，因为它是一个抽象基类。它不生成数据库表或拥有管理器，并且不能直接实例化或保存。

从抽象基类继承的字段可以用另一个字段或值覆盖，也可以用 None 删除。

对于许多用途，这种类型的模型继承正是您想要的。它提供了一种在 Python 级别分解通用信息的方法，同时在数据库级别仍然只为每个子模型创建一个数据库表。

from django.db import models


class CommonInfo(models.Model):
    # ...
    class Meta:
        abstract = True
        ordering = ["name"]


class Student(CommonInfo):
    # ...
    class Meta(CommonInfo.Meta):
        db_table = "student_info"

from django.db import models


class CommonInfo(models.Model):
    name = models.CharField(max_length=100)
    age = models.PositiveIntegerField()

    class Meta:
        abstract = True
        ordering = ["name"]


class Unmanaged(models.Model):
    class Meta:
        abstract = True
        managed = False


class Student(CommonInfo, Unmanaged):
    home_group = models.CharField(max_length=5)

    class Meta(CommonInfo.Meta, Unmanaged.Meta):
        pass

from django.db import models


class Base(models.Model):
    m2m = models.ManyToManyField(
        OtherModel,
        related_name="%(app_label)s_%(class)s_related",
        related_query_name="%(app_label)s_%(class)ss",
    )

    class Meta:
        abstract = True


class ChildA(Base):
    pass


class ChildB(Base):
    pass

from common.models import Base


class ChildB(Base):
    pass

多表继承¶

Django 支持的第二种模型继承类型是层次结构中的每个模型都是一个单独的模型。每个模型对应其自己的数据库表，可以单独查询和创建。继承关系在子模型与其每个父模型之间引入链接（通过自动创建的 OneToOneField）。例如

from django.db import models


class Place(models.Model):
    name = models.CharField(max_length=50)
    address = models.CharField(max_length=80)


class Restaurant(Place):
    serves_hot_dogs = models.BooleanField(default=False)
    serves_pizza = models.BooleanField(default=False)

Place 的所有字段都将在 Restaurant 中可用，尽管数据将驻留在不同的数据库表中。因此，以下两者都是可能的

>>> Place.objects.filter(name="Bob's Cafe")
>>> Restaurant.objects.filter(name="Bob's Cafe")

如果您有一个同时也是 Restaurant 的 Place，您可以使用模型名称的小写版本从 Place 对象获取 Restaurant 对象

>>> p = Place.objects.get(id=12)
# If p is a Restaurant object, this will give the child class:
>>> p.restaurant
<Restaurant: ...>

但是，如果上述示例中的 p 不是 Restaurant（它已直接创建为 Place 对象或是一些其他类的父级），则引用 p.restaurant 将引发 Restaurant.DoesNotExist 异常。

在 Restaurant 上自动创建的 OneToOneField 将其链接到 Place，如下所示

place_ptr = models.OneToOneField(
    Place,
    on_delete=models.CASCADE,
    parent_link=True,
    primary_key=True,
)

您可以通过在 Restaurant 上声明您自己的 OneToOneField 并使用 parent_link=True 来覆盖该字段。

class ChildModel(ParentModel):
    # ...
    class Meta:
        # Remove parent's ordering effect
        ordering = []

class Supplier(Place):
    customers = models.ManyToManyField(Place)

Reverse query name for 'Supplier.customers' clashes with reverse query
name for 'Supplier.place_ptr'.

HINT: Add or change a related_name argument to the definition for
'Supplier.customers' or 'Supplier.place_ptr'.

代理模型¶

使用 多表继承 时，将为模型的每个子类创建一个新的数据库表。这通常是期望的行为，因为子类需要一个地方来存储基本类中不存在的任何附加数据字段。但是，有时您只想更改模型的 Python 行为 - 可能更改默认管理器或添加新方法。

代理模型继承用于：为原始模型创建代理。您可以创建、删除和更新代理模型的实例，所有数据都将保存，就像您使用原始（非代理）模型一样。不同之处在于，您可以在代理中更改默认模型排序或默认管理器等内容，而无需更改原始内容。

代理模型声明与普通模型类似。通过将 proxy 特性 Meta 类的属性设置为 True，可以告知 Django 它是一个代理模型。

例如，假设您想向 Person 模型添加一个方法。您可以像这样操作

from django.db import models


class Person(models.Model):
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)


class MyPerson(Person):
    class Meta:
        proxy = True

    def do_something(self):
        # ...
        pass

MyPerson 类在与其父类 Person 相同的数据库表上运行。特别是， Person 的任何新实例都将可以通过 MyPerson 访问，反之亦然

>>> p = Person.objects.create(first_name="foobar")
>>> MyPerson.objects.get(first_name="foobar")
<MyPerson: foobar>

您还可以使用代理模型为模型定义不同的默认排序。您可能并不总是想对 Person 模型进行排序，但当您使用代理时，通常按 last_name 属性进行排序

class OrderedPerson(Person):
    class Meta:
        ordering = ["last_name"]
        proxy = True

现在，普通的 Person 查询将无序，而 OrderedPerson 查询将按 last_name 排序。

代理模型继承 Meta 特性 与普通模型的方式相同。

from django.db import models


class NewManager(models.Manager):
    # ...
    pass


class MyPerson(Person):
    objects = NewManager()

    class Meta:
        proxy = True

# Create an abstract class for the new manager.
class ExtraManagers(models.Model):
    secondary = NewManager()

    class Meta:
        abstract = True


class MyPerson(Person, ExtraManagers):
    class Meta:
        proxy = True

多重继承¶

就像 Python 的子类化一样，Django 模型可以从多个父模型继承。请记住，正常的 Python 名称解析规则适用。特定名称（例如 Meta）首次出现在的第一个基类将被使用；例如，这意味着如果多个父级包含 Meta 类，则仅使用第一个，而所有其他类都将被忽略。

通常，您不需要从多个父级继承。此功能有用的主要用例是“混合”类：向继承混合类的每个类添加特定的额外字段或方法。尽量保持继承层次结构尽可能简单和直接，这样您就不必费力找出特定信息来自何处。

请注意，从具有公共 id 主键字段的多个模型继承将引发错误。要正确使用多重继承，您可以在基本模型中使用显式的 AutoField

class Article(models.Model):
    article_id = models.AutoField(primary_key=True)
    ...


class Book(models.Model):
    book_id = models.AutoField(primary_key=True)
    ...


class BookReview(Book, Article):
    pass

或使用公共祖先来保存 AutoField。这需要使用从每个父模型到公共祖先的显式 OneToOneField，以避免自动生成并由子级继承的字段之间发生冲突

class Piece(models.Model):
    pass


class Article(Piece):
    article_piece = models.OneToOneField(
        Piece, on_delete=models.CASCADE, parent_link=True
    )
    ...


class Book(Piece):
    book_piece = models.OneToOneField(Piece, on_delete=models.CASCADE, parent_link=True)
    ...


class BookReview(Book, Article):
    pass

不允许“隐藏”字段名称¶

在正常的 Python 类继承中，允许子类覆盖父类的任何属性。在 Django 中，通常不允许对模型字段执行此操作。如果非抽象模型基类有一个名为 author 的字段，则无法在从该基类继承的任何类中创建另一个模型字段或定义名为 author 的属性。

此限制不适用于从抽象模型继承的模型字段。此类字段可以用另一个字段或值覆盖，或通过设置 field_name = None 删除。

覆盖父模型中的字段会导致在诸如初始化新实例（在 Model.__init__ 中指定要初始化哪个字段）和序列化等领域出现困难。这些是普通 Python 类继承不必以完全相同的方式处理的特性，因此 Django 模型继承与 Python 类继承之间的差异并非任意而为。

此限制仅适用于 Field 实例的属性。如果您愿意，可以覆盖普通的 Python 属性。它还仅适用于 Python 看到的属性名称：如果您手动指定数据库列名，则可以在子模型和祖先模型中同时出现相同的列名，用于多表继承（它们是两个不同数据库表中的列）。

如果您覆盖任何祖先模型中的任何模型字段，Django 将引发 FieldError。

请注意，由于在类定义期间解析字段的方式，从多个抽象父模型继承的模型字段将按照严格的深度优先顺序解析。这与标准 Python MRO 形成对比，后者在菱形继承的情况下按广度优先解析。此差异仅影响复杂的模型层次结构，（根据上述建议）您应尽量避免这种情况。