阿里 on 牛哥聊技术

Nacos 配置中心与服务发现的实战要点

Thu, 20 Jun 2024 15:30:00 +0800

为什么 Nacos 装起来容易，用对很难

Nacos 是当下国内最流行的"配置中心 + 注册中心"二合一组件——几乎所有用 Spring Cloud Alibaba 的项目都默认上它。

但用过的人会发现一些尴尬的事情：

团队所有项目的配置全堆在一个 namespace 里，环境/项目/团队划分混乱
一个微服务有十几个配置文件，谁也说不清哪个配置覆盖了哪个
修改一个配置后有些实例生效，有些没生效——监听机制写错了
重启 Nacos 后配置没了或者注册的服务全没了——存储模式选错了
灰度发布想"只让一台实例生效新配置"，根本做不到

Nacos 装起来 5 分钟，用对要几个月经验。本文把生产环境的关键决策点讲清楚——**namespace 怎么划、配置怎么组织、监听怎么写对、服务发现怎么用稳 **。

一、Nacos 的核心模型

flowchart TB
 Namespace["Namespace
(环境隔离)"]
 Group["Group
(逻辑分组)"]
 DataId["Data ID
(具体配置)"]

 Namespace --> Group
 Group --> DataId

 DataId -.读取.-> Client[应用实例]
 DataId -.推送变更.-> Client

三层模型：

Namespace：最高层级隔离——通常对应环境（dev/test/prod）
Group：第二层逻辑分组——通常对应项目或微服务
Data ID：最具体的配置文件——application-{profile}.yaml

这个三层结构怎么划分，是 Nacos 用得好不好的最大决定因素。

二、Namespace / Group / DataId 的划分原则

不要这样划

1
2
3
4


namespace: public（默认）
group: DEFAULT_GROUP
data id: my-service-dev.yaml, my-service-test.yaml, my-service-prod.yaml
my-other-service-dev.yaml, ...

所有配置堆在 default 命名空间和 default 组里——搜起来一团乱，多团队协作时互相覆盖也不会知道。

推荐划法：环境隔离 + 服务分组

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


namespace = 环境
 ├─ dev
 ├─ test
 ├─ pre (预发布)
 └─ prod

group = 服务名 / 项目名
 ├─ user-service
 ├─ order-service
 └─ shared-config (跨服务共享)

data id = application-{type}.yaml
 ├─ application-base.yaml (业务基础配置)
 ├─ application-rocketmq.yaml (中间件配置)
 └─ application-feature.yaml (功能开关)

关键决策：

Namespace 用环境——上线管控的核心边界。线上账号只给 prod namespace 权限，dev 不该看到 prod
Group 用服务名——同一个微服务的所有 Data ID 集中在一个 Group 里
Data ID 按职责拆分——业务配置、中间件配置、功能开关分开放，单个文件不会膨胀

跨服务共享配置怎么办

很多配置不是单一服务的——比如所有服务都要连同一个 Redis：

1
2


group = shared-config
data id = application-redis.yaml, application-mq.yaml

每个服务在 bootstrap.yml 里多 import 一份共享配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


spring:
 cloud:
 nacos:
 config:
 server-addr: ${NACOS_ADDR}
 namespace: ${ENV}
 group: user-service  # 自己的 group
 extension-configs:
 - data-id: application-redis.yaml
 group: shared-config
 refresh: true
 - data-id: application-mq.yaml
 group: shared-config
 refresh: true

三、配置文件的优先级和加载顺序

Spring Cloud Nacos 默认按这个优先级加载（从低到高）：

${spring.application.name}.${file-extension} 默认共享
${spring.application.name}-${profile}.${file-extension}（profile 独占）
extension-configs（按数组顺序，越后越高）
shared-configs（按数组顺序，越后越高）
命令行参数 / 环境变量

搞清楚这个优先级是排查"为什么我改了配置不生效"的前提——很可能你改的是低优先级，被高优先级覆盖了。

打开 Spring Boot Actuator 的 /actuator/configprops 或者 /actuator/env 能直观看到每个 key 来自哪个 PropertySource。

四、配置变更的监听：写错就完蛋

默认行为：自动刷新被 `@Value` 注入的字段

1
2
3
4
5


spring:
 cloud:
 nacos:
 config:
 refresh: true

1
2
3
4
5
6


@RestController
@RefreshScope // ★ 关键
public class FeatureController {
 @Value("${feature.enabled}")
 private boolean enabled;
}

@RefreshScope 让 Bean 在配置变更后重新创建，注入的 @Value 拿到新值。

容易踩的坑

坑 1：@RefreshScope 没加，配置不生效

新人最常踩——以为配 refresh: true 就够了。实际上还要在使用配置的 Bean 上加 @RefreshScope。

坑 2：@RefreshScope 不能加在 @Configuration 上

会导致整个 Configuration 重建，下面声明的所有 Bean 全部重建——副作用极大，可能引起内存泄漏（旧 Bean 没释放）。

坑 3：@ConfigurationProperties 默认就刷新

不需要 @RefreshScope：

1
2
3
4
5
6
7


@Component
@ConfigurationProperties(prefix = "feature")
public class FeatureConfig {
 private boolean enabled;
 private int threshold;
 // getters / setters
}

这是更推荐的姿势——比 @Value 类型安全、便于测试、自动刷新。

坑 4：手动监听用 @NacosConfigListener 已废弃

老博客经常推荐 @NacosConfigListener，但它属于早期 SDK 风格，Spring Cloud 集成下基本不该用。手动监听用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


@Autowired NacosConfigManager configManager;

@PostConstruct
public void listen() throws Exception {
 configManager.getConfigService().addListener(
 "application-feature.yaml", "user-service",
 new Listener() {
 public Executor getExecutor() { return null; }
 public void receiveConfigInfo(String content) {
 log.info("config changed: {}", content);
 // 自定义解析逻辑
 }
 });
}

但 99% 场景用 @ConfigurationProperties + @RefreshScope 就够了。

五、灰度发布：Nacos 自身能做到什么程度

很多人以为"灰度发布配置"是 Nacos 的标准能力——Nacos 开源版其实没有灰度配置。

Nacos 开源版：配置变更会推到所有订阅了这个 Data ID 的实例，没有"只推一台"的能力
Nacos 商业版（阿里云 MSE Nacos）：才有"配置灰度发布"功能，可以指定按 IP / 标签推送

如果用开源版又想做配置灰度，三种思路：

拆 namespace：灰度环境用单独的 namespace（最干净）
拆 group：同 namespace 不同 group，灰度实例订阅 xxx-gray group
配置里写规则：配置内容里写"哪些实例生效"，业务代码读自己 IP 来判断（最灵活但侵入大）

生产推荐方案 1：直接搞一个 pre namespace 给灰度环境，和 prod 完全隔离。

六、服务发现：被低估的复杂度

临时实例 vs 永久实例

Nacos 注册的服务有两种"实例类型"：

临时实例（默认）：客户端用心跳维持，断了 30 秒后自动剔除——适合业务微服务
永久实例：服务端永久持有，下线要主动调 API——适合有固定地址的传统服务（数据库、第三方系统）

1
2
3
4
5


spring:
 cloud:
 nacos:
 discovery:
 ephemeral: true # 临时实例

注意：1.x 时代两者可以混在同一服务，2.x 之后同一 service 必须全是临时或全是永久——升级时要核对。

心跳与剔除

版本差异（重要）：下面"5 秒心跳 / 15 秒不健康 / 30 秒剔除"是 Nacos 1.x（HTTP 短连接） 的行为；Nacos 2.x 起默认改为 gRPC 长连接 + keepalive——客户端不再定时发 HTTP 心跳，连接断开即被识别下线，整体响应时延显著缩短（亚秒级）。如果你用的是 2.x（2024 年起的主流版本），心跳模型已经不适用。

Nacos 1.x 行为：临时实例每 5 秒发心跳，15 秒没心跳变"不健康"，30 秒后剔除——这意味着实例突然 kill 后最长有 30 秒不可用窗口。

Nacos 2.x 行为：客户端与 server 维持 gRPC 长连接，server 通过连接状态判断实例存活；连接异常断开（进程崩溃、网络隔离）会立即触发下线事件，避免 30 秒窗口。

解决（不论版本都建议）：

客户端配置健康检查 + 重试（OpenFeign / Ribbon / Spring Cloud LoadBalancer）
实例下线前先调用 Nacos NamingService.deregisterInstance 优雅注销——通常用 Spring Boot 的 ApplicationListener<ContextClosedEvent>

七、生产部署：踩过的坑

1. 数据存储：默认嵌入式不能上生产

Nacos 单机默认用嵌入式 Derby 数据库——重启数据可能丢，集群模式根本无法工作。生产必须切到 MySQL：

1
2
3
4
5
6
7


# Nacos 1.x / 2.x 老 key（仍兼容）
spring.datasource.platform=mysql
# Nacos 2.2+ 自身基于较新 Spring Boot，server 端推荐改用：spring.sql.init.platform=mysql
db.num=1
db.url.0=jdbc:mysql://nacos-mysql:3306/nacos?characterEncoding=utf8&...
db.user=nacos
db.password=...

2. 集群模式：至少 3 节点

Nacos 是双协议架构——配置中心和永久实例走 JRaft（CP），默认服务发现的临时实例走自研的 Distro（AP）协议 。两类数据落到同一个集群、用不同的一致性模型。至少 3 节点保证高可用——单节点是写测试代码用的，生产部署单节点没有任何高可用保证，强烈不建议。

这个差异在调试时很重要：Distro 是 AP，节点挂掉时部分实例信息可能短暂不一致——这是设计如此，不是 bug。

flowchart LR
 LB[负载均衡 / SLB]
 LB --> N1[Nacos 1]
 LB --> N2[Nacos 2]
 LB --> N3[Nacos 3]
 N1 <--> MySQL[(MySQL 主从)]
 N2 <--> MySQL
 N3 <--> MySQL

3. 安全：默认是裸奔的

Nacos 默认没有鉴权——任何能访问端口的人都能改你的配置。生产必须开启：

1
2
3


nacos.core.auth.enabled=true
nacos.core.auth.server.identity.key=...
nacos.core.auth.server.identity.value=...

并给不同环境账号、不同 namespace 设置不同权限（开源版控制台里能配）。

4. JVM 参数

生产 Nacos 的 JVM 参数默认是 -Xms2g -Xmx2g，对大流量场景明显不够。配置数 ≥ 10000、连接客户端 ≥ 1000 时建议升到 4G 以上。

5. 不要在容器里跑临时数据

K8s 部署 Nacos 时，所有数据必须挂 PV，否则 Pod 重启数据全丢。MySQL 走外部，但 Nacos 自己的 logs / data 目录也要挂。

八、客户端容错：Nacos 挂了应用还能跑吗

Nacos 故障时（虽然概率小），客户端默认还能从本地 snapshot 文件读取上次拉到的配置——不会立刻挂：

1

~/nacos/config/snapshot/{namespace}/{group}/{dataId}

但有几个细节：

新增实例在 Nacos 故障时拉不到任何配置——直接启动失败
服务发现故障时正在运行的实例还能用上次缓存的服务列表，但新启动的实例发现不了任何服务

所以生产环境永远要保证：

Nacos 集群必须多节点 + 跨可用区
应用启动时用本地 fallback 配置（spring.cloud.nacos.config.import-check.enabled=false）
重要服务的服务发现要有降级机制

九、监控与排查

1. 看配置历史

Nacos 控制台保留每次变更的历史，改错了能直接 rollback。这是 Nacos 区别于"配置写在 yaml 里 + git" 模式的核心价值——* 不需要发版本就能改配置，但同时有审计*。

2. 看订阅者

Nacos 控制台 → 配置详情 → “订阅者列表”，能看到当前哪些实例订阅了这个配置——调试"为什么我的应用没收到推送"的第一步。

3. 应用侧日志

1

DEBUG com.alibaba.nacos.client = DEBUG

打开后能看到拉配置、心跳、推送等所有交互的细节。

十、生产配置 Checklist

部署前对照这份清单：

Namespace 按环境划分
Group 按服务划分
Data ID 按职责拆分（业务/中间件/开关）
共享配置走 shared-configs
使用 @ConfigurationProperties 而非 @Value
@RefreshScope 不加在 @Configuration 上
数据存储改 MySQL（不要嵌入式 Derby）
集群模式 ≥ 3 节点
鉴权开启 + 多账号权限隔离
JVM 内存 ≥ 4G
K8s 部署挂 PV
应用启动有 fallback 配置
Actuator 监控接入
业务配置变更走审批流程

小结

把全文压一句：

**Nacos 的真正价值不在『配置存哪里』，而在『配置变更能可控、可审计、能秒级生效』——但要让它真正可靠，命名空间、监听机制、集群部署一个都不能省。 **

记住几条工程纪律：

环境分 namespace，服务分 group，配置按职责拆 Data ID
优先 @ConfigurationProperties，少用 @Value + @RefreshScope
生产必上 MySQL + 3 节点 + 鉴权
永远要有本地 fallback——配置中心是单点故障源

把 Nacos 用对，是国内 Spring Cloud 项目走得远的基础设施之一。

用 EasyExcel 导出复杂组织机构树到 Excel

Fri, 02 Sep 2022 15:30:00 +0800

一个让人头大的需求

业务方：“把公司全部部门、员工、汇报关系导出到 Excel”。打开他们用的 Word 模板：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


+--------------+--------+--------+----------+--------+
| 一级部门 | 二级 | 三级 | 员工姓名 | 工号 |
+--------------+--------+--------+----------+--------+
| | | 一组 | 张三 | 001 |
| | | | 李四 | 002 |
| | 研发部 +--------+----------+--------+
| | | 二组 | 王五 | 003 |
| 技术中心 +--------+--------+----------+--------+
| | | | 赵六 | 004 |
| | 测试部 | | 钱七 | 005 |
+--------------+--------+--------+----------+--------+
| | | | ... | ... |
+--------------+--------+--------+----------+--------+

需求关键词：

层级关系：部门可能 1-5 层
单元格合并：同部门跨多行合并
数据量大：上千员工
样式要求：表头加粗、边框、分组色
导出快：用户等 30 秒会投诉

POI 拿来撸是噩梦——内存爆炸 + 写起来痛苦。EasyExcel 是这件事的事实标准答案——它把内存占用压到极致，API 也清爽很多。

本文用一个完整实例讲清楚 EasyExcel 导出树形结构 + 合并单元格的姿势。

一、EasyExcel 的核心优势

	Apache POI	EasyExcel
内存占用	一次性加载全部	流式写，几 MB 搞定
编码体验	大量 setCellValue	注解 + Java Bean
大数据量	容易 OOM	70 万行无压力
学习曲线	陡	平
复杂样式	灵活	灵活

EasyExcel 由阿里开源，本质是 POI 上加一层流式封装——背后还是 POI，但内存模型彻底改了。

二、最小可用 Demo

引入：

1
2
3
4
5


<dependency>
 <groupId>com.alibaba</groupId>
 <artifactId>easyexcel</artifactId>
 <version>3.3.2</version>
</dependency>

定义实体：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@Data
public class EmployeeRow {
 @ExcelProperty("一级部门")
 private String dept1;

 @ExcelProperty("二级部门")
 private String dept2;

 @ExcelProperty("三级部门")
 private String dept3;

 @ExcelProperty("员工姓名")
 private String name;

 @ExcelProperty("工号")
 private String empNo;
}

写出：

1
2
3
4
5


List<EmployeeRow> rows = buildRows(orgTree);

EasyExcel.write("org.xlsx", EmployeeRow.class)
 .sheet("组织架构")
 .doWrite(rows);

四行代码，搞定基础导出。

三、把组织树展平成行

业务里组织通常是个树——要导出必须展开成扁平的行集合。

树结构

1
2
3
4
5
6
7


@Data
public class OrgNode {
 private Long id;
 private String name;
 private List<OrgNode> children;
 private List<Employee> employees;
}

DFS 展平

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


public List<EmployeeRow> flatten(List<OrgNode> roots) {
 List<EmployeeRow> rows = new ArrayList<>();
 for (OrgNode root : roots) {
 traverse(root, new ArrayDeque<>(), rows);
 }
 return rows;
}

private void traverse(OrgNode node, Deque<String> path, List<EmployeeRow> rows) {
 path.push(node.getName());

 if (node.getChildren() != null && !node.getChildren().isEmpty()) {
 for (OrgNode child : node.getChildren()) {
 traverse(child, path, rows);
 }
 }
 if (node.getEmployees() != null) {
 for (Employee e : node.getEmployees()) {
 EmployeeRow row = new EmployeeRow();
 // 把 path 从根到叶填到 dept1/2/3
 String[] depts = path.descendingIterator().hasNext()
 ? toArray(path.descendingIterator()) : new String[0];
 row.setDept1(depts.length > 0 ? depts[0] : "");
 row.setDept2(depts.length > 1 ? depts[1] : "");
 row.setDept3(depts.length > 2 ? depts[2] : "");
 row.setName(e.getName());
 row.setEmpNo(e.getEmpNo());
 rows.add(row);
 }
 }
 path.pop();
}

这一步得到了 Excel 的扁平行数据——树形被打平、每个员工对应一行。

四、单元格合并：组织树的核心

光打平还不够——同部门下多个员工，部门列应该合并。这是组织树导 Excel 最核心的需求。

思路：写完后再合并

EasyExcel 写时按行流式输出，不能在写入时直接判断"和上一行合并"。最稳妥的做法是：

先按扁平行写完
再用 POI 的 addMergedRegion 合并同列连续相同值

EasyExcel 提供了 WriteHandler 让你介入流程：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


public class TreeMergeHandler extends AbstractMergeStrategy {

 private final List<EmployeeRow> data;

 public TreeMergeHandler(List<EmployeeRow> data) { this.data = data; }

 @Override
 protected void merge(Sheet sheet, Cell cell, Head head, Integer relativeRowIndex) {
 // 处理 dept1, dept2, dept3 三列
 if (relativeRowIndex == null || relativeRowIndex == 0) return;

 int colIdx = cell.getColumnIndex();
 if (colIdx > 2) return; // 后两列不合并（员工姓名/工号列）

 int absoluteRow = cell.getRowIndex();
 String prevValue = sheet.getRow(absoluteRow - 1).getCell(colIdx).getStringCellValue();
 String currValue = cell.getStringCellValue();

 if (Objects.equals(prevValue, currValue)) {
 // 找到现有 region 并扩展，或新建
 for (int i = sheet.getNumMergedRegions() - 1; i >= 0; i--) {
 CellRangeAddress region = sheet.getMergedRegion(i);
 if (region.getFirstColumn() == colIdx
 && region.getLastRow() == absoluteRow - 1) {
 sheet.removeMergedRegion(i);
 sheet.addMergedRegion(new CellRangeAddress(
 region.getFirstRow(), absoluteRow, colIdx, colIdx));
 return;
 }
 }
 // 没找到，新建
 sheet.addMergedRegion(new CellRangeAddress(
 absoluteRow - 1, absoluteRow, colIdx, colIdx));
 }
 }
}

1
2
3
4


EasyExcel.write("org.xlsx", EmployeeRow.class)
 .registerWriteHandler(new TreeMergeHandler(rows))
 .sheet("组织架构")
 .doWrite(rows);

效果——同部门跨多行的部门列被合并成一个单元格。

五、样式：表头加粗 + 居中 + 边框

通过 HorizontalCellStyleStrategy 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


WriteCellStyle headerStyle = new WriteCellStyle();
headerStyle.setFillForegroundColor(IndexedColors.GREY_25_PERCENT.getIndex());
headerStyle.setHorizontalAlignment(HorizontalAlignment.CENTER);
WriteFont headerFont = new WriteFont();
headerFont.setFontHeightInPoints((short) 12);
headerFont.setBold(true);
headerStyle.setWriteFont(headerFont);

WriteCellStyle bodyStyle = new WriteCellStyle();
bodyStyle.setHorizontalAlignment(HorizontalAlignment.CENTER);
bodyStyle.setVerticalAlignment(VerticalAlignment.CENTER);
bodyStyle.setBorderTop(BorderStyle.THIN);
bodyStyle.setBorderBottom(BorderStyle.THIN);
bodyStyle.setBorderLeft(BorderStyle.THIN);
bodyStyle.setBorderRight(BorderStyle.THIN);

EasyExcel.write("org.xlsx", EmployeeRow.class)
 .registerWriteHandler(new HorizontalCellStyleStrategy(headerStyle, bodyStyle))
 .registerWriteHandler(new TreeMergeHandler(rows))
 .sheet("组织架构")
 .doWrite(rows);

六、列宽自适应

LongestMatchColumnWidthStyleStrategy 让列宽根据内容长度自适应：

1

.registerWriteHandler(new LongestMatchColumnWidthStyleStrategy())

注意——它的算法是按"行最长字符串"算列宽，对中文支持不够好（一个汉字算一个字符宽，但实际显示更宽）。生产里通常自己写一个：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


public class CJKColumnWidthHandler implements CellWriteHandler {
 @Override
 public void afterCellDispose(CellWriteHandlerContext ctx) {
 Cell cell = ctx.getCell();
 Sheet sheet = cell.getSheet();
 int colIdx = cell.getColumnIndex();
 int len = cell.getStringCellValue() != null
 ? estimateWidth(cell.getStringCellValue()) : 10;
 if (sheet.getColumnWidth(colIdx) < len * 256) {
 sheet.setColumnWidth(colIdx, Math.min(len * 256, 80 * 256));
 }
 }

 private int estimateWidth(String s) {
 int w = 0;
 for (char c : s.toCharArray()) {
 w += (c >= '一' && c <= '龥') ? 2 : 1;
 }
 return w;
 }
}

七、Web 接口下载

Spring Controller 写法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@GetMapping("/export/org")
public void export(HttpServletResponse response) throws IOException {
 response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
 response.setCharacterEncoding("utf-8");
 String fileName = URLEncoder.encode("组织架构", "UTF-8").replaceAll("\\+", "%20");
 response.setHeader("Content-disposition", "attachment;filename*=utf-8''" + fileName + ".xlsx");

 List<EmployeeRow> rows = orgService.flattenForExport();
 EasyExcel.write(response.getOutputStream(), EmployeeRow.class)
 .registerWriteHandler(new TreeMergeHandler(rows))
 .sheet("组织架构")
 .doWrite(rows);
}

文件名编码这块要小心——中文不处理浏览器下载会乱码。filename*=utf-8''xxx 是 RFC 5987 标准。

八、大数据量场景

数据量到几万、几十万行时，几个工程要点：

1. 用流式写

1
2
3
4
5
6
7
8


ExcelWriter writer = EasyExcel.write(outputStream, EmployeeRow.class).build();
WriteSheet sheet = EasyExcel.writerSheet("组织架构").build();
int batchSize = 1000;
for (int offset = 0; offset < total; offset += batchSize) {
 List<EmployeeRow> batch = orgService.getRows(offset, batchSize);
 writer.write(batch, sheet);
}
writer.finish();

每次只加载一批，JVM 内存不会爆。

2. 多 Sheet

单 Sheet 上限 1,048,576 行——超过要拆 Sheet：

1
2
3
4


for (int sheetNo = 0; sheetNo < sheetCount; sheetNo++) {
 WriteSheet sheet = EasyExcel.writerSheet(sheetNo, "Sheet" + sheetNo).build();
 writer.write(getRows(sheetNo), sheet);
}

3. 合并单元格的内存瓶颈

合并单元格的 addMergedRegion 信息是全量记录在内存里——大量合并会让导出再次膨胀。几万行 + 大量合并是 EasyExcel 也吃不消的场景——这种情况建议改用 CSV 或者拆分多 Sheet。

4. 异步导出

接口同步返回 30 秒会超时——大数据量必须异步：

flowchart LR
 User --> API[POST /export/job]
 API --> Job[创建任务记录]
 API --> Queue[发到 MQ]
 Worker[Worker] --> Queue
 Worker --> S3[导出到 S3/OSS]
 Worker --> Notify[推送通知/邮件]
 User --> Status[GET /export/status]
 Status --> S3

九、踩坑提醒

1. 模板模式 vs Bean 模式

简单导出用 @ExcelProperty 注解（Bean 模式）；表头复杂、含图片、需要复用的导出用 模板模式：

1
2
3
4


EasyExcel.write("out.xlsx")
 .withTemplate("template.xlsx")
 .sheet()
 .doWrite(data);

模板里用 {name} 占位符。

2. POI 版本冲突

EasyExcel 自带 POI 4.x，如果项目里有其他依赖引入了 POI 3.x，冲突会让 ClassNotFound。用 mvn dependency:tree 检查并 exclude。

3. 中文表头乱码

@ExcelProperty("中文表头") 一般没问题，但如果中文出现在动态字段（比如表头从配置读），要确保字符串编码 UTF-8。

4. 日期格式

1
2
3


@ExcelProperty("入职日期")
@DateTimeFormat("yyyy-MM-dd")
private LocalDate joinDate;

不加 @DateTimeFormat 会导成 Excel 的"序列号"格式（比如 44927）。

5. 数字精度

金额最好用 BigDecimal，并配合：

1
2
3


@ExcelProperty("金额")
@NumberFormat("#,##0.00")
private BigDecimal amount;

小结