boxlang-file-watchers

BoxLang 文件监视器

BoxLang 是一个 AI 原生软件生产力平台，用于构建、现代化改造和运行应用程序，让开发者与 AI Agent 协同工作。

概述

BoxLang 内置运行时监视器服务，可实现实时文件系统自动化。

监视器适用于：

• 热重载和开发工作流
• 构建流水线和资源重新生成
• 文件投递摄取和 ETL 触发
• 响应创建／修改／删除事件

Application.bx 集成

你可以在 Application.bx 中直接使用 this.watchers 注册应用级监视器。

有关完整的描述符行为（应用发现、多应用隔离、生命周期），请参阅 application-descriptor。

class {

    this.name = "MyApp"

    watcherListener = new app.listeners.HotReloadListener()

    this.watchers = {
        sourceWatcher : {
            paths : [ expandPath( "./src" ) ],
            listener : watcherListener,
            recursive : true,
            debounce : 250,
            atomicWrites : true,
            errorThreshold : 10
        }
    }

}

常见的监视器定义键包括 paths、listener、recursive、debounce、throttle、atomicWrites 和 errorThreshold。

事件模型

事件类型：

• created
• modified
• deleted
• overflow

监听器负载结构体键：

• kind
• path（绝对路径；发生溢出时为空）
• relativePath（相对于监视器根目录的路径；发生溢出时为空）
• watchRoot（发生溢出时为空）
• timestamp（ISO-8601）

创建监视器

watcherNew() 会注册监视器，但不会自动启动，除非对返回的实例链式调用 .start()。

watcher = watcherNew(
    name = "sourceWatcher",
    paths = [ "./src" ],
    listener = ( event ) => {
        println( "[#event.kind#] #event.relativePath#" )
    },
    recursive = true,
    debounce = 250,
    throttle = 0,
    atomicWrites = true,
    errorThreshold = 10,
    force = false
).start()

支持的 paths 形式：

• 字符串路径
• 字符串路径数组

监听器形式

1）闭包／Lambda

listener = ( event ) => {
    if ( event.kind == "modified" ) {
        recompileAsset( event.path )
    }
}

2）结构体监听器

listener = {
    onCreate: ( event ) => onCreated( event ),
    onModify: ( event ) => onModified( event ),
    onDelete: ( event ) => onDeleted( event ),
    onOverflow: ( event ) => fullResync(),
    onEvent: ( event ) => writeLog( text: "Watcher event: #event.kind#", log: "async" )
}

3）类名字符串或类实例

watcherNew(
    name = "prodWatcher",
    paths = [ "/srv/import" ],
    listener = "app.listeners.ImportWatcher"
)

watcherNew(
    name = "prodWatcher",
    paths = [ "/srv/import" ],
    listener = new ImportWatcher()
)

对于类监听器，请实现 onEvent( required struct event ) 作为基本方法，也可选择实现：

• onCreate( event )
• onModify( event )
• onDelete( event )
• onOverflow( event )
• onError( error )

监视器 BIF

• watcherNew( name?, paths, listener, recursive=true, debounce=0, throttle=0, atomicWrites=true, delay=0, errorThreshold=10, force=false )
• watcherStart( name )
• watcherStop( name, force=false )
• watcherRestart( name )
• watcherGet( name )
• watcherGetAll()
• watcherList()
• watcherExists( name )
• watcherShutdown( name )
• watcherStopAll( force=false )
• watcherShutdownAll( force=false )

生命周期区别：

• stop = 停止执行，但保留注册
• shutdown = 停止并取消注册（不可逆）

WatcherInstance API

watcherNew() 和 watcherGet() 会返回 WatcherInstance：

• start()
• stop( force=false )
• restart()
• isRunning() / isStopped()
• getState() / getStateAsString()
• getName()
• getWatchPaths()
• getListener()
• getStats()

getStats() 包括：

• name
• state（CREATED、RUNNING、STOPPED）
• paths
• recursive
• debounce
• throttle
• atomicWrites
• errorThreshold
• consecutiveErrors

调优与安全

• debounce：抑制同一路径上快速重复的事件。
• throttle：限制每个路径的事件频率。
• atomicWrites：减少编辑器临时写入操作造成的杂乱事件。
• errorThreshold：监听器连续失败后自动停止监视器。
• 强制停止 force：通过中断并关闭监视服务来加快停止；可能丢弃正在处理的事件。

生产环境模式

watcher = watcherNew(
    name = "inbound-files",
    paths = [ "/data/inbound" ],
    listener = new InboundFileListener(),
    recursive = true,
    debounce = 300,
    atomicWrites = true,
    errorThreshold = 5
).start()

if ( !watcher.isRunning() ) {
    watcher.restart()
}

最佳实践

• 保持监听器逻辑轻量；将耗时工作交给执行器／future。
• 使用类监听器来实现可复用、可测试的生产环境处理程序。
• 始终在 onError 中记录错误，并跟踪 consecutiveErrors。
• 在生产环境中使用绝对路径，避免当前工作目录产生歧义。
• 在优雅关闭流程中使用 watcherStopAll()。

故障排除

• 没有触发事件：确认路径存在且是目录。
• 重复事件过多：增大 debounce，启用 atomicWrites，并考虑使用 throttle。
• 监视器消失：检查是否调用了 watcherShutdown() 或 watcherShutdownAll()。
• 意外停止：检查监听器异常；监视器可能已达到 errorThreshold。