# 函数流走向

一次调用从公开 API 走到 goja 要经过哪些函数、作用域和扩展在哪一步进入 VM。

`call-flow.md` 讲的是**三个阶段各自在做什么**（为什么要打包、错误怎么分类），
这一篇讲的是**函数之间怎么串起来的**——想改代码、想知道加一层该加在哪，看这篇。

---

## 全景

```mermaid
flowchart TB
    subgraph 公开API
        N["jscriptx.New(opts...)"]
        C["e.Compile(name, src)"]
        S["e.Script(name)"]
        EN["e.New(ctx, name, args...)"]
        SC["s.Call / CallInto / WithCall"]
        SN["s.New(ctx, args...)"]
        ST["s.CallStatic / HasStatic"]
        IC["i.Call / CallInto / WithCall"]
    end

    subgraph 脚本注册表
        LL["loadLocked"]
        CL["compileLocked"]
        BD["Bundle（含 FinalizeBundle）"]
        GC["goja.Compile → *Program"]
    end

    subgraph 取VM
        BR["s.borrow"]
        EQ["i.ensure"]
        BS["s.borrowStatic"]
        NV["**newVM**（唯一入口）"]
        LD["s.load"]
    end

    subgraph 调用
        CA["callAny / callInto"]
        IV["invoke"]
        LK["vm.lookup"]
        FR["frame.callWith"]
    end

    N --> S
    C --> CL
    S --> LL --> CL --> BD --> GC
    EN --> S
    EN --> SN
    SN --> EQ
    SC --> CA
    IC --> CA
    ST --> CA
    CA --> IV
    IV -->|"r.acquire"| BR
    IV -->|"r.acquire"| EQ
    IV -->|"r.acquire"| BS
    BR -->|"池里没有"| NV
    EQ --> NV
    BS --> NV
    NV --> LD
    IV --> LK --> FR
```

两个要点：

- **编译和取 VM 是分开的两条链**。`*Program` 是 goja 编译产物，不绑任何 Runtime，
  所有 VM 共用同一份。所以热更新（重编译）贵，建 VM 便宜——实测 213 μs vs 4 μs，
  编译占 99.7%。
- **取 VM 只有 `newVM` 一个入口**。三条路径（池化、实例、静态）都汇到它，
  作用域注入和 `scoped` 标记的规则才只有一份。这两件事分散过，结果就是
  `borrowStatic` 漏标了 `scoped`，带作用域的 VM 差点回池。

---

## 谁提供 VM：runner 三态

`invoke` 不关心 VM 从哪来，只认这个接口（`invoke.go`）：

```go
type runner interface {
	owner() *Script
	acquire(ctx) (*vmHandle, error)
	finish(inst *vmHandle, healthy bool)
}
```

三个实现，差别全在「用完怎么处理」：

| | `acquire` | `finish` | 语义 |
| --- | --- | --- | --- |
| `*Script` | `borrow` | `release` | 从池借，好的还回去，坏的丢 |
| `*Instance` | 加锁 + `ensure` | 解锁，坏的置 nil | 独占一个 VM，**锁持到 finish**，所以同一实例串行 |
| `staticTarget` | `borrowStatic` | 只记 `dropped` | 用完就丢，永不回池 |

所以「同一个实例的调用是串行的」不是靠额外机制，就是 `acquire` 到 `finish`
之间一直持着 `i.mu`。

---

## 建一个 VM：newVM 内部

```mermaid
flowchart TB
    A["newVM(ctx, sc, ctorArgs, noInstance)"] --> B{"sc != nil"}
    B -->|是| C["extra = sc.vmGlobals()"]
    B -->|否| D["extra = nil"]
    C --> E["goja.New()"]
    D --> E
    E --> F["SetMaxCallStackSize"]
    F --> G["**engine.bind(rt, name, extra)**"]
    G --> H["s.load(ctx, rt, ctorArgs, noInstance)"]
    H --> I["vm.scoped = sc != nil"]
    I --> J["*vmHandle"]
```

`sc` 是**显式参数，不是从 ctx 嗅的**。`Instance` 重建 VM 时要回到它**创建时**
那个作用域，而不是当次调用 ctx 里的——对一个作用域实例调
`Call(context.Background())` 不该把它的扩展弄丢。有测试守这条
（`TestScope_实例重建VM后仍在原作用域`）。

`vm.scoped` 决定 `release` 会不会把这个 VM 放回池子。带作用域的 VM 装着那个作用域的
扩展，回池就会漏给下一个调用。

---

## 作用域和扩展怎么进 VM

这是最容易看不清的一条链，从 `WithScope` 到 JS 全局变量一共五跳：

```mermaid
flowchart TB
    W["WithScope(ctx, ScopeExtensions(st), ScopeGlobals(m), ScopeKey(k))"]
    W --> SS["ctx 里存一个 *scope<br/>{key, exts, globals}"]
    SS --> SO["scopeOf(ctx) 取回来"]
    SO --> VG["**sc.vmGlobals()**<br/>拍平成 map[string]any"]
    VG --> BI["engine.bind(rt, name, extra)"]
    BI --> LG["lazyGlobal 逐个注入"]
    LG --> FZ["首次读取时才 freeze"]
    FZ --> JS["脚本里的全局变量"]
```

### `vmGlobals` 的拍平规则

```go
for _, ext := range sc.exts { g[ext.Name()] = ext.Bindings() }   // 扩展
for k, v := range sc.globals { g[k] = v }                        // ScopeGlobals 盖扩展
g["scope"] = map[string]any{"key": sc.key}                       // 身份
```

扩展交出去的是 `Bindings()` 返回的那张 `map[string]any`——**方法集，不是扩展对象本身**。
所以脚本看到的 `store` 是一个由 Go 函数组成的对象，那些函数闭包捏着同一个 Go 侧实例，
这才是「多个脚本共享状态」的实现方式：共享的是 Go 对象，不是共用 Runtime。

`scope.key` 总会有（`WithScope` 不传 key 就随机生成），所以**只要 ctx 里有作用域，
`extra` 就必然非空**——这也是「有作用域必然要单造 VM」的原因，池里的 VM 没装这些。

### `bind` 的优先级

```mermaid
flowchart LR
    A["e.globals<br/>（WithGlobals 白名单）"] -->|"同名时被跳过"| B["extra<br/>（作用域的）"]
    B --> C["console<br/>（两边都没占用才注入）"]
```

顺序是刻意的：作用域的东西盖白名单，`console` 只在没被占用时才给。
`WithLogger(nil)` 关掉 logger 就完全不注入 console。

### 为什么注入是惰性的

`lazyGlobal` 用 `DefineAccessorProperty` 装一个**只有 getter 没有 setter** 的属性：

```mermaid
flowchart LR
    A["脚本第一次读 db"] --> B{"cached == nil"}
    B -->|是| C["freeze(rt, val)"]
    C --> D["缓存并返回"]
    B -->|否| D
    E["脚本没读过 db"] --> F["freeze 从没跑过"]
```

- **没有 setter** = 脚本改不动。脚本跑在非严格模式下，给只读全局赋值是**静默失败**，
  不抛错（断言在 `engine_globals_test.go`）。注意这只说全局本身：`freeze` 拷出来的
  嵌套只读属性（`store.Set = null`）实测是**抛错**的，两种行为不一样。
- **惰性** = 脚本没读到的全局根本不转换。README 性能一节的内存表是「全都读到」的上界。

### `freeze` 只对 map 深拷贝

```mermaid
flowchart TB
    A["freeze(rt, val)"] --> B{"val 是 map[string]any"}
    B -->|是| C["递归 freeze 每个值<br/>+ defineReadOnly"]
    C --> D["各 VM 各持一份只读副本"]
    B -->|否| E["rt.ToValue(val)"]
    E --> F["**各 VM 共享同一个 Go 对象**"]
```

这一点常被误解成隔离保证。**放行结构体指针、slice、接口时，各个 VM 拿到的是同一个
Go 对象**，脚本通过它的方法改到的东西是真改了。扩展走的正是这条路（`Bindings()` 返回的
map 会被拷，但里面的函数闭包捏着同一个 Go 实例），要跨 VM 共享可变状态就该这么用。

---

## 一次调用：invoke 内部

```mermaid
flowchart TB
    A["invoke(ctx, r, fn, args, do)"] --> B{"脚本已关闭"}
    B -->|是| Z1["ErrClosed"]
    B -->|否| C["**r.acquire(ctx)**"]
    C --> D["defer r.finish(inst, healthy)"]
    D --> E["**inst.lookup(fn)**"]
    E -->|找不到| Z2["ErrFuncNotFound<br/>+ notFoundHint"]
    E --> F["**guard(ctx, rt, timeout)**<br/>装超时哨兵"]
    F --> G["defer stop()"]
    G --> H["defer recover()<br/>healthy = false"]
    H --> I["do(frame)"]
    I --> J["frame.callWith(args)"]
    J --> K["unwrapPromise"]
    K --> L{"返回值是 JS 函数"}
    L -->|是| Z3["ErrValueEscape"]
    L -->|否| M["res.Export() 或 res.Into(out)"]
```

### defer 的顺序很关键

注册顺序是 `finish` → `stop` → `recover`，执行是**后进先出**：

1. `recover` 先跑，把 `healthy` 置成 false
2. `stop` 清掉超时哨兵
3. `finish` 最后才交还 VM——这时 `healthy` 已经是正确的值

顺序错了的后果是：panic 过的 VM 带着不确定的状态回到池子里。

### `lookup` 的三级查找

```mermaid
flowchart TB
    A["lookup(fn)"] --> B{"fn == DefaultFunc"}
    B -->|是| C["defFn<br/>（export default function）"]
    B -->|否| D{"exports 上有"}
    D -->|有| E["实例方法<br/>this = exports"]
    D -->|没有| F{"ctor 上有"}
    F -->|有| G["**静态方法**<br/>this = ctor"]
    F -->|没有| H["全局函数兜底"]
```

这个顺序解释了两件事：

- `Script.Has("Startup")` 对一个**静态**方法也返回 true——它走的是同一个 `lookup`
- `HasStatic` 要额外判 `ctor != nil`，就是为了排除最后那个全局兜底分支

---

## 编译链：源码到 *Program

```mermaid
flowchart TB
    A["e.Script(name)"] --> B{"缓存里有 && !autoReload"}
    B -->|是| C["直接返回"]
    B -->|否| D["**loadLocked**"]
    D --> E["loader.Load(name)<br/>→ source, version"]
    E --> F{"version 跟缓存一样"}
    F -->|是| C
    F -->|否| G["**compileLocked**"]
    G --> H{"loader 实现了 Prepared"}
    H -->|"是（esm.Loader）"| I["源码已打包，直接用"]
    H -->|否| J["**Bundle**<br/>esbuild 内联 import + 转译 TS<br/>末尾自己调 FinalizeBundle<br/>把 ESM 改写成立即执行函数"]
    I --> L["goja.Compile → *Program"]
    J --> L
    L --> M["*Script{prog, pool}"]
```

`Prepared` 不是优化开关而是**正确性要求**：打包产物里已经没有 `export` 了，
再打一遍会被当死代码整段摇空。所以自定义 Loader 如果自己打过包，必须实现它。

---

## 想加一层该加在哪

| 想做的事 | 该动哪 |
| --- | --- |
| 给脚本加一个全局对象 | 实现 `Extension`，通过 `ScopeExtensions` 进作用域 |
| 全进程都有的全局 | `WithGlobals`（走 `e.globals`，被作用域同名项覆盖） |
| 换脚本来源 | 实现 `Loader`；已自己打包的加 `Prepared` |
| 多来源叠加 | `Overlay`（后面盖前面） |
| 自定义回调签名 | `WithCall` + `Caller.Arity`，别改 `invoke` |
| 改 VM 的建法 | 只改 `newVM`——三条路径都走它 |
| 加一种新的 VM 来源 | 实现 `runner` 三个方法，别绕过 `invoke` |