Plugins
Host API
四种运行时的完整 SDK 函数参考 — 数据库、HTTP、VFS、KV 存储、配置、事件。
Host API 是插件与 RaisFast 之间的接口。所有函数受权限控制 — 除非在 [permissions] 中声明，否则一律拒绝访问。
数据库
原始 SQL
| 函数 | 说明 |
|---|---|
dbQuery(sql, params?) | SELECT 查询，返回对象数组 |
dbExec(sql, params?) | INSERT / UPDATE / DELETE，返回 { rows_affected } |
dbBegin() | 开启事务 |
dbCommit() | 提交事务 |
dbRollback() | 回滚事务 |
const rows = dbQuery("SELECT * FROM products WHERE price > ?", [100]);
const result = dbExec("UPDATE products SET stock = stock - 1 WHERE id = ?", [id]);注意：
dbQuery返回的整数列为null，需用CAST(col AS TEXT)转为字符串后再parseInt。
高级 DB API
| 函数 | 返回 | 说明 |
|---|---|---|
dbInsert(table, data, options?) | { rows_affected } | 插入一行 |
dbFetchOne(table, where?, options?) | data 或 null | 获取单行 |
dbFetchAll(table, where?, options?) | { data, total } | 获取多行 |
dbUpdate(table, data, where?, options?) | { rows_affected } | 更新行 |
dbDelete(table, where?, options?) | { rows_affected } | 删除行 |
dbCount(table, where?, options?) | { count } | 计数 |
dbIncrement(table, cols, where?, options?) | { rows_affected } | 原子递增/递减 |
dbSum(table, column, where?, options?) | { sum } | SUM 聚合 |
dbGroupBy(table, options?) | { data, total } | GROUP BY 聚合 |
dbInsert("orders", { title: "新交易", amount: 5000 });
const deal = dbFetchOne("orders", { id: "abc123" });
const { data } = dbFetchAll("orders",
{ status: "active" },
{ order_by: "amount DESC", limit: 10, offset: 0 }
);
dbUpdate("orders", { status: "closed" }, { id: "abc123" });
dbDelete("orders", { status: "cancelled" });
const { count } = dbCount("orders", { status: "active" });
dbIncrement("orders", { view_count: 1 }, { id: "abc123" });
const { sum } = dbSum("orders", "amount", { status: "closed" });
const { data } = dbGroupBy("orders", {
group_by: "status",
count: true,
sum: "amount"
});Where 格式
where 参数接受两种格式：
对象（自动生成 WHERE col = ? AND ...）：
{ status: "active", category: "electronics" }数组（参数化 SQL）：
["amount > ? AND status = ?", [1000, "active"]]空值或 null 表示无 WHERE 条件。
Options
| 键 | 说明 |
|---|---|
order_by | 排序："col ASC" 或 "col1 ASC, col2 DESC" |
limit | 最大返回行数 |
offset | 跳过行数 |
tenant | "some_id"（显式）、false（禁用）、省略（自动） |
SQL 占位符
使用 dbPh(idx) 获取当前数据库的正确占位符：
- SQLite / MySQL：
? - PostgreSQL：
$1、$2、...
const ph = dbPh(1); // SQLite 上为 "?"，PostgreSQL 上为 "$1"事务
dbBegin();
try {
dbExec("INSERT INTO orders ...");
dbExec("UPDATE products SET stock = stock - 1 ...");
dbCommit();
} catch (e) {
dbRollback();
}HTTP
| 函数 | 返回 | 说明 |
|---|---|---|
httpGet(url) | string 或 null | HTTP GET 原始响应 |
httpGetJson(url) | object 或 null | HTTP GET 解析 JSON |
httpPost(url, body) | string 或 null | HTTP POST 原始响应 |
httpPostJson(url, body) | object 或 null | HTTP POST 解析 JSON |
需要 http 权限。10 秒超时，1 MB 最大响应体。
const data = httpGetJson("https://api.example.com/v1/products");
const result = httpPostJson("https://api.example.com/webhook", { event: "test" });虚拟文件系统（VFS）
| 函数 | 返回 | 说明 |
|---|---|---|
vfsRead(path) | string 或 null | 读取文件内容 |
vfsWrite(path, content) | bool | 写入文件（自动创建目录） |
vfsDelete(path) | bool | 删除文件 |
vfsExists(path) | bool | 检查文件是否存在 |
vfsList(path) | string[] | 列出目录 |
vfsStat(path) | object 或 null | 文件元数据 |
需要 filesystem 权限。每个插件在 {VFS_ROOT}/{plugin_id}/ 下有隔离沙箱。路径穿越（..）被阻止。
vfsWrite("/reports/daily.json", JSON.stringify(report));
const data = JSON.parse(vfsRead("/reports/daily.json"));
const exists = vfsExists("/reports/daily.json");
const files = vfsList("/reports");
const stat = vfsStat("/reports/daily.json");
// { size: 1024, is_dir: false, modified: 1700000000 }配额：单文件最大 PLUGIN_VFS_MAX_FILE_SIZE（默认 1 MB），总配额 PLUGIN_VFS_MAX_TOTAL_SIZE（默认 10 MB）。
KV 存储
| 函数 | 返回 | 说明 |
|---|---|---|
storeGet(key) | string 或 null | 读取值 |
storeSet(key, value) | bool | 写入值（upsert） |
数据按插件 ID 隔离 — 插件间互不可见。
storeSet("last_sync", "2026-01-01");
const val = storeGet("last_sync");配置
| 函数 | 返回 | 说明 |
|---|---|---|
configGet(key) | string 或 null | 读取配置值 |
需要 config 权限。可用的键：app.host、app.port、app.env、app.base_url、jwt.access_expires、jwt.refresh_expires、upload.dir、upload.max_size、plugin.max_memory_mb、plugin.default_timeout_ms。
内容查询
| 函数 | 返回 | 说明 |
|---|---|---|
getPost(slug) | object 或 null | 按 slug 获取文章 |
需要 read:posts 数据库权限。
工具函数
| 函数 | 返回 | 说明 |
|---|---|---|
ok(data) | any | 返回成功数据 |
fail(status, msg) | error | 返回 HTTP 错误 |
extractJson(input, field?) | any | 解析 JSON 并提取字段（支持点号路径："params.id"） |
logInfo(msg) | — | 日志（info 级别） |
logWarn(msg) | — | 日志（warn 级别） |
logError(msg) | — | 日志（error 级别） |
newId() | string | 生成 UUID v7 |
eventEmit(type, data) | — | 发射自定义事件 |
运行时函数名映射
JS 和 Lua 使用 camelCase。Rhai 使用 snake_case。WASM 在 WIT 中使用 kebab-case。
| JS / Lua | Rhai | WASM (WIT) |
|---|---|---|
dbQuery | db_query | db-query |
dbExec | db_execute | db-execute |
dbBegin | db_begin | db-begin |
dbCommit | db_commit | db-commit |
dbRollback | db_rollback | db-rollback |
dbInsert | db_insert | — |
dbFetchOne | db_fetch_one | — |
dbFetchAll | db_fetch_all | — |
dbUpdate | db_update | — |
dbDelete | db_delete | — |
dbCount | db_count | — |
dbIncrement | db_increment | — |
dbSum | db_sum | — |
dbGroupBy | db_group_by | — |
httpGet | http_get | http-get |
httpPost | http_post | http-post |
getConfig | get_config | get-config |
storeGet / getData | get_data | get-data |
storeSet / setData | set_data | set-data |
getPost | get_post | get-post |
vfsRead | vfs_read | vfs-read |
vfsWrite | vfs_write | vfs-write |
vfsDelete | vfs_delete | vfs-delete |
vfsExists | vfs_exists | vfs-exists |
vfsList | vfs_list | vfs-list |
vfsStat | vfs_stat | vfs-stat |
emitEvent | emit_event | emit-event |
newId | new_id | — |
log | log | log |
dbPh | db_ph | — |
运行时专属函数
Rhai 专属
| 函数 | 说明 |
|---|---|
parse_json(str) | 解析 JSON 为 Rhai 值 |
to_json(val) | 将 Rhai 值转为 JSON |
to_upper(str) | 转大写 |
to_lower(str) | 转小写 |
replace(str, from, to) | 字符串替换 |
remove(map, key) | 从 map 中移除键 |
Lua 专属
| 函数 | 说明 |
|---|---|
Host.jsonEncode(val) | 编码 Lua 值为 JSON |
Host.jsonDecode(str) | 解码 JSON 为 Lua 值 |
Lua 沙箱无原生 JSON 支持，因此作为宿主函数提供。
WASM 限制
WIT 接口目前仅提供原始 SQL（db-query、db-execute）。高级 DB API（dbInsert、dbFetchOne 等）、newId 和 dbPh 尚未在 WASM 中可用。