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 执行,结果再组装成对象。
    • 关系维护:外键、多对多中间表、级联删除策略都由模型声明。
  • 图解:
    ORM

  • 数据库连接与驱动的配置在《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
    15
    from 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 KEY
    • app_label 来自应用注册时的名字,不是模型自己决定的;跨应用引用模型时要用 "shop.Book" 这种字符串形式。
    • 表名可以改:class Meta: db_table = "tb_book"。
    • 没写主键时 Django 自动加一个 id,类型由 DEFAULT_AUTO_FIELD 决定(新项目默认 BigAutoField,实测建表就是 bigint)。
  • 定义完要跑两步才会真正建表:

    1
    2
    python manage.py makemigrations shop
    python manage.py migrate
    • makemigrations 只是生成 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
    7
    AutoField, 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 列类型 备注
    AutoField integer AUTO_INCREMENT PRIMARY KEY 32 位
    BigAutoField bigint AUTO_INCREMENT PRIMARY KEY 新项目默认
    SmallAutoField smallint AUTO_INCREMENT 16 位
    BooleanField bool MySQL 里其实是 tinyint(1)
    CharField(max_length=20) varchar(20) 必须给 max_length
    TextField longtext 不需要 max_length
    EmailField varchar(254) 上限固定 254
    URLField varchar(200) 上限固定 200
    SlugField varchar(50) + 建索引 默认 50,且自动 db_index
    FileField varchar(100) 存的是路径,不是文件内容
    IntegerField integer
    BigIntegerField bigint
    SmallIntegerField smallint
    PositiveIntegerField integer UNSIGNED + CHECK (>= 0) 数据库层也拦
    FloatField double precision
    DecimalField(max_digits=6, decimal_places=2) numeric(6, 2)
    DateField date
    DateTimeField datetime(6) 微秒精度到 6 位
    TimeField time(6)
    DurationField bigint 存的是微秒数
    JSONField json MySQL 5.7+ 原生类型
    BinaryField longblob
    GenericIPAddressField char(39) IPv6 最长 39 字符
    UUIDField char(32) 库里存不带连字符的 32 位
    • get_internal_type() 能看出继承关系(实测):EmailField、URLField 的内部类型都是 CharField,所以它们共享 varchar 那一套行为;SlugField 的内部类型是 SlugField 自己。
  • 数值范围(实测类属性)

    1
    IntegerField 范围: 2147483647 | Small: 32767 | Big: 9223372036854775807
    • 这是 Django 校验层的范围(full_clean 会报),数据库层还可能更早拦下(MySQL 的 integer 溢出会直接 DataError)。
  • 超长写入的真实报错(MySQL 严格模式,实测)

    1
    超长 title: DataError (1406, "Data too long for column 'title' at row 1")

    SQLite 会宽容地存进去(本机对比过),换库就会暴露,所以 max_length 不能随便写。

字段选项

  • 默认值一览(CharField(max_length=20) 实例上实测)

    1
    2
    3
    null=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 建表时列是 NULL
    blank=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
    3
    class 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_messages

    1
    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 / editable

    1
    2
    verbose_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=...)。
  • validators

    1
    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
    4
    ForeignKey: (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 同形,只是列上带 UNIQUE
    • on_delete 是必填位置参数(Django 2.0 起),漏了直接 TypeError。
  • 表名、列名、反向访问器(实测)

    1
    2
    3
    4
    5
    6
    Book.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
    4
    class 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
    7
    protect    : 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 ...)')
    策略 谁拦的 抛什么 前置条件
    CASCADE Django 先查再删(级联删子行) 无 —
    PROTECT Django ProtectedError —
    RESTRICT Django RestrictedError —
    SET_NULL Django 无(置空) 字段必须 null=True
    SET_DEFAULT Django 无(置默认值) 字段要有 default
    DO_NOTHING 交给数据库 数据库报错(MySQL 是 1451 IntegrityError) 库自己有没有约束
    • PROTECT 和 RESTRICT 的差别只在异常类型(实测两个都拦得住),Django 侧都是先 SELECT 再决定。
    • CASCADE 实测:Book.objects.filter(publisher=p2).delete() 只删引用行,父行 Publisher 还在;反过来删父行会连带删子行。
  • 多对多的读写

    1
    2
    3
    4
    5
    book.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() 要改成显式创建中间表对象。

Meta 选项

  • 内部类 Meta 放的是「模型级」配置,不是字段级。

    models.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    class 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
    5
    ordering: ['-title'] | verbose_name: 书 / 书们
    permissions: [('can_archive', '可以归档')]
    get_latest_by: title
    constraints: ['uniq_title_pub'] | indexes: ['idx_book_title']
    managed: True | db_table: shop_book
    • verbose_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
    2
    CREATE 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= 是旧参数名。
  • unique_together 已经废弃(实测)

    1
    2
    Meta 里还有这个属性吗: 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() 时才真查。
  • 常用 API 与实测返回

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    all 计数: 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? True
    • first() / 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 与 F

    1
    2
    3
    4
    5
    6
    7
    8
    9
    from 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 查询数: 2
    • select_related 用于 FK / OneToOne(JOIN 成一条 SQL);prefetch_related 用于 M2M / 反向(两条 SQL 在 Python 里拼)。
    • 判断要不要加,就用 django.test.utils.CaptureQueriesContext 数查询条数,别猜。
  • 自定义管理器 / 查询集

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    class 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
    4
    pk 与 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
    2
    save(force_insert): 成功, pk= 999999
    update_fields 后库里 views: 123
    • force_insert=True:只允许 INSERT(指定主键插入,实测成功);force_update=True:只允许 UPDATE,行不存在时报 DatabaseError。
    • update_fields=["views"]:只写这几列,别的列即使改了也不落库(并发场景下要小心覆盖)。
  • delete() 之后对象还在内存里(实测)

    1
    2
    delete 返回结构: (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
    2
    Book.DoesNotExist 基类: ['ObjectDoesNotExist']
    是 ObjectDoesNotExist 子类: True

    捕获顺序建议:先 Model.DoesNotExist,再 ObjectDoesNotExist(能同时兜住跨模型的 select_related 缺失)。

时间、精度、校验与事务

  • auto_now_add / auto_now(实测)

    1
    2
    auto_now_add 是 aware: True | auto_now: True
    save 后 updated 变了: True | created 不变: True
    • auto_now_add=True:只在插入时写一次;auto_now=True:每次 save() 都覆盖,所以它当不了「创建时间」,也意味着你手动改它没用。
    • 想「只在更新时改」要自己写 save() 或用信号(见《Django-Signals》)。
  • USE_TZ=True 时给 naive 时间会怎样(实测警告原文)

    1
    2
    RuntimeWarning: 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
    2
    Money.objects.filter(payload__has_key="a")
    Money.objects.filter(payload__a__contains=[1])
    • 键名里带特殊字符时这种「双下划线穿透」不好使,退回 payload__contains={"a": [1]}。
  • 校验只在 full_clean() 发生(实测)

    1
    2
    3
    clean 生效: {'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
    5
    from 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
    6
    python 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_delete TypeError: __init__() missing 1 required positional argument 必须写策略
    一个模型两个 FK 指向同一模型 反向名冲突,启动就报错 各写一个 related_name
    SET_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 上,也不会变成约束 用 UniqueConstraint
    CheckConstraint(check=...) RemovedInDjango60Warning: ... deprecated in favor of .condition 6.x 前改成 condition=
    class Draft(models.Model) + proxy TypeError: 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=lambda ValueError: Cannot serialize function: lambda 用具名函数
    表名靠模型名猜 查库时找不到表 实测规则:app_label_模型名小写

参考

本文结束 感谢您的阅读
正在加载今日诗词....