# 7.4 数据导入导出

:::tip 概述
Excel 能力基于 excelize 封装（utility/excel）：`ReadSheet` 读表（剥表头、跳空行）、`WriteSheet` 写表落盘返回文件。后端手写导入导出逻辑，前端配套导入组件与下载工具。
:::

## 后端 API（utility/excel）

| 函数 | 说明 |
|---|---|
| ReadSheet(file) | 读首个工作表：返回 headers + rows（首行表头剥离、空行跳过） |
| WriteSheet(dir, baseName, headers, rows) | 写 xlsx 到指定目录，返回 fileName/filePath |

## 导入范式（以 example 为例）

```text
dto：ExampleImportReq{ File *multipart.FileHeader } + UnmarshalBody
        ↓
service.Import：
  ReadSheet 拿 rows
  逐行校验（必填、格式）→ 合法行 Create，失败行记录原因（含工作表行号）
  无事务：逐行独立写入，失败行不影响已写入行
        ↓
返回 {Total, Success, Failed, Reasons[]} + ResMsg 提示语
```

## 导出范式

```text
service.Export：
  复用基座 exampleSpec.applyFilters（与分页同口径的查询条件）
  DictGetText 翻译枚举列（与 SerializeMaps 同字典）
  WriteSheet 落盘 → upload.GetFileUrl 返回访问 URL
        ↓
前端拿到 URL → download 工具落盘
```

## 约定

| 约定 | 说明 |
|---|---|
| 查询同口径 | 导出条件与分页请求字段一致（用户所见即所导） |
| 行号折算 | 失败提示行号 = 数据序号 + 2（含表头） |
| 无事务导入 | 大文件不占长事务；结果汇总告知成败 |
| 模板同源 | 导入模板经文件模板管理下载（[6.21](/zh/modules/file-template.html)），列头与解析一致 |

## 前端配套

- Excel 组件（`components/Excel`）：导入解析预览、导出生成
- importFile 组件：导入上传交互
- downloadFile 工具：URL 文件落盘

见 [9.12 Excel 导入导出组件](/zh/frontend/excel-components.html)。

## 相关

- [3.5 业务层开发（service）](/zh/guide/service.html)（手写导入导出完整实现）