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%。
This commit is contained in:
2026-09-10 15:44:19 +08:00
parent 7c9a70712e
commit 98eb734caa
2 changed files with 67 additions and 11 deletions
+27
View File
@@ -11,6 +11,33 @@
// .Where(db.C("name").Eq("测试产品"))
// .Select("name", "cost_price")
//
// # 这个库能做什么
//
// 核心就五个概念,覆盖九成用法:
//
// Engine 引擎。管编译缓存和配置,一个进程一个
// Script 一份编译好的脚本 + 它的 VM 池。热更新时整体顶替
// Instance 独占一个 VM 的实例,脚本里 this 上的状态跨调用保持
// Scope 作用域。让同一个 ctx 下的多个脚本共享 Go 侧对象
// Extension 扩展。给脚本添一个全局对象,并附上 TS 类型
//
// 用不到就不用看的(按需要翻):
//
// 脚本从哪来 Loader / LoaderFunc / Prepared / Versioned / Tag / Overlay
// 默认从目录加载(esm 子包)。要从数据库、配置中心取,实现 Loader;
// 多来源叠加、后面盖前面,用 Overlay
// 自己打包 Bundle / FinalizeBundle / BundleOption
// 只有一段源码、不走目录时用
// 自定义调用约定 Caller / Result / WithCall
// 本库不预设脚本回调该长什么样。要按形参个数分派、要传 Go 闭包
// 当 next,用它
// 观测与排错 Stats / Error / Kind / Frame
// VM 池统计;错误带齐「哪个脚本、哪个函数、脚本里哪一行」
//
// 明确**不做**的:不代管实例生命周期(没有按 key 复用、没有空闲回收)、
// 没有事件循环(定时器、网络、真正的异步都没有)、不提供沙箱隔离
// (脚本能拿到你放行的 Go 对象,它们的方法是真能调的)。
//
// # 基本用法
//
// loader, err := esm.NewLoader("app/src")