跳转至

Excel 导入运行时（ExcelImportRuntimeController）

Excel 导入运行时接口：当导入配置未提供静态模板文件（templatePath 为空）而仅配置 JSON 模板（jsonTemplate）时，按 JSON 即时生成并下载 .xlsx 导入模板。

  • 接口类型：REST 资源（@Component 继承 AbstractRuntimeController；类级 produces = MediaType.APPLICATION_JSON_VALUE，但本端点直接写回 HttpServletResponse.getOutputStream() 为 Excel 文件下载，实际响应非 JSON，据源码）
  • 基址：${myapps.context-path.runtime:}/api/runtime
  • Tag：Excel 导入运行时

公共说明

  • 鉴权（据源码）：类级基址位于 /api/runtime/**，在 RestSecurityHandlerInterceptor 覆盖范围内，且不在豁免名单（豁免仅覆盖 /api/runtime/login.*、/api/runtime/dingding/authlogin、/api/runtime/synchronization.*、URI 以 /showjrxml 结尾、含 /getCustomColumnsInfos、含 /accessToken、含 /macro、以 /clear 结尾、含 /pages/ 等，详见 login.md「公共说明 · 鉴权」）。拦截器走 Security.getUserIdFromToken(request)，未取到再尝试 Security.getDebugUserIdFromToken(request)，两者皆无则拒绝。故需 accessToken（或 debugToken），可通过 Cookie / 请求头 / query 参数任一方式传递。控制器内 getUser()（继承自 AbstractRuntimeController）必须能取到非空 WebUser，否则在 DesUtil.decryptTextByUserId(applicationId, getUser().getId()) 时即抛 NPE。
  • 路径变量 {applicationId} / {configId}：必填，经 DES 加密（按当前执行用户密钥），服务端在方法入口处 DesUtil.decryptTextByUserId(applicationId, getUser().getId()) 与 DesUtil.decryptTextByUserId(configId, getUser().getId()) 解密。
  • 响应：本控制器端点直接写回 HttpServletResponse 输出流为 Excel 文件下载（不返回 JSON Resource）。响应头由 HttpDownloadHelper.setExcelAttachmentHeaders(response, filename) 设置（Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 等，按 HttpDownloadHelper 实现）。模板不存在或未配置 JSON 模板时抛 OBPMValidateException（由全局异常处理转化为错误响应）。

1. 动态导出 Excel 导入模板

当 templatePath 为空时，按 jsonTemplate 即时生成 .xlsx 并以附件形式下载。配置不存在或未配置 JSON 模板时抛 OBPMValidateException。

  • 接口类型：REST 资源（文件下载，二进制响应）
  • 请求方式：GET
  • 请求路径：/{applicationId}/excelimport/{configId}/export-excel（完整：{runtime-context}/api/runtime/{applicationId}/excelimport/{configId}/export-excel）
  • 鉴权：是（需 accessToken，据源码）
  • Tag：Excel 导入运行时

请求参数

参数名 位置 类型 必填 说明
applicationId path string 是 应用Id（DES 加密密文）
configId path string 是 Excel 导入配置Id（DES 加密密文）

请求示例

GET /api/runtime/__APPID__/excelimport/__CONFIGID__/export-excel HTTP/1.1
Cookie: accessToken=eyJhbGciOiJIUzI1NiJ9...

响应

结构：二进制 Excel 文件（.xlsx）附件下载；不返回 JSON Resource。

  • 成功：HTTP 200，Content-Type 由 HttpDownloadHelper.setExcelAttachmentHeaders 设置（Excel 附件相关头），Content-Disposition: attachment; filename="<configName>.xlsx"（<configName> 取自 IMPMappingConfigVO.getName()，缺名时为 excel-template.xlsx）。响应体为 ExcelTemplateExportService.exportFromTemplateJson(jsonTemplate, outputStream) 写出的 .xlsx 字节流。
  • 失败（配置不存在 / 未配置 JSON 模板）：抛 OBPMValidateException("Excel 导入配置不存在") / OBPMValidateException("未配置 JSON 模板，无法动态生成导入模板")，由 AbstractRuntimeController 全局异常处理转化为错误响应（具体形态视平台统一异常处理实现而定）。