Django模型迁移指南：从命令用法到最佳实践

Django 的模型迁移（Migration）系统是管理数据库结构变更的核心工具。无论是初学者还是资深开发者，掌握迁移的正确用法都能大幅提升开发效率，避免数据丢失或结构错乱。本文将从基础命令入手，逐步深入到高级技巧与最佳实践，帮助你全面掌握 Django 迁移。### 1. 迁移基础：理解核心概念在 Django 中，迁移是 Python 文件，记录了模型（Model）的变更历史。每当你修改模型（如新增字段、删除表），Django 会生成一个迁移文件，随后通过命令将其应用到数据库。这一机制让团队协作和版本控制变得简单，因为数据库结构变更可以像代码一样被审查和回滚。核心命令速览 ：- python manage.py makemigrations：根据模型变化生成迁移文件（不直接修改数据库）。- python manage.py migrate：将迁移文件应用到数据库。- python manage.py showmigrations：查看迁移状态（哪些已应用、哪些待应用）。- python manage.py sqlmigrate <app_label> <migration_name>：预览迁移对应的 SQL 语句。### 2. 第一步：创建并应用你的第一个迁移假设你有一个博客应用，初始模型如下：python# blog/models.pyfrom django.db import modelsclass Article(models.Model): title = models.CharField(max_length=200) content = models.TextField() pub_date = models.DateTimeField(auto_now_add=True)现在，生成并应用迁移：bash# 1. 生成迁移文件（会在 blog/migrations/ 下创建 0001_initial.py）python manage.py makemigrations# 2. 应用迁移到数据库（创建 article 表）python manage.py migrate验证：运行 python manage.py showmigrations，你会看到 [X] 0001_initial，表示已应用。此时数据库已包含 blog_article 表。### 3. 进阶操作：修改模型和迁移的迭代开发中，模型常需调整。例如，给 Article 添加一个 slug 字段，并设置唯一约束：python# blog/models.py 修改后class Article(models.Model): title = models.CharField(max_length=200) slug = models.SlugField(unique=True) # 新增字段 content = models.TextField() pub_date = models.DateTimeField(auto_now_add=True)执行以下命令：bashpython manage.py makemigrations # 生成 0002_article_slug.pypython manage.py migrate # 应用该迁移注意：如果表中已有数据，新增非空字段会报错。此时可设置 default 或 null=True，或分步操作（先添加可空字段，再数据填充，最后修改约束）。### 4. 高级用法：数据迁移和自定义操作有时，你需要对现有数据执行一次性操作（如填充 slug 值）。这需要编写数据迁移 （Data Migration）。示例：为已有文章生成基于标题的 slug。bashpython manage.py makemigrations --empty blog -n populate_slug这会生成一个空迁移文件，然后手动编辑：python# blog/migrations/0003_populate_slug.pyfrom django.db import migrationsfrom django.utils.text import slugifydef populate_slug(apps, schema_editor): Article = apps.get_model('blog', 'Article') for article in Article.objects.all(): article.slug = slugify(article.title) article.save()class Migration(migrations.Migration): dependencies = [ ('blog', '0002_article_slug'), ] operations = [ migrations.RunPython(populate_slug), # 执行数据填充 ]然后运行 python manage.py migrate。注意：数据迁移中应使用 apps.get_model 而非直接导入模型，以保证迁移历史的一致性。### 5. 最佳实践：避免常见陷阱#### 5.1 始终使用版本控制迁移文件是代码的一部分，应提交到 Git。不要手动删除或修改已应用的迁移文件，否则会导致环境不一致。#### 5.2 合并迁移以保持简洁当项目长时间开发后，迁移文件可能膨胀。可使用 python manage.py squashmigrations blog 0003 将 0001~0003 压缩成一个迁移，但请谨慎操作，并确保团队同步。#### 5.3 谨慎处理依赖关系当多个应用相互依赖时，迁移文件会自动记录依赖。避免循环依赖，必要时使用 migrations.AlterModelOptions 等操作调整。#### 5.4 使用 --dry-run 预览变更在关键环境（如生产）前，使用 python manage.py makemigrations --check --dry-run 来检查是否有未生成的迁移，避免遗漏。#### 5.5 反向迁移（回滚）如果迁移出错，可回滚到上一个版本：python manage.py migrate blog 0002。但注意，如果迁移涉及删除字段或表，数据会丢失，务必备份。### 6. 完整示例：从零到部署的迁移流程下面是一个更完整的示例，包含模型、迁移以及数据操作：python# myapp/models.pyfrom django.db import modelsclass Product(models.Model): name = models.CharField(max_length=100) price = models.DecimalField(max_digits=10, decimal_places=2) stock = models.IntegerField(default=0) def __str__(self): return self.name生成并应用初始迁移 ：bashpython manage.py makemigrations myapppython manage.py migrate添加一个 is_active 字段并设置默认值 ：python# 修改模型class Product(models.Model): name = models.CharField(max_length=100) price = models.DecimalField(max_digits=10, decimal_places=2) stock = models.IntegerField(default=0) is_active = models.BooleanField(default=True) # 新增``````bashpython manage.py makemigrations myapppython manage.py migrate如果需要在迁移中执行 SQL 修改（例如，设置数据库级约束），可以使用 migrations.RunSQL：python# 生成空迁移后编辑operations = [ migrations.RunSQL( sql="ALTER TABLE myapp_product ADD COLUMN code VARCHAR(20) UNIQUE;", reverse_sql="ALTER TABLE myapp_product DROP COLUMN code;" ),]这展示了如何将原生 SQL 嵌入迁移，但推荐优先使用 Django 的字段选项，以保证跨数据库兼容性。### 7. 总结Django 迁移系统是开发中不可或缺的工具，它让数据库结构管理变得可追踪、可协作和可回滚。通过掌握基础命令、理解迁移文件结构、编写数据迁移以及遵守最佳实践，你就能高效地管理模型演进，避免生产事故。记住：迁移文件是团队资产，保持其清晰、可读，并始终与代码同步。在实际项目中，多测试迁移的回滚操作，并定期整理迁移历史，这样你的 Django 项目将更加健壮。