django-import-export 是目前 Django 生态中最成熟、功能最全面的模型数据导入/导出工具，它最大的设计哲学是：
通过Resource这一声明式桥梁，把“模型字段 ↔ 数据行 ↔ 文件格式”三者之间的转换逻辑完全解耦，并天然深度集成 Django Admin。
1. 核心设计理念与架构（2025 年视角）
| 层级 | 组件/概念 | 核心职责 | 是否必须自定义 | 2025 年重要变化/注意点 |
|---|---|---|---|---|
| 数据格式层 | tablib.Dataset | 内存中统一的数据表结构 | 否 | 支持更多格式解析优化 |
| 转换/映射层 | Resource / ModelResource | 字段 ↔ 模型实例 ↔ 数据行 的双向转换 | 是（核心） | 更严格的类型校验 |
| 流程控制层 | ImportMixin / ExportMixin | 提供钩子（before/after/row） | 否/可选 | — |
| Admin 集成层 | ImportExportModelAdmin 等 | 自动添加导入/导出按钮与确认页面 | 否 | 支持自定义导出表单 |
| 异步/大文件层 | django-import-export-celery / stomp / extensions | 把 import/export 任务放入队列 | 视场景 | 推荐 extensions 1.9+ |
一句话总结核心模式：
“Resource 是数据搬运工 + 校验员 + 清洗工”，所有自定义逻辑几乎都写在 Resource 里。
2. 主要使用场景（按频率排序）
后台批量维护（最常见）
运营/编辑人员通过 Admin 导入 Excel/CSV 批量创建/更新商品、会员、订单备注等数据迁移 / 上线初始化
从旧系统、ERP、Excel 迁移历史数据报表 & 数据交付
给市场/财务/合作伙伴导出 Excel / CSV 格式的筛选后数据定时全量/增量备份
结合管理命令 + cron 每天导出关键表命令行 ETL 脚本
数据同步、清洗、格式转换超大数据量场景（>10万行）
必须结合 Celery / RQ / django-stomp 等异步方案
3. 完整实战案例：图书馆管理系统（2025 推荐写法）
3.1 项目结构
library/ ├── models.py ├── admin.py ├── resources.py ← 推荐把 Resource 独立出来，便于复用 └── settings.py3.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.title3.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-extensions≥1.9 |
| 后台异步导入导出 | 使用 celery / stomp 后端 | ImportExportStompModelAdmin |
| 导出自定义筛选条件 | 重写get_export_queryset()或自定义导出表单 | def get_export_queryset(self): ... |
| 多对多字段导出 | 使用ManyToManyWidget或自定义 widget | tags = fields.Field(widget=ManyToManyWidget(...)) |
| 导入时自动创建关联对象 | ForeignKeyWidget默认支持“get_or_create” | — |
| 导出带计算字段 | 定义非模型字段 + dehydrate_xxx 方法 | def dehydrate_full_info(self, obj): ... |
| 命令行批量导入导出 | python manage.py importexport --resource=BookResource books.xlsx | 官方 management command |
5. 总结：什么时候选择 django-import-export？
强烈推荐：
- 需要 Admin 界面操作导入导出
- 数据量 < 10 万行（或配合异步）
- 需要处理外键、多对多、日期、小数等常见类型
- 希望代码声明式、可维护
考虑替代方案：
- 纯 API 导入导出 → drf + pandas / openpyxl
- 超大规模 ETL → Airflow + pandas + SQLAlchemy
- 只导出简单 CSV → 自己写视图 +
csv模块
