跳到主要内容
版本：Next

数据导入导出

本文档引用的文件

目录​

  1. 简介
  2. 导入功能详解
  3. 导出功能详解
  4. 数据模型说明
  5. 错误处理机制

简介​

本文档详细描述了系统中关于MyEntityName实体的数据导入与导出API功能。通过POST /api/v{version}/MyPluginName/MyEntityName/Import端点实现Excel文件的批量创建或更新操作，通过GET /api/v{version}/MyPluginName/MyEntityName/Export端点实现基于查询条件的数据导出功能。文档涵盖文件格式要求、数据结构、处理流程及异常处理机制。

Section sources

导入功能详解​

请求端点​

POST /api/v{version}/MyPluginName/MyEntityName/Import

请求参数​

  • file: 类型为IFormFile，必须为.xlsx格式的Excel文件，以multipart/form-data方式提交。

处理流程​

  1. 接收上传的Excel文件并读取为内存流。
  2. 检查是否存在名为“配置”的工作表。
  3. 使用MiniExcelLibs库解析“配置”工作表中的数据，映射为MyEntityNamesImportModel.MyEntityNameImportModel对象列表。
  4. 若无有效数据行，则抛出用户友好异常。
  5. 调用应用服务IMyEntityNameAppService.ImportAsync方法进行批量处理。

批量处理逻辑​

  • 遍历导入数据，根据名称判断是否已存在：
    • 若存在同名记录，则生成MyEntityNameUpdateDto用于更新。
    • 若不存在，则生成MyEntityNameCreateDto用于创建。
  • 对所有创建项执行CreateAsync操作。
  • 对所有更新项执行UpdateAsync操作。
  • 任一操作失败时，捕获异常并包装为带行号信息的UserFriendlyException终止导入。

Section sources

导出功能详解​

请求端点​

GET /api/v{version}/MyPluginName/MyEntityName/Export

请求参数​

  • Filter: 模糊搜索过滤条件。
  • Name: 名称精确匹配。
  • Sorting: 排序字段（默认为Sort字段）。
  • MaxResultCount: 最大返回数量（导出时自动设为int.MaxValue）。
  • SkipCount: 跳过数量。

处理流程​

  1. 接收查询参数并调用IMyEntityNameAppService.ExportAsync方法获取导出数据。
  2. 查找名为MyEntityName导出模板.xlsx的模板文件，优先从当前运行目录查找，若不存在则回退到程序集目录。
  3. 使用MiniExcelLibs库将数据填充至模板文件。
  4. 返回FileStreamResult，设置MIME类型为application/vnd.openxmlformats-officedocument.spreadsheetml.sheet，并生成唯一文件名。

文件命名规则​

导出文件名格式为：{基础文件名}_{yyyyMMddhhmmss}.xlsx

  • 当导出多条记录时，基础文件名为MyEntityName列表
  • 当导出单条记录时，基础文件名为该记录的名称
  • 当无记录时，基础文件名为MyEntityName模版

Section sources

数据模型说明​

导入模型结构​

MyEntityNamesImportModel包含一个MyEntityNames列表，每个元素为MyEntityNameImportModel类型，继承自WorkSectionExportModel，具有以下字段：

  • Name: 名称（必填）
  • Code: 编号
  • Remark: 备注
  • RowIndex: 行号（自动赋值，从第2行开始）

导出模型结构​

MyEntityNameDto包含以下可导出字段：

  • Code: 编号
  • Name: 名称
  • Sort: 排序
  • Remark: 备注
  • IsDisabled: 是否禁用
  • ConcurrencyStamp: 并发戳

通过GetExportData()方法将DTO属性转换为字典格式，供模板引擎使用。

Sheets字典结构​

ExportAsync返回的Sheets为Dictionary<string, object>类型，当前仅包含一个键：

  • "配置": 值为MyEntityNameDto导出数据的列表

该结构支持未来扩展多个工作表。

Section sources

错误处理机制​

用户友好异常（UserFriendlyException）​

系统在数据校验失败或业务规则冲突时抛出UserFriendlyException，确保前端能展示清晰的错误信息。

导入场景常见错误​

  • 空文件或无有效数据：提示“请检查导入的表格”
  • 名称重复（文件内）：提示“第X,X行：名称重复”
  • 必填字段为空：提示“第X行：MyEntityName名称不能为空”
  • 创建/更新失败：提示“第X行：具体错误信息”

校验规则​

  • 编号（Code）: 非空，最大长度由MyEntityNameConsts.MaxCodeLength定义
  • 名称（Name）: 非空，最大长度由MyEntityNameConsts.MaxNameLength定义
  • 备注（Remark）: 最大长度由MyEntityNameConsts.MaxRemarkLength定义

注意：常量定义文件未在当前上下文中找到，但校验逻辑存在于CheckCreateOrUpdateDtoAsync方法中。

Section sources