楷模¶

字段类型¶

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

• 列类型，它告诉数据库存储什么类型的数据（例如，INTEGER，VARCHAR，TEXT）。

• 在呈现表单字段（例如 <input type="text">，<select>）时使用的默认HTML 窗口小部件。

• 最小验证要求，用于Django admin及其自动生成的表单。

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'),
)

每个元组中的第一个元素是将存储在数据库中的值。第二个元素将由默认表单窗口小部件或在 ModelChoiceField 中显示。给定模型实例，可以使用 get_FOO_display() 方法访问选项字段的显示值。例如:

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'

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)
['Apple', 'Pear']

unique

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

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

自动主键字段¶

默认情况下，Django为每个模型提供以下字段:

id = models.AutoField(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提供了定义三种最常见类型的数据库关系的方法：many-to-one，many-to-many和one-to-one。

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):              # __unicode__ on Python 2
        return self.name

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

    def __str__(self):              # __unicode__ on Python 2
        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>]>

>>> # THIS WILL NOT WORK
>>> beatles.members.add(john)
>>> # NEITHER WILL THIS
>>> beatles.members.create(name="George Harrison")
>>> # AND NEITHER WILL THIS
>>> beatles.members.set([john, paul, ringo, george])

>>> 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 WILL NOT WORK BECAUSE IT CANNOT TELL WHICH MEMBERSHIP TO REMOVE
>>> beatles.members.remove(ringo)

>>> # 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!
   

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

SQL保留字，例如 join，where 或 select，are 允许作为模型字段名称，因为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(Blog, self).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(Blog, self).save(*args, **kwargs) # Call the "real" save() method.

重要的是要记住调用超类方法 - 那就是 super(Blog, self).save(*args, **kwargs) 业务 - 以确保对象仍然保存到数据库中。如果你忘记调用超类方法，默认行为不会发生，数据库不会被触摸。

同样重要的是你通过可以传递给模型方法的参数 - 这就是 *args, **kwargs 位。 Django将不时地扩展内置模型方法的能力，添加新的参数。如果您在方法定义中使用 *args, **kwargs，那么您将确保您的代码在添加时将自动支持这些参数。

执行自定义SQL¶

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

抽象基类¶

当你想把一些常用的信息放入一些其他模型时，抽象基类很有用。你写你的基类并把 abstract=True 放在 元 类中。此模型将不会用于创建任何数据库表。相反，当它被用作其他模型的基类时，它的字段将被添加到子类的那些。在抽象基类中的字段与子类中的字段具有相同的名称（和Django将引发异常）是错误的。

一个例子:

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模型，因为它是一个抽象基类。它不生成数据库表或具有管理器，并且不能直接实例化或保存。

对于许多用途，这种类型的模型继承将是你想要的。它提供了一种在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 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 是 not a Restaurant （它已经直接创建为 Place 对象或者是其他类的父类），则引用 p.restaurant 将引发 Restaurant.DoesNotExist 异常。

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。您可以创建，删除和更新代理模型的实例，并且所有数据将被保存，就像您使用原始（非代理）模型一样。不同之处在于，您可以更改代理中的默认模型排序或默认管理器，而无需更改原始模型。

代理模型声明为正常模型。你告诉Django它是一个代理模型，通过将 Meta 类的 proxy 属性设置为 True。

例如，假设您要向 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名称解析规则适用。特定名称（例如 元）出现的第一个基类将是所使用的；例如，这意味着如果多个父节点包含 元 类，则只有第一个将被使用，并且所有其他父节点将被忽略。

一般来说，你不需要继承多个父母。主要用例在这里是有用的是“混入”类：添加一个特殊的额外字段或方法到每个继承混合的类。尝试保持您的继承层次结构尽可能简单和直接，以便您不必努力找出特定的信息来源。

注意，从具有公共 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:

class Piece(models.Model):
    pass

class Article(Piece):
    ...

class Book(Piece):
    ...

class BookReview(Book, Article):
    pass

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

在正常的Python类继承中，允许子类重写父类的任何属性。在Django中，这通常不允许用于模型字段。如果非抽象模型基类有一个名为 author 的字段，则不能创建另一个模型字段或在从该基类继承的任何类中定义一个名为 author 的属性。

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

覆盖父模型中的字段导致在诸如初始化新实例（指定在 Model.__init__ 中初始化哪个字段）和序列化等领域中的困难。这些是正常的Python类继承不必以相同的方式处理的特性，因此Django模型继承和Python类继承之间的区别不是任意的。

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

如果你覆盖任何祖先模型中的任何模型字段，Django将提出一个 FieldError。