EasyExcel 导出下载中心与导入设计方案

同步与异步的分界#

不超过 5 万行仍走同步响应流：建任务、投递 MQ、轮询这组固定开销，对 5 秒内能完成的导出不划算。超过 5 万行走下载中心。分界依据：EasyExcel 写出速度按保守 2 万行/s 估，5 万行写出约 2.5 s，加上查询和传输，落在网关 30 s 超时内有余量。该分界值是初值，上线前用真实数据分布压测校准。

数据读取：ID 游标分页优先，Cursor 兜底#

offset 深分页先排除：LIMIT 900000, 5000 要扫描并丢弃前 90 万行，全程重复扫描量级为 O(n²)。

两个候选：

Cursor 方案的实测数据值得写进决策依据：同样 100 万行，List 全量接收占 885 MB，Cursor 加 fetchSize=Integer.MIN_VALUE 后堆压到 50 MB 上限时吞吐仍有 90%，压到 10 MB 时 GC 占 34 s、吞吐只剩 13%。内存换吞吐的平衡点在 20 MB 附近。

决策：默认 ID 游标分页，一批 5000 行，导出任务支持从 lastId 断点重跑；无自增主键或必须按业务字段排序时降级 Cursor，且必须同时满足 forward-only、read-only、try-with-resources 关闭三个条件。

1
// 导出主循环（示意）
2
long lastId = 0L;
3
int sheetNo = 0;
4
try (ExcelWriter writer = EasyExcel.write(tmpFile)
5
        .registerConverter(new LongTextConverter())
6
        .build()) {
7
    WriteSheet sheet = EasyExcel.writerSheet(sheetNo, "sheet-" + sheetNo)
8
            .head(FlowVO.class).build();
9
    List<FlowVO> batch;
10
    while (!(batch = flowMapper.listByIdCursor(queryParams, lastId, PAGE_SIZE)).isEmpty()) {
11
        writer.write(batch, sheet);
12
        lastId = batch.get(batch.size() - 1).getId();
13
        rows += batch.size();
14
        if (rows % SHEET_CAPACITY == 0) {          // 每 50 万行换 sheet
15
            sheet = EasyExcel.writerSheet(++sheetNo, "sheet-" + sheetNo)
16
                    .head(FlowVO.class).build();
17
        }
18
        progressReporter.tick(rows);
19
    }
20
}   // 触发 finish()：合并临时文件并清理

写入：分 sheet 与临时文件#

xlsx 单 sheet 硬上限 1,048,576 行乘 16,384 列（来源：Microsoft Excel specifications and limits），超限写出直接失败；社区反馈 Excel 实际打开 20 到 40 万行起就明显卡顿（来源：Numerous.ai 汇总）。决策：单 sheet 封顶 50 万行，百万行导出拆 2 个 sheet，行数上限和打开体验都留余量。

临时文件两条工程约束：写入目录指向独立数据盘，与系统盘隔离，水位 80% 告警；finally 中显式删文件，进程异常退出留下的残留文件由机器级定时清扫兜底。

上传、通知与下载#

1. 文件落本地后 OSS 分片上传：50 MB 以上走 multipart，分片 10 MB、并发 3，按分片重试 2 次。
2. 桶设私有。任务 SUCCESS 后前端点击下载时实时换取 15 min 有效期的预签名 URL，不用公共读：导出文件常含全量业务数据。
3. 通知只做轮询：下载中心页 5 s 一次拉任务列表，列表只查当前 owner，走 idx_owner_created 索引。WebSocket 推送列为可选增强，不做短信。
4. 桶生命周期 7 天自动删文件，xxl-job 每小时把超期任务置 EXPIRED，任务记录保留 90 天。

并发控制与幂等#

幂等：建任务前按 owner_id + biz_code + query_params 摘要算指纹，命中 5 min 内同指纹且状态非 FAILED / EXPIRED 的任务直接返回原任务号。

并发闸门三层：

超出全站闸门的任务留在 PENDING 排队，消费端按许可拉取，不丢弃。导入优先级低于导出：导出是读操作，积压只占磁盘；导入在写库，影响在线业务。

安全#

1. 越权下载（P0）：下载接口校验 owner_id，预签名 URL 15 min 有效，任务表记审计字段。回归用例必含跨用户取他人 task_no 的负例。
2. 公式注入：单元格内容以等号、加号、减号、@ 开头（含前导 Tab 与回车）时前置单引号转义，防 DDE 类攻击（参考：公式注入公开分析）。转义收敛在 Facade。
3. 长数字精度：Excel 只存 15 位有效数字，第 16 位起截断为 0，超 11 位默认按科学计数法显示（来源：简道云汇总 + EasyExcel Issue #2204）。雪花 ID 是 18 到 19 位，导出后必然损坏且不可逆。统一规则：ID、订单号、第三方流水号一律 String 字段加文本单元格，Facade 默认注册 LongTextConverter。

上传与任务创建#

前端用预签名 PUT 直传 OSS，拿 file_key 后调创建导入任务接口，20 MB 以上走分片上传。服务端校验三道：扩展名白名单（xlsx / xls）、文件头魔数（PK 头，防改后缀伪装）、大小上限 100 MB。xlsx 本质是 zip，超压缩比文件在解析期触发 POI ZipSecureFile 的解压比率保护，这里把比率阈值前置到校验阶段拦截，不让恶意文件打到 Worker。

解析与攒批#

1
public class BatchImportListener<T> extends AnalysisEventListener<T> {
2
    private static final int BATCH_SIZE = 1000;
3
    private final List<T> buffer = new ArrayList<>(BATCH_SIZE);
4
    private final Consumer<List<T>> processor;
5
    private final ErrorCollector errorCollector;
6

7
    @Override
8
    public void invoke(T row, AnalysisContext context) {
9
        RowError err = validator.check(row, context.readRowHolder().getRowIndex() + 1);
10
        if (err != null) {
11
            errorCollector.add(err);            // 错误行不进 buffer
12
            return;
13
        }
14
        buffer.add(row);
15
        if (buffer.size() >= BATCH_SIZE) {
16
            flush();
17
        }
18
    }
19

20
    private void flush() {
21
        processor.accept(new ArrayList<>(buffer));   // 副本防中途篡改
22
        buffer.clear();
23
    }
24

25
    @Override
26
    public void doAfterAllAnalysed(AnalysisContext context) {
27
        flush();
28
    }
29
}

两条纪律：监听器每次导入 new 一个实例，Service 用构造器传入，绝不注册成 Spring 单例，成员 buffer 在单例并发下必然串数据；BATCH_SIZE 取 1000，依据见下节。

写库：批量与事务#

JDBC URL 必须带 rewriteBatchedStatements=true。MySQL 驱动在该开关关闭时把 addBatch 的多条 INSERT 拆成逐条发送，打开后改写为单条多值 INSERT，社区实测为数量级差距（来源：阿里云开发者社区、dbaplus 实测文章）。上线检查单里必须有这一项，因为它不报错、只变慢。

批次 1000 的依据：按每行 20 列乘平均 50 字节估，合并后单条 SQL 约 1 到 2 MB，低于 MySQL 8.0 默认 max_allowed_packet（64 MB）两个数量级；再大收益递减，且单批失败的重试代价上升。

事务策略：每批独立事务提交，不做整文件单事务。百万行单事务意味着一个连接持锁十几分钟，主从延迟飙升，中途任何一行失败还要全部回滚重来。代价是部分成功语义，由任务报告与错误回执兜底。

校验策略与部分成功#

两种模式并存，创建任务时按业务声明：

默认部分成功的理由：百万行文件错 3 行却要求全部重传，运营要改文件再等一轮 15 min；错误回执加失败行清单已给出修复路径。资金类选全量校验，代价是解析两遍，总耗时约 1.7 倍。

幂等两道防线：表上建业务唯一键（如外部单号），写库用 INSERT … ON DUPLICATE KEY UPDATE，重复行不产生脏数据；任务层用 file_md5 + biz_code 挡重复文件，命中 24 h 内 SUCCESS 任务直接拒绝并返回原任务号。

错误回执#

错误行写独立 xlsx，三列：原行号、原始内容、错误原因，随任务上传 OSS 挂到 error_url。错误行超 10 万条时回执截断为前 10 万行加一行汇总，防止错误文件比原文件还大。