Go SJSON 数组末尾追加元素时路径应该怎么写

在 Go 里用 SJSON 往已有 JSON 数组末尾追加元素，路径写成 数组字段.-1。例如数组字段叫 items，就使用 items.-1；这里的 -1 是 SJSON 对“追加到数组尾部”的特殊约定，不是要访问一个名为 -1 的普通成员。

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

这个区别很重要：items.1 表示定位已有的第二个元素，items.4 则是把值放到更靠后的位置，可能在中间留下 null。下面只围绕“数组末尾追加”这个问题拆开说明。

SJSON 追加数组元素时，路径的关键是 -1

假设原始 JSON 是一个对象，items 是数组。追加时不要先计算数组长度再拼出数字下标，直接把末段写成 -1 更能表达意图：

package main

import (
    "fmt"
    "log"

    "github.com/tidwall/sjson"
)

func main() {
    input := `{"items":[{"id":1},{"id":2}]}`

    // -1 表示把新值追加到 items 数组当前末尾。
    output, err := sjson.Set(input, "items.-1", map[string]int{"id": 3})
    if err != nil {
        // 路径或输入不符合预期时保留错误，避免静默发布坏 JSON。
        log.Fatal(err)
    }

    fmt.Println(output)
}

这段代码的路径只有两段：先找到 items，再用 -1 表示追加位置。返回值会保留原来的两个对象，并在数组尾部增加 {"id":3}。SJSON 的 Set 接收 JSON 文本、路径和要写入的值，返回改写后的 JSON 文本与错误。

不要把追加路径和具体下标混在一起

同一个数组里，数字下标和 -1 表达的是两类不同动作。数字下标面向一个确定位置，-1 面向“当前末尾”。写排障代码时，先问清楚调用方是要更新某条已有记录，还是要产生一条新记录。

尤其不要把 len(items) 当成永远安全的追加下标：如果 JSON 在另一个协程或请求路径里已经变化，预先计算的长度就可能和真正写入时的结构不一致。对“只追加”这个意图，-1 更直接。

越过数组末尾时，为什么会出现 null

如果把路径写成一个明显大于当前长度的数字下标，SJSON 会把这个位置视为目标位置，中间缺少的位置可能以 null 补齐。这和末尾追加不是一回事，也会让下游遍历逻辑遇到空元素。

package main

import (
    "fmt"

    "github.com/tidwall/sjson"
)

func main() {
    input := `{"items":["a","b"]}`

    // 4 是明确的目标下标，不是“追加”的别名；中间位置可能出现 null。
    output, err := sjson.Set(input, "items.4", "e")
    if err != nil {
        fmt.Println("path error:", err)
        return
    }
    fmt.Println(output)
}

因此，业务只是追加新对象时应回到 items.-1。只有接口协议真的要求一个固定位置，才考虑数字下标，并同时处理中间空位对序列化、遍历和校验的影响。

嵌套数组和数字对象键要分别判断

追加规则可以放进更深的路径，例如订单对象里有一个 lines 数组时，可以写成 orders.-1.lines.-1，但这表达的是“给 orders 末尾追加一个对象，再给它的 lines 追加元素”的组合意图。若对象本身已经存在，才适合写确定的对象或数组路径，比如 orders.0.status。

另一个容易混淆的情况是对象键本身由数字组成。数组下标通常写成数字段；如果 JSON 对象里真的有一个键名 2313，则应使用冒号形式把它标记为对象键，例如 users.:2313.name，不要把它当成数组位置。

写入前后记住这份小清单

• 只想向已有数组末尾新增值：使用 items.-1。
• 要改已有元素：使用确定的数字下标，并确认下标确实属于目标数组。
• 不希望产生 null 空位：不要用越过末尾的数字下标模拟追加。
• 数组或父对象可能不存在：先根据业务决定是补建结构，还是返回错误，不要把隐式创建当成数据校验。
• 路径中的点号、冒号有特殊含义；字段名含这些字符时，按 SJSON 的转义规则处理。

归根结底，SJSON 的追加写法就是把数组字段和 -1 连接起来。把它和“修改某个位置”“跳到更远位置”“访问数字对象键”分开，路径就会从一串字符串变成清晰的写入意图。

相关问题

空数组也能使用 items.-1 吗？

文章中的核心用法针对已有数组。遇到空数组时，先确认输入结构和业务期望，再处理返回值与错误，不要仅凭路径字符串推断最终对象形状。

为什么不直接用数组长度作为下标？

长度需要在写入前单独读取，容易和实际写入时的结构脱节；-1 直接表达追加语义，代码也更容易审查。

追加对象时可以传 Go struct 吗？

SJSON 支持多种 Go 值；不在本文范围内的类型仍应结合序列化结果和错误返回谨慎处理。