Clerk项目中的异常显示问题分析与解决

问题背景

在Nextjournal的Clerk项目中，当使用带有过滤功能的观察器(watcher)时，如果笔记本文件中包含语法错误或运行时错误，浏览器端不会显示任何异常信息，进度条会卡在"分析中"的状态。

问题现象

具体表现为：当使用如下配置启动观察器时：

(clerk/serve! {:watch-paths ["notebooks" "src"] 
               :show-filter-fn #(clojure.string/starts-with? % "notebooks")})

如果被监控的笔记本文件发生变更且包含错误，浏览器界面不会显示任何错误信息，而是停留在分析状态。

问题根源

经过分析，问题的根本原因在于当出现异常时，系统会将整个clerk/serve!的配置选项附加到文档中，其中包括了:show-filter-fn选项的函数对象。这个函数对象在转换为EDN格式时会产生不可读的表达式，导致客户端无法正确解析和显示错误信息。

具体来说，异常信息中的:nextjournal.clerk/doc部分包含了完整的服务配置，其中:show-filter-fn的值被表示为类似#function[user/eval60926/fn--60927]的形式，这种表示法无法被客户端正确解析。

技术细节

1. 异常传播机制：Clerk在捕获到异常后，会将异常信息连同当前文档状态一起发送到客户端。

2. 数据序列化问题：在序列化过程中，Clojure函数对象无法被完整地序列化为可传输的格式，导致客户端接收到的数据不完整。

3. 客户端渲染失败：由于异常信息中包含无法解析的函数对象，客户端的错误渲染器无法正常工作，最终表现为进度条卡住。

解决方案探讨

针对这个问题，可以考虑以下几种解决方案：

1. 过滤敏感配置项：在将文档状态发送到客户端前，过滤掉可能包含函数对象的配置项，如:show-filter-fn。

2. 自定义函数序列化：实现专门的函数序列化逻辑，将函数转换为可传输的表示形式（如函数名或描述字符串）。

3. 精简异常数据：在异常信息中只包含必要的调试信息，而不是完整的服务配置。

从项目维护的角度看，第一种方案（过滤敏感配置项）可能是最直接和可靠的解决方案，因为它：

• 实现简单
• 不会引入额外的序列化复杂性
• 保持了核心功能的稳定性

实现建议

在具体实现上，可以在文档状态准备阶段添加一个过滤步骤：

(defn sanitize-doc [doc]
  (dissoc doc :show-filter-fn ;; 移除函数配置
              :other-sensitive-keys)) ;; 其他可能需要移除的敏感项

然后在异常处理流程中应用这个过滤函数：

(catch Exception e
  (let [sanitized-doc (sanitize-doc current-doc)]
    ;; 使用过滤后的文档构建异常响应
    ))

总结

这个问题揭示了在复杂系统中数据序列化和异常处理时需要特别注意的几个方面：

1. 数据边界：明确哪些数据需要在系统各组件间传输，哪些应该保留在服务端。

2. 异常信息设计：异常信息应该包含足够的调试信息，但不应包含可能影响传输的复杂对象。

3. 客户端兼容性：确保发送到客户端的数据结构始终是可解析的，特别是在包含动态内容时。

通过合理设计异常信息的结构和内容，可以显著提高系统的健壮性和用户体验。对于Clerk这样的交互式笔记本系统来说，清晰的错误反馈机制尤为重要，因为它直接影响用户的工作效率和问题排查能力。