Go JMESPath 怎么提前编译并复用字段查询

如果同一个 JMESPath 表达式会处理多份 JSON 数据，推荐把 jmespath.Compile 放到初始化或配置加载阶段，只保留一个可复用的 *jmespath.JMESPath，请求到来后直接调用它的 Search。这样能把“表达式有没有语法错误”和“这份数据能不能查到结果”分开处理。

官方地址：https://pkg.go.dev/github.com/jmespath/go-jmespath

本文使用的 go-jmespath 文档把查询对象定义为已编译的 JMESPath，并明确说明它可以被多个 goroutine 并发使用。下面从一次常见的“查询越来越慢、错误又不容易定位”的故障复盘开始。

先定位：问题通常不是 Search，而是重复解析表达式

故障现场常见的写法是把表达式字符串和输入数据一起交给 jmespath.Search。它适合低频、一次性的查询，但当每个请求都使用同一条字段路径时，表达式解析也会被重复触发。此时应把固定查询从数据处理函数中拿出来。

可以把一次查询拆成两个阶段：

• Compile：解析表达式并构造查询对象，失败通常意味着表达式本身写错。
• Search：让已经编译的对象作用于一份具体数据，失败则应结合当前输入排查。

用 Compile 在初始化阶段固定查询对象

下面的例子把订单列表中的高价值订单筛选出来。表达式只编译一次，构造失败直接返回错误，调用方可以决定是终止启动还是回退到默认配置。

package query

import (
    "fmt"

    "github.com/jmespath/go-jmespath"
)

type OrderQuery struct {
    compiled *jmespath.JMESPath
}

func NewOrderQuery(expression string) (*OrderQuery, error) {
    // 配置加载时编译，尽早暴露表达式语法错误。
    compiled, err := jmespath.Compile(expression)
    if err != nil {
        return nil, fmt.Errorf("compile order query: %w", err)
    }
    return &OrderQuery{compiled: compiled}, nil
}

func (q *OrderQuery) Select(data any) (any, error) {
    if q == nil || q.compiled == nil {
        return nil, fmt.Errorf("order query is not initialized")
    }
    // 每次只替换输入数据，复用同一个已编译查询。
    result, err := q.compiled.Search(data)
    if err != nil {
        return nil, fmt.Errorf("search orders: %w", err)
    }
    return result, nil
}

这个封装有两个重点：Compile 的错误不会被延迟到请求高峰才暴露；Select 不修改查询对象，只接收当前文档。因此它适合被多个处理器共享。

复用时只替换数据，不要反复创建查询对象

初始化完成后，可以把同一个查询对象交给多份已经解码的 JSON 数据。这里的示例使用 map[string]any 和 []any，避免把 JMESPath 查询结果误解成固定的 Go 结构体。

expression := "orders[?total > `1000`].{id: id, total: total}"

// 稳定表达式只在初始化阶段编译一次。
query, err := NewOrderQuery(expression)
if err != nil {
    return err
}

documents := []any{
    map[string]any{
        "orders": []any{
            map[string]any{"id": "A-01", "total": 1200},
            map[string]any{"id": "A-02", "total": 800},
        },
    },
    map[string]any{
        "orders": []any{
            map[string]any{"id": "B-01", "total": 1800},
        },
    },
}

for _, document := range documents {
    // 搜索阶段使用同一查询对象，输入文档彼此独立。
    result, err := query.Select(document)
    if err != nil {
        return err
    }
    fmt.Printf("%v\n", result)
}

查询结果仍然是接口值，实际类型由表达式决定。字段缺失、投影结果为空或输入结构不符合预期时，应在业务层定义清晰的空结果策略，而不是在查询函数里偷偷补默认值。

并发和动态表达式要分开处理

官方 API 文档说明，已编译的 JMESPath 可以被多个 goroutine 并发使用。因此稳定表达式可以作为只读依赖注入到处理器中，不需要为每个请求复制一份查询对象。

但“查询对象可并发复用”不等于“所有输入都能共享”。每个请求仍应使用自己的数据值；如果业务会原地修改输入 map 或切片，应先解决输入数据的所有权问题。

动态表达式则是另一条路径：表达式来自用户或外部配置时，必须调用 Compile 并返回错误，不能为了省代码使用 MustCompile。后者在解析失败时会 panic，只适合源码中可控、固定的全局表达式。若确实需要缓存动态表达式，应以完整字符串为键，设置大小上限和失效策略，避免把无限输入变成无限缓存。

常见问题

Compile 成功后，Search 还会返回 error 吗？

会。Compile 只负责解析表达式，Search 仍可能因为当前输入或函数执行产生错误，所以两处都要保留错误处理。

没有重复查询时也要预编译吗？

不必为了形式而预编译。单次低频查询可以直接使用包级 Search；当表达式稳定且会被多份数据反复执行时，预编译才有清晰的维护价值。

小结

这次故障的修复点不是盲目更换 JSON 库，而是把 JMESPath 的表达式生命周期和数据生命周期分开：稳定表达式在初始化阶段用 Compile，请求路径只调用可复用对象的 Search，动态表达式保留显式错误处理。这样既能提前发现配置问题，也能让并发复用边界保持清楚。