JSONata 查询（jsonata）
灵感：能力工具箱 jsonata-query（pkg: jsonata）。
> 小四原创：一条表达式从深层客户 JSON 取出联系人、跟进列表或聚合结果，免手写多层可选链。
何时使用
- 嵌套客户资料要按路径批量抽字段
- 报表/导出前用表达式过滤子数组
- 配置化「取数规则」，不想写死一堆
?.
硬约束
- 使用
jsonata；表达式由业务配置或用户输入，默认只读查询。 - 对不可信表达式：超时/复杂度限制；勿把任意表达式当
eval。 - 查询失败返回可读错误，不抛到白屏。
- 示例数据勿含真实手机号明文（可用脱敏样例）。
- 实现要点注释标 小四原创。
推荐实现
import jsonata from 'jsonata'
// 小四原创：安全求值客户 JSON
export async function queryCustomerJson<T = unknown>(
data: unknown,
expression: string,
opts?: { timeoutMs?: number },
): Promise<{ ok: true; value: T } | { ok: false; error: string }> {
const expr = String(expression || '').trim()
if (!expr) return { ok: false, error: '表达式为空' }
if (expr.length > 500) return { ok: false, error: '表达式过长' }
try {
const compiled = jsonata(expr)
// 小四原创：部分环境支持 timeout；无则直接 evaluate
const value = (await Promise.resolve(
typeof (compiled as any).evaluate === 'function'
? compiled.evaluate(data, opts?.timeoutMs ? { timeout: opts.timeoutMs } : undefined)
: compiled.evaluate(data),
)) as T
return { ok: true, value }
} catch (e) {
return { ok: false, error: e instanceof Error ? e.message : String(e) }
}
}
常用表达式示例
name
contacts[0].phone
followups[type="visit"].{ "at": at, "note": note }
$count(followups)
Agent 步骤
- 安装/引入
jsonata。 - 提供：JSON 输入框 + 表达式框 + 结果预览。
- 预置 3～5 条客户域示例表达式。
- 自测：深层路径与数组过滤能出结果。
不要做
- 用 JSONata 执行副作用写盘/发请求。
- 把用户整库 JSON 默认上传第三方。
附加
- README.md · reference.md · templates/usage.md
