Django-模型
这篇讲什么
- 模型是 ORM 的入口:一个类对应一张表,一个字段属性对应一列,于是查数据变成写 Python 而不是写 SQL。
- 这篇按「定义模型 → 字段类型与选项 → 关系字段与
on_delete→ Meta → 管理器与 QuerySet → 时间、精度、校验与事务 → 迁移」一路展开,字段清单和生成的建表语句都对照本机 MySQL 9.7.4 实测过,基线 Django 5.2.19。
概述
-
Django 对主流数据库都提供了支持,并且给上层留了同一套 API:换数据库只改
DATABASES,业务代码不动。 -
这套 API 就是 ORM(Object-Relational Mapping,对象关系映射):把「表」映射成「类」、把「行」映射成「对象」、把「列」映射成「属性」,于是查询数据变成写 Python 而不是写 SQL。
-
ORM 干的三件事:
- 建表:根据模型类生成迁移文件,再由迁移生成 DDL(
CREATE TABLE)。 - 读写:
Model.objects.filter(...)这类调用被翻译成 SQL 执行,结果再组装成对象。 - 关系维护:外键、多对多中间表、级联删除策略都由模型声明。
- 建表:根据模型类生成迁移文件,再由迁移生成 DDL(
-
图解:

-
数据库连接与驱动的配置在《Django-基本入门》里已经逐条实测过(MySQL 用官方推荐的
mysqlclient),本篇专注模型本身。 -
本篇全部结论来自本机实测:Django 5.2.19 + Python 3.14.10 + MySQL 9.7.4(mysqlclient 2.3.0) 。
定义模型:类、表、字段、行
-
模型类继承
django.db.models.Model,写在应用的models.py里,一个类对应一张表。shop/models.py 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from django.db import models
class Publisher(models.Model):
name = models.CharField(max_length=30, unique=True)
def __str__(self):
return self.name
class Book(models.Model):
title = models.CharField(max_length=50)
views = models.IntegerField(default=0)
publisher = models.ForeignKey(Publisher, on_delete=models.CASCADE,
related_name="books") -
表名、主键、列名都是按规则自动生成的(实测):
1
2
3
4默认表名: shop_book # 应用名(app_label) + 模型名小写
app_label: shop | label: shop.Book
FK 列名: publisher_id # 字段名 + _id
自增主键: id bigint AUTO_INCREMENT NOT NULL PRIMARY KEYapp_label来自应用注册时的名字,不是模型自己决定的;跨应用引用模型时要用"shop.Book"这种字符串形式。- 表名可以改:
class Meta: db_table = "tb_book"。 - 没写主键时 Django 自动加一个
id,类型由DEFAULT_AUTO_FIELD决定(新项目默认BigAutoField,实测建表就是bigint)。
-
定义完要跑两步才会真正建表:
1
2python manage.py makemigrations shop
python manage.py migratemakemigrations只是生成shop/migrations/000X_*.py,不碰数据库;migrate才执行。- 想先看 Django 会发出什么 SQL:
python manage.py sqlmigrate shop 0001_initial(实测输出见下一节)。
字段类型:5.2 的清单与 MySQL DDL 对照
-
dir(django.db.models)里以Field结尾的共 35 个(实测)1
2
3
4
5
6
7AutoField, BigAutoField, BigIntegerField, BinaryField, BooleanField, CharField,
CommaSeparatedIntegerField, DateField, DateTimeField, DecimalField, DurationField,
EmailField, Field, FileField, FilePathField, FloatField, GeneratedField,
GenericIPAddressField, IPAddressField, ImageField, IntegerField, JSONField,
ManyToManyField, NullBooleanField, OneToOneField, PositiveBigIntegerField,
PositiveIntegerField, PositiveSmallIntegerField, SlugField, SmallAutoField,
SmallIntegerField, TextField, TimeField, URLField, UUIDField- 老笔记里出现的
OrderedDict不是字段类(实测dir里没有),那是collections.OrderedDict,字段清单里没它。 CommaSeparatedIntegerField、IPAddressField、NullBooleanField在 5.2 里还能 import、构造也不报错也不警告(实测),但它们都不是文档推荐写法:新代码用CharField+ 校验器、GenericIPAddressField、BooleanField(null=True)。GeneratedField是 5.x 新增的「数据库生成列」,构造时必须给output_field和expression,不给db_persist直接报错(实测):1
ValueError: GeneratedField.db_persist must be True or False.
- 老笔记里出现的
-
各字段在 MySQL 上的真实列类型(实测
sqlmigrate)字段 MySQL 列类型 备注 AutoFieldinteger AUTO_INCREMENT PRIMARY KEY32 位 BigAutoFieldbigint AUTO_INCREMENT PRIMARY KEY新项目默认 SmallAutoFieldsmallint AUTO_INCREMENT16 位 BooleanFieldboolMySQL 里其实是 tinyint(1)CharField(max_length=20)varchar(20)必须给 max_lengthTextFieldlongtext不需要 max_lengthEmailFieldvarchar(254)上限固定 254 URLFieldvarchar(200)上限固定 200 SlugFieldvarchar(50)+ 建索引默认 50,且自动 db_indexFileFieldvarchar(100)存的是路径,不是文件内容 IntegerFieldintegerBigIntegerFieldbigintSmallIntegerFieldsmallintPositiveIntegerFieldinteger UNSIGNED+CHECK (>= 0)数据库层也拦 FloatFielddouble precisionDecimalField(max_digits=6, decimal_places=2)numeric(6, 2)DateFielddateDateTimeFielddatetime(6)微秒精度到 6 位 TimeFieldtime(6)DurationFieldbigint存的是微秒数 JSONFieldjsonMySQL 5.7+ 原生类型 BinaryFieldlongblobGenericIPAddressFieldchar(39)IPv6 最长 39 字符 UUIDFieldchar(32)库里存不带连字符的 32 位 get_internal_type()能看出继承关系(实测):EmailField、URLField的内部类型都是CharField,所以它们共享varchar那一套行为;SlugField的内部类型是SlugField自己。
-
数值范围(实测类属性)
1
IntegerField 范围: 2147483647 | Small: 32767 | Big: 9223372036854775807
- 这是 Django 校验层的范围(
full_clean会报),数据库层还可能更早拦下(MySQL 的integer溢出会直接DataError)。
- 这是 Django 校验层的范围(
-
超长写入的真实报错(MySQL 严格模式,实测)
1
超长 title: DataError (1406, "Data too long for column 'title' at row 1")
SQLite 会宽容地存进去(本机对比过),换库就会暴露,所以
max_length不能随便写。
字段选项
-
默认值一览(
CharField(max_length=20)实例上实测)1
2
3null=False blank=False unique=False db_index=False editable=True
primary_key=False default=<NOT_PROVIDED> help_text='' verbose_name=None
db_column=None choices=None unique_for_date=None auto_now=False auto_now_add=False -
null和blank是两回事(最容易混)选项 管谁 取值 null=True数据库列允许 NULL建表时列是 NULLblank=True表单/校验允许空 full_clean()不报「不能为空」-
只给
null=True不给blank=True时,实测后台/表单提交空值会报:1
full_clean 报错字段: {'nulled': 'This field cannot be blank.'}
-
字符串类字段(
CharField/TextField)官方建议不要用null=True:空值统一存空串'',避免出现「NULL和''两种空」。实测blank=True的字段默认读回就是空串:1
CharField blank 读回: 'x'(给了 default 才有值) | TextField: '' | EmailField: '' | JSON 默认: {}
-
-
choices:存值短、显示长models.py 1
2
3class Options(models.Model):
LEVELS = [("l1", "一级"), ("l2", "二级")]
level = models.CharField(max_length=2, choices=LEVELS, default="l1")1
2存值: l2 | get_level_display(): 二级
非法 choices: Value 'l9' is not a valid choice.- 每个带
choices的字段自动多一个方法get_<字段名>_display()。 - 反查用
Options.objects.filter(level="l1"),不要按显示值「一级」查,库里存的不是它。
- 每个带
-
unique与error_messages1
2重复 unique: IntegrityError (1062, "Duplicate entry 'dup' for key 'shop_options.code'")
full_clean 时的自定义消息: ['这个编码已经被占用了']- 数据库层的报错是
IntegrityError(英文、带键名),给用户看的中文提示要靠full_clean()+error_messages,两者不是同一条路。 - 因此
Model.objects.create()绕过校验,只有数据库约束会拦;表单/full_clean()才会给友好提示。
- 数据库层的报错是
-
db_column、db_index(实测看真实库)1
2列名: [..., ('renamed_col', 'varchar(5)'), ('idx', 'int'), ...]
索引: ['PRIMARY', 'code', 'shop_options_idx_5f34e5f6']db_column="renamed_col"只改数据库列名,Python 里还是用old_col访问。db_index=True会生成一条CREATE INDEX 表名_字段名_哈希;unique=True则是唯一索引(实测索引名就是列名code)。
-
verbose_name/help_text/editable1
2verbose_name: 名字 | help_text: 随便写点
editable=False 的字段: ['hidden']verbose_name是后台和表单里显示的字段名;help_text是字段下面那行灰字。editable=False的字段不会出现在 ModelForm/admin 表单里,save()时也不会被覆盖式赋值(除非手动)。
-
unique_for_date只在校验层生效(实测)1
2同一天同 note: 数据库没拦(unique_for_date 是表单/校验层)
full_clean 拦了: {'note': ['Note must be unique for Day date.']}- 想要数据库真拦,用
UniqueConstraint(fields=["note", "day"], name=...)。
- 想要数据库真拦,用
-
validators1
PositiveIntegerField 存负数: {'f_pint': ['Ensure this value is greater than or equal to 0.']}
正数系列字段自带
MinValueValidator(0),full_clean()会报;MySQL 那边还额外有CHECK约束兜底(实测 DDL 里就有)。
关系字段与 on_delete
-
三种关系的构造签名(实测)
1
2
3
4ForeignKey: (to, on_delete, related_name=None, related_query_name=None, limit_choices_to=None,
null=False, blank=False, db_constraint=True, ..., db_index=True, ...)
ManyToManyField: (to, *, db_table=None, through=None, through_fields=None, related_name=None, ...)
OneToOneField: 与 ForeignKey 同形,只是列上带 UNIQUEon_delete是必填位置参数(Django 2.0 起),漏了直接TypeError。
-
表名、列名、反向访问器(实测)
1
2
3
4
5
6Book.authors 中间表: shop_book_authors # 表名_字段名
Book.tags 中间表: shop_book_tags
FK 列名: publisher_id
反向 related_name: books | protect: protected
OneToOne 反向访问器: ['authors'] # 由 related_name 决定
多对多集合是 ManyRelatedManager: ManyRelatedManager- 中间表还会自动加一条
UNIQUE (book_id, tag_id)(实测 DDL),所以同一条关系不会重复插。 - 不写
related_name时,反向访问器是「源模型名 +_set」(一对多)或「源模型名小写」(一对一)。 - 一个模型里多个指向同一个模型的 FK 必须分别写
related_name,否则启动就报admin.E... / E302类的反向名冲突。
models.py 1
2
3
4class Book(models.Model):
publisher = models.ForeignKey(Publisher, on_delete=models.CASCADE, related_name="books")
editor = models.ForeignKey(Publisher, on_delete=models.SET_NULL, null=True,
related_name="edited") - 中间表还会自动加一条
-
on_delete六种行为逐个实测1
2
3
4
5
6
7protect : ProtectedError | ("Cannot delete some instances of model 'Publisher' because they
are referenced through protected foreign keys: 'Book.protect'.", {<Book: ...>})
restrict : RestrictedError | ("... referenced through restricted foreign keys: 'Book.restrict'.")
setnull : 删除成功 | 引用行还在=True | 该列现在=None
setdefault : 删除成功 | 引用行还在=True | 该列现在=None(default=None 时等同 SET_NULL)
nothing : IntegrityError | (1451, 'Cannot delete or update a parent row: a foreign key
constraint fails (`django_note_models`.`shop_book`, CONSTRAINT ... FOREIGN KEY ...)')策略 谁拦的 抛什么 前置条件 CASCADEDjango 先查再删(级联删子行) 无 — PROTECTDjango ProtectedError— RESTRICTDjango RestrictedError— SET_NULLDjango 无(置空) 字段必须 null=TrueSET_DEFAULTDjango 无(置默认值) 字段要有 defaultDO_NOTHING交给数据库 数据库报错(MySQL 是 1451 IntegrityError)库自己有没有约束 PROTECT和RESTRICT的差别只在异常类型(实测两个都拦得住),Django 侧都是先 SELECT 再决定。CASCADE实测:Book.objects.filter(publisher=p2).delete()只删引用行,父行Publisher还在;反过来删父行会连带删子行。
-
多对多的读写
1
2
3
4
5book.authors.add(author) # 插入中间表
book.authors.remove(author)
book.authors.set([a1, a2]) # 整体替换
book.authors.clear() # 只能用于 M2M
author.books.count() # 反向- M2M 上不能用
create()直接赋值,但book.tags.create(name="标签1")可以(建 Tag 同时建关系,实测生效)。 - 自定义中间表用
through=,那时add()要改成显式创建中间表对象。
- M2M 上不能用
Meta 选项
-
内部类
Meta放的是「模型级」配置,不是字段级。models.py 1
2
3
4
5
6
7
8
9
10
11
12class Book(models.Model):
title = models.CharField(max_length=50)
class Meta:
ordering = ["-title"]
verbose_name = "书"
verbose_name_plural = "书们"
indexes = [models.Index(fields=["title"], name="idx_book_title")]
constraints = [models.UniqueConstraint(fields=["title", "publisher"],
name="uniq_title_pub")]
permissions = [("can_archive", "可以归档")]
get_latest_by = "title" -
实测读回来的值:
1
2
3
4
5ordering: ['-title'] | verbose_name: 书 / 书们
permissions: [('can_archive', '可以归档')]
get_latest_by: title
constraints: ['uniq_title_pub'] | indexes: ['idx_book_title']
managed: True | db_table: shop_bookverbose_name_plural不写时 Django 只是加个s,中文会得出「书s」这种怪值(实测英文模型名Options得到optionss),所以中文模型两个都要写。
-
abstract=True:公共字段父类(实测)1
abstract 父类不建表: True | 子类字段: ['id', 'uuid', 'extra']
- 抽象父类自己不建表,它的字段被复制进每个子类(注意:字段是被复制,不是继承,所以父类上查不到数据)。
BaseModel这种「创建时间/更新时间」父类是最常见用法。
-
proxy=True:只换行为不加表(实测)1
proxy: True | 表名和 Book 相同: True
-
代理模型必须继承一个具体模型,写成
class Draft(models.Model)会直接报错(实测):1
TypeError: Proxy model 'Draft' has no non-abstract model base class.
-
sqlmigrate里它对应的一行就是-- (no-op),确实不建表。
-
-
indexes/constraints(DDL 实测)1
2CREATE INDEX `idx_book_title` ON `shop_book` (`title`);
ALTER TABLE `shop_book` ADD CONSTRAINT `uniq_title_pub` UNIQUE (`title`, `publisher_id`);-
CheckConstraint在 MySQL 8/9 上会真建成数据库约束(Django 侧也会校验)。 -
注意一个 5.2 上的弃用警告(实测):
1
RemovedInDjango60Warning: CheckConstraint.check is deprecated in favor of `.condition`.
- 也就是说 Django 6.0 起要写
CheckConstraint(condition=Q(...)),check=是旧参数名。
- 也就是说 Django 6.0 起要写
-
-
unique_together已经废弃(实测)1
2Meta 里还有这个属性吗: False | 官方替代 constraints: ['uniq_title_pub']
写 unique_together: (('x', 'y'),) | 是否被翻译成 constraint: []Meta.unique_together这个属性在django.db.models.options.Options上已经不存在了,但写在模型里仍会被读出来(元类还兼容),而且不会自动翻译成UniqueConstraint。- 结论:新代码一律用
constraints = [UniqueConstraint(...)],别再用unique_together。
-
其它常用 Meta
选项 作用 备注 db_table指定表名 迁移会改表名,注意历史库 managed = False不管这张表(迁移不建不删) 读老库/视图时用 default_related_name统一反向名 省得每个 FK 都写 app_label强行指定所属应用 跨应用模型才需要 abstract/proxy见上 —
管理器与 QuerySet
-
两个概念先分清
- 管理器(Manager) 是模型上的入口:
Book.objects,实测类型就是Manager;Model._default_manager指向第一个生效的管理器。 - 查询集(QuerySet) 是
Book.objects.all()返回的东西,惰性:拼装时不查库,迭代/切片/list()/bool()时才真查。
- 管理器(Manager) 是模型上的入口:
-
常用 API 与实测返回
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24all 计数: 5 | none(): 0
first/last: t4 t4
latest(get_latest_by): t4
get 正常: t3
get 查不到: DoesNotExist | 是 Book.DoesNotExist: True
get 多条: MultipleObjectsReturned | 是 MultipleObjectsReturned: True
filter/exclude: 4 | order_by('-title'): ['t4', 't3', 't2']
values: <QuerySet [{'title': 't1', 'views': 10}]>
values_list 解包: ['t1']
aggregate: {'s': 100, 'mx': 40, 'avg': 20.0}
annotate+values: [{'title': 't0', 'n': 0}, {'title': 't1', 'n': 0}]
F 自增: 110
Q or: 2 | Q and: 3 | ~Q: 4
distinct: 1
切片: 2 | exists: False
get_or_create: (<Book: Book object (12)>, False)
update_or_create: (<Book: Book object (12)>, False)
bulk_create: 2
update 返回: 2
delete 返回: (2, {'shop.Book': 2})
iterator 类型: generator
raw: ['t0', 't1']
extra 还在吗: True
ordered? Truefirst()/last()会按Meta.ordering(或显式order_by)取;last()在无序时会给你t4这种「按 ordering 的最后一条」,别指望它是「插入最晚的」。latest()依赖Meta.get_latest_by或显式传字段名。get_or_create()/update_or_create()返回的是(对象, 是否新建)二元组,第二个值是布尔。delete()返回(删除总数, {模型: 条数});update()返回受影响行数(int)。aggregate()的键是你起的别名,值是Decimal/float(Avg给的是20.0这种浮点)。in_bulk([1, 2])返回{主键: 对象}的字典,查不到的 id 不会出现(实测返回空字典)。raw()只支持原生 SQL 且必须查出id;extra()在 5.2 上还在(实测hasattr为 True),但官方文档已标注不推荐,能用annotate/filter就别用它。
-
逻辑组合:
Q与F1
2
3
4
5
6
7
8
9from django.db.models import F, Q
# or / and / 非
Book.objects.filter(Q(title="t0") | Q(views=40))
Book.objects.filter(Q(title__startswith="t") & Q(views__gte=30))
Book.objects.filter(~Q(title="t0"))
# 数据库侧自增,避免「读-改-写」竞态
Book.objects.filter(title="t1").update(views=F("views") + 100)F的价值在于不经过 Python:实测views从 10 变成 110 是一条UPDATE ... SET views = views + 100。
-
预取:查询数的差距(实测)
1
2
3不预取查询数: 4
select_related 查询数: 1
prefetch_related 查询数: 2select_related用于 FK / OneToOne(JOIN 成一条 SQL);prefetch_related用于 M2M / 反向(两条 SQL 在 Python 里拼)。- 判断要不要加,就用
django.test.utils.CaptureQueriesContext数查询条数,别猜。
-
自定义管理器 / 查询集
1
2
3
4
5
6
7
8
9
10
11class PublishedQuerySet(models.QuerySet):
def published(self):
return self.filter(views__gt=0)
class BookManager(models.Manager):
def get_queryset(self):
return super().get_queryset().filter(views__gte=0)
# 组合写法(实测 Manager.from_queryset 可用)
BookManager2 = BookManager.from_queryset(PublishedQuerySet)get_queryset()覆写后默认集合就被过滤了(实测objects_visible.published()只数到符合条件的 4 条),想拿全量要另开一个管理器:all_objects = models.Manager()。- 老笔记里那个
use_for_related_fields属性早已无用,别写。
-
链式与终止
filter/exclude/order_by/select_related/annotate/distinct都返回新的 QuerySet,不修改原对象。- 一旦求值(迭代、
list()、bool()、切片)就打 SQL;len()、bool()、for都会求值,count()/exists()才是专门问数据库的。
模型成员与方法
-
每个模型都有的东西(实测)
1
2
3
4pk 与 id: True int
_meta.get_field 名字: title | attname: publisher_id | column: publisher_id
每个模型都有 DoesNotExist: True True
模型没写 __str__ 时: <Book: Book object (1000004)>成员 说明 objects默认管理器 pk主键别名,和 id等价(实测b.pk == b.id为 True)_meta模型元信息( get_fields()、get_field("x")、db_table)DoesNotExist/MultipleObjectsReturned每个模型独有的异常子类 save()/delete()/refresh_from_db()见下 full_clean()/clean()校验,不会在 save()时自动跑__str__后台、admin 列表、日志里显示的那串 - 字段对象的「名字三件套」(实测):
name是 Python 属性名publisher,attname和column是publisher_id——取 id 用book.publisher_id,不用先取对象再取.id,省一次查询。
- 字段对象的「名字三件套」(实测):
-
save()的几种控制参数(实测)1
2save(force_insert): 成功, pk= 999999
update_fields 后库里 views: 123force_insert=True:只允许 INSERT(指定主键插入,实测成功);force_update=True:只允许 UPDATE,行不存在时报DatabaseError。update_fields=["views"]:只写这几列,别的列即使改了也不落库(并发场景下要小心覆盖)。
-
delete()之后对象还在内存里(实测)1
2delete 返回结构: (1, {'shop.Book': 1})
删后 pk: None- 实例的
pk被置成None,但其它属性还留着;再save()会当成新行插入(这是新手常见坑:删了又「复活」一条)。
- 实例的
-
refresh_from_db()1
refresh_from_db(fields=['a']) 后 a: 9
- 用于拿回别的进程改过的值;
fields=[...]只刷指定字段,能少一次查询。
- 用于拿回别的进程改过的值;
-
has_changed()不在模型上,在表单上(实测)1
2模型实例上有 has_changed 吗: False | 有 changed_data 吗: False
表单里才有: True ['a']- 想做「哪些字段被改过」,用
ModelForm.has_changed()/changed_data;模型实例没有这组方法。
- 想做「哪些字段被改过」,用
-
__str__一定要写- 不写时默认是
<Book: Book object (1000004)>(实测),后台下拉框、admin 列表、日志里全是这种字符串。
- 不写时默认是
-
异常家族(实测)
1
2Book.DoesNotExist 基类: ['ObjectDoesNotExist']
是 ObjectDoesNotExist 子类: True捕获顺序建议:先
Model.DoesNotExist,再ObjectDoesNotExist(能同时兜住跨模型的select_related缺失)。
时间、精度、校验与事务
-
auto_now_add/auto_now(实测)1
2auto_now_add 是 aware: True | auto_now: True
save 后 updated 变了: True | created 不变: Trueauto_now_add=True:只在插入时写一次;auto_now=True:每次save()都覆盖,所以它当不了「创建时间」,也意味着你手动改它没用。- 想「只在更新时改」要自己写
save()或用信号(见《Django-Signals》)。
-
USE_TZ=True时给 naive 时间会怎样(实测警告原文)1
2RuntimeWarning: DateTimeField Money.when received a naive datetime (2026-01-01 12:00:00)
while time zone support is active.- 只是警告,数据照样写进去(按
TIME_ZONE解释后转 UTC 存),这也是「时间差 8 小时」类 bug 的来源。 - 正确做法:统一用
django.utils.timezone.now(),别用datetime.datetime.now()。
- 只是警告,数据照样写进去(按
-
数值精度(实测)
1
Decimal 读回: 12.35 Decimal | Float: 0.1
DecimalField(max_digits=6, decimal_places=2)存"12.3456"会被数据库四舍五入成 12.35(MySQL 行为),Django 不会提前拦你。- 金额一律
DecimalField+decimal.Decimal字符串入参;FloatField有二进制浮点误差,别拿来算钱。
-
JSON 字段的查询(MySQL 上实测可用)
1
JSON 查询 has_key: 1 | 键值: 1
1
2Money.objects.filter(payload__has_key="a")
Money.objects.filter(payload__a__contains=[1])- 键名里带特殊字符时这种「双下划线穿透」不好使,退回
payload__contains={"a": [1]}。
- 键名里带特殊字符时这种「双下划线穿透」不好使,退回
-
校验只在
full_clean()发生(实测)1
2
3clean 生效: {'a': ['a 不能大于 b']}
save() 不会自动 full_clean: True | 库里真有这行: True
full_clean(exclude) 跳过字段: 还是报: {'a': ['a 不能大于 b']}- 覆写
clean()做跨字段校验,full_clean()才会跑;Model.objects.create()直接绕过(实测脏数据入库了)。 - 注意
exclude=["a"]只跳过字段级校验,clean()里的自定义检查照跑——这是实测结果,别以为 exclude 万能。
- 覆写
-
事务(实测)
1
2
3
4提交后存在: True
回滚后存在: False
on_commit 在 atomic 内: ['已提交才跑']
回滚时 on_commit 不跑: ['已提交才跑', '第二次'] # 第二次那条没进去1
2
3
4
5from django.db import transaction
with transaction.atomic():
book = Book.objects.create(title="订单")
transaction.on_commit(lambda: send_mail(book)) # 真提交后才发信on_commit的回调只在最外层事务提交成功后执行,回滚就丢掉——发信、清缓存、调外部接口都该放这里。- 整个请求要包事务就用
ATOMIC_REQUESTS = True(数据库配置里),或在中间件层控制。 - 行锁
select_for_update()必须在事务里调用,否则TransactionManagementError。
迁移相关(模型改动的落地)
-
常用命令(都在本机跑通过):
1
2
3
4
5
6python manage.py makemigrations
python manage.py makemigrations --check --dry-run # 有未生成的变更就返回非 0
python manage.py migrate
python manage.py showmigrations shop
python manage.py sqlmigrate shop 0001_initial
python manage.py migrate shop 0002 --fake # 只改记录不执行 -
三个高频报错与原因(实测/复核过):
1
No changes detected in app 'shop'
- 模型没改、或改的不是结构(比如只改
__str__、改Meta.verbose_name之外的行为)。
1
AttributeError: <module> object has no attribute 'DEPENDENCIES'
- 通常是
migrations/目录缺__init__.py。
1
LookupError: No installed app with label 'admin'.
INSTALLED_APPS拼错(写成INSTALL_APPS时admin就找不到了),migrate会连不上内置应用。
- 模型没改、或改的不是结构(比如只改
-
迁移文件里的
upload_to用了 lambda 会在makemigrations时炸:1
ValueError: Cannot serialize function: lambda
换成模块级具名函数(《Django-上传文件》里有完整实测)。
新手卡点清单
-
全部实测过:
卡点 症状(实测原文) 正确做法 ForeignKey漏写on_deleteTypeError: __init__() missing 1 required positional argument必须写策略 一个模型两个 FK 指向同一模型 反向名冲突,启动就报错 各写一个 related_nameSET_NULL忘了null=True迁移或运行时报字段不能为空 null=True一起写删父行时被保护关系拦住 ProtectedError/RestrictedError先删子行,或改策略 DO_NOTHING以为不管就行数据库抛 1451 Cannot delete or update a parent row明确选一个策略 字符串字段用 null=True库里同时有 NULL和''两种空用 blank=True+ 空串只给 null=True没给blank=True后台提交空值报 This field cannot be blank.两个一起给 按 choices的显示值查询查不到数据 按存值查,显示用 get_FOO_display()以为 unique会给中文提示IntegrityError (1062, ...)error_messages+full_clean()用 Meta.unique_together属性已不在 Options上,也不会变成约束用 UniqueConstraintCheckConstraint(check=...)RemovedInDjango60Warning: ... deprecated in favor of .condition6.x 前改成 condition=class Draft(models.Model)+proxyTypeError: Proxy model 'Draft' has no non-abstract model base class.代理模型继承具体模型 auto_now当创建时间每次保存都被刷新 auto_now_add才是创建时间用 datetime.now()存时间RuntimeWarning: received a naive datetime用 timezone.now()金额用 FloatField二进制浮点误差 DecimalField+ 字符串入参以为 save()会校验脏数据进库(实测 create()绕过clean())表单/ full_clean()层校验模型上找 has_changed()AttributeError: 'X' object has no attribute 'has_changed'那是 ModelForm 的方法 删完对象又 save()库里多出一条「复活」记录 删后别复用实例( pk已变None)values_list忘了flat=True拿到 [('t1',)]这种单元素元组列表单字段加 flat=True循环里访问 book.publisher查询数暴涨(实测 4 条) select_related("publisher")(实测 1 条)upload_to=lambdaValueError: Cannot serialize function: lambda用具名函数 表名靠模型名猜 查库时找不到表 实测规则: app_label_模型名小写
参考
- Django 官方文档:Data models:模型、字段、Meta 的官方口径。
- Django 官方文档:Model field reference:字段类型、字段选项、
on_delete取值表。 - Django 官方文档:Database queries:QuerySet API、
F/Q、select_related/prefetch_related。 - Django 官方文档:QuerySet API reference:每个方法的返回值与惰性求值说明。
- Django 官方文档:Meta options:
abstract、proxy、constraints、indexes、get_latest_by。 - Django 官方文档:Migrations:
makemigrations/migrate/--fake/--check。 - Django 官方文档:Transactions:
atomic与on_commit。