模型

字段类型

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

一系列二元组，用作此字段的选项。如果提供了二元组，默认表单小部件是一个选择框，而不是标准文本字段，并将限制给出的选项。

一个选项列表：

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

备注

每当 choices 的顺序变动时将会创建新的迁移。

每个二元组的第一个值会储存在数据库中，而第二个值将只会用于在表单中显示。

对于一个模型实例，要获取该字段二元组中相对应的第二个值，使用 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'

你也可以使用枚举类以简洁的方式来定义 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.choices, max_length=10)

model field reference 中定义了更多的示例。

default

该字段的默认值。可以是一个值或者是个可调用的对象，如果是个可调用对象，每次实例化模型时都会调用该对象。

help_text

额外的“帮助”文本，随表单控件一同显示。即便你的字段未用于表单，它对于生成文档也是很有用的。

primary_key

如果设置为 True ，将该字段设置为该模型的主键。

在一个模型中，如果你没有对任何一个字段设置 primary_key=True 选项。 Django 会自动添加一个 IntegerField 字段，并设置为主键，因此除非你想重写 Django 默认的主键设置行为，你可以不手动设置主键。详情请见 自动设置主键 。

主键字段是只可读的，如果你修改一个模型实例的主键并保存，这等同于创建了一个新的模型实例。例如：

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 提供了定义三种最常见的数据库关联关系的方法：多对一，多对多，一对一。

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 查询当中清洗了所有的数据库表名和字段名，通过使用特定数据库引擎的引用语法。

自定义的字段类型

如果已经存在的模型字段不能满足你的需求，或者你希望支持一些不太常见的数据库列类型，你可以创建自己的字段类。在 编写自定义模型字段 中提供了创建自定义字段的各方面内容。