说起 Django ORM很多人第一反应是“帮我省掉 SQL 的工具”可真到了单表实例上连字段类型选错、迁移漏跑、查询集缓存这种基础坑都能把人卡半天。我在几个项目里反复折腾过 Django 的单表模型从简单的博客文章表到订单记录表发现只要把“单表”这件事嚼透后面学多表关联、复杂查询都会顺很多。这篇文章就围绕 Django ORM 单表实例把模型定义、增删改查、自定义管理器、迁移和性能陷阱完整过一遍。适合刚接触 Django 的初学者也适合写了两三年代码但一直在“能用就行”的开发者——读完你可以照着落地一个真实可用的单表模块不用再被 ORM 的“玄学”折磨。1. 单表模型远没你想的那么简单——为什么值得单独聊很多人觉得单表有什么好聊的不就是一个类对应一张表然后增删改查吗实际上我见过太多项目里单表代码写得乱七八糟字段定义随意、查询逻辑堆在视图里、迁移文件加到十几个却没人知道哪些该删、线上数据因为一次错误 save() 被覆盖。单表是 ORM 的最小单位也是所有数据操作的基石这块地基没打牢后面加外键、多对多、复杂聚合只会更痛苦。1.1 “ORM 只是自动生成 SQL”这个理解会害了你如果把 ORM 单纯理解成“自动生成 SQL”的翻译器你一定会写出很奇怪的代码。比如为了省事用一个很大的values()把所有字段捞出来然后丢给前端去处理或者在一个视图里连续写五个 filter 条件每个条件之间没有 relation看起来好像很厉害实际查询效率极低。ORM 的核心价值是“把数据库表映射成对象”让你用 Python 的思维操作数据。但映射不意味着免费你写下的每一个.filter()、.order_by()最终都会变成 SQL 片段只不过由框架帮你拼装。真正懂 ORM 的人会先想清楚“我要取哪些行、哪些列、什么顺序”再选择对应的方法。单表实例就是训练这个思维最好的沙盒没有复杂的 join 干扰没有外键链式加载的问题你只需要关心一张表上的行为这时候最容易把 QuerySet 的懒加载、缓存、求值时机看得一清二楚。1.2 单表操作占了业务里八成以上我拆过几个中等体量的后台项目里面有用户表、文章表、分类表、订单表、日志表翻来覆去的高频操作就是按条件过滤、排序、分页、统计数量、更新某个字段。这些基本都是单表操作顶多加一两个外键字段用于列表展示。真正需要三表以上 join 的场景反而少之又少。所以把单表实例吃透等于解决了日常开发里大部分数据库问题。比如一个文章列表页无非是Article.objects.filter(statuspublished).order_by(-published_at)再加个分页一个统计接口无非是aggregate(Count(...))或者annotate(...)。这些动作如果每次都是靠“百度出代码然后复制”你永远不知道它背后怎么工作。但当你能独立设计一个单表模型并且通过 ORM 完成全部增删改查、迁移、测试之后再遇到复杂需求至少知道问题可能出在哪一层。2. 从零定义一个能上线的单表模型字段选型与迁移过程模型定义是所有 ORM 操作的起点。字段选型直接影响数据库存储、查询效率和后续扩展。很多人图省事清一色CharField连数字和时间都用字符串存最后排序、比较、统计全成了灾难。这一章我直接用最常见的“文章表”作为例子把字段设计和迁移流程完整走一遍。2.1 一个可以直接用的 Article 模型假设我们要做一个博客后台文章表需要存标题、唯一标识 slug、正文、状态、浏览量、创建时间、更新时间。我通常会这样定义from django.db import models class Article(models.Model): title models.CharField(max_length200) slug models.SlugField(max_length220, uniqueTrue) content models.TextField() status models.CharField( max_length10, choices[(draft, 草稿), (published, 已发布)], defaultdraft, ) views models.PositiveIntegerField(default0) created_at models.DateTimeField(auto_now_addTrue) updated_at models.DateTimeField(auto_nowTrue) class Meta: ordering [-created_at] indexes [ models.Index(fields[status, created_at]), ] def __str__(self): return self.title这里有几个细节值得展开说一说。CharField的max_length是必填参数它不仅是 Django 层面的校验也会映射成数据库里的varchar(n)不同数据库对长度的处理不同比如 MySQL 里varchar(200)可能还会涉及索引长度限制。SlugField其实是对CharField的封装加了uniqueTrue可以保证每个文章的访问路径唯一同时数据库会自动建唯一索引。TextField对应数据库的text类型适合存大段内容不要拿来存短字符串排序和过滤时数据库对 text 类型的支持往往不如 varchar 方便。auto_now_add和auto_now是新手最容易搞混的一对。auto_now_addTrue只在对象第一次创建时写入当前时间之后 save() 不会更新它auto_nowTrue则在每次 save() 时自动更新为当前时间。这两个都会把字段设置成editableFalse也就是说在 admin 表单里看不到也不应该手工赋值。我见过有人为了“兼容”在视图里手动给created_at传时间结果发现永远不生效其实就是没弄清楚这两个参数由 ORM 接管了。2.2 迁移如何变成数据库表结构模型定义好之后Django 不会自动建表需要两步操作python manage.py makemigrations python manage.py migratemakemigrations会在应用的migrations目录下生成一个新的迁移文件里面记录了模型层面的改动比如创建表、加字段、改字段类型。migrate才真正把改动同步到数据库。很多人都卡在“我明明定义了模型为什么查询时报 no such table”原因就是只做了makemigrations忘了migrate或者压根没做第一步。迁移文件是文本文件在 SQLite、MySQL、PostgreSQL 之间表现会有差异。以 SQLite 为例上面的模型大致会被翻译成类似这样的建表语句CREATE TABLE app_article ( id integer NOT NULL PRIMARY KEY AUTOINCREMENT, title varchar(200) NOT NULL, slug varchar(220) NOT NULL UNIQUE, content text NOT NULL, status varchar(10) NOT NULL, views integer NOT NULL, created_at datetime NOT NULL, updated_at datetime NOT NULL ); CREATE INDEX app_article_status_created_at_idx ON app_article (status, created_at);注意 Django 默认会给表名加上应用名前缀比如应用名是blog表名就是blog_article。如果你不喜欢这种命名可以在Meta里用db_table my_article_table指定。但我的建议是除非有明确的遗留系统对接需求否则别改表名默认命名反而能避免跨应用重名。字段映射方面BooleanField在 MySQL 里是boolIntegerField是intFloatField对应double。这些常规映射大家都不容易错真正容易出问题的是DecimalField它必须指定max_digits和decimal_places否则makemigrations会直接报错因为它不知道要建多长的 DECIMAL 类型。3. 单表增删改查的“肌肉记忆”QuerySet 实操要点单表操作说到底就是增删改查但 Django ORM 的写法细节能决定代码是简洁还是啰嗦是高效还是低效。这一章我按创建更新、查询、分页聚合三个维度来拆全程用上面这个 Article 模型。3.1 创建和更新save() 与 create() 不是一回事创建单条记录有两种常见写法# 方式一 article Article(title标题, slugtitle-slug, content正文) article.save() # 方式二 article Article.objects.create(title标题, slugtitle-slug, content正文)create()内部也是先实例化对象再调用save()但它返回的是刚创建的对象并且代码更紧凑。需要强调的是create()会立即执行 INSERT 语句而先实例化再save()也会立即执行不存在“延迟”的说法。如果你需要批量创建应该用bulk_create()那是另一套机制会构造一次批量 INSERT性能提升明显。更新记录时同样有两种路径# 先取出对象再改字段 article Article.objects.get(id1) article.title 新标题 article.save() # 直接用 QuerySet.update() 批量更新 Article.objects.filter(id1).update(title新标题)第一种方式走的是 ORM 的完整流程读出原数据、内存中修改、save 时生成 UPDATE 语句。第二种方式直接用 SQL 层的 UPDATE不会触发模型里的save()方法也不会更新auto_now字段。如果你正好需要更新updated_at那用update()会漏掉这个字段。反过来如果你只是批量置一个状态不需要改时间update()会更高效。update_or_create是另一个高频工具适合“存在就更新不存在就创建”的场景obj, created Article.objects.update_or_create( slugtitle-slug, defaults{title: 新标题, content: 新内容}, )这里slug是用于匹配的唯一键defaults里是其他要写入的字段。返回值obj是对象created是布尔值表示是否新建。这个方法背后其实是先查一次再决定 INSERT 还是 UPDATE所以并发场景下可能会遇到唯一键冲突需要结合get_or_create和异常处理来兜底。3.2 查询组合拳filter、order_by、values、annotate查询是 ORM 的重头戏。先记住一个核心概念QuerySet 是懒加载的。写Article.objects.filter(statuspublished)时并不会立刻查数据库真正执行 SQL 是在你开始迭代、切片、调用list()、count()、exists()等操作时。# 链式过滤 articles Article.objects.filter(statuspublished) articles articles.filter(views__gte100) articles articles.order_by(-created_at) # 切片也会触发查询相当于 SQL 里的 LIMIT page_articles articles[:10]链式调用的过程不断返回新的 QuerySet你可以按条件分支构建不同的结果但要注意缓存问题。同一个 QuerySet 如果先遍历一次再调用count()第二次不会重新查数据库而是使用缓存结果。这有时很方便但如果你在两次遍历之间数据发生了变化可能拿到的是旧结果。需要最新数据时可以调用.all()重新求值或者不要复用同一个 QuerySet 变量。# 只取指定字段返回字典 Article.objects.filter(statuspublished).values(id, title) # 返回元组列表适合给 select 框用 Article.objects.filter(statuspublished).values_list(id, title)values()和values_list()能把 ORM 查询结果从模型对象变成轻量数据结构在写接口时很常用。但要留意一旦用了values()后面就不能再按模型对象的属性去访问了。更关键的是它并不会自动帮你优化查询只是减少 Python 层面的对象封装SQL 层面仍然可能 SELECT 了所有列除非你配合only()或defer()。annotate()是给 QuerySet 添加“聚合出来的字段”经常和分组一起出现。比如统计每个状态下的文章数量from django.db.models import Count Article.objects.values(status).annotate(totalCount(id))这句代码几乎所有 Django 面试都会考。它先按status分组然后生成一个total字段。有人会困惑为什么不直接用aggregate()因为aggregate()返回的是单个汇总值不分组annotate()返回的是 QuerySet每一行都带上了汇总结果。单表场景里按某个分类字段计数、求和、平均都是annotate的典型用途。3.3 分页与聚合单表场景的两个高频需求分页最标准的做法是使用 Django 内置的Paginatorfrom django.core.paginator import Paginator articles Article.objects.filter(statuspublished).order_by(-created_at) paginator Paginator(articles, 10) # 每页 10 条 page_obj paginator.get_page(request.GET.get(page))Paginator会先执行一次count()获取总条数再根据当前页数计算 offset。单表场景下这个 count 通常走主键或普通索引性能还行。但如果数据量到了百万级单纯的count()也会慢很多项目会额外维护一个计数缓存或者改用按游标分页。聚合方面除了之前的Count还有Sum、Avg、Max、Min。比如博客后台想统计所有文章的总浏览量from django.db.models import Sum total_views Article.objects.aggregate(totalSum(views))返回结果是一个字典{total: 12345}如果没有任何记录Sum会返回None而不是 0所以在模板里使用时要注意默认值。也可以用Coalesce把None转成 0但这在简单单表场景里通常没必要视图层判断一下即可。4. 别把单表逻辑全堆在视图里自定义 Manager 与模型能力很多初学者会把所有查询逻辑写在视图函数里一个列表页里塞四五个 filter视图变得越来越肿。实际上单表模型的业务逻辑完全可以下沉到模型层利用 Manager 和模型方法让代码更干净也更好测试。4.1 自定义 Manager 让业务语义下沉Manager 是 Django 模型默认的数据访问入口Article.objects就是默认 Manager。你可以通过自定义 Manager 封装常用的查询条件比如“所有已发布的文章”这个逻辑如果每个视图都写一遍filter(statuspublished)一旦状态值变了就要全局搜索替换。更优雅的方式是这样的class PublishedManager(models.Manager): def get_queryset(self): return super().get_queryset().filter(statuspublished) class Article(models.Model): # ... objects models.Manager() # 保留默认 Manager published PublishedManager()用法变成Article.published.all()语义非常清楚。这里有个细节如果自定义了 Manager并且没有把默认 Manager 赋给objects那么 Django 会把第一个出现的 Manager 作为默认 Manager。所以最好显式保留objects models.Manager()避免第三方库行为异常。有人担心自定义 Manager 会不会导致后门比如后台需要看草稿文章就用Article.objects.filter(statusdraft)因为默认 Manager 还在。这种“默认查询全部业务 Manager 封装常用过滤”的模式在单表单场景很实用。4.2 模型方法、property 和 get_absolute_url模型上除了 Manager还可以定义普通方法和property用来封装针对某个对象的行为。比如 Article 需要一个“摘要”方法class Article(models.Model): # ... property def summary(self): if len(self.content) 50: return self.content[:50] ... return self.content def get_absolute_url(self): return f/articles/{self.slug}/property的好处是调用时不带括号模板里写{{ article.summary }}即可。get_absolute_url是 Django 的习惯用法后台管理、模板里的链接、重定向都能用它避免 URL 硬编码散落各处。这些方法并不会生成额外的 SQL 查询它们只是在 Python 对象上做计算所以可以放心使用。4.3 Meta 里的讲究ordering、db_table、indexesMeta内部类是很多人容易忽略的部分但它对数据库行为的影响很大。ordering指定默认排序class Meta: ordering [-created_at]设置了ordering后Article.objects.all()会自带排序很多场景确实省事。但它也有坑如果你在某个查询里特意写了order_by(title)它会覆盖默认排序如果没写默认排序会应用到所有查询包括关联查询里的子查询性能上未必好。所以我个人建议全局默认排序只在“绝大多数情况都要这个顺序”时设置否则宁可每次显式order_by让 SQL 意图更明确。db_table可以指定表名indexes可以定义联合索引。单表模型最常用的联合索引是“过滤字段 排序字段”比如文章管理页经常按状态过滤、按创建时间降序排列那么status和created_at的联合索引就很有用。索引不是越多越好每个索引都会拖慢写入速度单表实例里我一般只给真正高频的查询组合建索引。5. 单表最容易踩的坑从迁移报错到更新覆盖实操中犯过的错比文档里的知识值钱得多。这一章聊几个我在单表实例上踩过、也帮别人解决过的坑每一个都是真实场景。5.1 no such table 与“字段认不出来”的真凶最常见的第一反应是“模型没问题啊为什么一查就报错”。如果你遇到OperationalError: no such table: app_article先检查三步应用是否注册到INSTALLED_APPS迁移文件是否生成是否执行过 migrate。很多时候是新建应用后忘了把应用名加进INSTALLED_APPSmakemigrations会提示“没有检测到更改”数据库自然没有表。另一种情况是改了模型字段后在视图里直接用了新字段结果报OperationalError: no such column: app_article.new_field。这通常是因为迁移没有应用。记住一个操作顺序先makemigrations再migrate然后重启开发服务器。不要相信“改了模型自动生效”这种错觉Django 从设计上就强制你走迁移流程这是为了保持数据库结构可控。5.2 只取必要字段defer、only 与 values_list 怎么选有些大字段比如TextField的内容可能占几 KB如果你只需要文章列表的标题和发布时间默认Article.objects.all()会把整行所有字段都 SELECT 出来。在 SQLite 里还不明显在 MySQL 里如果表宽、行数多会造成不必要的 IO。Django 提供only()和defer()来控制字段加载# 只加载 title 和 created_at其他字段在访问时才查 Article.objects.only(title, created_at) # 延迟加载 content访问 content 时才查 Article.objects.defer(content)用only()时要注意如果只指定了少数字段后续访问未指定的字段会触发额外查询。也就是说only()可能制造 N1 查询。所以它适合“确定只需要这些字段”的列表接口。values_list()直接返回元组没有对象封装内存占用更小但代价是丢失了模型方法。三者的选择逻辑很简单要模型对象和模型方法用only()只要简单数据做序列化用values_list()既想要对象又想尽量少查大字段用defer()。5.3 save() 覆盖字段的坑用 F 表达式和 update 来解这是一档高并发场景最容易踩的坑。假设要统计浏览量有人会这样写article Article.objects.get(id1) article.views 1 article.save()看起来没问题但两个请求同时执行时后保存的请求会覆盖先保存的结果。因为流程都是“先读出旧值在 Python 里加 1再整体 UPDATE”最终浏览量可能只加了 1而不是 2。正确的做法是用数据库层面的原子操作from django.db.models import F Article.objects.filter(id1).update(viewsF(views) 1)F(views)会生成 SQL 里的views views 1这个更新由数据库执行天然避免了并发覆盖。同理给所有文章加一个固定值、按某个表达式更新字段都用 F 表达式。save()方法适合修改当前对象已知值不适合“读改写”这种复合操作。另外还要注意save()默认更新所有字段不是只更新你修改的那个字段。即使你只改了title生成的 UPDATE 也会带上整行所有列。想只更新指定字段可以给save()传update_fieldsarticle.save(update_fields[title])这不仅能减少 SQL 体积还能避免并发场景下意外覆盖其他字段。5.4 迁移交互给非空字段加默认值的那点事给已有数据的表添加非空字段时Django 会要求你提供默认值或者让你在迁移中给出一次性默认值。比如给 Article 加一个is_featured models.BooleanField(defaultFalse)这在本地没问题。但如果在生产环境有大量历史数据迁移过程可能会锁表。更稳妥的做法是分几步先加允许为空的字段再写一个数据迁移脚本填充默认值最后修改字段为不可空。单表实例不一定每个项目都要这么做但如果你带着线上数据跑迁移这个顺序值得记住。还有一个常见反例字段类型修改。比如把status从CharField(max_length10)改成IntegerField(choices[...])Django 会生成 ALTER TABLE 语句。在 SQLite 上对已有数据的类型转换支持有限可能报错或需要重建表。所以字段类型定义尽量想清楚上线后宁可新增字段也别频繁改类型。6. 测试中的单表数据准备TestCase 里少走弯路ORM 代码写多了测试就成了守护网。Django 的测试框架对数据库做了隔离每个测试用例都会在独立事务里跑但具体怎么写数据准备还是有讲究的。6.1 setUpTestData 比 setUp 更适合准备单表数据setUp()是每个测试方法执行前都会调用如果测试类里方法很多数据会被反复创建拖慢整个测试速度。setUpTestData是在类级别一次性创建数据所有测试方法共享速度会快很多。单表模型没有外键关联数据准备逻辑简单更适合用setUpTestDatafrom django.test import TestCase class ArticleModelTests(TestCase): classmethod def setUpTestData(cls): Article.objects.create( title测试文章, slugtest-article, content正文, statuspublished, views5, ) def test_views_default(self): # 拿不到具体对象时就从数据库里取回来再断言 article Article.objects.get(slugtest-article) self.assertEqual(article.views, 5) def test_published_manager(self): self.assertEqual(Article.published.count(), 1)注意一个坑setUpTestData里创建的Article.objects.create()是一个持久化对象但测试方法里如果修改了它比如article.views 100; article.save()之后的其他测试方法再访问这个共享对象时可能会看到被污染的数据。所以在测试方法内部尽量别去修改共享对象或者每次查询数据库取新实例。6.2 用 assertQuerySetEqual 验证查询结果Django 专门提供了针对 QuerySet 的断言方法比assertEqual(list(qs), [...])更直观也更符合数据库查询的语义。例如def test_filter_by_status(self): Article.objects.create( title草稿文章, slugdraft-article, statusdraft ) published Article.published.all() self.assertQuerySetEqual( published, [测试文章], transformlambda a: a.title, )transform参数会把 QuerySet 里的每个对象映射成我们要比较的值这样不用手动把对象列表转成标题列表断言失败时的错误信息也更清楚。如果你的查询结果用了values_list()可以直接拿列表比较但要注意顺序和类型。写测试不是走形式而是把 ORM 行为固化下来。尤其当你重构 Manager 或改动过滤条件时一套单表测试能让你放心地改代码。我在实际项目里的一个习惯是遇到任何不确定的 ORM 行为先开 Django shell 跑一遍打印str(queryset.query)看看生成的 SQL再决定要不要写测试。Django ORM 单表实例看似简单但正是这些最基础的操作决定了你的代码在数据量增长之后是依然流畅还是变成一堆慢查询。把这些细节练成肌肉记忆比背多少高级技巧都有用。
