应统一抛出自定义ExportException，继承RuntimeException并携带错误码与原始异常，避免直接throw RuntimeException，在导出逻辑中按场景主动封装抛出，配合@ControllerAdvice全局处理返回结构化响应。

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

<p>在 Java 中导出 Excel 时，若使用 Apache POI、EasyExcel 等库动态生成文件出错，应统一抛出自定义异常 <code>ExportException</code>，便于上层统一捕获和处理（如返回友好提示、记录日志、回滚事务等）。</p>

<H3>定义 ExportException</H3>
<p>继承 <code>RuntimeException</code>，避免强制 try-catch，同时支持携带错误码、消息、原始异常等信息：</p>
<p><font color="gray"><pre>public class ExportException extends RuntimeException {
    private final int errorCode;

    public ExportException(String message) {
        this(message, 500);
    }

    public ExportException(String message, int errorCode) {
        super(message);
        this.errorCode = errorCode;
    }

    public ExportException(String message, Throwable cause) {
        this(message, 500, cause);
    }

    public ExportException(String message, int errorCode, Throwable cause) {
        super(message, cause);
        this.errorCode = errorCode;
    }

    public int getErrorCode() {
        return errorCode;
    }
}</pre></font></p>

<H3>在导出逻辑中主动抛出</H3>
<p>不要依赖底层异常穿透，应在关键失败点主动封装并抛出 <code>ExportException</code>：</p>
<ul>
  <li>模板不存在或读取失败 → 抛出 <code>ExportException("导出模板未找到", 404)</code></li>
  <li>数据为空或校验不通过 → 抛出 <code>ExportException("无可导出数据", 400)</code></li>
  <li>POI 写入单元格时发生 <code>IllegalArgumentException</code> → 封装为 <code>ExportException("单元格值非法", 400, e)</code></li>
  <li>EasyExcel 回调中解析失败 → 在 <code>invoke()</code> 或 <code>doAfterAllAnalysed()</code> 中捕获并转为 <code>ExportException</code></li>
</ul>

<H3>避免直接 throw new RuntimeException</H3>
<p>常见错误是用通用异常掩盖业务语义：</p>
<ul>
  <li>❌ <code>throw new RuntimeException("导出失败");</code> —— 无法区分是网络、权限还是数据问题</li>
  <li>✅ <code>throw new ExportException("用户无导出权限", 403);</code> —— 明确错误类型与 HTTP 状态码映射</li>
  <li>✅ <code>throw new ExportException("日期格式不合法", 400, e);</code> —— 保留堆栈，方便排查</li>
</ul>

<H3>全局异常处理器统一响应</H3>
<p>Spring Boot 中可配合 <code>@ControllerAdvice</code> 捕获 <code>ExportException</code>，返回结构化 JSON 或重定向错误页：</p>
<p><font color="gray"><pre>@ExceptionHandler(ExportException.class)
public ResponseEntity<Map<String, Object>> handleExportException(ExportException e) {
    Map<String, Object> result = new HashMap<>();
    result.put("success", false);
    result.put("message", e.getMessage());
    result.put("code", e.getErrorCode());
    return ResponseEntity.status(e.getErrorCode()).body(result);
}</pre></font></p>