1. 为什么选择NPOI.Mapper处理Excel
在.NET Core项目中处理Excel文件时，原生NPOI虽然功能强大，但需要手动处理单元格、样式等细节，代码量较大。而NPOI.Mapper作为其增强封装，通过属性标记和流式处理，能用更简洁的代码实现数据映射。实测下来，相同功能的导出代码能从50行缩减到10行以内，且支持动态列名映射、多Sheet操作等实用特性。
举个例子，传统NPOI导出用户列表需要逐行创建单元格：
// 传统NPOI写法 var row = sheet.CreateRow(0); row.CreateCell(0).SetCellValue("用户名"); row.CreateCell(1).SetCellValue(user.Name);而使用NPOI.Mapper只需定义模型属性：
public class User { [Column("用户名")] public string Name { get; set; } } var mapper = new Mapper(); mapper.Save("users.xlsx", userList);2. 快速配置开发环境
2.1 安装必要组件
通过NuGet安装核心包：
dotnet add package NPOI.Mapper --version 3.5.1 dotnet add package NPOI --version 2.6.0这两个包分别提供：
- NPOI.Mapper：核心映射功能
- NPOI：基础Excel操作支持
2.2 基础模型定义
以学生信息表为例，演示属性标记的两种方式：
方式1：Attribute标注
public class Student { [Column("学号")] public int Id { get; set; } [Column("姓名")] public string Name { get; set; } }方式2：Fluent API配置
var mapper = new Mapper(); mapper.Map<Student>("学号", s => s.Id) .Map<Student>("姓名", s => s.Name);3. 高效导出Excel实战
3.1 基础导出流程
典型WebAPI中的导出示例：
[HttpGet("export")] public IActionResult Export() { var data = _studentService.GetAll(); var mapper = new Mapper(); var stream = new MemoryStream(); mapper.Save(stream, data, "学生列表"); return File(stream.ToArray(), "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "students.xlsx"); }3.2 高级导出技巧
多Sheet导出：
mapper.Put(data1, "Sheet1", true); mapper.Put(data2, "Sheet2", true); mapper.Save("multi.xlsx");动态列控制：
// 忽略属性 [Ignore] public string TempField { get; set; } // 条件导出 mapper.Format<Student>("yyyy-MM-dd", s => s.BirthDate);4. 智能导入数据方案
4.1 基础数据导入
处理上传文件的典型代码：
[HttpPost("import")] public ActionResult Import(IFormFile file) { using var stream = file.OpenReadStream(); var mapper = new Mapper(stream); var results = mapper.Take<Student>().ToList(); var successCount = _studentService.BulkInsert( results.Select(r => r.Value) ); return Ok($"成功导入{successCount}条数据"); }4.2 异常处理机制
NPOI.Mapper会自动捕获转换异常：
foreach (var row in mapper.Take<Student>()) { if (row.ErrorColumnIndex >= 0) { _logger.Warning($"第{row.RowNumber}行{row.ErrorColumnName}列数据格式错误"); continue; } validData.Add(row.Value); }5. 性能优化实践
5.1 内存管理技巧
处理大文件时建议使用文件流而非内存流：
// 推荐做法 using var fileStream = new FileStream("large.xlsx", FileMode.Open); var mapper = new Mapper(fileStream);5.2 批量操作建议
- 导入时使用EF Core的
AddRangeAsync替代单条插入 - 导出超过10万行数据时建议分多个Sheet存储
- 设置
FirstRowIndex跳过表头行提升解析速度
// 批量插入优化 await _context.BulkInsertAsync(data, batchSize: 1000);6. 实际开发中的坑与解决方案
日期格式问题：Excel中的日期可能被解析为数字或错误格式，建议统一处理：
[Column("生日", CustomFormat = "yyyy-MM-dd")] public DateTime BirthDate { get; set; }动态类型支持：当不想定义实体类时：
var dynamicData = mapper.Take<dynamic>().Select(r => { return new { Name = r.Value.姓名, Age = int.Parse(r.Value.年龄) }; });流关闭问题：NPOI会自动关闭输入流，需要复制流后再处理：
var ms = new MemoryStream(); excelFile.CopyTo(ms); ms.Position = 0; // 关键重置位置我在最近的一个项目中处理5万条数据导出时，最初使用原生NPOI需要约8秒，改用NPOI.Mapper配合异步流后降至3秒。对于需要复杂样式的场景，可以混合使用原生NPOI的样式API和Mapper的映射功能，兼顾开发效率与灵活性。
