简介面向需要在Lotus Domino平台的浏览器服务器模式下处理Excel数据的开发人员是一份以LotusScript代理与Java代理双路线讲解数据导入导出的技术资料覆盖从视图批量导出数据到Excel、解析Excel文件并写入Notes文档、报表生成与数据迁移等常见场景适合正在做Domino后台功能开发或BS应用集成的工程师参考。资料从Java代理导出入手完整展示OutputToExcel类的实现先获取会话与代理上下文再定位数据库和视图建立PrintWriter输出对象通过设置application/vnd.ms-excel响应头让浏览器将输出识别为Excel随后用制表符分隔字段并调用getItemValue读取文档域值还点明多值域返回Vector后的处理方式。对导入方向则梳理出使用Apache POI打开Excel、逐行读取单元格数据、在Domino中新建或更新NotesDocument并保存的完整步骤并对比LotusScript下NotesDocument、NotesItem的用法差异。压缩包内只有1个doc文件大小35KB内容精炼可直接套用代码示例与分步说明适合作为速查资料。已有140人学习下载。1. 为什么在 Domino 的 B/S 开发里Excel 导入导出会让你反复翻车做过 Lotus Domino B/S 开发的人多半都遇到过同一个需求用户拿着 Excel 表格要批量导入系统或者要求页面数据能一键导出成 Excel 留档。这个需求听起来简单落地却很容易翻车。很多人习惯性在服务器上装一套 Office再用 LotusScript 的 OLE 去创建 Excel 对象结果就是任务挂起、Excel 进程残留、中文乱码、日期错位一个比一个玄学。反直觉的事实是真正稳定的方案不是「调用 Excel」而是「绕过 Excel」。本文按这条路线把 Excel 导入导出在 Domino 里的选型、代码、部署和踩坑一次说透适合 Domino 应用开发与运维人员也适合 Notes 系系统里做数据交换的同事参考。2. 选型先于编码LotusScript 代理和 Java 代理在 Excel 上的能力边界2.1 LotusScript 操作 Excel 的三条路线OLE、文本解析与 XMLLotusScript 代理处理 Excel 时常见做法有三条路线能力和代价完全不同。第一条是 OLE 自动化。通过 CreateObject(Excel.Application) 拿到一个 Excel 的 COM 对象然后像操作桌面 Excel 那样读写工作簿。这条路线最直观代码量也最少Dim xlApp As Variant Set xlApp CreateObject(Excel.Application) xlApp.Visible False xlApp.Workbooks.Open(C:\temp\template.xls) 直接改单元格值 xlApp.Cells(1,1).Value 张三 xlApp.ActiveWorkbook.Save xlApp.Quit逻辑并不复杂但落地时问题很多。OLE 依赖服务器装了 Office而且要求是 Windows 环境B/S 下的 HTTP 任务以服务方式跑没有桌面会话Excel 的 COM 对象经常会因为交互模式、权限、启动参数等问题报自动化错误。更麻烦的是进程管理任何一次异常退出没有走到 Quit任务管理器里就会多一个残留的 EXCEL.EXE久而久之服务器越来越卡。第二条路线是文本协议。把数据写成 CSV 或制表符分隔的文本文件扩展名改成 .xls 或 .csvExcel 都能打开。这条路线完全不依赖 Office 安装最适合导出导入时自己逐行解析文本即可。代价是拿不到 Excel 的样式、公式和多 Sheet 布局但大多数 B/S 场景要的就是数据本身样式反而是次要需求。第三条路线是直接解析 xlsx 的内部结构。xlsx 本质是一个 zip 压缩包里面是一堆 XML 文件理论上可以自己解包读 SharedStrings、sheet1.xml 这些内容。问题在于 LotusScript 不自带成熟的 zip 解压能力要借助第三方 LSX 扩展维护成本高遇到大文件性能也堪忧。我一般不推荐这条路除非项目禁止引入任何 Java 组件。2.2 Java 代理可以拿到什么POI 生态与类加载的部署约束Java 代理进入同一场景后局面完全不一样。Domino 设计器支持创建 Java 代理运行在 Domino 自带的 JVM 上可以调用第三方 Java 库。Excel 处理业界最常用的是 Apache POI它能读写 xls 和 xlsx、处理公式、日期、样式、合并单元格、大数据量导出这些恰好是 LotusScript 文本协议做不到的。需要清醒认识的是部署成本。Domino 的 Java 代理并不能像普通 Java Web 应用那样直接丢一个 war 包进去第三方 jar 必须放到 Domino JVM 能加载到的类路径里。常见做法是把 jar 复制到 Domino 程序目录下的 jvm/lib/ext 目录然后重启 HTTP 任务代理的类加载器才会看到这些类。我记得第一次这么干的时候重启 HTTP 后代理还是 ClassNotFoundException后来确认是放错了目录——Domino 服务器的程序目录和数据目录不是同一个jar 必须放到程序目录的 jvm/lib/ext 下。另一个约束是 JVM 版本兼容。不同版本的 Domino 自带的 JVM 差别很大POI 的新版本往往要求较高版本的 Java 运行时。直接把最新版 POI 扔进去跑起来很容易报 UnsupportedClassVersionError。稳妥的做法是先看当前 Domino 的 java -version再选一个发布时间对得上的 POI 版本。不要为了追新而给自己埋雷。2.3 一张选型表对应三种常见业务规模结合上面两条线我把实际项目中见过的匹配关系整理成一张表。没做过的人最容易在这里选错。业务场景推荐方案核心理由主要风险后台导出 5000 行以内报表LotusScript 输出 CSV零依赖飘轻快无格式需处理逗号和换行用户上传 xlsx 批量导入Java 代理 POI自动识别 xls/xlsx单元格解析可靠需要部署 jar注意类路径Windows 服务器且 Office 环境可控LotusScript OLE能写样式、多 Sheet、公式进程残留服务器会越跑越慢混合场景、多人同时上传大文件Java 代理 SXSSFWorkbook流式写 Sheet内存可控代码复杂度上升从这张表能看出来我并不是无条件反对用 OLE。如果系统只在内网用服务器 Windows 版本和 Office 版本都统一处理的是小文件那么 LotusScript OLE 在写格式这件事上确实比 CSV 方便。但只要是 B/S 模式、面向多个用户、服务器环境不可控我的习惯是直接砍掉 OLE导出走 CSV 或 Java导入走 POI。还有一类场景值得单独说用户上传的 Excel 往往并不规范比如表头有两行、中间有空行、日期列混着文本和序列号。这类「脏数据」导入LotusScript 文本方式解析会很吃力Java 代理里配合 POI 的行遍历和单元格类型判断会从容得多。所以很多项目最终会同时保留两个代理轻量导出走 LotusScript复杂导入走 Java。3. LotusScript 代理实现导入导出三块最小代码把流程跑通3.1 导出把视图数据写成 Excel 能直接打开的 CSV先给一段最精简但能直接跑的导出代理。它的目标是把一个视图里的每条文档转成一行 CSV最终生成的文件用 Excel 或 WPS 双击就能打开。Sub Initialize Dim session As New NotesSession Dim db As NotesDatabase Dim view As NotesView Dim doc As NotesDocument Dim fnum As Integer Set db session.CurrentDatabase Set view db.GetView(LotusByName) 目标文件路径建议放在 Domino 数据目录下 fnum Freefile() Open C:\DominoData\temp\export.csv For Output As fnum 第一行写 UTF-8 BOM避免用 Excel 打开时中文乱码 Print #fnum, Chr(239) Chr(187) Chr(191) 表头行列名和最终 Excel 里的列一一对应 Print #fnum, 姓名,工号,部门,金额,登记日期 Set doc view.GetFirstDocument Do While Not doc Is Nothing Dim name As String Dim empNo As String Dim dept As String Dim amount As String Dim regDate As String GetItemValue 返回的是数组取第一个值 name CleanField(CStr(doc.GetItemValue(fullname)(0))) empNo CleanField(CStr(doc.GetItemValue(empNo)(0))) dept CleanField(CStr(doc.GetItemValue(dept)(0))) amount CStr(doc.GetItemValue(amount)(0)) regDate Format$(doc.GetItemValue(regDate)(0), yyyy-mm-dd) 每行字段用逗号分隔 Print #fnum, name , empNo , dept , amount , regDate Set doc view.GetNextDocument(doc) Loop Close #fnum End Sub Function CleanField(ByVal value As String) As String 逗号、双引号、回车都会破坏 CSV 结构统一处理 value Replace(value, Chr(34), ) value Replace(value, Chr(13), ) value Replace(value, Chr(10), ) If InStr(value, ,) 0 Then CleanField value Else CleanField value End If End Function这段代码有几个参数值得说明。Open 的目标路径是写死的实际项目中应改成从配置文档或环境变量读取否则每个数据库都要改一遍。视图名 LotusByName 是示例你需要替换成自己数据库里的视图。Print #fnum 是 LotusScript 里写文件的经典方式第二行先输出 BOM 是为了让 Excel 打开时正确识别 UTF-8 编码否则中文很容易变成问号。CleanField 函数解决的是 CSV 字段转义问题。真实业务数据里地址、备注这类字段经常携带逗号和换行直接拼进 CSV 会让 Excel 打开后整列错位。这里先去掉换行再把含逗号的字段用双引号包起来是 CSV 的标准转义规则。金额字段没有做处理如果它是数值且包含千分位导出的结果 Excel 会当成文本这一点在后续避坑章展开。3.2 导入B/S 上传后的附件释放与逐行解析导入比导出多一个环节用户在前端上传文件Domino 会把文件作为附件存到一个文档里代理需要先把附件释放到磁盘再读取解析。以下代码展示的是从一张「待导入」表单里取附件、释放、逐行读 CSV 的过程。Dim db As NotesDatabase Dim uploadDoc As NotesDocument Dim attach As NotesEmbeddedObject Dim fnum As Integer Dim lineText As String Set db session.CurrentDatabase 实际项目中这里用搜索或 URL 参数定位待导入文档 Set uploadDoc db.GetDocumentByUNID(527D9B...) Set attach uploadDoc.GetAttachment(file) If Not attach Is Nothing Then Call attach.ExtractFile(C:\DominoData\temp\upload.csv) End If fnum Freefile() Open C:\DominoData\temp\upload.csv For Input As fnum 跳过表头行先读一行再进入循环 Line Input #fnum, lineText Do Until EOF(fnum) Line Input #fnum, lineText 空行直接跳过避免生成本空文档 If Trim(lineText) Then GoTo nextLine Dim fields() As String fields Split(lineText, ,) If Ubound(fields) 4 Then GoTo nextLine Dim newDoc As NotesDocument Set newDoc db.CreateDocument newDoc.Form Employee newDoc.fullname fields(0) newDoc.empNo fields(1) newDoc.dept fields(2) newDoc.amount fields(3) newDoc.regDate fields(4) Call newDoc.Save(True, False) nextLine: Loop Close #fnum这里有几个点新手容易踩。ExtractFile 的目标目录必须事先存在否则会报文件写入失败我在项目里通常会在 Open 之前调用 Mkdir 语句创建目录。Line Input 一次读一行遇到包含换行的字段会被截断所以上一节导出时才要把换行替换掉——这两个环节必须对称。Split 按逗号切分是个偷懒做法只能应对简单数据。如果上传的 CSV 里有字段带双引号和逗号这里就会错列。要做得严谨需要写一个状态机来解析但绝大多数内部表格不会那么复杂所以先把 Split 作为第一步跑通后续再换解析库。每个字段写入文档后调用 Save(True, False)第一个参数表示强制保存第二个参数 False 表示不生成回执这个口诀可以记一下。3.3 URL 触发代理OpenAgent 传参与返回方式B/S 模式下代理不是点了 Designer 里的运行按钮才跑而是通过浏览器访问一个专门 URL 来触发。最标准的格式是http://server/app.nsf/impAgent?OpenAgenttypeimportfileId527D9B...问号后面的 OpenAgent 告诉 Domino 这是一个代理请求不是打开文档。后续的 type 和 fileId 是自定义参数。在 LotusScript 代理里可以用 session.DocumentContext 拿到这些参数Dim ctx As NotesSession Dim params As Variant Set ctx New NotesSession() DocumentContext 里的 Query_String 是原始参数串 params ctx.DocumentContext.Query_String(0)写代码时要注意New NotesSession()和 Initialize 里自带的 session 都是合法写法但代理被 Web 调用时必须从当前请求上下文里取参数而不是读环境变量。代理能否被 Web 调用需要在代理的属性里设置允许 Web 用户运行否则浏览器访问会直接返回 403 或报权限不足。输出方式上LotusScript 代理可以通过 Print 直接往响应流里写内容。返回 HTML 片段是最常见做法如果做下载场景可以返回一段带定时跳转的页面或者在响应头里设置 Content-Disposition 触发保存。Domino 对响应头的控制能力有限我的习惯是文件先写到服务器临时目录再给前端一个下载 URL这样比在代理里拼大段 Base64 更稳。4. Java 代理实现导入导出POI 部署、读取与日期统一处理4.1 把 POI 装进 Domino 运行时jvm/lib/ext 与类加载检查Java 代理接入 POI 的第一步不是写代码而是让 Domino 的 JVM 能找到这些 jar。常规做法如下# 进入 Domino 程序目录不是数据目录 cd $DIRECTION/domino/jvm/lib/ext # 把 POI 及依赖 jar 复制到这里至少包含 poi、poi-ooxml、xmlbeans ls -l poi*.jar # 重启 HTTP 任务让类加载器重新扫描 tell http restart命令里的$DIRECTION/domino是占位Windows 上安装路径通常是C:\Program Files\HCL\DominoLinux 上常见路径是/opt/ibm/domino或/opt/hcl/domino。判断是否生效的方式有两个一个是看代理运行时报的异常是否已经从 ClassNotFoundException 变成了业务错误另一个是用一段极小的 Java 代理输出当前 ClassLoader 里有没有 POI 的类文件。很多人忽略第二个验证结果把 jar 放到了数据目录重启了半天也没效果。类路径冲突也要留意。Domino 自带的 JVM 里本身有一些基础库如果你的 POI 版本里带的依赖和服务器已有 jar 重名、且版本不一致可能在加载时互相覆盖。表现很迷惑同一个代理在测试服务器上正常生产环境就报 AbstractMethodError。这类问题没有快捷排查手段只能是先把所有 POI 相关 jar 的清单列出来对比两边的 JVM 是否有同包名的旧版本。4.2 Java 代理导出 ExcelXSSFWorkbook 的最小写法下面这段代码把一个视图数据写成 xlsx 文件。它涉及 POI 最核心的 Workbook、Sheet、Row、Cell 四级结构。import lotus.domino.*; import org.apache.poi.ss.usermodel.*; import org.apache.poi.xssf.usermodel.XSSFWorkbook; import java.io.FileOutputStream; public class ExcelExport extends AgentBase { public void NotesMain() { try { Session session getSession(); AgentContext ctx session.getAgentContext(); Database db ctx.getCurrentDatabase(); View view db.getView(LotusByName); Workbook wb new XSSFWorkbook(); Sheet sheet wb.createSheet(台账); String[] headers {姓名, 工号, 部门, 金额, 登记日期}; Row headerRow sheet.createRow(0); for (int i 0; i headers.length; i) { headerRow.createCell(i).setCellValue(headers[i]); } Document doc view.getFirstDocument(); int rowIdx 1; while (doc ! null) { Row row sheet.createRow(rowIdx); row.createCell(0).setCellValue(doc.getItemValueString(fullname)); row.createCell(1).setCellValue(doc.getItemValueString(empNo)); row.createCell(2).setCellValue(doc.getItemValueString(dept)); row.createCell(3).setCellValue(doc.getItemValueDouble(amount)); row.createCell(4).setCellValue(doc.getItemValueString(regDate)); doc view.getNextDocument(doc); } FileOutputStream out new FileOutputStream(/tmp/export.xlsx); wb.write(out); out.close(); wb.close(); } catch (Exception e) { e.printStackTrace(); } } }关键参数在 createRow 和 createCell 的下标上Excel 的行和列都从 0 开始第一行做表头所以第二行行号是 1。getItemValueString 适合文本字段金额列我改成了 getItemValueDouble这样写到 Excel 里以后是真正的数字类型Excel 数据分析时可以直接求和。如果全部用字符串写入导出文件能看但用户一排序一求和就报错。文件写到 /tmp/export.xlsx 后还要考虑如何给用户下载。常见做法是 Java 代理里再通过 response 输出流把文件内容返回或者在 Domino 里建一个下载视图让前端拼 URL。我更倾向于后者因为 Domino 天生支持附件下载没必要让代理二次处理二进制流。4.3 Java 代理导入 ExcelWorkbookFactory 解析上传文件导入侧的关键是用 WorkbookFactory 而不是手动判断文件后缀。WorkbookFactory.create 会自动识别 xls 和 xlsx省去一层 if。以下代码从待导入文档中取出附件解析 Sheet 后逐行建文档。import lotus.domino.*; import org.apache.poi.ss.usermodel.*; import java.io.File; public class ExcelImport extends AgentBase { public void NotesMain() { try { Session session getSession(); AgentContext ctx session.getAgentContext(); Database db ctx.getCurrentDatabase(); // 定位待导入文档这里只是示例筛选条件 Document uploadDoc db.search(Form\ImportTemp\, null, 1).getFirstDocument(); EmbeddedObject attach uploadDoc.getAttachment(file); String tempFile /tmp/import.xlsx; // 释放前确认目录存在POI 不会自动建目录 attach.extractFile(tempFile); Workbook wb WorkbookFactory.create(new File(tempFile)); Sheet sheet wb.getSheetAt(0); // 第一行往往是表头从第二行开始读 for (int i 1; i sheet.getLastRowNum(); i) { Row row sheet.getRow(i); if (row null || isRowEmpty(row)) { continue; } Document newDoc db.createDocument(); newDoc.replaceItemValue(Form, Employee); newDoc.replaceItemValue(fullname, getCellValue(row.getCell(0))); newDoc.replaceItemValue(empNo, getCellValue(row.getCell(1))); newDoc.replaceItemValue(dept, getCellValue(row.getCell(2))); newDoc.replaceItemValue(amount, getCellValue(row.getCell(3))); newDoc.replaceItemValue(regDate, getCellValue(row.getCell(4))); newDoc.save(true, false); } wb.close(); } catch (Exception e) { e.printStackTrace(); } } private static boolean isRowEmpty(Row row) { for (int i row.getFirstCellNum(); i row.getLastCellNum(); i) { Cell cell row.getCell(i); if (cell ! null !getCellValue(cell).trim().isEmpty()) { return false; } } return true; } }这段代码里有三个位置容易翻车。第一个是getFirstDocument()如果数据库里没有符合条件的文档返回的是 null后面取附件就会空指针生产代码必须加判空。第二个是sheet.getLastRowNum()它返回的是最大行号而不是总行数中间有空行时用这个循环没问题但要注意最后一行的索引。第三个是row.getCell(i)POI 在读取稀疏行时可能返回 null所以 getCellValue 里必须处理空指针不能无脑调用。导入性能上逐行 createDocument 再 save 是典型的慢路径。几千行数据可以接受如果单次导入几万行建议先落到临时视图或数组最后批量提交否则用户会在页面等得很焦虑。POI 本身的解析速度没有问题瓶颈基本都在 Domino 的文档写入上。4.4 单元格统一取值DateUtil、DataFormatter 与精度处理导入 Excel 时读取单元格最忌讳直接cell.getStringCellValue()。原因很简单一个用户手动输入的「2024-05-01」可能是字符串、可能是日期格式、还可能是一个肉眼看不出来的公式。统一取值的方法能省掉大半多格式兼容问题。import org.apache.poi.ss.usermodel.*; import java.text.SimpleDateFormat; import java.text.DecimalFormat; private static String getCellValue(Cell cell) { if (cell null) { return ; } if (cell.getCellType() CellType.NUMERIC) { // 判断是不是真正的日期单元格 if (DateUtil.isCellDateFormatted(cell)) { SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd); return sdf.format(cell.getDateCellValue()); } // 长数字列用 DecimalFormat 避免科学计数法 DecimalFormat df new DecimalFormat(0); return df.format(cell.getNumericCellValue()); } // 其余情况包括文本、公式、空白统统交给 DataFormatter DataFormatter formatter new DataFormatter(); return formatter.formatCellValue(cell); }DateUtil.isCellDateFormatted 是判断日期单元格的官方手段它检查的是单元格的格式编码而不是值本身。DecimalFormat 处理身份证号、银行卡号这类长数字时尤其重要否则 POI 会把 1234567890123456 读成 1.234567890123456E15导入数据库后看起来就像乱码。DataFormatter 是兜底它能按单元格的显示格式输出文本对公式单元格返回计算结果。这个组合基本覆盖了用户上传表格时能想到的各种情况。5. 避坑Excel 导入导出最容易翻车的五个现场5.1 导出的 CSV 用 Excel 打开后中文全是问号现象代理跑完文件下载后用 Excel 打开中文全部变成???或者直接乱码英文和数字正常。原因LotusScript 的 Print 语句往文件写内容时使用的是服务器当前语言环境对应的编码。如果 Domino 服务器是英文系统或者没有装中文字体支持写进文件的就是非 UTF-8 字节Excel 打开时按本地编码解析自然对不上。解决在 CSV 文件第一行写入 UTF-8 BOM也就是Chr(239) Chr(187) Chr(191)让 Excel 强制用 UTF-8 解码。Java 代理里同样处理用 OutputStreamWriter 指定 UTF-8并且写内容前先输出\ufeff。我见过有人只在代码里改了中文内容漏加 BOM结果问题依旧所以这两步必须一起做。5.2 Excel 里的日期导入系统后变成一串数字现象用户表格里明明是「2024-05-01」导入系统后成了 45413或者年份月份错乱导出再回写时日期面目全非。原因Excel 里日期本质是自 1900 年 1 月 1 日以来的序列号。POI 的 getNumericCellValue 拿到的是这个序列号LotusScript 用 OLE 读 Value 也一样。不判断单元格格式的话日期就是普通数字。解决Java 侧必须用DateUtil.isCellDateFormatted(cell)先判断再走 getDateCellValue 加 SimpleDateFormat 格式化。LotusScript 文本解析则要把「看起来像日期」的列单独硬解析一次写个正则把常见的yyyy-mm-dd和yyyy/mm/dd归一化。这里最容易翻车的是两种写法混用有人前几行是文本日期后几行是日期格式导入结果一半对一半错。统一走 4.4 的 getCellValue 就不存在这个问题。5.3 用 OLE 的代理在 Windows 服务器上挂起现象代理调用 Excel 后报「自动化错误」同时任务管理器里的 EXCEL.EXE 进程数量持续增长服务器响应越来越慢最后只能重启机器。原因OLE 在服务器环境下每次调用都可能新起一个 Excel 实例任何一个异常分支没走到 Quit实例就常驻内存。服务器没有交互桌面Excel 崩溃时用户根本看不到弹窗于是进程就成了黑匣子越积越多。解决所有 OLE 分支必须保证最后执行 Quit包括错误分支。更彻底的做法是放弃 OLE导出改用 CSV 文本导入改用 Java POI。如果你的服务器已经被残留进程拖垮先taskkill /F /IM EXCEL.EXE清理再决定代码方向。进程管理是 OLE 方案的根本痛点不是补几个 Quit 就能根治的。5.4 Web 上传的附件在代理里提示文件不存在现象用户在前端页面上传 Excel 成功代理运行时报 FileNotFoundException文件路径明明复制过去也能看到但代理就是读不到。原因Domino B/S 的上传文件在落到数据库之前可能先被写到服务器临时目录如果你的代理里直接引用了临时路径HTTP 任务的临时目录清理策略会把它删掉。另一个常见原因是附件对象还没有从文档里释放出来只是存在数据库的 rich text 字段里你拿一个「逻辑文件名」按普通文件去打开自然找不到。解决先通过 NotesEmbeddedObject 或 Java 侧doc.getAttachment(file)拿到附件对象再调用extractFile释放到绝对路径最后读取这个释放出来的文件。释放之前先创建目标目录例如用一个启动时自动建立 temp 目录的公共函数。排查这类问题第一步永远是在代理里输出实际文件路径和 File.exists 的结果不要靠猜。5.5 用户调用代理报 403 或者身份错乱现象自己在 Designer 里运行代理一切正常普通用户在浏览器访问就报 403或者导入的数据写入者全是某个管理员账号明明用户自己登录的。原因代理属性里的「运行时身份」设错了。B/S 代理被 URL 触发时运行时身份可以选「以 Web 用户身份运行」或「以代理作者身份运行」。如果选了后者ACL 里没给调用者执行权限就会 403如果选了前者但数据库 ACL 对匿名用户开放的权限太大则可能绕过用户名限制。解决一般登录系统的数据操作代理要选「以 Web 用户身份运行」这样写入者才是当前用户。供管理员批量导数据的专用导入代理可以改成「以代理作者身份运行」但必须在代理入口校验用户角色。另外客户端本机如果装了安全软件或者 Excel 加载项被禁用页面弹出的自动化错误往往会误导排查方向这种错误要先去服务器看 nsd 日志别被客户端弹窗带着走。6. 把导入导出沉淀成公共模块接口化、日志与回归验证6.1 接口化用参数驱动一个代理代理和代码最忌讳复制粘贴后再改字段名。同一个导入逻辑A 系统导员工B 系统导资产差别只是字段映射和表头位置。抽出公共参数后一个导入代理就能应对多个场景。我习惯用四个入参视图名或文档筛选条件、Excel 列与字段映射、输出文件路径、导入模式新建还是更新。映射关系通常放在配置文档里而不是写死在代码里。这样做的直接收益是日志也统一了。每次导入把成功行数、失败行数、首条报错记录写到日志数据库用户发现问题时可以直接从日志里看到是哪一行哪一列错了配合 Excel 快速定位错位数据比让用户口头描述「有个文件导不进去」高效得多。6.2 回归验证一份故意做坏的 Excel我现在每个 Domino 项目里都会固定维护一份「错乱测试专用.xlsx」里面故意放空行、合并单元格、长数字、日期序列号、文本形式日期、带逗号的地址、超长文本。每次改完导入代码先拿它跑一遍回归再放真实数据。需求沟通阶段的字段映射表直接用 Markdown 表格列出来再转成 Excel 字段模板给用户确认能提前挡掉大量「我以为这个列是日期」式的返工。这个习惯是从一次线上事故里学来的当时用户导入的表格里身份证号列被 Excel 自动转成了科学计数法我这边没做精度处理几千条数据导进去全部尾部归零只能让用户重新提交。从那以后凡是涉及 Excel 数据对接我第一件事就是问清字段类型和最大长度然后按最坏情况准备测试文件。把这个验证步骤固化到团队里Excel 导入导出这类需求才能真正从「能跑」变成「敢上线」。希望帮到你。本文还有配套的精品资源点击获取
Domino中Excel导入导出稳定方案：绕过OLE，用LotusScript与Java代理避坑
简介面向需要在Lotus Domino平台的浏览器服务器模式下处理Excel数据的开发人员是一份以LotusScript代理与Java代理双路线讲解数据导入导出的技术资料覆盖从视图批量导出数据到Excel、解析Excel文件并写入Notes文档、报表生成与数据迁移等常见场景适合正在做Domino后台功能开发或BS应用集成的工程师参考。资料从Java代理导出入手完整展示OutputToExcel类的实现先获取会话与代理上下文再定位数据库和视图建立PrintWriter输出对象通过设置application/vnd.ms-excel响应头让浏览器将输出识别为Excel随后用制表符分隔字段并调用getItemValue读取文档域值还点明多值域返回Vector后的处理方式。对导入方向则梳理出使用Apache POI打开Excel、逐行读取单元格数据、在Domino中新建或更新NotesDocument并保存的完整步骤并对比LotusScript下NotesDocument、NotesItem的用法差异。压缩包内只有1个doc文件大小35KB内容精炼可直接套用代码示例与分步说明适合作为速查资料。已有140人学习下载。1. 为什么在 Domino 的 B/S 开发里Excel 导入导出会让你反复翻车做过 Lotus Domino B/S 开发的人多半都遇到过同一个需求用户拿着 Excel 表格要批量导入系统或者要求页面数据能一键导出成 Excel 留档。这个需求听起来简单落地却很容易翻车。很多人习惯性在服务器上装一套 Office再用 LotusScript 的 OLE 去创建 Excel 对象结果就是任务挂起、Excel 进程残留、中文乱码、日期错位一个比一个玄学。反直觉的事实是真正稳定的方案不是「调用 Excel」而是「绕过 Excel」。本文按这条路线把 Excel 导入导出在 Domino 里的选型、代码、部署和踩坑一次说透适合 Domino 应用开发与运维人员也适合 Notes 系系统里做数据交换的同事参考。2. 选型先于编码LotusScript 代理和 Java 代理在 Excel 上的能力边界2.1 LotusScript 操作 Excel 的三条路线OLE、文本解析与 XMLLotusScript 代理处理 Excel 时常见做法有三条路线能力和代价完全不同。第一条是 OLE 自动化。通过 CreateObject(Excel.Application) 拿到一个 Excel 的 COM 对象然后像操作桌面 Excel 那样读写工作簿。这条路线最直观代码量也最少Dim xlApp As Variant Set xlApp CreateObject(Excel.Application) xlApp.Visible False xlApp.Workbooks.Open(C:\temp\template.xls) 直接改单元格值 xlApp.Cells(1,1).Value 张三 xlApp.ActiveWorkbook.Save xlApp.Quit逻辑并不复杂但落地时问题很多。OLE 依赖服务器装了 Office而且要求是 Windows 环境B/S 下的 HTTP 任务以服务方式跑没有桌面会话Excel 的 COM 对象经常会因为交互模式、权限、启动参数等问题报自动化错误。更麻烦的是进程管理任何一次异常退出没有走到 Quit任务管理器里就会多一个残留的 EXCEL.EXE久而久之服务器越来越卡。第二条路线是文本协议。把数据写成 CSV 或制表符分隔的文本文件扩展名改成 .xls 或 .csvExcel 都能打开。这条路线完全不依赖 Office 安装最适合导出导入时自己逐行解析文本即可。代价是拿不到 Excel 的样式、公式和多 Sheet 布局但大多数 B/S 场景要的就是数据本身样式反而是次要需求。第三条路线是直接解析 xlsx 的内部结构。xlsx 本质是一个 zip 压缩包里面是一堆 XML 文件理论上可以自己解包读 SharedStrings、sheet1.xml 这些内容。问题在于 LotusScript 不自带成熟的 zip 解压能力要借助第三方 LSX 扩展维护成本高遇到大文件性能也堪忧。我一般不推荐这条路除非项目禁止引入任何 Java 组件。2.2 Java 代理可以拿到什么POI 生态与类加载的部署约束Java 代理进入同一场景后局面完全不一样。Domino 设计器支持创建 Java 代理运行在 Domino 自带的 JVM 上可以调用第三方 Java 库。Excel 处理业界最常用的是 Apache POI它能读写 xls 和 xlsx、处理公式、日期、样式、合并单元格、大数据量导出这些恰好是 LotusScript 文本协议做不到的。需要清醒认识的是部署成本。Domino 的 Java 代理并不能像普通 Java Web 应用那样直接丢一个 war 包进去第三方 jar 必须放到 Domino JVM 能加载到的类路径里。常见做法是把 jar 复制到 Domino 程序目录下的 jvm/lib/ext 目录然后重启 HTTP 任务代理的类加载器才会看到这些类。我记得第一次这么干的时候重启 HTTP 后代理还是 ClassNotFoundException后来确认是放错了目录——Domino 服务器的程序目录和数据目录不是同一个jar 必须放到程序目录的 jvm/lib/ext 下。另一个约束是 JVM 版本兼容。不同版本的 Domino 自带的 JVM 差别很大POI 的新版本往往要求较高版本的 Java 运行时。直接把最新版 POI 扔进去跑起来很容易报 UnsupportedClassVersionError。稳妥的做法是先看当前 Domino 的 java -version再选一个发布时间对得上的 POI 版本。不要为了追新而给自己埋雷。2.3 一张选型表对应三种常见业务规模结合上面两条线我把实际项目中见过的匹配关系整理成一张表。没做过的人最容易在这里选错。业务场景推荐方案核心理由主要风险后台导出 5000 行以内报表LotusScript 输出 CSV零依赖飘轻快无格式需处理逗号和换行用户上传 xlsx 批量导入Java 代理 POI自动识别 xls/xlsx单元格解析可靠需要部署 jar注意类路径Windows 服务器且 Office 环境可控LotusScript OLE能写样式、多 Sheet、公式进程残留服务器会越跑越慢混合场景、多人同时上传大文件Java 代理 SXSSFWorkbook流式写 Sheet内存可控代码复杂度上升从这张表能看出来我并不是无条件反对用 OLE。如果系统只在内网用服务器 Windows 版本和 Office 版本都统一处理的是小文件那么 LotusScript OLE 在写格式这件事上确实比 CSV 方便。但只要是 B/S 模式、面向多个用户、服务器环境不可控我的习惯是直接砍掉 OLE导出走 CSV 或 Java导入走 POI。还有一类场景值得单独说用户上传的 Excel 往往并不规范比如表头有两行、中间有空行、日期列混着文本和序列号。这类「脏数据」导入LotusScript 文本方式解析会很吃力Java 代理里配合 POI 的行遍历和单元格类型判断会从容得多。所以很多项目最终会同时保留两个代理轻量导出走 LotusScript复杂导入走 Java。3. LotusScript 代理实现导入导出三块最小代码把流程跑通3.1 导出把视图数据写成 Excel 能直接打开的 CSV先给一段最精简但能直接跑的导出代理。它的目标是把一个视图里的每条文档转成一行 CSV最终生成的文件用 Excel 或 WPS 双击就能打开。Sub Initialize Dim session As New NotesSession Dim db As NotesDatabase Dim view As NotesView Dim doc As NotesDocument Dim fnum As Integer Set db session.CurrentDatabase Set view db.GetView(LotusByName) 目标文件路径建议放在 Domino 数据目录下 fnum Freefile() Open C:\DominoData\temp\export.csv For Output As fnum 第一行写 UTF-8 BOM避免用 Excel 打开时中文乱码 Print #fnum, Chr(239) Chr(187) Chr(191) 表头行列名和最终 Excel 里的列一一对应 Print #fnum, 姓名,工号,部门,金额,登记日期 Set doc view.GetFirstDocument Do While Not doc Is Nothing Dim name As String Dim empNo As String Dim dept As String Dim amount As String Dim regDate As String GetItemValue 返回的是数组取第一个值 name CleanField(CStr(doc.GetItemValue(fullname)(0))) empNo CleanField(CStr(doc.GetItemValue(empNo)(0))) dept CleanField(CStr(doc.GetItemValue(dept)(0))) amount CStr(doc.GetItemValue(amount)(0)) regDate Format$(doc.GetItemValue(regDate)(0), yyyy-mm-dd) 每行字段用逗号分隔 Print #fnum, name , empNo , dept , amount , regDate Set doc view.GetNextDocument(doc) Loop Close #fnum End Sub Function CleanField(ByVal value As String) As String 逗号、双引号、回车都会破坏 CSV 结构统一处理 value Replace(value, Chr(34), ) value Replace(value, Chr(13), ) value Replace(value, Chr(10), ) If InStr(value, ,) 0 Then CleanField value Else CleanField value End If End Function这段代码有几个参数值得说明。Open 的目标路径是写死的实际项目中应改成从配置文档或环境变量读取否则每个数据库都要改一遍。视图名 LotusByName 是示例你需要替换成自己数据库里的视图。Print #fnum 是 LotusScript 里写文件的经典方式第二行先输出 BOM 是为了让 Excel 打开时正确识别 UTF-8 编码否则中文很容易变成问号。CleanField 函数解决的是 CSV 字段转义问题。真实业务数据里地址、备注这类字段经常携带逗号和换行直接拼进 CSV 会让 Excel 打开后整列错位。这里先去掉换行再把含逗号的字段用双引号包起来是 CSV 的标准转义规则。金额字段没有做处理如果它是数值且包含千分位导出的结果 Excel 会当成文本这一点在后续避坑章展开。3.2 导入B/S 上传后的附件释放与逐行解析导入比导出多一个环节用户在前端上传文件Domino 会把文件作为附件存到一个文档里代理需要先把附件释放到磁盘再读取解析。以下代码展示的是从一张「待导入」表单里取附件、释放、逐行读 CSV 的过程。Dim db As NotesDatabase Dim uploadDoc As NotesDocument Dim attach As NotesEmbeddedObject Dim fnum As Integer Dim lineText As String Set db session.CurrentDatabase 实际项目中这里用搜索或 URL 参数定位待导入文档 Set uploadDoc db.GetDocumentByUNID(527D9B...) Set attach uploadDoc.GetAttachment(file) If Not attach Is Nothing Then Call attach.ExtractFile(C:\DominoData\temp\upload.csv) End If fnum Freefile() Open C:\DominoData\temp\upload.csv For Input As fnum 跳过表头行先读一行再进入循环 Line Input #fnum, lineText Do Until EOF(fnum) Line Input #fnum, lineText 空行直接跳过避免生成本空文档 If Trim(lineText) Then GoTo nextLine Dim fields() As String fields Split(lineText, ,) If Ubound(fields) 4 Then GoTo nextLine Dim newDoc As NotesDocument Set newDoc db.CreateDocument newDoc.Form Employee newDoc.fullname fields(0) newDoc.empNo fields(1) newDoc.dept fields(2) newDoc.amount fields(3) newDoc.regDate fields(4) Call newDoc.Save(True, False) nextLine: Loop Close #fnum这里有几个点新手容易踩。ExtractFile 的目标目录必须事先存在否则会报文件写入失败我在项目里通常会在 Open 之前调用 Mkdir 语句创建目录。Line Input 一次读一行遇到包含换行的字段会被截断所以上一节导出时才要把换行替换掉——这两个环节必须对称。Split 按逗号切分是个偷懒做法只能应对简单数据。如果上传的 CSV 里有字段带双引号和逗号这里就会错列。要做得严谨需要写一个状态机来解析但绝大多数内部表格不会那么复杂所以先把 Split 作为第一步跑通后续再换解析库。每个字段写入文档后调用 Save(True, False)第一个参数表示强制保存第二个参数 False 表示不生成回执这个口诀可以记一下。3.3 URL 触发代理OpenAgent 传参与返回方式B/S 模式下代理不是点了 Designer 里的运行按钮才跑而是通过浏览器访问一个专门 URL 来触发。最标准的格式是http://server/app.nsf/impAgent?OpenAgenttypeimportfileId527D9B...问号后面的 OpenAgent 告诉 Domino 这是一个代理请求不是打开文档。后续的 type 和 fileId 是自定义参数。在 LotusScript 代理里可以用 session.DocumentContext 拿到这些参数Dim ctx As NotesSession Dim params As Variant Set ctx New NotesSession() DocumentContext 里的 Query_String 是原始参数串 params ctx.DocumentContext.Query_String(0)写代码时要注意New NotesSession()和 Initialize 里自带的 session 都是合法写法但代理被 Web 调用时必须从当前请求上下文里取参数而不是读环境变量。代理能否被 Web 调用需要在代理的属性里设置允许 Web 用户运行否则浏览器访问会直接返回 403 或报权限不足。输出方式上LotusScript 代理可以通过 Print 直接往响应流里写内容。返回 HTML 片段是最常见做法如果做下载场景可以返回一段带定时跳转的页面或者在响应头里设置 Content-Disposition 触发保存。Domino 对响应头的控制能力有限我的习惯是文件先写到服务器临时目录再给前端一个下载 URL这样比在代理里拼大段 Base64 更稳。4. Java 代理实现导入导出POI 部署、读取与日期统一处理4.1 把 POI 装进 Domino 运行时jvm/lib/ext 与类加载检查Java 代理接入 POI 的第一步不是写代码而是让 Domino 的 JVM 能找到这些 jar。常规做法如下# 进入 Domino 程序目录不是数据目录 cd $DIRECTION/domino/jvm/lib/ext # 把 POI 及依赖 jar 复制到这里至少包含 poi、poi-ooxml、xmlbeans ls -l poi*.jar # 重启 HTTP 任务让类加载器重新扫描 tell http restart命令里的$DIRECTION/domino是占位Windows 上安装路径通常是C:\Program Files\HCL\DominoLinux 上常见路径是/opt/ibm/domino或/opt/hcl/domino。判断是否生效的方式有两个一个是看代理运行时报的异常是否已经从 ClassNotFoundException 变成了业务错误另一个是用一段极小的 Java 代理输出当前 ClassLoader 里有没有 POI 的类文件。很多人忽略第二个验证结果把 jar 放到了数据目录重启了半天也没效果。类路径冲突也要留意。Domino 自带的 JVM 里本身有一些基础库如果你的 POI 版本里带的依赖和服务器已有 jar 重名、且版本不一致可能在加载时互相覆盖。表现很迷惑同一个代理在测试服务器上正常生产环境就报 AbstractMethodError。这类问题没有快捷排查手段只能是先把所有 POI 相关 jar 的清单列出来对比两边的 JVM 是否有同包名的旧版本。4.2 Java 代理导出 ExcelXSSFWorkbook 的最小写法下面这段代码把一个视图数据写成 xlsx 文件。它涉及 POI 最核心的 Workbook、Sheet、Row、Cell 四级结构。import lotus.domino.*; import org.apache.poi.ss.usermodel.*; import org.apache.poi.xssf.usermodel.XSSFWorkbook; import java.io.FileOutputStream; public class ExcelExport extends AgentBase { public void NotesMain() { try { Session session getSession(); AgentContext ctx session.getAgentContext(); Database db ctx.getCurrentDatabase(); View view db.getView(LotusByName); Workbook wb new XSSFWorkbook(); Sheet sheet wb.createSheet(台账); String[] headers {姓名, 工号, 部门, 金额, 登记日期}; Row headerRow sheet.createRow(0); for (int i 0; i headers.length; i) { headerRow.createCell(i).setCellValue(headers[i]); } Document doc view.getFirstDocument(); int rowIdx 1; while (doc ! null) { Row row sheet.createRow(rowIdx); row.createCell(0).setCellValue(doc.getItemValueString(fullname)); row.createCell(1).setCellValue(doc.getItemValueString(empNo)); row.createCell(2).setCellValue(doc.getItemValueString(dept)); row.createCell(3).setCellValue(doc.getItemValueDouble(amount)); row.createCell(4).setCellValue(doc.getItemValueString(regDate)); doc view.getNextDocument(doc); } FileOutputStream out new FileOutputStream(/tmp/export.xlsx); wb.write(out); out.close(); wb.close(); } catch (Exception e) { e.printStackTrace(); } } }关键参数在 createRow 和 createCell 的下标上Excel 的行和列都从 0 开始第一行做表头所以第二行行号是 1。getItemValueString 适合文本字段金额列我改成了 getItemValueDouble这样写到 Excel 里以后是真正的数字类型Excel 数据分析时可以直接求和。如果全部用字符串写入导出文件能看但用户一排序一求和就报错。文件写到 /tmp/export.xlsx 后还要考虑如何给用户下载。常见做法是 Java 代理里再通过 response 输出流把文件内容返回或者在 Domino 里建一个下载视图让前端拼 URL。我更倾向于后者因为 Domino 天生支持附件下载没必要让代理二次处理二进制流。4.3 Java 代理导入 ExcelWorkbookFactory 解析上传文件导入侧的关键是用 WorkbookFactory 而不是手动判断文件后缀。WorkbookFactory.create 会自动识别 xls 和 xlsx省去一层 if。以下代码从待导入文档中取出附件解析 Sheet 后逐行建文档。import lotus.domino.*; import org.apache.poi.ss.usermodel.*; import java.io.File; public class ExcelImport extends AgentBase { public void NotesMain() { try { Session session getSession(); AgentContext ctx session.getAgentContext(); Database db ctx.getCurrentDatabase(); // 定位待导入文档这里只是示例筛选条件 Document uploadDoc db.search(Form\ImportTemp\, null, 1).getFirstDocument(); EmbeddedObject attach uploadDoc.getAttachment(file); String tempFile /tmp/import.xlsx; // 释放前确认目录存在POI 不会自动建目录 attach.extractFile(tempFile); Workbook wb WorkbookFactory.create(new File(tempFile)); Sheet sheet wb.getSheetAt(0); // 第一行往往是表头从第二行开始读 for (int i 1; i sheet.getLastRowNum(); i) { Row row sheet.getRow(i); if (row null || isRowEmpty(row)) { continue; } Document newDoc db.createDocument(); newDoc.replaceItemValue(Form, Employee); newDoc.replaceItemValue(fullname, getCellValue(row.getCell(0))); newDoc.replaceItemValue(empNo, getCellValue(row.getCell(1))); newDoc.replaceItemValue(dept, getCellValue(row.getCell(2))); newDoc.replaceItemValue(amount, getCellValue(row.getCell(3))); newDoc.replaceItemValue(regDate, getCellValue(row.getCell(4))); newDoc.save(true, false); } wb.close(); } catch (Exception e) { e.printStackTrace(); } } private static boolean isRowEmpty(Row row) { for (int i row.getFirstCellNum(); i row.getLastCellNum(); i) { Cell cell row.getCell(i); if (cell ! null !getCellValue(cell).trim().isEmpty()) { return false; } } return true; } }这段代码里有三个位置容易翻车。第一个是getFirstDocument()如果数据库里没有符合条件的文档返回的是 null后面取附件就会空指针生产代码必须加判空。第二个是sheet.getLastRowNum()它返回的是最大行号而不是总行数中间有空行时用这个循环没问题但要注意最后一行的索引。第三个是row.getCell(i)POI 在读取稀疏行时可能返回 null所以 getCellValue 里必须处理空指针不能无脑调用。导入性能上逐行 createDocument 再 save 是典型的慢路径。几千行数据可以接受如果单次导入几万行建议先落到临时视图或数组最后批量提交否则用户会在页面等得很焦虑。POI 本身的解析速度没有问题瓶颈基本都在 Domino 的文档写入上。4.4 单元格统一取值DateUtil、DataFormatter 与精度处理导入 Excel 时读取单元格最忌讳直接cell.getStringCellValue()。原因很简单一个用户手动输入的「2024-05-01」可能是字符串、可能是日期格式、还可能是一个肉眼看不出来的公式。统一取值的方法能省掉大半多格式兼容问题。import org.apache.poi.ss.usermodel.*; import java.text.SimpleDateFormat; import java.text.DecimalFormat; private static String getCellValue(Cell cell) { if (cell null) { return ; } if (cell.getCellType() CellType.NUMERIC) { // 判断是不是真正的日期单元格 if (DateUtil.isCellDateFormatted(cell)) { SimpleDateFormat sdf new SimpleDateFormat(yyyy-MM-dd); return sdf.format(cell.getDateCellValue()); } // 长数字列用 DecimalFormat 避免科学计数法 DecimalFormat df new DecimalFormat(0); return df.format(cell.getNumericCellValue()); } // 其余情况包括文本、公式、空白统统交给 DataFormatter DataFormatter formatter new DataFormatter(); return formatter.formatCellValue(cell); }DateUtil.isCellDateFormatted 是判断日期单元格的官方手段它检查的是单元格的格式编码而不是值本身。DecimalFormat 处理身份证号、银行卡号这类长数字时尤其重要否则 POI 会把 1234567890123456 读成 1.234567890123456E15导入数据库后看起来就像乱码。DataFormatter 是兜底它能按单元格的显示格式输出文本对公式单元格返回计算结果。这个组合基本覆盖了用户上传表格时能想到的各种情况。5. 避坑Excel 导入导出最容易翻车的五个现场5.1 导出的 CSV 用 Excel 打开后中文全是问号现象代理跑完文件下载后用 Excel 打开中文全部变成???或者直接乱码英文和数字正常。原因LotusScript 的 Print 语句往文件写内容时使用的是服务器当前语言环境对应的编码。如果 Domino 服务器是英文系统或者没有装中文字体支持写进文件的就是非 UTF-8 字节Excel 打开时按本地编码解析自然对不上。解决在 CSV 文件第一行写入 UTF-8 BOM也就是Chr(239) Chr(187) Chr(191)让 Excel 强制用 UTF-8 解码。Java 代理里同样处理用 OutputStreamWriter 指定 UTF-8并且写内容前先输出\ufeff。我见过有人只在代码里改了中文内容漏加 BOM结果问题依旧所以这两步必须一起做。5.2 Excel 里的日期导入系统后变成一串数字现象用户表格里明明是「2024-05-01」导入系统后成了 45413或者年份月份错乱导出再回写时日期面目全非。原因Excel 里日期本质是自 1900 年 1 月 1 日以来的序列号。POI 的 getNumericCellValue 拿到的是这个序列号LotusScript 用 OLE 读 Value 也一样。不判断单元格格式的话日期就是普通数字。解决Java 侧必须用DateUtil.isCellDateFormatted(cell)先判断再走 getDateCellValue 加 SimpleDateFormat 格式化。LotusScript 文本解析则要把「看起来像日期」的列单独硬解析一次写个正则把常见的yyyy-mm-dd和yyyy/mm/dd归一化。这里最容易翻车的是两种写法混用有人前几行是文本日期后几行是日期格式导入结果一半对一半错。统一走 4.4 的 getCellValue 就不存在这个问题。5.3 用 OLE 的代理在 Windows 服务器上挂起现象代理调用 Excel 后报「自动化错误」同时任务管理器里的 EXCEL.EXE 进程数量持续增长服务器响应越来越慢最后只能重启机器。原因OLE 在服务器环境下每次调用都可能新起一个 Excel 实例任何一个异常分支没走到 Quit实例就常驻内存。服务器没有交互桌面Excel 崩溃时用户根本看不到弹窗于是进程就成了黑匣子越积越多。解决所有 OLE 分支必须保证最后执行 Quit包括错误分支。更彻底的做法是放弃 OLE导出改用 CSV 文本导入改用 Java POI。如果你的服务器已经被残留进程拖垮先taskkill /F /IM EXCEL.EXE清理再决定代码方向。进程管理是 OLE 方案的根本痛点不是补几个 Quit 就能根治的。5.4 Web 上传的附件在代理里提示文件不存在现象用户在前端页面上传 Excel 成功代理运行时报 FileNotFoundException文件路径明明复制过去也能看到但代理就是读不到。原因Domino B/S 的上传文件在落到数据库之前可能先被写到服务器临时目录如果你的代理里直接引用了临时路径HTTP 任务的临时目录清理策略会把它删掉。另一个常见原因是附件对象还没有从文档里释放出来只是存在数据库的 rich text 字段里你拿一个「逻辑文件名」按普通文件去打开自然找不到。解决先通过 NotesEmbeddedObject 或 Java 侧doc.getAttachment(file)拿到附件对象再调用extractFile释放到绝对路径最后读取这个释放出来的文件。释放之前先创建目标目录例如用一个启动时自动建立 temp 目录的公共函数。排查这类问题第一步永远是在代理里输出实际文件路径和 File.exists 的结果不要靠猜。5.5 用户调用代理报 403 或者身份错乱现象自己在 Designer 里运行代理一切正常普通用户在浏览器访问就报 403或者导入的数据写入者全是某个管理员账号明明用户自己登录的。原因代理属性里的「运行时身份」设错了。B/S 代理被 URL 触发时运行时身份可以选「以 Web 用户身份运行」或「以代理作者身份运行」。如果选了后者ACL 里没给调用者执行权限就会 403如果选了前者但数据库 ACL 对匿名用户开放的权限太大则可能绕过用户名限制。解决一般登录系统的数据操作代理要选「以 Web 用户身份运行」这样写入者才是当前用户。供管理员批量导数据的专用导入代理可以改成「以代理作者身份运行」但必须在代理入口校验用户角色。另外客户端本机如果装了安全软件或者 Excel 加载项被禁用页面弹出的自动化错误往往会误导排查方向这种错误要先去服务器看 nsd 日志别被客户端弹窗带着走。6. 把导入导出沉淀成公共模块接口化、日志与回归验证6.1 接口化用参数驱动一个代理代理和代码最忌讳复制粘贴后再改字段名。同一个导入逻辑A 系统导员工B 系统导资产差别只是字段映射和表头位置。抽出公共参数后一个导入代理就能应对多个场景。我习惯用四个入参视图名或文档筛选条件、Excel 列与字段映射、输出文件路径、导入模式新建还是更新。映射关系通常放在配置文档里而不是写死在代码里。这样做的直接收益是日志也统一了。每次导入把成功行数、失败行数、首条报错记录写到日志数据库用户发现问题时可以直接从日志里看到是哪一行哪一列错了配合 Excel 快速定位错位数据比让用户口头描述「有个文件导不进去」高效得多。6.2 回归验证一份故意做坏的 Excel我现在每个 Domino 项目里都会固定维护一份「错乱测试专用.xlsx」里面故意放空行、合并单元格、长数字、日期序列号、文本形式日期、带逗号的地址、超长文本。每次改完导入代码先拿它跑一遍回归再放真实数据。需求沟通阶段的字段映射表直接用 Markdown 表格列出来再转成 Excel 字段模板给用户确认能提前挡掉大量「我以为这个列是日期」式的返工。这个习惯是从一次线上事故里学来的当时用户导入的表格里身份证号列被 Excel 自动转成了科学计数法我这边没做精度处理几千条数据导进去全部尾部归零只能让用户重新提交。从那以后凡是涉及 Excel 数据对接我第一件事就是问清字段类型和最大长度然后按最坏情况准备测试文件。把这个验证步骤固化到团队里Excel 导入导出这类需求才能真正从「能跑」变成「敢上线」。希望帮到你。本文还有配套的精品资源点击获取
