Go Goja 怎么把 JavaScript 对象导出到 Go 结构体

在 Goja 中执行 JavaScript 后，最直接的做法不是把对象先转成 JSON 再反序列化，而是把脚本返回的 goja.Value 交给 Runtime.ExportTo()，让 Goja 按目标变量的类型完成一次定向导出。目标是固定领域模型时，通常可以这样写：

package main

import (
    "fmt"

    "github.com/dop251/goja"
)

// Profile 是脚本对象在 Go 侧的领域模型。
type Profile struct {
    Name  string `json:"name"`
    Age   int    `json:"age"`
    Roles []string `json:"roles"`
}

func main() {
    vm := goja.New()
    // 脚本返回普通对象，字段名与 Profile 的 json 标签对应。
    value, err := vm.RunString(`({ name: "Lin", age: 28, roles: ["editor", "reviewer"] })`)
    if err != nil {
        panic(err)
    }

    var profile Profile
    // ExportTo 负责把 Value 写入目标结构体，失败时保留错误上下文。
    if err := vm.ExportTo(value, &profile); err != nil {
        panic(err)
    }
    fmt.Printf("%s %d %v\n", profile.Name, profile.Age, profile.Roles)
}

官方项目地址：https://github.com/dop251/goja

固定结构的 JavaScript 对象优先使用 vm.ExportTo(value, &target)。如果只调用 value.Export()，得到的是 Goja 默认选择的 Go 值，后续还要自己做类型断言；需要小写字段或第三方脚本命名时，再给 Runtime 配置字段名映射。

先分清 Export 和 ExportTo 的职责

Goja 提供两条不同的导出路径。Value.Export() 返回一个默认 Go 表示，适合你还不确定对象形状、需要继续检查字段的场景。Runtime.ExportTo() 则接收目标指针，适合把脚本数据直接落到已有的结构体、切片或其他 Go 变量。

这两条路径都建立在同一个 goja.Value 上，但后续的数据责任不同：前者把类型判断留给调用方，后者把目标类型交给 Goja。文章下面的例子只围绕第二种路径展开。

用 Runtime.ExportTo 把对象写入结构体

关键调用只有一行：vm.ExportTo(value, &profile)。第一个参数是脚本执行得到的值，第二个参数必须是可写目标的指针。把指针漏掉，Goja 没有地方写入字段，导出自然无法按预期完成。

type Account struct {
    ID      string `json:"id"`
    Enabled bool   `json:"enabled"`
    Quota   int64  `json:"quota"`
}

func readAccount(vm *goja.Runtime, source string) (Account, error) {
    value, err := vm.RunString(source)
    if err != nil {
        return Account{}, fmt.Errorf("运行 JavaScript 失败: %w", err)
    }

    var account Account
    // 目标传指针，Goja 才能把字段写回 account。
    if err := vm.ExportTo(value, &account); err != nil {
        return Account{}, fmt.Errorf("导出 Account 失败: %w", err)
    }
    return account, nil
}

工程代码里建议把脚本运行错误和导出错误分开包装。这样一眼就能看出问题发生在 JavaScript 语法/执行阶段，还是发生在对象到 Go 类型的转换阶段。

字段名不一致时配置 FieldNameMapper

默认情况下，Goja 会按 Go 字段名处理映射。如果结构体字段是 UserID，脚本却使用更自然的 user_id 或 userId，就应该在创建 Runtime 后配置字段名映射，而不是把结构体字段改成不符合 Go 约定的写法。

type Session struct {
    UserID    string `json:"user_id"`
    ExpiresAt int64  `json:"expires_at"`
}

func exportSession() (Session, error) {
    vm := goja.New()
    // 让 JavaScript 使用 json 标签中的字段名，保持协议命名稳定。
    vm.SetFieldNameMapper(goja.TagFieldNameMapper("json", true))

    value, err := vm.RunString(`({ user_id: "u-17", expires_at: 1893456000 })`)
    if err != nil {
        return Session{}, fmt.Errorf("运行脚本失败: %w", err)
    }

    var session Session
    // 同一个 Runtime 的字段映射会参与本次导出。
    if err := vm.ExportTo(value, &session); err != nil {
        return Session{}, fmt.Errorf("导出 Session 失败: %w", err)
    }
    return session, nil
}

第二个参数传 true 表示使用标签值时也考虑标签选项。这里的重点不是机械记住参数，而是让 JavaScript 的公开字段名和 Go 的内部字段名有一个明确协议。字段映射必须在导出前配置到同一个 Runtime 上。

嵌套对象和数组怎么处理

只要目标结构体把嵌套层级声明清楚，嵌套对象和数组可以跟普通字段一起定向导出。下面这个模型把脚本对象中的 meta 和 items 保留为 Go 的嵌套类型。

type Item struct {
    Code  string `json:"code"`
    Count int    `json:"count"`
}

type Payload struct {
    Meta  struct {
        TraceID string `json:"trace_id"`
    } `json:"meta"`
    Items []Item `json:"items"`
}

func exportPayload(vm *goja.Runtime) (Payload, error) {
    vm.SetFieldNameMapper(goja.TagFieldNameMapper("json", true))
    value, err := vm.RunString(`({
        meta: { trace_id: "trace-9" },
        items: [{ code: "A", count: 2 }, { code: "B", count: 5 }]
    })`)
    if err != nil {
        return Payload{}, fmt.Errorf("运行脚本失败: %w", err)
    }

    var payload Payload
    // 目标类型表达嵌套对象与数组形状，导出时统一处理。
    if err := vm.ExportTo(value, &payload); err != nil {
        return Payload{}, fmt.Errorf("导出 Payload 失败: %w", err)
    }
    return payload, nil
}

如果脚本返回的对象有额外字段，固定结构体通常只关心已声明字段；如果字段类型无法转换，例如把需要整数的 count 设计成不可接受的字符串，就应该保留 ExportTo 返回的错误，不要在错误后继续使用半填充对象。

导出失败时按三层信息排查

遇到导出错误，可以按下面三层排查，而不是先把所有数据改成字符串：

1. 先看脚本值：确认 RunString 返回的确实是对象，而不是脚本异常、null 或函数。
2. 再看目标指针：确认传入的是 &target，并且目标结构体字段是可导出的 Go 字段。
3. 最后看字段与类型：检查 JSON 标签、字段名映射、数字/布尔值以及嵌套数组元素是否和目标类型一致。

func exportWithContext(vm *goja.Runtime, value goja.Value) (Profile, error) {
    var profile Profile
    // 不吞掉转换错误，调用方可以据此决定丢弃当前脚本结果。
    if err := vm.ExportTo(value, &profile); err != nil {
        return Profile{}, fmt.Errorf("JavaScript 对象转换为 Profile 失败: %w", err)
    }
    return profile, nil
}

还要注意 Goja Runtime 的使用边界：官方资料说明一个 Runtime 不能被多个 goroutine 同时使用。因此，把导出函数封装好并不意味着可以把同一个 Runtime 随意并发共享；并发任务应分别管理自己的 Runtime。

什么时候改用 Value.Export

如果对象结构是动态的，或者你需要先检查某个属性再决定落到哪一种模型，value.Export() 更灵活。它返回 Goja 的默认 Go 表示，常见结果是 map、slice 或基础类型，但调用方需要自己做类型判断。

func inspectDynamic(value goja.Value) (map[string]interface{}, error) {
    // Export 适合未知结构，先拿到默认 Go 表示再做业务判断。
    exported := value.Export()
    data, ok := exported.(map[string]interface{})
    if !ok {
        return nil, fmt.Errorf("期望对象，实际类型为 %T", exported)
    }
    return data, nil
}

可以把选择规则记成一句话：固定协议、固定字段和固定后续处理用 ExportTo；结构不固定、需要动态探查用 Export。不要为了省一次类型声明，把所有领域数据都退回到 map[string]interface{}。

常见问题

为什么导出后字段是零值？

先检查目标字段是否为导出字段、脚本字段名是否与默认映射一致，以及是否需要 TagFieldNameMapper。还要确认导出的对象确实包含该字段。

JavaScript 对象可以直接导出成指针结构体吗？

可以把目标指针传给 ExportTo，但目标类型、嵌套字段和脚本数据仍要能对应。不要把“传了指针”理解成跳过类型转换。

导出失败后还能继续使用目标对象吗？

不建议。导出过程中可能已经写入部分字段，失败后应丢弃这个目标值并返回错误，让上层重新决定是否重试或拒绝数据。

同一个 Goja Runtime 能否在多个 goroutine 中共享？

不能把同一个 Runtime 当成并发安全对象使用。需要并发执行时，为不同任务准备独立 Runtime，并把各自的脚本值和导出目标限制在对应 Runtime 内。

小结

Goja 把 JavaScript 对象交给 Go 结构体的核心是 Runtime.ExportTo(value, &target)：先运行脚本得到 goja.Value，再用目标结构体表达字段、嵌套对象和数组形状；命名不一致时配置 TagFieldNameMapper；动态数据才考虑 Value.Export()。把执行错误和转换错误分开处理，能让这条跨语言数据链路更容易维护。