说起 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(status='published').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_length=200) slug = models.SlugField(max_length=220, unique=True) content = models.TextField() status = models.CharField( max_length=10, choices=[('draft', '草稿'), ('published', '已发布')], default='draft', ) views = models.PositiveIntegerField(default=0) created_at = models.DateTimeField(auto_now_add=True) updated_at = models.DateTimeField(auto_now=True) 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的封装，加了unique=True可以保证每个文章的访问路径唯一，同时数据库会自动建唯一索引。TextField对应数据库的text类型，适合存大段内容，不要拿来存短字符串，排序和过滤时数据库对 text 类型的支持往往不如 varchar 方便。
auto_now_add和auto_now是新手最容易搞混的一对。auto_now_add=True只在对象第一次创建时写入当前时间，之后 save() 不会更新它；auto_now=True则在每次 save() 时自动更新为当前时间。这两个都会把字段设置成editable=False，也就是说在 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 里是bool，IntegerField是int，FloatField对应double。这些常规映射大家都不容易错，真正容易出问题的是DecimalField，它必须指定max_digits和decimal_places，否则makemigrations会直接报错，因为它不知道要建多长的 DECIMAL 类型。
3. 单表增删改查的“肌肉记忆”：QuerySet 实操要点
单表操作说到底就是增删改查，但 Django ORM 的写法细节能决定代码是简洁还是啰嗦，是高效还是低效。这一章我按创建更新、查询、分页聚合三个维度来拆，全程用上面这个 Article 模型。
3.1 创建和更新：save() 与 create() 不是一回事
创建单条记录有两种常见写法：
# 方式一 article = Article(title='标题', slug='title-slug', content='正文') article.save() # 方式二 article = Article.objects.create(title='标题', slug='title-slug', content='正文')create()内部也是先实例化对象再调用save()，但它返回的是刚创建的对象，并且代码更紧凑。需要强调的是：create()会立即执行 INSERT 语句，而先实例化再save()也会立即执行，不存在“延迟”的说法。如果你需要批量创建，应该用bulk_create()，那是另一套机制，会构造一次批量 INSERT，性能提升明显。
更新记录时，同样有两种路径：
# 先取出对象再改字段 article = Article.objects.get(id=1) article.title = '新标题' article.save() # 直接用 QuerySet.update() 批量更新 Article.objects.filter(id=1).update(title='新标题')第一种方式走的是 ORM 的完整流程：读出原数据、内存中修改、save 时生成 UPDATE 语句。第二种方式直接用 SQL 层的 UPDATE，不会触发模型里的save()方法，也不会更新auto_now字段。如果你正好需要更新updated_at，那用update()会漏掉这个字段。反过来，如果你只是批量置一个状态，不需要改时间，update()会更高效。
update_or_create是另一个高频工具，适合“存在就更新，不存在就创建”的场景：
obj, created = Article.objects.update_or_create( slug='title-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(status='published')时并不会立刻查数据库，真正执行 SQL 是在你开始迭代、切片、调用list()、count()、exists()等操作时。
# 链式过滤 articles = Article.objects.filter(status='published') articles = articles.filter(views__gte=100) articles = articles.order_by('-created_at') # 切片也会触发查询，相当于 SQL 里的 LIMIT page_articles = articles[:10]链式调用的过程不断返回新的 QuerySet，你可以按条件分支构建不同的结果，但要注意缓存问题。同一个 QuerySet 如果先遍历一次，再调用count()，第二次不会重新查数据库，而是使用缓存结果。这有时很方便，但如果你在两次遍历之间数据发生了变化，可能拿到的是旧结果。需要最新数据时，可以调用.all()重新求值，或者不要复用同一个 QuerySet 变量。
# 只取指定字段，返回字典 Article.objects.filter(status='published').values('id', 'title') # 返回元组列表，适合给 select 框用 Article.objects.filter(status='published').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(total=Count('id'))这句代码几乎所有 Django 面试都会考。它先按status分组，然后生成一个total字段。有人会困惑为什么不直接用aggregate()，因为aggregate()返回的是单个汇总值，不分组；annotate()返回的是 QuerySet，每一行都带上了汇总结果。单表场景里，按某个分类字段计数、求和、平均，都是annotate的典型用途。
3.3 分页与聚合：单表场景的两个高频需求
分页最标准的做法是使用 Django 内置的Paginator：
from django.core.paginator import Paginator articles = Article.objects.filter(status='published').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(total=Sum('views'))返回结果是一个字典：{'total': 12345}，如果没有任何记录，Sum会返回None而不是 0，所以在模板里使用时要注意默认值。也可以用Coalesce把None转成 0，但这在简单单表场景里通常没必要，视图层判断一下即可。
4. 别把单表逻辑全堆在视图里：自定义 Manager 与模型能力
很多初学者会把所有查询逻辑写在视图函数里，一个列表页里塞四五个 filter，视图变得越来越肿。实际上单表模型的业务逻辑完全可以下沉到模型层，利用 Manager 和模型方法，让代码更干净，也更好测试。
4.1 自定义 Manager 让业务语义下沉
Manager 是 Django 模型默认的数据访问入口，Article.objects就是默认 Manager。你可以通过自定义 Manager 封装常用的查询条件，比如“所有已发布的文章”这个逻辑，如果每个视图都写一遍filter(status='published')，一旦状态值变了，就要全局搜索替换。更优雅的方式是这样的：
class PublishedManager(models.Manager): def get_queryset(self): return super().get_queryset().filter(status='published') 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(status='draft')，因为默认 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、indexes
Meta内部类是很多人容易忽略的部分，但它对数据库行为的影响很大。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_APPS，makemigrations会提示“没有检测到更改”，数据库自然没有表。
另一种情况是改了模型字段后，在视图里直接用了新字段，结果报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()可能制造 N+1 查询。所以它适合“确定只需要这些字段”的列表接口。values_list()直接返回元组，没有对象封装，内存占用更小，但代价是丢失了模型方法。三者的选择逻辑很简单：要模型对象和模型方法，用only()；只要简单数据做序列化，用values_list()；既想要对象又想尽量少查大字段，用defer()。
5.3 save() 覆盖字段的坑：用 F 表达式和 update 来解
这是一档高并发场景最容易踩的坑。假设要统计浏览量，有人会这样写：
article = Article.objects.get(id=1) article.views += 1 article.save()看起来没问题，但两个请求同时执行时，后保存的请求会覆盖先保存的结果。因为流程都是“先读出旧值，在 Python 里加 1，再整体 UPDATE”，最终浏览量可能只加了 1，而不是 2。正确的做法是用数据库层面的原子操作：
from django.db.models import F Article.objects.filter(id=1).update(views=F('views') + 1)F('views')会生成 SQL 里的views = views + 1，这个更新由数据库执行，天然避免了并发覆盖。同理，给所有文章加一个固定值、按某个表达式更新字段，都用 F 表达式。save()方法适合修改当前对象已知值，不适合“读改写”这种复合操作。
另外还要注意，save()默认更新所有字段，不是只更新你修改的那个字段。即使你只改了title，生成的 UPDATE 也会带上整行所有列。想只更新指定字段，可以给save()传update_fields：
article.save(update_fields=['title'])这不仅能减少 SQL 体积，还能避免并发场景下意外覆盖其他字段。
5.4 迁移交互：给非空字段加默认值的那点事
给已有数据的表添加非空字段时，Django 会要求你提供默认值，或者让你在迁移中给出一次性默认值。比如给 Article 加一个is_featured = models.BooleanField(default=False)，这在本地没问题。但如果在生产环境有大量历史数据，迁移过程可能会锁表。更稳妥的做法是分几步：先加允许为空的字段，再写一个数据迁移脚本填充默认值，最后修改字段为不可空。单表实例不一定每个项目都要这么做，但如果你带着线上数据跑迁移，这个顺序值得记住。
还有一个常见反例：字段类型修改。比如把status从CharField(max_length=10)改成IntegerField(choices=[...])，Django 会生成 ALTER TABLE 语句。在 SQLite 上对已有数据的类型转换支持有限，可能报错或需要重建表。所以字段类型定义尽量想清楚，上线后宁可新增字段，也别频繁改类型。
6. 测试中的单表数据准备：TestCase 里少走弯路
ORM 代码写多了，测试就成了守护网。Django 的测试框架对数据库做了隔离，每个测试用例都会在独立事务里跑，但具体怎么写数据准备，还是有讲究的。
6.1 setUpTestData 比 setUp 更适合准备单表数据
setUp()是每个测试方法执行前都会调用，如果测试类里方法很多，数据会被反复创建，拖慢整个测试速度。setUpTestData是在类级别一次性创建数据，所有测试方法共享，速度会快很多。单表模型没有外键关联，数据准备逻辑简单，更适合用setUpTestData：
from django.test import TestCase class ArticleModelTests(TestCase): @classmethod def setUpTestData(cls): Article.objects.create( title='测试文章', slug='test-article', content='正文', status='published', views=5, ) def test_views_default(self): # 拿不到具体对象时，就从数据库里取回来再断言 article = Article.objects.get(slug='test-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='草稿文章', slug='draft-article', status='draft' ) published = Article.published.all() self.assertQuerySetEqual( published, ['测试文章'], transform=lambda a: a.title, )transform参数会把 QuerySet 里的每个对象映射成我们要比较的值，这样不用手动把对象列表转成标题列表，断言失败时的错误信息也更清楚。如果你的查询结果用了values_list()，可以直接拿列表比较，但要注意顺序和类型。写测试不是走形式，而是把 ORM 行为固化下来。尤其当你重构 Manager 或改动过滤条件时，一套单表测试能让你放心地改代码。
我在实际项目里的一个习惯是，遇到任何不确定的 ORM 行为，先开 Django shell 跑一遍，打印str(queryset.query)看看生成的 SQL，再决定要不要写测试。Django ORM 单表实例看似简单，但正是这些最基础的操作，决定了你的代码在数据量增长之后是依然流畅，还是变成一堆慢查询。把这些细节练成肌肉记忆，比背多少高级技巧都有用。
