Freemarker Debugger API实现及参考示例咨询

官方原生API参考 #

• FreeMarker官方自带freemarker.debug包下的全套调试能力，核心接口包含DebuggerService、Breakpoint、EnvironmentSuspendedEvent，可直接用于实现断点设置、单步执行、上下文变量抓取等核心调试功能。
• 开启调试模式的配置非常简单，仅需要在初始化FreeMarker配置时开启对应开关：configuration.setDebug(true)，之后注册DebuggerListener即可监听所有模板执行的生命周期事件。
• 如果你需要实现模板语法错误定位、语法高亮相关功能，可以对接freemarker.core.Parser的扩展点，直接获取模板解析后的AST节点结构，不需要自己实现模板语法解析逻辑。

通用实现思路参考 #

现有FreeMarker调试类工具的实现逻辑基本一致，可以直接复用这套成熟方案：

• 首先在运行模板的目标进程中启动FreeMarker调试服务，监听本地端口接收调试指令
• 你的插件作为客户端和调试服务建立通信，发送断点增删、单步执行、变量查询等操作指令
• 服务端触发断点或执行到指定位置时，将当前模板的执行行号、变量堆栈、全局配置参数等数据返回给插件端展示即可

如果你需要实现热重载调试功能，可以扩展官方的TemplateCache类，修改模板缓存的校验逻辑，监听到模板文件修改后自动清除缓存重新加载，不需要重启目标应用就能调试修改后的模板。

最小化调试接入示例代码 #

// 初始化FreeMarker配置
Configuration cfg = new Configuration(Configuration.VERSION_2_3_31);
// 开启调试模式
cfg.setDebug(true);
// 获取全局调试服务实例
DebuggerService debugger = DebuggerService.getDebuggerService();
// 注册调试事件监听器
debugger.addDebuggerListener(new DebuggerListener() {
    @Override
    public void environmentSuspended(EnvironmentSuspendedEvent event) {
        // 触发断点时获取当前执行环境
        Environment currentEnv = event.getEnvironment();
        // 获取当前执行的模板行号
        int currentLine = currentEnv.getCurrentDirectiveCallPlace().getLine();
        // 获取指定名称的上下文变量
        TemplateModel targetVar = currentEnv.getVariable("yourVarName");
        // 此处将获取到的调试数据回传给插件前端展示即可
    }
});

内容的提问来源于stack exchange，提问作者Michiel