字段类型¶

模型中的每个字段都应该是相应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

字段的默认值。可以是值或可调用对象。如果可调用，则每次创建新对象时都会调用它。

db_default

字段的数据库计算默认值。可以是字面值或数据库函数。

如果同时设置了db_default和Field.default，则在 Python 代码中创建实例时，default将优先。

db_default 仍然会在数据库级别设置，并在 ORM 外部插入行或在迁移中添加新字段时使用。

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, **kwargs):
        do_something()
        super().save(**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, **kwargs):
        if self.name == "Yoko Ono's blog":
            return  # Yoko shall never have her own blog!
        else:
            super().save(**kwargs)  # Call the "real" save() method.

重要的是要记住调用超类方法——那就是 super().save(**kwargs) 部分——以确保对象仍然保存到数据库中。如果您忘记调用超类方法，则默认行为将不会发生，并且数据库将不会被修改。

同样重要的是，您需要传递可以传递给模型方法的参数——这就是 **kwargs 的作用。Django 将不时扩展内置模型方法的功能，添加新的关键字参数。如果您在方法定义中使用 **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, **kwargs):
        self.slug = slugify(self.name)
        if (
            update_fields := kwargs.get("update_fields")
        ) is not None and "name" in update_fields:
            kwargs["update_fields"] = {"slug"}.union(update_fields)
        super().save(**kwargs)

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

执行自定义 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")

如果你有一个既是Place 又是Restaurant 的对象，你可以使用模型名称的小写版本从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和Place的OneToOneField看起来像这样。

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 行为——也许是为了更改默认管理器或添加新方法。

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

代理模型的声明方式与普通模型相同。通过将Meta类的proxy属性设置为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 类，则只使用第一个，其他所有类都将被忽略。

通常，不需要从多个父类继承。这有用的主要用例是“mixin”类：向继承 mixin 的每个类添加特定的额外字段或方法。尽量使继承层次结构保持简单明了，这样就不必费力地找出特定信息来自哪里。

请注意，从具有公共 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 形成对比，后者在菱形继承的情况下以广度优先顺序解析。此差异仅影响复杂的模型层次结构，根据上述建议，应尽量避免这种情况。