Go JSONPatch 怎样用 JSON Pointer 表示包含斜杠的键

Go 的 evanphx/json-patch 使用 JSON Pointer 表达补丁位置。键名中的斜杠 / 要写成 ~1，波浪线 ~ 要写成 ~0。例如单个键 display/name 的路径是 /display~1name，不能写成 /display/name，后者表达的是 display 对象下的 name 成员。

官方地址：https://github.com/evanphx/json-patch

这项规则来自 JSON Pointer，并不是 Go 字符串语法。只要前端生成的补丁和后端采用相同路径约定，就能准确定位成员；是否使用浏览器生成请求，不会改变键名的转义方法。本文使用该库的 v5 导入路径，聚焦带斜杠键名的定位。

斜杠是键名，还是对象层级

配置导入经常会遇到带分隔符的成员名，例如展示名称键 display/name。这里的斜杠是业务键的一部分；但同一份配置也可以有一个 display 对象，其内部再有 name。两处数据即使外观看起来相近，也是两个独立位置。

设计调用接口时，建议接收“各层的原始键名列表”。一个字符串既可能是原始键，也可能是完整 Pointer；若让调用者自行猜测，最容易在字段本来包含斜杠时出错。

先转义每个键，再用斜杠连接

封装函数应当按成员处理，而不是先把完整路径拼好后统一替换。逐段处理能够保留层级分隔符；把完整路径中的斜杠全部替换，则会连层级关系一起抹掉。

下面的 pointer 函数先替换原始波浪线，再替换斜杠。代码中的“先后”只是编码函数的实现细节，不是业务操作步骤。这个顺序让新增的 ~1 不会被当成原始文本再次编码。函数接收原始名称，并不承担解析、解码或识别已转义文本的职责。

用一个补丁只修改目标键

以下原创示例可以放入已经依赖 github.com/evanphx/json-patch/v5 的 Go 项目。补丁把三个现有成员替换为新值，同时保留嵌套的 display.name。operation 只用于本例的 replace；如果扩展到 remove、copy 或 move，应按对应操作定义字段，尤其不能把所有操作都当成必须带 value。

package main

import (
    "encoding/json"
    "fmt"
    "strings"

    jsonpatch "github.com/evanphx/json-patch/v5"
)

// pointer 只接收原始键名，不接收已转义的 token 或完整路径。
func pointer(keys ...string) string {
    parts := make([]string, len(keys))
    for i, key := range keys {
        // 先处理原来的波浪线，避免再次转义后面新增的波浪线。
        key = strings.ReplaceAll(key, "~", "~0")
        parts[i] = strings.ReplaceAll(key, "/", "~1")
    }
    if len(parts) == 0 {
        return "" // 无成员层级表示整个文档。
    }
    return "/" + strings.Join(parts, "/")
}

type operation struct {
    Op    string `json:"op"`
    Path  string `json:"path"`
    Value any    `json:"value"`
}

func main() {
    // 同时保留含斜杠的键和嵌套对象，让两种目标容易区分。
    source := []byte(`{
        "display/name":"旧标题",
        "display":{"name":"嵌套标题"},
        "prefs":{"theme/name":"light"},
        "a~b":"原值"
    }`)
    ops := []operation{
        {Op: "replace", Path: pointer("display/name"), Value: "新标题"},
        {Op: "replace", Path: pointer("prefs", "theme/name"), Value: "dark"},
        {Op: "replace", Path: pointer("a~b"), Value: "更新值"},
    }
    // 让标准库负责 JSON 字符串编码，不手工拼接补丁文本。
    rawPatch, err := json.Marshal(ops)
    if err != nil {
        fmt.Println("补丁编码失败:", err)
        return
    }
    patch, err := jsonpatch.DecodePatch(rawPatch)
    if err != nil {
        fmt.Println("补丁解析失败:", err)
        return
    }
    result, err := patch.Apply(source)
    if err != nil {
        // replace 的目标不存在等情况会在应用补丁时报告错误。
        fmt.Println("补丁应用失败:", err)
        return
    }
    fmt.Println(string(result))
}

按示例的结构推导，display/name 会变为“新标题”，prefs 下的 theme/name 会变为 dark，a~b 会变为“更新值”；嵌套的 display.name 仍为“嵌套标题”。这些是代码语义说明，未附带本地运行记录。不要依赖输出 JSON 的成员顺序判断修改是否正确。

DecodePatch 处理补丁本身，Apply 才将补丁用于具体文档。即使补丁 JSON 能解析，也不能保证目标字段存在。这里选择 replace，是希望已有配置字段被准确修改；不应在应用失败时直接改成 add 来掩盖键名写错的问题。

不要把 Pointer 编码与其他编码混用

JSON Patch 的 path 是普通 JSON 字符串中的 Pointer。原始键包含引号、反斜杠或控制字符时，让 json.Marshal 处理 JSON 字符串这一层，不要自己在拼接的补丁文本中添加转义。它不会代替 pointer 函数编码成员中的斜杠。

同样，URL 编码不能代替成员名编码。把斜杠替换成 %2F 放进普通 path 字段，不能表达同样的成员名。带 # 的 URI fragment 表示法属于另一种表示形式，不要把它直接当成本例的 path。系统若把路径放在 URL 中，应明确外层传输编码在哪里解码，再交给补丁处理层。

对业务代码而言，最清楚的分工是：调用方给原始键列表，pointer 生成路径字符串，Marshal 编码整个补丁对象，库处理补丁应用。每一层都只编码一次。

几个容易误判的边界

键名原本就包含 ~1，要怎样表示？把它当原始文本交给 pointer，波浪线仍需要编码。因此原始键 ~1 对应 /~01。不能因为文字看起来像转义结果就跳过处理。反过来，已生成的 Pointer 也不能再次传入这个构造函数。

空字符串与只有一个斜杠一样吗？不一样。无参数调用 pointer 得到空路径，表示整个文档；给一个空字符串键则得到 /，表达空成员名。本例的参数列表设计能够保留两者差别。

键名编码好了，是否就能接受任意补丁？编码只解决定位问题。接口仍应限制可修改成员和操作类型，按业务需要限制补丁大小及操作数量。若设置允许修改的字段，最好根据解析后的成员层级进行授权判断，不要只对原始 path 做宽泛字符串前缀判断。

嵌套对象不存在怎么办？这是目标结构及操作语义的问题，不是斜杠转义问题。明确哪些父对象应该存在，并处理 Apply 返回的错误。是否允许创建缺失结构，应由接口契约决定。

参考：JSON Pointer 规范；JSON Patch 规范；Go json-patch 官方使用说明。