1. 文件导入这事儿，远没有想象中简单
在做后台管理系统的时候，文件导入几乎是绕不开的需求：客户名单批量录入、商品SKU批量上架、订单数据迁移、老系统历史数据搬库……表面上看，"接收一个文件，逐行往数据库里写"而已，但真正在 .NET 环境里把这个功能做到生产可用，你会碰到一连串问题：几万行数据导入会不会超时？Excel 里的合并单元格和空行怎么处理？用户传错模板时错误信息怎么说人话？防止重复导入怎么做？这些问题我几乎都在真实项目里踩过一遍。
在 .NET Framework 时代我写过不少导入接口，后来全面切到 .NET Core，再到 .NET 7.0，最大的感受是：跨平台部署、依赖注入、管道式中间件、成熟的异步 I/O，让文件导入这类本职工作就是"读数据、写数据"的功能有了干净得多的实现方式。特别在 .NET 7.0 里，IFormFile的流式处理、Kestrel 的请求体限制配置、配合Minimal API或者传统 Controller 都能写得很顺手。
这篇文章的核心内容就一件事：用 .NET 7.0 Core 实现一个生产可用的文件导入接口。我会从接口设计思路讲起，把文件接收、格式解析、行级校验、错误回执、性能优化这些环节逐一展开，最后把我实际项目里踩过的坑和排查思路一并交代。适合正在用 ASP.NET Core 做管理后台、需要实现批量数据导入的开发者，也适合想系统梳理一下导入流程设计逻辑的朋友参考。
2. 动手编码前，先定三个方向：同步异步、接口契约、解析抽象
很多人写导入接口容易上来就写 Controller 里的SaveChanges()，但等你把代码写完了才发现，当初随便定的决策会卡住后面的扩展。我建议动手前先花半小时想清楚三个方向，这会直接影响整个模块的架构。
2.1 同步导入还是异步导入：先看数据量和用户预期
同步导入最直观：用户上传文件，接口同步解析、校验、写入，最后返回导入结果。适合数据量在几千行以内、单次处理时长几秒内能搞定的场景。比如后台管理员手动导入一份几百行的部门架构表，同步完全没有问题，体验反而好——上传完立刻看到结果。
异步导入适合两种场景：一是文件行数很多，比如一次导入10万行商品数据，全量校验加落库可能要一分多钟，HTTP 请求根本扛不住这么久，前端也会超时；二是导入之后还需要触发一系列后续处理，比如导入完成后通知下游系统、生成统计报表，这些耗时操作不适合塞在请求链路里。
我的经验是：不要一开始就上异步方案，异步会带来任务状态管理、结果查询接口、失败重试机制等一系列额外复杂度。如果当前业务明确是几千行级别，先同步实现，把接口契约设计好，后期要改异步时，把处理逻辑抽到一个独立的ImportService里，Controller 这层只是从"直接调用"变成"丢进任务队列"，改动量完全可控。文档里我说的同步异步之分，本质是"处理逻辑和运输层解耦"，这一点在项目刚开始时就要守住。
2.2 接口契约设计：URL、参数、返回值一次定清楚
导入接口本质上是一个"上传文件 + 返回处理结果"的服务。我习惯这样设计契约：
- 接口地址：
POST /api/import/goods，语义明确，一个资源一种导入业务。 - 入参：
multipart/form-data格式，字段名固定为file，如果有业务相关的附加参数（比如导入到哪个店铺、用什么规则集），用普通 form 字段传。 - 出参：统一的响应结构，包含成功/失败标识、总行数、成功条数、失败条数、错误明细列表。
响应结构用泛型包装，全项目统一，前端对接起来零成本：
public class ApiResult<T> { public bool Success { get; set; } public string Message { get; set; } public T Data { get; set; } public static ApiResult<T> Ok(T data, string message = "ok") => new() { Success = true, Message = message, Data = data }; public static ApiResult<T> Fail(string message) => new() { Success = false, Message = message }; } public class ImportResult { public int TotalCount { get; set; } public int SuccessCount { get; set; } public int FailCount { get; set; } public List<ImportErrorItem> Errors { get; set; } = new(); } public class ImportErrorItem { public int RowIndex { get; set; } // 第几行出错，从1开始，方便用户对照Excel public string Message { get; set; } // 错误描述，要人话 }关于错误码，我的建议是：导入接口的返回值里不带代码级错误码（比如IMPORT_FILE_EMPTY这种枚举），因为前端只需要知道"成功还是失败，失败在哪些行、原因是什么"。过度的错误码设计在这个场景里是自我感动，徒增沟通成本。HTTP 状态码层面，400 表示请求不合法（文件缺失、格式不对、校验不通过），200 表示请求处理完毕（哪怕有部分行失败，也在 200 里返回明细，因为请求本身是成功的）。
2.3 解析层抽象：每种文件格式是一个策略
一个看起来"只有 Excel 导入"的需求，上线之后大概率会冒出"能不能支持 CSV""能不能支持 xls 老格式"。甚至有客户会问"能不能支持我复制的表格直接粘贴"。所以解析层必须抽象。
我通常定义统一的IImportParser接口，输出统一的数据中间结构——一个List<Dictionary<string, string>>，键是列名，值是单元格文本。所有的校验逻辑只依赖这个中间结构，完全不关心文件原始格式是 Excel 还是 CSV：
public interface IImportParser { bool CanHandle(string fileExtension); Task<List<Dictionary<string, string>>> ParseAsync( Stream stream, CancellationToken cancellationToken); }CanHandle用来在运行时按扩展名路由到对应解析器，ParseAsync只负责"把文件内容变成行数据"。列头和单元格约定（比如日期格式、金额字段）提前在模板和文档里和业务方对齐，解析器内部做好容错。
这个抽象的价值在后期才会体现出来：当你要新增一种导入格式时，写一个新解析器，在依赖注入里注册一下，业务校验代码一行都不用改。
3. 核心实现拆解：从文件落地到错误回执
方向定好了，代码实现层面其实是按"接收 -> 解析 -> 校验 -> 落库 -> 回执"这条流水线走。下面每个环节我都会给出实际可用的代码和需要注意的细节。
3.1 文件接收与请求体限制设置
Controller 里接收文件的写法很简单，但生产环境真正要处理的是"限制"问题。没有限制的上传接口，就是给服务器内存埋雷。Kestrel 默认的最大请求体是 30MB，我记得在 .NET 7 里默认值没变，但对导入场景，30MB 已经偏大了，一个 1MB 的 xlsx 解压后可能有几十万行。实际上绝大多数导入场景，10MB 之内足够，除非业务里有人非要传图片塞进 Excel（这种事确实发生过，真实项目里真有人把商品主图塞进 Excel 单元格里）。
我一般这样配置：Controller 层用特性约束单接口，全局配置文件兜底。
[HttpPost("goods")] [RequestSizeLimit(20 * 1024 * 1024)] [RequestFormLimits(MultipartBodyLengthLimit = 20 * 1024 * 1024)] public async Task<IActionResult> ImportGoods( [FromForm] IFormFile file, [FromForm] long? tenantId, CancellationToken ct) { if (file == null || file.Length == 0) return BadRequest(ApiResult<ImportResult>.Fail("请选择要上传的文件")); var extension = Path.GetExtension(file.FileName).ToLowerInvariant(); if (!_allowedExtensions.Contains(extension)) return BadRequest(ApiResult<ImportResult>.Fail($"不支持的文件类型：{extension}")); // ... 后续处理 }注意CancellationToken要从请求管道传入到后续所有异步方法里。连接断开、用户取消上传时，token 会触发取消，避免服务端傻傻地继续跑完整个导入流程，浪费 CPU 和内存。
全局层面的配置在Program.cs里做：
builder.Services.Configure<FormOptions>(options => { options.MultipartBodyLengthLimit = 20 * 1024 * 1024; }); builder.WebHost.ConfigureKestrel(options => { options.Limits.MaxRequestBodySize = 20 * 1024 * 1024; });MultipartBodyLengthLimit管的是表单整体大小，MaxRequestBodySize管的是请求体上限，两者都要设，否则其中一个默认值会成为隐藏的天花板。这里踩过一次坑：只改了 Kestrel 的MaxRequestBodySize，部署到 IIS 反向代理场景时又超限了，后来排查发现是 IIS 的maxAllowedContentLength（默认 30MB）在起作用。生产环境如果前面挂着 Nginx 或 IIS，反向代理层的请求体限制也要一起查，三层限制任何一层没放开，都会表现为"上传一段时间后连接被重置"。
3.2 CSV 与 Excel 的解析实现
解析这一步最能体现库选型的差异。
CSV 解析：不要用string.Split(',')，CSV 规范里字段内可能出现逗号（比如地址"北京市,朝阳区"），还可能带引号转义。无脑 Split 碰到这类数据就是灾难。老老实实用CsvHelper，NuGet 直接装：
dotnet add package CsvHelperpublic class CsvParser : IImportParser { public bool CanHandle(string fileExtension) => fileExtension is ".csv" or ".txt"; public async Task<List<Dictionary<string, string>>> ParseAsync( Stream stream, CancellationToken ct) { var result = new List<Dictionary<string, string>>(); using var reader = new StreamReader(stream, detectEncodingFromByteOrderMarks: true); using var csv = new CsvReader(reader, CultureInfo.InvariantCulture); csv.Read(); csv.ReadHeader(); var headers = csv.HeaderRecord; while (await csv.ReadAsync()) { var row = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase); foreach (var header in headers) { row[header] = csv.GetField(header)?.Trim() ?? string.Empty; } result.Add(row); } return result; } }这里detectEncodingFromByteOrderMarks: true很关键，后文坑位篇会细说编码问题。
Excel 解析：.NET 生态里常用的是 NPOI 和 ClosedXML。NPOI 免费且支持 xls、xlsx 两种格式，ClosedXML 只支持 xlsx 但 API 设计更现代、更易用。考虑到老系统经常还有 xls 文件存量，我通常选 NPOI。NuGet 安装：
dotnet add package NPOIpublic class ExcelParser : IImportParser { public bool CanHandle(string fileExtension) => fileExtension is ".xlsx" or ".xls"; public Task<List<Dictionary<string, string>>> ParseAsync( Stream stream, CancellationToken ct) { var result = new List<Dictionary<string, string>>(); var workbook = WorkbookFactory.Create(stream); var sheet = workbook.GetSheetAt(0); // 只解析第一个工作表 // 找到表头行 var headerRow = sheet.GetRow(0); if (headerRow == null) throw new InvalidDataException("Excel 文件是空的，没有表头"); var headers = new List<string>(); for (int c = 0; c < headerRow.LastCellNum; c++) { var cell = headerRow.GetCell(c); var header = cell?.ToString()?.Trim() ?? string.Empty; headers.Add(header); } for (int r = 1; r <= sheet.LastRowNum; r++) { ct.ThrowIfCancellationRequested(); var excelRow = sheet.GetRow(r); if (excelRow == null) continue; // 整行为空，跳过 var hasValue = false; var row = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase); for (int c = 0; c < headers.Count; c++) { var cell = excelRow.GetCell(c); var value = GetCellValue(cell); if (!string.IsNullOrEmpty(value)) hasValue = true; row[headers[c]] = value; } if (hasValue) result.Add(row); } return Task.FromResult(result); } private static string GetCellValue(ICell cell) { if (cell == null) return string.Empty; switch (cell.CellType) { case CellType.Numeric: if (DateUtil.IsValidDate(cell.NumericCellValue)) return cell.DateCellValue?.ToString("yyyy-MM-dd HH:mm:ss") ?? string.Empty; return cell.NumericCellValue.ToString(CultureInfo.InvariantCulture); case CellType.String: return cell.StringCellValue.Trim(); case CellType.Formula: // 公式单元格，尝试取缓存结果 return cell.CachedFormulaResultType switch { CellType.String => cell.StringCellValue.Trim(), CellType.Numeric => cell.NumericCellValue.ToString(CultureInfo.InvariantCulture), _ => string.Empty }; case CellType.Boolean: return cell.BooleanCellValue.ToString(); default: return string.Empty; } } }注意几个关键处理：
- 日期单元格：我最开始做导入的时候，日期读取直接用
ToString()，结果拿到一串数字（Excel 序列号），后来才知道DateUtil.IsValidDate+DateCellValue才能正确还原日期。Excel 的日期本质是自 1900 年起的序列号，NPOI 在数字单元格上默认不会自动转日期，必须显式判断。 - 公式单元格：如果用户在模板里写了个公式（比如合计列），
CellType会是Formula，直接取值拿不到结果，要用CachedFormulaResultType拿 Excel 已经缓存的计算值。这又是一个实战中很常见但文档里不太提的细节。 - 数字转字符串的格式陷阱：手机号、身份证号这种"长数字"在 Excel 里经常被存成数值类型，直接
ToString()会变成科学计数法。这种问题的根治方法是让业务方在模板里把列格式设为"文本"，但解析器这边也要做兜底——把数值统一转成无小数点的整数形式并尝试去掉末尾多余的.0。
3.3 行级校验与错误收集策略
解析出来的List<Dictionary<string, string>>还是"哑数据"，所有行都是字符串。导入校验要回答的是：哪些行能入库、哪些行不能、为什么。
校验逻辑我习惯按"字段级校验 -> 行级业务校验"两层做。字段级校验处理"必填、格式、长度、枚举值"这类通用规则，行级业务校验处理"这条记录在数据库里是否重复、关联表里是否存存在"这种带业务语义的规则。
public class GoodsImportValidator { private readonly IGoodsRepository _goodsRepository; public GoodsImportValidator(IGoodsRepository goodsRepository) { _goodsRepository = goodsRepository; } public ImportErrorItem? ValidateRow(Dictionary<string, string> row, int rowIndex) { var sku = row.GetValueOrDefault("SKU编号"); var name = row.GetValueOrDefault("商品名称"); var price = row.GetValueOrDefault("销售价格"); // 字段级：必填 if (string.IsNullOrWhiteSpace(sku)) return new ImportErrorItem { RowIndex = rowIndex, Message = "SKU编号不能为空" }; if (string.IsNullOrWhiteSpace(name)) return new ImportErrorItem { RowIndex = rowIndex, Message = "商品名称不能为空" }; // 字段级：格式 if (!decimal.TryParse(price, out var priceValue) || priceValue <= 0) return new ImportErrorItem { RowIndex = rowIndex, Message = "销售价格必须是大于0的数字" }; // 行级：唯一性（数据库里已存在则拒绝） if (_goodsRepository.ExistsBySku(sku)) return new ImportErrorItem { RowIndex = rowIndex, Message = $"SKU {sku} 已存在，请勿重复导入" }; return null; } }校验要遵循"一票否决，但错误只报第一个"还是"收集所有错误"？我的实践是：一行内收集所有字段错误，用分号拼接，比如"SKU编号不能为空；销售价格必须是大于0的数字"。这个体验比一次只报一个错好太多，用户改一次文件可以少改好几轮。但要注意别报太细导致信息过载，"必填为空 + 格式非法"同时报就有点噪音了，所以同字段内的错误可以合并。
另一个技巧：把校验和数据组装分离。上面只说了校验，数据组装（把字符串行转成实体对象）我也放在这层做而不是放到落库时，这样"校验未通过的记录不影响已通过记录的组装"，逻辑职责更干净。
3.4 导入结果回执与错误文件生成
导入完成后，前端需要一个直观的东西告诉业务人员"哪里错了"。返回 JSON 错误明细是最基础的，但几千行数据里有三百行错误时，前端逐行渲染不现实，业务人员也不可能对着网页去改数据。更实用的方案是：生成一份"错误标注版 Excel"回传给前端下载，错误行标红，并在右侧追加一列"错误原因"。
实现思路是：用 NPOI 重新打开原始文件，遍历错误行，CellStyle设置红色背景，在表头右侧写进错误信息，然后以FileStreamResult返回。
var memStream = new MemoryStream(); workbook.Write(memStream, true); memStream.Position = 0; return File(memStream, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "导入错误标注.xlsx");这是我在实际项目里最受好评的一个细节。业务人员不需要理解"第123行第4列格式错误"这种技术描述，他们看到的是"哪一行标红了、为什么红、怎么改"。文件导入这个功能到最后拼的往往不是技术，而是业务体验，错误反馈的形态直接决定了用户对这个功能的耐心。
4. 大文件和高并发场景下的性能调优
导入接口的性能瓶颈基本都在"内存占用"和"数据库写入"两处。几千行的文件怎么折腾都没事，一旦行数上了五位数，很多想当然的写法就会出问题。
4.1 流式解析，别把整个文件一次性读进内存
很多初版实现喜欢先await file.CopyToAsync(ms)把整个文件灌进MemoryStream，再交给解析器。小文件没问题，50MB 的文件就有问题了——IIS 或 Kestrel 进程内存会瞬间飙升，频繁 GC，严重点直接 OOM。
正确姿势是拿到IFormFile.OpenReadStream()直接传给解析器，让解析器流式读取。NPOI 的WorkbookFactory.Create(stream)传一个非 seekable 流（一般直接传file.OpenReadStream()）在我实测中是可以的，因为它内部会自己缓冲，内存占用远小于整个文件副本。CSV 更是天然支持流式，CsvReader本身读的就是流。
另一个内存大户是中间数据：解析出的List<Dictionary<string, string>>在六万行、三四十列的情况下大概能吃掉上百 MB 内存，而且全是引用类型，GC 压力不小。我在高数据量项目里的做法是解析出来的数据不完全滞留内存——CSV 边读边校验边写库，用类似"分段管道"的方式把内存峰值压住。但这样做代码复杂度会上升，如果你的场景是常规的管理后台导入（几千到一两万行），先把整表解析到内存里完全够用，不要过度设计。折中方案是加一个可配置的行数阈值，超过阈值走管道式分段处理，通常业务后台根本不会触到这个阈值。
4.2 批量写入与事务边界
逐行SaveChanges()是导入性能的头号杀手。一万行数据逐行写入，保守估计几十秒到几分钟，磁盘 IO 和 SQL 往返都吃不消。EF Core 的标准做法是AddRange+ 一次性SaveChanges：
var goodsList = new List<Goods>(); foreach (var row in validRows) goodsList.Add(MapToEntity(row)); await _dbContext.Goods.AddRangeAsync(goodsList, ct); await _dbContext.SaveChangesAsync(ct);几万行的AddRange在 EF Core 里会生成一条巨大的INSERT语句或者多条批量插入语句，实测效率能接受。但注意.SaveChanges()的默认行为是开启隐式事务的：一旦中途某一行违反约束抛异常，整个批次全部回滚，而且你已经"全有或全无"地把所有行绑在了一个事务里。
我这里的做法分两种情况：如果导入任务本身要求"要么全部成功，要么全部失败"，那隐式事务正中下怀。但更多业务场景是"能成功的尽量成功，失败的行收集起来反馈给用户"，这种情况下我会先做完全部校验和预检查，把肯定会报错的行筛掉，剩下能落库的行再走批量写入——因为前面已经做了一遍完整校验和重复性检查，落库阶段几乎不会触发异常，这个事务就只是"兜底"而不是"常态"。真遇到并发抢插同一主键这种极端情况，落入 catch 再输出一个整体失败，也比每行独立开事务快一个数量级。
4.3 数据量真的大到离谱，再用异步任务队列
如果单次导入能到几十万行起步，同步方案再怎么优化也扛不住 HTTP 连接的等待。这时候把导入任务丢进队列（Channel<T>、Hangfire、RabbitMQ 均可），接口立刻返回"任务已接收，ID 为 xxx"，前端轮询/api/import/{taskId}/status查询处理进度。
用Channel<T>做进程内队列是最轻量的方案：
var channel = services.GetRequiredService<Channel<ImportTask>>(); await channel.Writer.WriteAsync(new ImportTask { FilePath = savedPath, TaskId = taskId }, ct);后台消费者从Reader.ReadAllAsync()里拿任务执行导入，进度和结果写进数据库或内存字典。需要注意进程内队列在应用重启时会丢任务，生产环境建议落库保存任务状态，队列只做"触发器"。
我用这个方案处理过单次 25 万行的库存导入，异步任务 + 分批写入（每批次 5000 行独立事务），整体耗时约 2 分钟，用户体验完全不一样——提交后页面显示"导入任务进行中，完成率 43%"，而不是干瞪眼看着菊花转圈。
5. 我实际项目里踩过的坑，都是文档不会告诉你的
这一段的价值来自真实项目里的血泪教训，我按"编码、Excel 结构、幂等"三条线来说，每条都能单独写一篇排查文章。
5.1 CSV 乱码与 Excel 的长数字丢失：编码问题两个典型现场
场景一：用户用 Excel 另存为 CSV，然后用记事本打开正常，传到系统里却变成乱码。根因是 Excel 生成的 CSV 走的是 GB2312/GBK 编码（中文环境），而程序默认按 UTF-8 解码。StreamReader的detectEncodingFromByteOrderMarks: true只能识别带 BOM 的文件，Excel 导出的 CSV 不带 BOM，照样识别失败。
我的解法是：解析前做编码探测，先取前 4 个字节判断 UTF-8 BOM（EF BB BF），没有 BOM 时默认从 GB18030 解码，并把这个规则写进接口文档里告知用户"请用 UTF-8 编码另存为 CSV"。CsvHelper 里指定编码：
using var reader = new StreamReader(stream, Encoding.GetEncoding("GB18030"), detectEncodingFromByteOrderMarks: true);场景二：用户 Excel 里的一串 18 位身份证号或订单号，导入后末尾几位变成 000。这是 Excel 数值精度的限制，数字超过 15 位就会丢精度，解析器怎么努力都救不回来。唯一可靠的解法是在模板源头控制：在 Excel 模板里把该列格式预置为"文本"，同时写清填写规范："SKU 编号列必须是文本格式，否则后 4 位会被 Excel 转成 0"。这类问题属于"工具本性"，要在需求阶段和业务方对齐，不然你会面临"为什么系统把我数据搞坏了"的投诉，而问题其实出在 Excel 端。
5.2 Excel 模板里的隐形结构：合并单元格、空行、公式残留
合并单元格是解析时最容易"串行"的结构。比如表头两行合并了一个大单元格"商品信息"，NPOI 得到的只有第一个单元格有值，其余合并区域单元格值为 null。很多初级实现解析表头时直接cell.ToString()，拿到一堆空字符串，列名对不上，校验全乱。处理办法是解析表头时对空值做"向左继承"：
for (int c = 0; c < headerRow.LastCellNum; c++) { var header = headerRow.GetCell(c)?.ToString()?.Trim() ?? string.Empty; if (string.IsNullOrEmpty(header) && c > 0) headers.Add(headers[c - 1]); // 合并单元格场景，继承左侧列名 else headers.Add(header); }数据区内的空白行：用户模板里预留了 50 行，只填了 20 行，剩下的"空行"里其实藏着样式对象，GetRow(r)不为 null。前面代码里的hasValue逻辑就是为这个准备的，判断整行所有字段都是空字符串才跳过，不能光看行对象是否为 null。
公式残留：我遇到过一次导入价格时金额全部变成 0 的线上问题。排查后定位到是模板里价格列部分单元格带了"平时隐藏的公式"（Excel 里有一个显示值，但底层是公式），用户手动改动单元格后公式没重算，缓存结果是 0。前面解析代码里处理CellType.Formula时用CachedFormulaResultType读缓存值就来自这次教训。更稳健的做法是导入前用 NPOI 强制重算整个工作簿：workbook.ForceFormulaRecalculation = true;，但这只对 Excel 打开时生效，纯编程读取时缓存值可能不可靠。所以模板规范里我直接写了一条硬性要求："所有列必须为静态值，禁止使用公式"，并定期抽查。
5.3 重复导入与接口幂等：一个好习惯，省一堆事
用户手抖点两次提交，或者导入失败后重试，结果库里多了一倍数据。这就是幂等缺失的后果。最简单的方案是"业务键唯一约束"：导入前用业务自然键（SKU、身份证号、合同号）查重，库里已有则报错。但那只是面上解决了，大多数系统里同期批量导入的数据里就自带重复，这种场景还需要在导入逻辑内维护"本次文件内已见集合"：
var seenSkus = new HashSet<string>(); foreach (var row in rows) { var sku = row.GetValueOrDefault("SKU编号"); if (!seenSkus.Add(sku)) errors.Add(new ImportErrorItem { RowIndex = rowIndex, Message = $"SKU {sku} 在本文件内重复" }); }另一个更彻底的做法是给导入请求生成一个幂等键：前端提交时生成 GUID 放在 form 字段里，服务端记录"该 GUID 已处理过则直接返回上次结果"。这个机制在"前端超时重试"场景下非常有用，能保证即使服务端第一次已经处理完了，用户重试也不会导致数据翻倍。实现成本不高，就是一张表或者 Redis 里的一个 key，但上线后能帮你挡掉大量"我以为没提交成功，所以又提交了一次"的脏数据。
5.4 事务与跨库写入的一致性边界
最后一个坑来自一个库存导入项目：导入逻辑里同时写主库存表和历史明细表，明细表每天要分区归档，跨了两个库甚至可能跨数据库实例（MySQL + SQL Server）。EF Core 的隐式事务在这里就失灵了——它不是分布式事务，跨库写一半挂了，库存更新了但明细没写进去，对不上账。
这类场景我把"一致性边界"拆成两段：主表写入用本地事务，明细表写失败时记录日志并让导入任务进入"人工复核"状态，而不是强行回滚前一段。导入这种海量操作，一旦强依赖分布式事务，性能会很难看，可用性也下降。你要在需求评审阶段就明确一点：导入数据最终一致性可以接受"延迟"和"人工对账"，但绝不能接受"静默丢失"。把这一点和业务方达成共识，写进接口文档，远比你在代码里硬撑分布式事务靠谱得多。
我在实际项目里的体会是：文件导入接口的难点从来不在"上传"本身，而在上传之后那一整套"解析、校验、反馈、补偿"的工程化设计。把上面这些环节逐个想清楚、用代码验证过、和业务方对齐过，你写的导入接口才能从"能跑"变成"好用"。最后分享一个容易忽略的小技巧：给导入模块加一个"模板下载"接口，和导入接口配套发布。用户永远不记得列名规范，但你把模板和填写说明一起给出去，导入失败率能直接下降一半，这是我在多个项目里反复验证过的经验。
