注册与缓存
- 先注册后建环境：
FluxonRuntime会在registerFunction/Extension时打脏标记。 下一次newEnvironment()会自动重新烘焙缓存。 避免在已创建的环境上直接修改Environment内部映射。 - 参数个数显式声明：使用
List<Integer>或@Optional表达可选参数，避免在实现里硬编码“长度判断”。 - 命名空间一致性：
registerFunction(namespace, ...)与脚本里的import 'namespace'保持一致（如import 'fs:crypto'）。 重命名时记得更新函数目录与文档。
类型与错误处理
- 使用
FunctionContext#getInt/getString/getAsDouble等方法获取参数；类型不符会抛出ArgumentTypeMismatchError。 - 在扩展函数内先用
getArgumentCount()判断参数个数。 - 返回值确实无意义时再返回
Function.VOID，否则优先返回真实结果，避免触发VoidError。 - 对外暴露的导出类优先使用
@Export+ExportRegistry，由生成的ClassBridge替代反射调用。
并发与线程模型
- 异步逻辑交给
ThreadPoolManager（submitAsync/runAsync），避免自行创建线程导致池外资源泄漏。 - 需要主线程的函数使用
registerPrimarySyncFunction/registerSyncExtensionFunction。 - 通过
FluxonRuntime#setPrimaryThreadExecutor指向宿主主线程。 - 长耗时或 IO 操作尽量设计为异步函数，调用侧用
await，减少阻塞。
环境与性能
Environment已共享函数/扩展的数组缓存（见EnvironmentCacheTest）。 频繁创建开销很小；若需要共享状态，请显式通过defineRootVariable注入。- 生成函数目录时使用
./gradlew :core:dumpFluxonCatalog，确保 VS Code 补全和文档与最新注册表一致。 - 在性能调优前先运行
ParserPerformanceTest或ParserJmhBenchmark，必要时使用jfr/记录分析热点。
调试与诊断
- 控制台前缀
$可以输出词法/语法树，快速定位解析问题。 Environment#getRootFunctions()/getRootExtensionFunctions()能检查注册表。- 当扩展函数匹配异常时，可通过
FunctionDumper导出的fluxon-functions.json对照目标类型与命名空间。 - 编译/解释差异优先用
FluxonTestUtil.runSilent复现，TestResult#isMatch()能直接判断差异。