> ## Documentation Index
> Fetch the complete documentation index at: https://fluxon.tabooproject.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 扩展函数 API

> ExtensionBuilder 与环境中的扩展检索流程

扩展函数把 `target::method()` 映射到 Java 侧实现，用于为特定宿主类型增加上下文能力（文件、集合、游戏对象等）。

核心代码分布在 `FluxonRuntime`、`ExtensionBuilder`、`Environment`。

## 快速上手（Builder）

```java theme={null}
import static org.tabooproject.fluxon.runtime.FunctionSignature.returns;
import org.tabooproject.fluxon.runtime.Type;

FluxonRuntime runtime = FluxonRuntime.getInstance();
runtime.registerExtension(File.class, "fs:io")
       .function("exists", returns(Type.Z).noParams(), ctx -> {
           ctx.setReturnBool(ctx.getTarget().exists());
       })
       .asyncFunction("length", returns(Type.J).noParams(), ctx -> {
           ctx.setReturnLong(ctx.getTarget().length());
       })
       .syncFunction("getName", returns(Type.STRING).noParams(), ctx -> {
           ctx.setReturnRef(ctx.getTarget().getName());
       });
```

* `function`：同步扩展。
* `asyncFunction`：异步扩展（在线程池执行）。
* `syncFunction`：主线程同步扩展（通过 primaryThreadExecutor 执行）。
* `sharedFunction`：同步扩展 + 自动导出到跨 CL 共享注册表。
* `sharedAsyncFunction`：异步扩展 + 自动导出。
* `sharedSyncFunction`：主线程同步扩展 + 自动导出。

`ExtensionBuilder` 只是语法糖，底层仍调用 `FluxonRuntime` 的注册方法。

## 直接注册

使用 `FluxonRuntime.registerExtensionFunction` 方法直接注册扩展函数：

```java theme={null}
runtime.registerExtensionFunction(
    extensionClass,   // 目标类型，如 File.class
    namespace,        // 命名空间，可为 null
    name,             // 函数名
    signature,        // FunctionSignature 签名
    implementation,   // NativeCallable 实现
    isAsync,          // 是否异步
    isPrimarySync     // 是否主线程同步
);
```

命名空间前缀会与函数名组合为脚本调用形态。

例如 `fs:io` + `readText` -> `fs:io::readText()`。

## 查找与匹配流程

1. 解释器确定 `target` 的 `Class<?>`。
2. `Environment#getExtensionFunction` 优先在烘焙的 `systemExtensionFunctions` 二维数组中按名称匹配。
3. 若未命中，回退到 `extensionFunctions`（名称 -> `Map<Class<?>, Function>`）。
4. 匹配顺序为精确类型，再尝试 `isAssignableFrom`，确保子类可复用父类扩展。

## 实战提示

* 复杂类型示例可参考
  [`core/src/main/java/org/tabooproject/fluxon/runtime/function/extension`](https://github.com/TabooLib/fluxon/tree/master/core/src/main/java/org/tabooproject/fluxon/runtime/function/extension)（`Path`、`Collection` 等）。
* 想支持索引访问 (`obj[index]`)，需实现 `IndexAccessor`（详见运行时章节）。
* 调试：`Environment#getRootExtensionFunctions()` 查看当前映射。
* 若调用失败，检查是否遗漏 `import` 或命名空间不一致。
* `dumpFluxonCatalog` 可确认导出签名。

## 相关链接

* [运行时注册 API](/developer/runtime-registry)
* [跨 ClassLoader 函数共享](/developer/cross-cl-sharing)
* [@Export 与桥接](/developer/export-bridge)
* [环境与作用域](/runtime/environment)
* [解释器执行流](/runtime/interpreter)