RedisJSON中JSON.SET的用法小結(jié)
更新時(shí)間：2025年11月12日 11:26:00 作者：Hello.Reader
本文全面解析 RedisJSON 插件的核心指令JSON.SET,涵蓋語法規(guī)則、典型用法、易錯(cuò)點(diǎn)和性能優(yōu)化建議,感興趣的可以了解一下
1 · 為什么要寫這篇文章？
在結(jié)構(gòu)化數(shù)據(jù)存儲(chǔ)場景里，傳統(tǒng)的字符串鍵值對(duì)已難以滿足靈活查詢與字段級(jí)更新的需求。RedisJSON 插件為 Redis 帶來了對(duì)原生 JSON 文檔的讀寫支持，其中最核心也最常用的指令就是 JSON.SET。本文將帶你徹底吃透 JSON.SET 的各個(gè)細(xì)節(jié)——從語法、時(shí)間復(fù)雜度到多路徑批量更新，再到在生產(chǎn)環(huán)境中容易踩到的坑和性能調(diào)優(yōu)方法，并提供一套 Go-Redis 的完整示例代碼，幫助你快速落地。
2 · RedisJSON 與 JSON.SET 概覽
| 特性 | 說明 | |
|---|---|---|
| 插件版本 | RedisJSON ≥ 1.0 （推薦 2.x 與 Redis 7.x+ 搭配使用） | |
| 指令 | `JSON.SET key path value [NX | XX]` |
| 功能 | 按 JSONPath 將 value 寫入 key 對(duì)應(yīng)的 JSON 文檔 | |
| ACL 標(biāo)記 | @json @write @slow | |
| 時(shí)間復(fù)雜度 | O(M + N) —— M 為原值大小，N 為新值大小 × 匹配路徑數(shù) |
3 · 語法詳解
JSON.SET <key> <path> <value> [NX | XX]
| 參數(shù) | 必填 | 說明 |
|---|---|---|
| key | ? | Redis 中的鍵；不存在時(shí)必須從根路徑寫入 |
| path | ? | JSONPath 表達(dá)式；$ 或 . 代表根 |
| value | ? | 合法 JSON 字符串，或原樣字符串（無需額外引號(hào)） |
| NX | 僅當(dāng)目標(biāo)不存在時(shí)寫入 | |
| XX | 僅當(dāng)目標(biāo)已存在時(shí)覆蓋 |
小貼士：NX 與 XX 不僅作用于 Redis 鍵，也作用于 JSON 文檔內(nèi)部鍵。這點(diǎn)經(jīng)常被忽略！
4 · JSONPath 規(guī)則速查
- 根路徑：$ 或 .
- 點(diǎn)式：$.address.city
- 數(shù)組下標(biāo)：$.items[0]
- 切片：$.items[1:3]（RedisJSON 2.x 支持）
- 通配：$..price 匹配所有層級(jí)的 price 字段
- 多路徑：$..a 與 $..b 可一次性傳入多條
注意：JSON.SET 不支持在一次調(diào)用中寫入 不同 的值到多條路徑；如果傳入多路徑，所有匹配點(diǎn)都會(huì)被同一個(gè) value 覆蓋。
5 · 返回值與錯(cuò)誤處理
| 情況 | 返回 |
|---|---|
| 寫入成功 | OK |
| 路徑不存在且無法創(chuàng)建 | (nil) |
| NX/XX 條件不滿足 | (nil) |
| 根鍵不存在但路徑不是 $ | (error) ERR new objects must be created at the root |
生產(chǎn)環(huán)境中推薦顯式檢查返回值，而不要只依賴 err == nil。示例見 § 9。
6 · 典型用法示例
6.1 替換已有字段
redis> JSON.SET doc $ '{"a":2}'
OK
redis> JSON.SET doc $.a 3
OK
redis> JSON.GET doc $
"[{\"a\":3}]"
6.2 追加新字段
redis> JSON.SET doc $ '{"a":2}'
OK
redis> JSON.SET doc $.b 8
OK
redis> JSON.GET doc $
"[{\"a\":2,\"b\":8}]"
6.3 一次性批量更新多路徑
redis> JSON.SET doc $ '{"f1":{"a":1},"f2":{"a":2}}'
OK
redis> JSON.SET doc $..a 3
OK
redis> JSON.GET doc
"{\"f1\":{\"a\":3},\"f2\":{\"a\":3}}"
6.4 結(jié)合 NX / XX 條件
# 僅當(dāng)字段不存在時(shí)寫入 redis> JSON.SET user:1 $.nickname '"neo"' NX OK # 第一次成功 redis> JSON.SET user:1 $.nickname '"smith"' NX (nil) # 條件未滿足
7 · 易踩坑匯總
| 坑 | 現(xiàn)象 | 解決方案 |
|---|---|---|
| 鍵不存在卻寫子路徑 | 拋錯(cuò) ERR new objects must be created at the root | 第一次寫必須用根路徑 $ |
| 值未用 JSON 字符串包裹 | 若忘記加引號(hào)：JSON.SET $.name neo ⇒ 解析失敗 | 非數(shù)值 / 布爾需雙引號(hào)或 'neo' |
| NX/XX 作用域誤解 | 誤以為只檢查 Redis 鍵 | 其實(shí)同時(shí)檢查 JSON 內(nèi)目標(biāo)字段 |
| 字符串過長 | 超出 512 MB 限制 | 拆分存儲(chǔ)或壓縮再存 |
8 · 性能調(diào)優(yōu)與并發(fā)安全
- Pipeline / MULTI
連續(xù)多次 JSON.SET 可使用 Pipelining 或事務(wù)批量發(fā)送，減少 RTT。 - 避免大文檔頻繁寫
時(shí)間復(fù)雜度包含原值大小 M：越大的 JSON，寫一次越慢?？蓪狳c(diǎn)字段拆分為獨(dú)立鍵或使用 JSON.NUMINCRBY 等增量指令。 - 合理選擇 NX/XX
在冪等場景下使用 NX 或 XX 可避免無謂的重寫，降低寫放大。 - 監(jiān)控慢日志
Redis 會(huì)將執(zhí)行時(shí)間 > slowlog-log-slower-than 的指令記錄；JSON 操作本質(zhì)屬 @slow 類別，應(yīng)重點(diǎn)關(guān)注。 - Lua/RedisGears 樂觀鎖
高并發(fā)寫同一字段，可結(jié)合 WATCH/MULTI 或 Lua 腳本實(shí)現(xiàn) CAS。
9 · Go-Redis 完整示例（可直接運(yùn)行）
依賴：Go ≥ 1.22、github.com/redis/go-redis/v9
// 文件 main.go
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"github.com/redis/go-redis/v9"
)
var ctx = context.Background()
type Profile struct {
Name string `json:"name"`
Age int `json:"age"`
Tags []string `json:"tags"`
}
func must(err error) {
if err != nil {
log.Fatalf("fatal: %v", err)
}
}
func main() {
rdb := redis.NewClient(&redis.Options{
Addr: "localhost:6379",
})
defer rdb.Close()
// ---------- 1. 寫入根文檔 ----------
profile := Profile{Name: "Alice", Age: 27, Tags: []string{"gopher", "redis"}}
raw, _ := json.Marshal(profile)
if res, err := rdb.Do(ctx, "JSON.SET", "user:1001", "$", raw).Text(); err != nil {
must(err)
} else {
fmt.Println("set root:", res) // OK
}
// ---------- 2. 更新子字段 ----------
if res, err := rdb.Do(ctx, "JSON.SET", "user:1001", "$.age", 28, "XX").Text(); err != nil {
must(err)
} else if res == "" {
fmt.Println("XX unmet, age not updated")
} else {
fmt.Println("update age:", res) // OK
}
// ---------- 3. 讀取文檔 ----------
data, err := rdb.Do(ctx, "JSON.GET", "user:1001", "$").Result()
must(err)
fmt.Println("profile =", data.(string))
// ---------- 4. 錯(cuò)誤示例 ----------
if _, err := rdb.Do(ctx, "JSON.SET", "user:1002", "$.name", "\"Bob\"").Result(); err != nil {
fmt.Println("expected error:", err)
}
// Output:
// set root: OK
// update age: OK
// profile = [{"name":"Alice","age":28,"tags":["gopher","redis"]}]
// expected error: ERR new objects must be created at the root
}
運(yùn)行后，你將看到成功寫入、條件更新、讀回以及錯(cuò)誤處理的完整流程。
10 · 進(jìn)階話題
| 方向 | 價(jià)值 |
|---|---|
| 與 RediSearch 集成 | 對(duì) JSON 字段建立二級(jí)索引，支持全文檢索與聚合分析 |
| 存儲(chǔ)版本化配置 | 使用 NX 寫入新版本，配合 JSON.NUMINCRBY 維護(hù)版本號(hào) |
| 灰度發(fā)布 | 通過數(shù)組/對(duì)象結(jié)構(gòu)保存多線路配置信息，再用 JSON.DEL 快速回滾 |
| Streaming JSON | 將大文檔拆分到 Stream 或 List，再按需合并到 RedisJSON |
11 · 總結(jié)
- JSON.SET 是 RedisJSON 最核心的寫入指令，先掌握根寫入，再逐步學(xué)習(xí)多路徑與條件寫。
- 時(shí)間復(fù)雜度與文檔大小 線性相關(guān)，因此避免頻繁重寫大 JSON。
- 正確使用 NX/XX 可實(shí)現(xiàn)冪等更新、樂觀鎖等高級(jí)場景。
- 在 Go-Redis 中通過 Do(ctx, "JSON.SET", …) 可無縫調(diào)用，務(wù)必檢查返回值而非只關(guān)注 err。
- 生產(chǎn)環(huán)境要結(jié)合 慢日志、Pipeline、事務(wù) 等手段進(jìn)行性能與可靠性保障。
到此這篇關(guān)于RedisJSON中JSON.SET的用法小結(jié)的文章就介紹到這了,更多相關(guān)RedisJSON JSON.SET內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
在高并發(fā)系統(tǒng)架構(gòu)中,Redis作為核心緩存組件扮演著至關(guān)重要的角色,它不僅能夠顯著提升系統(tǒng)響應(yīng)速度,還能有效減輕數(shù)據(jù)庫壓力,然而,當(dāng)Redis服務(wù)出現(xiàn)故障、性能下降或連接超時(shí)時(shí),如果沒有適當(dāng)?shù)慕导?jí)機(jī)制,可能導(dǎo)致系統(tǒng)雪崩,所以本文給大家介紹了Redis緩存降級(jí)的四種策略2025-04-04
今天小編就為大家分享一篇關(guān)于Redis的5種數(shù)據(jù)類型與常用命令講解，小編覺得內(nèi)容挺不錯(cuò)的，現(xiàn)在分享給大家，具有很好的參考價(jià)值，需要的朋友一起跟隨小編來看看吧2019-03-03
這篇文章主要介紹了redis分布式鎖與zk分布式鎖的對(duì)比分析，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2022-11-11
Redis 的 HyperLogLog 是一種概率性數(shù)據(jù)結(jié)構(gòu),用于統(tǒng)計(jì)唯一元素的數(shù)量（基數(shù)）,本文主要介紹了Redis中HyperLogLog的使用小結(jié),感興趣的可以了解一下2025-05-05
Redisson分布式限流的實(shí)現(xiàn)原理分析
這篇文章主要介紹了Redisson分布式限流的實(shí)現(xiàn)原理分析,具有很好的參考價(jià)值,希望對(duì)大家有所幫助,如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2024-07-07
使用Redis命令操作數(shù)據(jù)庫的常見錯(cuò)誤及解決方法
由于Redis是內(nèi)存數(shù)據(jù)庫,因此可能會(huì)存在一些安全問題,下面這篇文章主要給大家介紹了關(guān)于使用Redis命令操作數(shù)據(jù)庫的常見錯(cuò)誤及解決方法,文中通過代碼介紹的非常詳細(xì),需要的朋友可以參考下2024-02-02
本文主要介紹了redis專屬鏈表ziplist的使用，文中通過示例代碼介紹的非常詳細(xì)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2021-12-12
Redis報(bào)錯(cuò):無法連接Redis服務(wù)的解決方法
在Linux系統(tǒng)上運(yùn)行Redis服務(wù)時(shí),有時(shí)會(huì)遇到“無法連接Redis服務(wù)”的報(bào)錯(cuò),本文就詳細(xì)的介紹一下解決方法,具有一定的參考價(jià)值,感興趣的可以了解一下2023-09-09
Redis不是一直號(hào)稱單線程效率也很高嗎，為什么又采用多線程了？
這篇文章主要介紹了Redis不是一直號(hào)稱單線程效率也很高嗎，為什么又采用多線程了的相關(guān)資料,本文給大家介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值，需要的朋友可以參考下2021-03-03
SCAN 命令是一個(gè)基于游標(biāo)的迭代器，每次被調(diào)用之后， 都會(huì)向用戶返回一個(gè)新的游標(biāo)， 用戶在下次迭代時(shí)需要使用這個(gè)新游標(biāo)作為 SCAN 命令的游標(biāo)參數(shù)， 以此來延續(xù)之前的迭代過程，這篇文章給大家介紹了Redis?SCAN命令的相關(guān)知識(shí)，感興趣的朋友一起看看吧2022-07-07