Redis JSONPath 查询数组字段的返回边界

Redis JSONPath 查询数组字段时，最容易误判的不是路径能不能写，而是返回值到底代表什么。以 $.orders[*].items[*].sku 为例，它会匹配多个 sku 节点；JSON.GET 会用一个顶层数组承载这些匹配值，如果每个订单本身还有一层 items 数组，响应中的嵌套层级也会保留。它不是一个名为 sku 的标量字段，也不会自动替调用方“拍平”数组。

官方地址：https://redis.io/docs/latest/develop/data-types/json/path/

本文只围绕 Redis JSONPath 查询数组字段的返回边界展开：怎样判断命中节点、为什么会看到两层数组，以及什么时候应该改路径、改输出契约或改用投影。示例使用静态命令和响应说明，不把说明图当作实际运行截图。

先把 JSONPath 和 legacy path 分开

Redis JSON 同时支持 JSONPath 和早期的 legacy path。路径以 $ 开头时使用 JSONPath；不以 $ 开头时，Redis 按 legacy path 解释。这个首字符会改变多匹配的行为，不能只看后面的 [*] 就认为两种写法等价。

这也是排查“为什么结果多了一层数组”的第一步：先确认调用方传入的是以 $ 开头的 JSONPath，还是 legacy path。路径字符串前是否有 $，比是否使用点号更关键。

用一个嵌套数组样例固定命中对象

先建立一个两层数组文档。外层是订单，内层是订单商品；路径最终查询每个商品的 sku。命令块里的注释只解释步骤，不能混入 JSON 本身，因为 JSON 文档必须保持有效。

# 写入一个外层订单数组、内层商品数组的最小样例
redis-cli JSON.SET order:demo $ '{"orders":[{"id":"o-100","items":[{"sku":"A100"},{"sku":"A101"}]},{"id":"o-200","items":[{"sku":"B200"}]}]}'

# 查询所有订单中所有商品的 sku，$ 表示使用 JSONPath
redis-cli JSON.GET order:demo '$.orders[*].items[*].sku'

这个路径经过 orders[*] 时选择多个订单，再经过 items[*] 时选择每个订单中的多个商品，最后落到每个商品的 sku 值。它命中的不是一个数组节点，而是三个字符串节点：A100、A101 和 B200。

JSON.GET 为什么会保留数组层级

对单个 JSONPath，JSON.GET 返回 JSON 序列化的匹配结果。多匹配结果需要一个容器表达“命中了哪些节点”，所以响应至少有一个顶层数组。若命中的节点本身就是数组，数组字段的结构也会继续存在。

例如查询每个订单的商品数组：

# 查询的是每个订单的 items 数组，而不是数组里的每个元素
redis-cli JSON.GET order:demo '$.orders[*].items'

概念上的响应形态是：

[
  [
    {"sku":"A100"},
    {"sku":"A101"}
  ],
  [
    {"sku":"B200"}
  ]
]

最外层表示“匹配到两个订单的 items 节点”，每个内层数组则是对应订单原本的商品数组。把它误读成一张扁平商品表，会在订单与商品的对应关系上丢失边界。若路径改成 $.orders[*].items[*].sku，结果会变成“每个匹配 sku 的值组成的顶层数组”，但不要据此推断所有嵌套数组都自动扁平化。

用具体路径区分字段、元素和匹配集合

当调用方说“查询数组字段”时，通常可能指三件不同的事：返回整个数组、返回数组中的一个元素，或者返回多个元素的集合。它们的路径边界不同。

如果接口只需要某个订单的商品数组，直接按订单下标或稳定字段选中订单，再返回 items。如果接口要聚合所有订单的 sku，就应该在接口契约中明确返回“字符串数组”，而不是让消费者根据响应中出现的括号数量猜含义。

空结果、单值和数组集合要分开处理

JSONPath 的结果边界不仅影响成功响应，也影响无匹配情况。查询条件没有命中时，调用方应把空集合当作“没有匹配节点”，不要直接当成 Redis key 不存在。key 不存在、路径存在但结果为空、路径命中一个空数组，这三种状态可能需要不同的业务处理。

package main

import (
    "encoding/json"
    "fmt"
)

// DecodeStringList 只接受 JSONPath 返回的字符串集合，拒绝把嵌套数组误当成字符串。
func DecodeStringList(raw string) ([]string, error) {
    var values []string
    // 反序列化失败时把错误交给调用方，避免用空切片掩盖响应格式变化。
    if err := json.Unmarshal([]byte(raw), &values); err != nil {
        return nil, fmt.Errorf("decode JSONPath string list: %w", err)
    }
    return values, nil
}

func main() {
    // 这里的 raw 对应 JSON.GET 对多个 sku 命中的 JSON 文本。
    values, err := DecodeStringList(`["A100","A101","B200"]`)
    if err != nil {
        panic(err)
    }
    fmt.Println(len(values))
}

这个 Go 示例只适合调用契约已经收窄为“顶层字符串数组”的场景。如果路径是 $.orders[*].items，响应应解码成 [][]Item 或更明确的 DTO，而不是强行解码成 []string。客户端类型必须跟路径实际命中节点保持一致。

需要时再用过滤或 projection 收窄结果

路径选择正确后，才考虑过滤表达式。例如只查询订单号为 o-100 的商品 sku，可以把过滤放在订单数组层，再进入商品数组。过滤改变的是命中范围，不会把一个数组字段凭空变成标量。

# 先筛选订单，再读取该订单下的 sku；引号避免 shell 解释方括号和引号
redis-cli JSON.GET order:demo '$.orders[?(@.id=="o-100")].items[*].sku'

在支持 projection 的 Redis 版本中，还可以使用诸如 $.orders.length() 这样的表达式得到计算结果；这属于“计算一个值”，不应与普通路径的“选择节点”混为一谈。文章的核心边界仍然是：普通 JSONPath 路径可能选中多个节点，JSON.GET 会用数组表达匹配集合。

排查时记住这四个判断

1. 先看路径是否以 $ 开头，确认使用的是 JSONPath 还是 legacy path。
2. 再看最后一个路径段落到的是数组节点、对象节点还是标量节点。
3. 看到多一层数组时，分别标记“匹配集合层”和“命中值本身的数组层”。
4. 最后让应用 DTO 与查询路径绑定，空集合、单值集合和嵌套数组不要共用一个反序列化类型。

常见问题：为什么 $.items[*] 不是返回一个 item？因为 [*] 选择的是多个数组元素，JSONPath 用集合表达命中结果。为什么查 $.orders[*].items 会出现两层数组？外层是多个订单的匹配集合，内层是每个订单自己的 items 数组。legacy path 和 JSONPath 能混用吗？可以在命令能力允许时同时存在，但返回语义必须按实际包含的路径语法理解。空数组和 key 不存在一样吗？不一定，前者可能是存在的文档或路径没有匹配项，业务上应单独定义。

Redis JSONPath 的返回边界可以归结为一句话：路径负责选择节点，JSON.GET 负责把匹配节点序列化出来，节点本身的数组结构不会因为查询而消失。把这两层职责分开，数组字段的响应就不会再靠猜。