 what
|
98eb734caa
|
docs: 把能力面摆出来，更新性能数字
起因是「不知道有什么功能」——公开 API 有 14 个类型、17 个 With* 选项，全部平铺
在同一层文档里，看不出哪些是必须懂的。
doc.go 和 README 顶部都加了分层的能力清单：核心五个概念（Engine / Script /
Instance / Scope / Extension，覆盖九成用法），加上「用不到就不用看的」四类。
同时写清楚明确**不做**的三件事：不代管实例生命周期、没有事件循环、不提供沙箱隔离
（脚本能拿到你放行的 Go 对象，它们的方法是真能调的）。
性能数字重测了一遍。InstanceCall 454 → 300 ns——删掉 lastUsed 省下的两次
time.Now() 兑现了。
顺带加了一句测量方法的提醒：这些数字取的是多轮**最小值**。我这轮一度以为
Script.Call 退化了 27%，逐个 commit 二分下去发现跳变落在一个只删死代码和改注释
的 commit 上——那不可能影响调用路径。加大样本后两边最小值持平，是机器噪声。
中位数会被离群值带偏，微基准在有别的负载时能飘 30%。
|
2026-09-10 15:44:19 +08:00 |
|
|
what
|
7e1893b246
|
refactor: 文件按主类型划分，一个 struct 一个功能
约定：文件名 = 主类型名；同一个类型要拆多个文件时用 类型_子项.go。
engine.go 355 → 231 行。原来混了三件不相干的事
engine_globals.go ← bind / lazyGlobal / freeze / defineReadOnly（96 行）
它是「Go 值 → 只读 JS 全局」的转换层，跟脚本缓存毫无关系
engine_console.go ← console.go，跟上面是同一主题
script.go 325 → 100 行，只留公开方法
script_vm.go ← VM 的取、还、装载。上个 commit 合一的三条路径现在住一起
script_static.go ← static.go
errors.go 364 → 150 行
errors_goja.go ← goja 错误的翻译层
errors_hints.go ← missingGlobalHint，一份 JS 运行时知识库，跟错误分类是
两回事；拆出来之后 missing_global_test.go 才有对应源文件
bundle_finalize.go ← esmwrap.go
bundle.go 收下 validIdent / hashVersion（原来住在 engine.go）
Engine.New 原来排在所有私有函数之后，挪到导出方法那一段。
classify 83 → 54 行：四个 errors.As 分支各手搓一个 8 字段的 &Error{}，脚本上下文
那三行重复了 4 遍，抽出 gojaError 构造器。
顺带修四处注释漂移：
Session/会话 代码里叫 Instance，注释里大面积残留。engine_globals.go 那条
「注入会话全局对象失败」还是用户可见文案，而公开 API 里根本
没有「会话」这个概念
Extension 文档示例写 Module() string，接口是 Module() (path, source string)。
这是唯一一段教人写扩展的文档，照抄编译不过
doc.go 的 freeze 说白名单「逐层拷贝成只读对象，不会跨 VM 共享可变的 Go map」，
但那只对 map[string]any 成立。结构体指针和 slice 是**共享同一个
对象**的——扩展走的正是这条路，不该被当成隔离保证
|
2026-09-10 15:28:59 +08:00 |
|
|
what
|
0627d49425
|
feat: 嵌入式 JS 脚本引擎核心
用 goja 承载业务回调，让业务逻辑变更不必重新编译发布 Go 程序。脚本用
ESM + TypeScript 写，Go 侧按名字把它们当普通对象实例化并调用方法。
主要组成：
- Engine 编译脚本、管配置，公开 API 不暴露任何 goja 类型
- Script 一份编译好的脚本 + 它的 VM 池，热更新时整体顶替
- Instance 独占一个 VM 的实例，状态留在 JS 侧
- Caller 自定义调用约定，把脚本函数适配成 Go 侧要的签名
- Scope 让同一个 ctx 下的多个脚本共享 Go 侧对象
- Extension 扩展接口：给脚本添全局对象，配套 TS 类型
- Overlay 多层 Loader 叠加，后面的盖前面的
几个关键取舍：
- 源码一律先过 esbuild 打包成 ESM，再改写成立即执行函数。goja 不认
import/export，而业务脚本要能拆文件、用 TypeScript。
- VM 池化复用，但每个 VM 单线程。goja 的 Runtime 不是 goroutine 安全的。
- Go 侧函数返回的 error 在脚本里表现为抛异常，不占返回值位置。
- 脚本能看见的全局只有白名单放行的那些，且注入是惰性的——没读到的
全局根本不会被转换。
|
2026-09-05 22:11:55 +08:00 |
|