【技术教程】django-import-export示例和教程

django-import-export 是目前 Django 生态中最成熟、功能最全面的模型数据导入/导出工具，它最大的设计哲学是：

通过Resource这一声明式桥梁，把“模型字段 ↔ 数据行 ↔ 文件格式”三者之间的转换逻辑完全解耦，并天然深度集成 Django Admin。

1. 核心设计理念与架构（2025 年视角）

一句话总结核心模式：
“Resource 是数据搬运工 + 校验员 + 清洗工”，所有自定义逻辑几乎都写在 Resource 里。

2. 主要使用场景（按频率排序）

1. 后台批量维护（最常见）
   运营/编辑人员通过 Admin 导入 Excel/CSV 批量创建/更新商品、会员、订单备注等

2. 数据迁移 / 上线初始化
   从旧系统、ERP、Excel 迁移历史数据

3. 报表 & 数据交付
   给市场/财务/合作伙伴导出 Excel / CSV 格式的筛选后数据

4. 定时全量/增量备份
   结合管理命令 + cron 每天导出关键表

5. 命令行 ETL 脚本
   数据同步、清洗、格式转换

6. 超大数据量场景（>10万行）
   必须结合 Celery / RQ / django-stomp 等异步方案

3. 完整实战案例：图书馆管理系统（2025 推荐写法）

3.1 项目结构

library/ ├── models.py ├── admin.py ├── resources.py ← 推荐把 Resource 独立出来，便于复用 └── settings.py

3.2 模型（models.py）

fromdjango.dbimportmodelsclassAuthor(models.Model):name=models.CharField(max_length=100,unique=True)nationality=models.CharField(max_length=50,blank=True)def__str__(self):returnself.nameclassBook(models.Model):title=models.CharField(max_length=200)author=models.ForeignKey(Author,on_delete=models.CASCADE,related_name="books")isbn=models.CharField(max_length=13,unique=True,db_index=True)publish_date=models.DateField()price=models.DecimalField(max_digits=8,decimal_places=2,null=True,blank=True)created_at=models.DateTimeField(auto_now_add=True)def__str__(self):returnself.title

3.3 核心：Resource 定义（resources.py）

# library/resources.pyfromimport_exportimportresources,fieldsfromimport_export.widgetsimportForeignKeyWidget,DateWidget,DecimalWidgetfrom.modelsimportBook,AuthorclassBookResource(resources.ModelResource):# --------------- 重点：外键处理 ----------------author=fields.Field(column_name="作者",# Excel/CSV 表头名称（中文也支持）attribute="author",widget=ForeignKeyWidget(Author,"name"),# 通过 name 查找或创建)# 日期格式控制（非常实用）publish_date=fields.Field(column_name="出版日期",attribute="publish_date",widget=DateWidget(format="%Y-%m-%d"),# 支持多种常见日期写法)# 小数处理（防止科学计数法）price=fields.Field(column_name="价格",attribute="price",widget=DecimalWidget(),)classMeta:model=Book# 导出/导入字段及顺序（顺序很重要！）fields=("id","title","author","publish_date","isbn","price",)# 用于判断“是否已存在”的唯一键（更新而非重复创建）import_id_fields=("isbn",)# 跳过完全没变化的行，减少无谓写入skip_unchanged=Truereport_skipped=True# 支持中文表头（2024+ 版本表现更好）export_order=fields# --------------- 常用钩子示例 ----------------defbefore_import_row(self,row,row_result=None,**kwargs):"""清洗数据 - 常用来规范化 ISBN、去除空格等"""if"isbn"inrow:row["isbn"]="".join(cforcinstr(row["isbn"]).strip()ifc.isdigit())# 如果作者名为空，设置为“佚名”ifnotrow.get("作者"):row["作者"]="佚名"defafter_import_row(self,row,row_result,row_id=None,**kwargs):"""导入后额外操作，例如记录日志、发通知等"""ifrow_result.import_type=="new":print(f"新增书籍：{row['title']}")# 自定义导出筛选（常见需求：只导出今年出版的书）defget_export_queryset(self):returnsuper().get_export_queryset().filter(publish_date__year=2025)

3.4 Admin 集成（admin.py）

fromdjango.contribimportadminfromimport_export.adminimportImportExportModelAdmin,ExportActionMixinfrom.modelsimportAuthor,Bookfrom.resourcesimportBookResource@admin.register(Author)classAuthorAdmin(admin.ModelAdmin):list_display=["name","nationality"]search_fields=["name"]@admin.register(Book)classBookAdmin(ImportExportModelAdmin,ExportActionMixin):resource_class=BookResource list_display=["title","author","isbn","publish_date","price"]list_filter=["publish_date","author"]search_fields=["title","isbn","author__name"]# 可选：自定义导出表单（例如增加日期范围筛选）# from import_export.forms import ExportForm# export_form = MyCustomExportForm

完成后，进入/admin/library/book/就能看到醒目的导入/导出按钮。

4. 进阶实用技巧（2025 年高频用法）

5. 总结：什么时候选择 django-import-export？

强烈推荐：

• 需要 Admin 界面操作导入导出
• 数据量 < 10 万行（或配合异步）
• 需要处理外键、多对多、日期、小数等常见类型
• 希望代码声明式、可维护

考虑替代方案：

• 纯 API 导入导出 → drf + pandas / openpyxl
• 超大规模 ETL → Airflow + pandas + SQLAlchemy
• 只导出简单 CSV → 自己写视图 +csv模块