Go GJSON 怎么只提取 JSON 数组中的指定字段

Go 里用 GJSON 处理一段 JSON 字符串时，如果目标是“只留下数组对象中的几个字段”，关键不是先把整段 JSON 反序列化成 map[string]any，而是把数组路径和字段路径写清楚。直接提取单字段时使用 items.#.id；需要保留多个字段时，再用条件查询后的字段路径或 v1.3.0 引入的多路径语法构造对象。

官方地址：https://github.com/tidwall/gjson

下面的示例都围绕一个边界：输入是对象中的 JSON 数组，输出只包含调用方需要的字段。GJSON 返回的是 Result，需要时再用 Array()、String() 或 Raw 取成 Go 值。

先把数组字段投影出来

假设订单服务返回了 items 数组，每个元素都有 id、sku、quantity 和 price。只取所有订单号，路径写成 items.#.id；只取商品编码则换成 items.#.sku。其中 # 表示数组位置，后面的字段会作用到每个元素。

package main

import (
    "fmt"

    "github.com/tidwall/gjson"
)

func main() {
    payload := `{"items":[{"id":101,"sku":"A-17","quantity":2},{"id":102,"sku":"B-03","quantity":1}]}`

    // # 遍历 items 的每个对象，只保留 id 字段。
    ids := gjson.Get(payload, "items.#.id")
    fmt.Println(ids.Raw) // [101,102]

    // Array() 适合继续逐个读取 Result，而不是手动拆 Raw 字符串。
    for _, itemID := range ids.Array() {
        // String() 对数字也能给出可展示的文本；需要整数时应改用 Int()。
        fmt.Println(itemID.Int())
    }
}

这个写法的结果仍然是 JSON 数组，不是 Go 的 []int64。如果后续接口需要强类型切片，可以在遍历 Result.Array() 时调用 Int() 并自行追加；如果只需要把字段原样转发，保留 ids.Raw 更省事。

条件筛选后再提取字段

只提取字段不等于筛选字段。比如订单列表里只想找状态为 paid 的订单号，先用 #(status=="paid")# 找出所有命中的对象，再接上 .id：

package main

import (
    "fmt"

    "github.com/tidwall/gjson"
)

func main() {
    payload := `{"items":[{"id":101,"status":"paid"},{"id":102,"status":"pending"},{"id":103,"status":"paid"}]}`

    // 末尾的 # 表示保留全部命中项；省略它只会取第一个匹配对象。
    paidIDs := gjson.Get(payload, `items.#(status=="paid")#.id`)
    fmt.Println(paidIDs.Raw) // [101,103]

    // 不存在的数组路径会得到空数组；业务上仍要根据场景决定是否视为空结果。
    if !paidIDs.Exists() {
        fmt.Println("没有找到 paid 订单")
    }
}

这里有两个容易混淆的符号：#(条件) 默认返回第一个匹配项，#(条件)# 才表示全部匹配项。要提取多个字段，可以分别写 items.#(status=="paid")#.id 和 items.#(status=="paid")#.sku；如果希望每个结果仍是对象，则使用下一节的多路径。

用多路径一次构造对象

GJSON v1.3.0 起支持多路径：方括号构造数组，对象路径用花括号包裹。把它放在数组投影之后，就可以从每个元素里只保留所需键。下面的路径将每个用户投影成 id 和 display_name 两个字段：

package main

import (
    "fmt"

    "github.com/tidwall/gjson"
)

func main() {
    payload := `{"users":[{"id":7,"name":"Lin","role":"editor"},{"id":8,"name":"Qiao","role":"viewer"}]}`

    // .{...} 为每个数组元素建立一个只含指定字段的新对象。
    projected := gjson.Get(payload, `users.#.{"id":id,"display_name":name}`)
    fmt.Println(projected.Raw) // [{"id":7,"display_name":"Lin"},{"id":8,"display_name":"Qiao"}]

    // Result.Raw 保留 JSON 形态，适合直接写入下游响应。
    if projected.Type != gjson.JSON {
        fmt.Println("投影结果不是 JSON 数组")
    }
}

如果还要筛选角色，可以把条件放在数组路径中：users.#(role=="editor")#.{"id":id,"display_name":name}。多路径中的键名可以与原字段不同，因此它适合给前端或消息消费者生成稳定的“展示对象”，但不要把它误认为 Go 结构体解码。

字节输入和缺失字段要分开处理

上游已经给你 []byte 时，优先使用 gjson.GetBytes，避免先把字节转成字符串。字段可能缺失时，不要用 String() 的空字符串来判断“字段不存在”，应该先看 Exists()，再按类型取值。

package main

import (
    "fmt"

    "github.com/tidwall/gjson"
)

func firstLabel(data []byte) (string, bool) {
    // GetBytes 直接读取字节输入；路径只提取第一个元素的 label。
    label := gjson.GetBytes(data, "items.0.label")
    if !label.Exists() {
        // 缺失字段与存在但为空字符串是两个业务状态。
        return "", false
    }
    return label.String(), true
}

func main() {
    label, ok := firstLabel([]byte(`{"items":[{"label":"主商品"}]}`))
    fmt.Println(label, ok)
}

数组投影得到的 Result.Array() 在路径不存在时是空数组；这对列表接口很方便，但也意味着“路径写错”和“确实没有元素”可能需要额外的输入约束来区分。若 JSON 来自不可控来源，可以先用 gjson.Valid 判断格式，再进行字段读取。

从旧查询写法迁移到当前路径

如果项目里曾经使用过 #[...] 查询，不要把它和多路径的方括号混为一谈。GJSON 文档说明，v1.3.0 为避免与多路径语法冲突，把数组查询写法改成 #(...)；旧写法在下一个大版本前仍保持兼容。新代码建议直接采用当前写法，减少未来迁移时的歧义：

// 旧写法：历史代码中可能出现，继续运行不代表应该新增。
oldPath := `items.#[status=="paid"]#.id`

// 当前写法：用圆括号表示查询条件，用末尾 # 表示返回全部命中项。
currentPath := `items.#(status=="paid")#.id`

// 迁移检查：把查询路径集中成常量，避免散落在业务代码中难以替换。
_ = oldPath
_ = currentPath

真正需要迁移的是旧版本中形如 items.#[status=="paid"]#.id 的路径；它不等同于当前的 items.#(status=="paid")#.id。如果你的代码还包含 v1.3.0 的多路径对象，应单独检查花括号内的字段名和别名，不要只做字符替换。

几个容易写错的路径

最后可以按这份迁移清单收口：先确认数组实际位于哪一层，再决定是单字段投影还是多路径对象；需要全部匹配项时保留查询末尾的 #；向下游输出时区分 Raw、Array() 与具体类型取值；旧查询只在维护旧代码时保留，新代码统一使用 #(...)。

相关问题

GJSON 的 #.field 会返回 Go 切片吗？

不会，它先返回 gjson.Result，结果内容是 JSON 数组。需要 Go 切片时遍历 Array()，再按字段调用 Int、String 等方法。

为什么条件查询后只有一个对象？

检查条件后是否写了第二个 #。#(条件) 取第一个匹配项，#(条件)# 才会收集全部匹配项。

多个字段一定要先反序列化吗？

不一定。只需要 JSON 形态的对象数组时，可以用多路径直接投影；如果后续要做复杂业务计算或强类型校验，再考虑解码到结构体。