后端 on 吾爱主机

Redis 分布式锁：互斥、安全释放与续期工程实践

Thu, 30 Jul 2026 00:00:00 +0800

下单扣库存、定时任务防重、接口幂等窗口、分片任务抢占——多进程/多实例同时触达同一共享资源时，都需要互斥。本地 synchronized 或 Mutex 只覆盖本机；跨进程时，工程上常见做法是把锁状态放到 Redis 这类高可用共享存储里。

本文依据 Redis 官方 Distributed Locks with Redis、SET 命令文档（含 Patterns）、Scripting with Lua 与 GETDEL 说明，把单实例正确加解锁、误删他人锁、主从异步复制下的安全边界、锁续期，以及 Redlock/fencing token 的工程取舍讲清楚，并给出可复现命令实验与排错清单。它和本站「缓存穿透/击穿/雪崩」互补：那篇讲缓存一致性与流量保护，本篇讲跨实例互斥原语本身。

一、问题背景：分布式互斥要什么

官方把有效的分布式锁最小保证概括为三条（Safety / Liveness）：

属性	含义	工程直觉
互斥（Safety）	任意时刻最多一个客户端持有锁	两台机器不能同时“以为自己锁住了”
无死锁（Liveness A）	持锁客户端崩溃或分区后，锁最终可被再次获取	必须有 TTL / 自动释放
容错（Liveness B）	多数 Redis 节点存活时仍可加解锁（面向 Redlock 场景）	单点故障与多数派策略

只满足“看起来能 SET 成功”不够。真正会在生产踩雷的，通常是：

加锁非原子：SETNX 成功后再 EXPIRE，进程在中间崩溃 → 永久锁死；
解锁不安全：业务超时后锁已过期被别人抢走，本客户端仍 DEL → 删掉别人的锁；
无 token 签名：所有客户端写同一个固定 value，无法判断“这把锁还是不是我的”；
把主从 failover 当强一致：异步复制下会出现双持锁窗口。

二、核心机制：单实例正确加解锁

2.1 原子加锁：`SET key token NX PX ttl`

官方单实例推荐写法（毫秒 TTL 示例）：

SET resource_name my_random_value NX PX 30000

对应语义（见 SET 文档）：

选项	作用
`NX`	仅当 key 不存在时才设置
`PX milliseconds`	以毫秒设置过期（也可用 `EX seconds`）
value = 随机 token	标识“这把锁属于哪个客户端/哪次加锁”

SET 成功返回 OK 表示抢到锁；key 已存在时（NX 条件不满足）返回空，表示未抢到。NX 与过期时间在同一条命令里完成，避免“加锁成功但没 TTL”的经典坑。

SET 文档的 Patterns 小节也写了同类形态：

SET resource-name anystring NX EX max-lock-time

并强调：简单 DEL 解锁可工作，但更稳健的做法是 token + 条件删除。

2.2 为什么 value 必须是随机 token

官方要求 value 在所有客户端、所有加锁请求间唯一。建议量级约 20 字节随机（如 /dev/urandom）；也可用“微秒时间戳 + 客户端 ID”等折中方案（安全性略弱，但多数场景够用）。

token 的唯一用途：解锁时证明“我仍是当前持有者”，避免过期后误删他人锁。

2.3 安全解锁：条件删除，而不是裸 `DEL`

错误写法：

DEL resource_name

时序灾难：

客户端 A 加锁，TTL = 30s；
A 业务卡住超过 30s，key 过期；
客户端 B 成功 SET NX 拿到同一资源；
A 恢复后执行 DEL → B 的锁被删掉，C 又能进入临界区。

官方正确路径有两层：

（1）Redis 8.4+：DELEX 条件删除（文档写法）

DELEX key IFEQ my_random_value

（2）更通用：Lua 脚本（8.4 之前也适用）

if redis.call("get", KEYS[1]) == ARGV[1] then
 return redis.call("del", KEYS[1])
else
 return 0
end

调用形态：

EVAL "<script>" 1 resource_name token-value

GET 比较与 DEL 在脚本内完成。官方 Scripting with Lua 明确：脚本在服务器侧原子执行，执行期间阻塞其他活动——这对“校验 token 再删除”至关重要，客户端侧的 GET + DEL 两步命令不是安全等价物。

注意：GETDEL 会“读出并删除”，但它不校验 token，不能单独当作安全解锁命令。

2.4 锁有效期（lock validity time）的双重含义

TTL 既是：

自动释放时间（持锁者崩溃后的死锁自愈）；
持锁者必须在此窗口内完成工作的时间预算。

互斥保证是时间窗口内的互斥，不是“进程活着就永远持锁”。业务若可能超过 TTL，要么加大合理 TTL，要么做续期，并在业务层准备好超时后的幂等/回滚。

三、主从复制为什么不够“天然安全”

单实例方案在“偶尔双持可接受”的业务里很实用；但若把 Redis 主从 + 自动 failover 当成强一致锁，会踩官方点名的竞态：

客户端 A 在 master 上拿到锁；
master 在把该写复制到 replica 前崩溃；
replica 升主；
客户端 B 在新 master 上再次 SET NX 成功 → Safety 被破坏。

原因：Redis 复制默认是异步的。官方态度很务实：若故障场景下短暂双持可接受，复制方案可用；否则应认真评估 Redlock 或更强的一致性组件，并在业务侧使用 fencing token。

四、Redlock 概要：多数派 + 耗时校验

Redlock 假设有 N 个独立 Redis master（示例 N=5，互不依赖复制协调）。客户端流程：

记录当前毫秒时间戳 T1；
用相同 key 与相同随机 value，在 N 个实例上并行 SET ... NX PX；对每个实例使用远小于锁 TTL 的连接/命令超时（例如 TTL=10s 时超时约 5–50ms），避免卡在不可用节点上；
计算耗时 elapsed = now - T1；仅当在多数实例（至少 N/2+1）加锁成功，且 elapsed < TTL 时，才认为获得锁；
有效剩余时间约为 TTL - elapsed（再扣一点时钟漂移余量）；
若失败：对所有实例尝试解锁（包括“以为没锁上”的），尽快释放部分锁。

失败重试应加随机退避，降低多客户端同时抢锁导致的“脑裂式空转”。释放时无论是否自认成功，都应尝试释放，降低依赖 TTL 的可用性惩罚。

4.1 续期（lock extension）

若工作可拆成小步骤，可用较短默认 TTL，并在接近过期时向多数实例发送 Lua：

仅当 key 存在且 value 仍是自己的 token 时，延长 TTL；
仅当多数实例续期成功且仍在有效时间内，才认为续期成功；
必须限制最大续期次数，否则可能破坏 liveness（锁永远被同一客户端拖住）。

这与许多客户端库里的 “watchdog / lock watchdog” 思路一致：续期是持锁期间的重新确认，不是“进程活着就一定安全”。

4.2 时钟与一致性免责声明（官方 disclaimer）

官方在文档末尾明确提醒：

若关心正确性，应实现 fencing tokens；不要假设“进程还活着 = 锁一定还在”；
Redis TTL 不依赖单调时钟，墙钟跳变理论上可能导致异常；应规范运维（避免手工乱改时间、正确配置 NTP），但仍不能把时钟理想化。

Martin Kleppmann 对 Redlock 的分析与 antirez 的回应均被官方列入阅读清单——工程选型时请当作必读辩论，而不是站队口号。

五、工程增强：Fencing Token 与临界区设计

即使锁服务偶发双持，业务仍可把破坏降到最低：

Fencing token：每次成功加锁从单调递增源（DB 序列、强一致元数据服务等）取一个 token；写共享资源时带上该 token；资源端拒绝小于已接受 token 的写。这样后拿到“旧锁”的客户端写不进去。
临界区尽量短：锁内只做“决策 + 提交意图”，重 IO 放到锁外并用幂等键保护。
业务幂等：以订单号、任务 ID、版本号做天然去重，锁失败/超时可安全重试。
可观测性：记录加锁耗时、失败原因、续期次数、解锁脚本返回 0 的次数（token 不匹配）。

六、可复现实验（单实例）

下面用 redis-cli 演示互斥、过期与误删防护。假设本地 6379 有 Redis。

6.1 互斥：第二个客户端抢不到

# 终端 A：抢锁
redis-cli SET lock:order:1001 "token-A-111" NX PX 15000
# 期望：OK

# 终端 B：同 key 再抢
redis-cli SET lock:order:1001 "token-B-222" NX PX 15000
# 期望：(nil) —— NX 失败

redis-cli GET lock:order:1001
# 期望：token-A-111
redis-cli PTTL lock:order:1001
# 期望：正数毫秒

6.2 安全解锁 vs 危险 `DEL`

# 正确：仅 token 匹配才删
redis-cli EVAL 'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end' 1 lock:order:1001 token-A-111
# 期望：1

# 再抢，模拟 B 持锁
redis-cli SET lock:order:1001 "token-B-222" NX PX 15000

# A 拿着过期旧 token 误删：应失败
redis-cli EVAL 'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end' 1 lock:order:1001 token-A-111
# 期望：0 —— 不会删掉 B 的锁

redis-cli GET lock:order:1001
# 期望：仍是 token-B-222

6.3 续期：仅持有者可延长

redis-cli SET lock:job:9 "token-C" NX PX 5000

# 错误 token 续期（应不改 TTL / 不改 value）
redis-cli EVAL 'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("pexpire", KEYS[1], ARGV[2]) else return 0 end' 1 lock:job:9 wrong-token 20000
# 期望：0

# 正确 token 续期
redis-cli EVAL 'if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("pexpire", KEYS[1], ARGV[2]) else return 0 end' 1 lock:job:9 token-C 20000
# 期望：1
redis-cli PTTL lock:job:9
# 期望：接近 20000ms

6.4 伪代码骨架（语言无关）

import secrets, time

def acquire(r, key, ttl_ms=30000, retry=3, backoff=0.05):
 token = secrets.token_hex(16)
 for _ in range(retry):
 if r.set(key, token, nx=True, px=ttl_ms):
 return token
 time.sleep(backoff)
 return None

UNLOCK_LUA = """
if redis.call("get", KEYS[1]) == ARGV[1] then
 return redis.call("del", KEYS[1])
else
 return 0
end
"""

def release(r, key, token):
 return r.eval(UNLOCK_LUA, 1, key, token)

def with_lock(r, key, fn, ttl_ms=30000):
 token = acquire(r, key, ttl_ms=ttl_ms)
 if not token:
 raise RuntimeError("lock not acquired")
 try:
 return fn(token) # 可把 token 当作 fencing 的一部分上送
 finally:
 release(r, key, token)

生产中请再补：续期协程/线程、最大持锁时间、指标与超时取消。

七、常见坑与排查清单

现象	可能原因	排查/修复
锁永远解不开	只 `SETNX` 未设过期；或 TTL 极大	统一 `SET NX PX`；审计历史 key
偶发并发进入临界区	解锁用了裸 `DEL`；或业务超时后无 fencing	Lua/`DELEX IFEQ`；加 fencing token
故障切换后双写	依赖异步主从当强一致锁	评估是否可接受；否则 Redlock/外部强一致 + fencing
加锁抖动高	固定重试无退避；热点锁竞争	随机退避 + 缩短临界区 + 锁粒度拆分
续期把锁续成“永不释放”	无限 watchdog	上限次数/墙钟最大持锁时间
集群下 Lua 访问了未声明的 key	违反脚本 key 规则	所有 key 经 `KEYS` 传入；遵循 Cluster 槽约束
以为 `GETDEL` 能安全解锁	`GETDEL` 不校验 owner	必须条件删除

八、选型建议（务实版）

单机房、可接受极低概率异常双持、业务幂等完善：单 Redis + SET NX PX + token Lua 解锁通常足够，实现简单、延迟低。
对互斥更敏感、可运维多实例独立 Redis：评估 Redlock 及成熟库（官方文档列出 Redisson、Redsync、node-redlock 等），并读完 Kleppmann/antirez 讨论。
金融级强一致临界区：不要只靠 Redis TTL 语义；优先考虑带 fencing 的共识/事务系统，Redis 锁最多做“快速失败的互斥提示”。
任何方案：临界区短、幂等、可观测、可回滚，比纠结算法名词更重要。

九、总结

分布式锁的底线是 互斥 + 可自动释放 + 安全解锁。
单实例正确骨架：SET key token NX PX ttl + token 条件删除（Lua 或 Redis 8.4 DELEX IFEQ）。
裸 DEL、拆分的 SETNX+EXPIRE、固定 value，是三大经典错误。
异步主从 failover 不能保证互斥；是否可接受取决于业务与是否有 fencing。
Redlock 用多数派与耗时校验提升容错，但涉及时钟漂移、持久化/延迟重启与社区争议——官方自己要求你读分析文章。
工程上把锁当作辅助互斥，用 fencing token、幂等与短临界区兜底正确性。

参考资料

Redis 官方文档：Distributed Locks with Redis（含单实例实现、Redlock、续期、disclaimer）
https://redis.io/docs/latest/develop/clients/patterns/distributed-locks/
Redis 命令：SET（NX / PX / EX 与 Patterns 中的加解锁说明）
https://redis.io/docs/latest/commands/set/
Redis 官方文档：Scripting with Lua（脚本原子执行、EVAL/KEYS/ARGV）
https://redis.io/docs/latest/develop/programmability/eval-intro/
Redis 命令：GETDEL（读删一体，但不替代 token 校验解锁）
https://redis.io/docs/latest/commands/getdel/
Redis 文档源码（可检索原文）：distributed-locks markdown
https://raw.githubusercontent.com/redis/docs/main/content/develop/clients/patterns/distributed-locks.md
Martin Kleppmann：How to do distributed locking（Redlock 分析，官方文末引用）
https://martin.kleppmann.com/2016/02/08/how-to-do-distributed-locking.html
antirez：Is Redlock safe?（对上述分析的回应，官方文末引用）
http://antirez.com/news/101

Go channel 与 select：阻塞语义、关闭规则与工程实践

Wed, 29 Jul 2026 00:00:00 +0800

goroutine 之间如何安全地交换数据、如何表达“没有更多结果了”、如何在多个就绪通道里做非确定性选择——这些都落在 channel 与 select 上。Go 语言规范把 channel 定义为并发函数之间按指定元素类型发送/接收的通信机制；官方博客的口号则是：

Do not communicate by sharing memory; instead, share memory by communicating.

本文依据 Go 语言规范（Channel types / Send / Receive / close / Select statements）、Effective Go 的 Channels 章节、官方博客 Share Memory By Communicating 与 Go Concurrency Patterns: Pipelines and cancellation，把无缓冲/有缓冲阻塞规则、关闭语义、select 调度、管道关闭与取消讲清楚，并给出可复现实验与排错清单。它和「context 取消传播」互补：context 解决“该停了”，channel/select 解决“值怎么传、何时结束、多路怎么选”。

一、问题背景：共享内存锁 vs 通道通信

传统多线程模型里，线程通过共享数据结构 + 锁协作：谁拿到锁谁改状态。Go 的 CSP 风格把协作点显式化——发送/接收本身就是同步点。

常见踩坑往往不是“不会写 ch <- v”，而是对阻塞条件判断错误：

无缓冲通道上“先发后收”在单 goroutine 里会永久阻塞；
向已关闭通道发送触发 runtime panic；
对 nil 通道发送/接收会永远阻塞，select 里一不小心就“整段卡死”；
只 close 不约定所有权，多发送者并发 close 直接 panic；
管道中游生产者退出却不 close，下游 range 永不结束。

把规范里的规则记成表，比背 API 更有用。

二、核心模型：无缓冲握手与有缓冲队列

1. 创建与零值

var ch chan int // nil channel，零值
ch = make(chan int) // 无缓冲（容量 0）
ch2 := make(chan int, 0) // 同样无缓冲
buf := make(chan int, 8) // 缓冲容量 8

规范要点：

概念	规范语义	工程含义
元素类型	`chan T` / 方向 `chan<- T`、`<-chan T`	编译期限制发送/接收方向
make 容量	可选 capacity；0 或省略 → unbuffered	无缓冲 = 同步通信
缓冲通道	缓冲未满可发送、非空可接收且不阻塞	解耦生产/消费速率
零值 nil	未初始化的 channel 为 nil	对 nil 收发会永久阻塞
FIFO	通道是先进先出队列	多 goroutine 共用同一通道无需额外同步结构（仍要注意关闭约定）

无缓冲通道：只有发送方与接收方都就绪时通信才成功——值直接从发送方拷到接收方，同时完成同步。有缓冲通道：发送在缓冲有空位时即可完成；接收在缓冲有数据时即可完成。

Effective Go 的表述更偏工程直觉：

接收方总是阻塞到有数据可收；
无缓冲时，发送方阻塞到接收方取走值；
有缓冲时，发送方阻塞到值被拷入缓冲；缓冲满则等到有接收方腾出空位。

2. 发送 / 接收何时可推进

规范对 send 的可推进条件可以压缩成：

操作	可立即推进的条件	否则
无缓冲发送	已有接收方就绪	阻塞
有缓冲发送	缓冲未满	阻塞
向 closed 发送	—	runtime panic
向 nil 发送	—	永久阻塞
接收（开通道）	有数据或有发送方（无缓冲握手）	阻塞
从 closed 接收	总是可立即推进	先排空缓冲，再得到零值
从 nil 接收	—	永久阻塞

// 无缓冲：必须另一端参与
ch := make(chan string)
go func() { ch <- "ready" }()
msg := <-ch

// 有缓冲：容量内发送不阻塞
b := make(chan int, 2)
b <- 1
b <- 2
// b <- 3 // 若无接收方，此处阻塞

3. 关闭、ok 与 range

内建 close(ch) 表示“不会再有新值”。规范与管道博客共同强调的接收语义：

关闭后，先前已发送、仍在缓冲中的值会被正常接收完；
排空后，接收立即返回元素类型零值且不阻塞；
双返回值形式 v, ok := <-ch：ok == false 表示通道已关闭且没有更多值；
close(nil)、close 已关闭通道 → runtime panic；
向已关闭通道发送 → panic（这是最常见的线上事故之一）。

out := make(chan int, 3)
out <- 1
out <- 2
close(out)

for v := range out { // 自动在关闭且排空后结束
 fmt.Println(v)
}
v, ok := <-out
fmt.Println(v, ok) // 0 false

关闭约定（工程硬规则）：

发送侧关闭：通常由唯一“拥有发送权”的一方 close；多个发送者需要额外同步（例如用 sync.Once 或先汇合再 close）。
接收侧不要 close（除非协议明确且全局只有你发送——极少见）。
需要“广播停工”时，更常见的是 close 一个只读 done 信号通道（见下文管道取消），而不是让每个工作通道被多方乱关。

三、select：多路就绪与非确定性选择

select 像 switch，但 case 全部是通信操作。规范给出的执行步骤值得逐条对照代码：

进入 select 时，按源码顺序对所有 case 的通道操作数（以及发送右侧表达式）各求值恰好一次——副作用一定会发生，与最终选中哪个 case 无关；
若一个或多个通信可推进，用均匀伪随机选中其中一个；
若都不能推进且存在 default，走 default；
若都不能推进且无 default，阻塞直到至少一个可推进；
仅有 nil 通道 且无 default 的 select 永久阻塞。

select {
case v := <-a:
 handleA(v)
case b <- x:
 // 发送成功
case <-time.After(200 * time.Millisecond):
 // 超时分支（timer channel）
default:
 // 非阻塞探测：此刻无人可通信
}

工程模式

1）非阻塞试探（try-send / try-recv）

select {
case ch <- job:
default:
 // 队列满或无接收方：降级、丢弃或写指标
}

Effective Go 用 free-list + select/default 演示：缓冲通道兼作资源池，满则新建。

2）有缓冲通道当信号量

sem := make(chan struct{}, MaxOutstanding)

func handle(r *Request) {
 sem <- struct{}{} // 占坑；满则阻塞
 defer func() { <-sem }() // 释放
 process(r)
}

容量限制同时在飞的 process 数。注意：若外层对每个请求都 go handle 而不做接纳控制，仍可能制造海量 goroutine——需要在入口再限流。

3）与 context 组合：可取消等待

select {
case res := <-resultCh:
 return res, nil
case <-ctx.Done():
 return nil, ctx.Err()
}

channel 负责传结果，context 负责传“该停了”。二者不要互相替代。

四、可复现实验：阻塞、关闭与 select

下面用标准库即可在本机验证规范语义（Go 1.20+ 均可）。

package main

import (
 "fmt"
 "time"
)

func mustPanic(name string, fn func()) {
 defer func() {
 if r := recover(); r != nil {
 fmt.Println(name, "panic OK:", r)
 } else {
 fmt.Println(name, "ERROR: expected panic")
 }
 }()
 fn()
}

func main() {
 // 1) 无缓冲：单 goroutine 发送会死锁（用超时模拟探测）
 ub := make(chan int)
 go func() {
 select {
 case ub <- 1:
 fmt.Println("unexpected send success")
 case <-time.After(50 * time.Millisecond):
 fmt.Println("unbuffered send blocked as expected")
 }
 }()
 time.Sleep(80 * time.Millisecond)

 // 2) 有缓冲：容量内不阻塞
 b := make(chan int, 1)
 b <- 42
 fmt.Println("buffered len/cap:", len(b), cap(b))

 // 3) 关闭后接收
 close(b)
 v, ok := <-b
 fmt.Println("drain closed:", v, ok) // 42 true
 v, ok = <-b
 fmt.Println("after empty:", v, ok) // 0 false

 // 4) 向关闭通道发送 → panic
 mustPanic("send-on-closed", func() { b <- 1 })

 // 5) close(nil) → panic
 var n chan int
 mustPanic("close-nil", func() { close(n) })

 // 6) select 伪随机：两个都就绪时多次运行会看到不同分支
 a1, a2 := make(chan int, 1), make(chan int, 1)
 a1 <- 1
 a2 <- 2
 counts := map[string]int{}
 for i := 0; i < 200; i++ {
 // 重新填满，保证两 case 均可推进
 select {
 case <-a1:
 counts["a1"]++
 a1 <- 1
 case <-a2:
 counts["a2"]++
 a2 <- 2
 }
 }
 fmt.Println("select distribution:", counts)

 // 7) 仅 nil + 无 default：用超时包裹，避免真死锁进程
 var nilCh chan int
 select {
 case <-nilCh:
 fmt.Println("unreachable")
 case <-time.After(50 * time.Millisecond):
 fmt.Println("nil-only select would block forever without timeout")
 }
}

预期观察：

无缓冲在无人接收时发送走超时分支；
关闭通道先拿到缓冲残留，再 ok=false；
向关闭通道发送、close(nil) 触发 panic；
双就绪 select 的计数大致接近（伪随机，不保证 50/50 精确）。

五、管道：关闭传播与 done 取消

官方 Pipelines 博客的模型：

A pipeline is a series of stages connected by channels, where each stage is a group of goroutines running the same function.

每阶段从上游 channel 读、处理后写入下游 channel。结束信号有两种常见方式：

关闭数据通道：表示“没有更多输入”。因对已关闭通道的接收总可立即完成，下游 range 能自然退出；发送方在发完后 close(out)。
显式取消（done channel）：当下游提前退出、不再消费时，上游若继续发送会阻塞。博客做法是额外传入 done <-chan struct{}，由下游（或 main）close(done) 做广播，上游在 select 里同时监听 done 与数据发送，从而放弃未完成发送。

func gen(done <-chan struct{}, nums ...int) <-chan int {
 out := make(chan int)
 go func() {
 defer close(out)
 for _, n := range nums {
 select {
 case out <- n:
 case <-done:
 return
 }
 }
 }()
 return out
}

// main 中：
done := make(chan struct{})
defer close(done) // 退出时广播取消
for n := range sq(done, gen(done, 2, 3)) {
 fmt.Println(n)
 break // 提前结束也安全：done 关闭后上游不再堵在发送上
}

这与 context 的取消树是同一思想的两种载体：done 通道是轻量广播；复杂调用链更推荐 context.Context。

六、常见坑与排查清单

症状	可能根因	排查 / 修复
`fatal error: all goroutines are asleep - deadlock!`	无缓冲自收自发；所有 goroutine 互相等待	用 `go` 起对端；检查是否缺接收/发送
`panic: send on closed channel`	接收方误 close，或多发送者重复 close	单一发送所有者 close；多生产者用 WaitGroup 汇合后再 close
`panic: close of closed channel` / `close of nil channel`	重复 close 或 close 零值	`sync.Once`；初始化后再 close
goroutine 数量持续上涨	发送阻塞无人收；`go handle` 无限接纳	有缓冲限流 + context 取消；pprof `goroutine`
`range` 永不结束	上游未 close	契约：最后一个发送者负责 close
select “总是”走同一分支	另一 case 实际不可推进（nil/满/空）	打印 `len/cap`、是否 nil、是否已 close
定时器泄漏	`time.After` 在热路径大量创建	复用 `time.NewTimer` 并 `Stop`
数据竞争仍在	channel 传的是指针/切片头，共享底层数组	发送所有权转移；或拷贝；或明确只读契约

补充 runtime 视角（runtime/chan.go 注释）：缓冲通道上，缓冲非空时接收队列为空、缓冲未满时发送队列为空——实现上把“数据在缓冲”与“对端在等待队列”分成清晰不变量。排障时你不需要背这些字段，但要理解：阻塞 = 进入 sendq/recvq 等待被对端或 close 唤醒。

七、总结

无缓冲 channel = 通信 + 同步；有缓冲 = 带容量的 FIFO，用于削峰与信号量。
关闭是“不再发送”的信号，不是“销毁”；排空后接收零值；禁止向已关闭通道发送。
nil 通道收发永久阻塞；select 求值有副作用，多就绪 case 伪随机，无就绪且无 default 则阻塞。
管道靠 close 数据通道 表达结束，靠 done/context 表达提前取消，避免上游堵死。
与上一篇 Go context 取消传播 搭配：context 管生命周期，channel/select 管数据面与多路选择。

把“谁发送、谁关闭、谁取消、缓冲多大”四件事写进代码评审清单，比事后查 deadlock 日志便宜得多。

参考资料

AgentScope Java 2.0 实战：构建带权限审批与可恢复执行的生产级 Agent

Thu, 23 Jul 2026 00:00:00 +0800

能调用 Shell、修改文件和派发子任务的 Agent，比普通聊天机器人更有价值，也更危险。Prompt 中一句“执行危险操作前请确认”不是安全边界：模型可能误判上下文、被工具输出诱导，或者在重试中重复执行副作用。

AgentScope Java 2.0 把这类生产问题放进框架核心：每次工具调用都经过权限系统，结果是 ALLOW、DENY 或 ASK；ASK 会暂停 Agent，等待用户确认后再恢复。同时，Harness、Workspace、Sandbox 和分布式状态后端用来承载长时间任务。

本文基于 AgentScope Java 2.0.0 GA 和 JDK 17，先搭建一个 HarnessAgent，再实现“读操作自动放行、写操作必须审批、生产资源不可绕过”的权限策略，最后说明 session 恢复与沙箱的边界。

一、ReActAgent 与 HarnessAgent 的分工

AgentScope Java 2.0 提供两层抽象：

抽象	适合场景	核心关注点
`ReActAgent`	轻量聊天、受限 Tool Calling	推理—行动循环、模型、工具
`HarnessAgent`	长任务、文件/代码 Agent、企业部署	Workspace、Memory、Skills、Subagent、Sandbox、恢复

如果只需调用一个天气 API，ReActAgent 已经足够。若 Agent 要在目录里读写文件、执行命令、跨会话继续任务，应该从 Harness 开始，因为这些能力需要共享一致的运行上下文。

官方 2.0 的设计还强调 Agent 本身无状态：运行状态通过 (userId, sessionId) 和后端管理。这比把可变消息列表放进单例 Agent 更适合多实例部署。

二、依赖和模型配置

AgentScope Java 2.0 要求 JDK 17+。Harness 与模型提供商从 2.0 起拆分为独立模块：

<properties>
 <maven.compiler.release>17</maven.compiler.release>
 <agentscope.version>2.0.0</agentscope.version>
</properties>

<dependencies>
 <dependency>
 <groupId>io.agentscope</groupId>
 <artifactId>agentscope-harness</artifactId>
 <version>${agentscope.version}</version>
 </dependency>

 <dependency>
 <groupId>io.agentscope</groupId>
 <artifactId>agentscope-extensions-model-dashscope</artifactId>
 <version>${agentscope.version}</version>
 </dependency>
</dependencies>

其他官方可选模型模块包括 OpenAI、Anthropic、Gemini 和 Ollama。使用 DashScope 时，把密钥放进环境变量而不是源码：

export DASHSCOPE_API_KEY="你的密钥"

然后创建最小 HarnessAgent：

import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.UserMessage;
import io.agentscope.harness.agent.HarnessAgent;
import java.nio.file.Paths;

public class OpsAgentApp {
 public static void main(String[] args) {
 HarnessAgent agent = HarnessAgent.builder()
 .name("ops_assistant")
 .sysPrompt("""
 你是运维分析助手。先读后写，输出每一步依据；
 未获得权限系统批准时，不得声称已经修改任何资源。
 """)
 .model("dashscope:qwen-plus")
 .workspace(Paths.get(".agentscope/workspace"))
 .build();

 RuntimeContext ctx = RuntimeContext.builder()
 .userId("alice")
 .sessionId("incident-20260724-001")
 .build();

 var result = agent.call(
 new UserMessage("检查工作区里的故障日志并给出处理建议"), ctx)
 .block();
 if (result != null) {
 System.out.println(result.getTextContent());
 }
 }
}

模型字符串由 ModelRegistry 解析。workspace 不是随便给 Agent 一个宿主机根目录，而应该是专门分配、权限收敛的工作目录。

三、权限系统如何做决策

权限系统位于 io.agentscope.core.permission，拦截每次工具调用。它综合三类信息：

Rules：针对工具和调用模式的显式 ALLOW、ASK、DENY；
Mode：未命中规则时的默认策略；
Built-in Checks：工具根据真实入参执行的不可绕过检查。

决策顺序中，DENY 规则和危险路径检查优先。即使启用 BYPASS，这类保护仍然生效。

官方提供五种常用模式：

模式	未命中规则时的行为	适用情况
`DEFAULT`	要求显式规则或用户确认	推荐默认值
`ACCEPT_EDITS`	放行工作目录内安全文件操作	用户在场的开发任务
`EXPLORE`	只读，拒绝写与命令	代码探索、规划
`BYPASS`	通常放行，但不可绕过的检查仍有效	完全可信且隔离的 Sandbox
`DONT_ASK`	将 ASK 变为 DENY	无人值守任务

DONT_ASK 尤其重要：定时任务没有用户在线，不能让 Agent 永久等待审批，也不应默认放行。

四、配置 ALLOW、ASK 与 DENY 规则

下面的策略允许安全读取，删除操作必须询问，删表始终拒绝：

import io.agentscope.core.permission.PermissionBehavior;
import io.agentscope.core.permission.PermissionContextState;
import io.agentscope.core.permission.PermissionMode;
import io.agentscope.core.permission.PermissionRule;

PermissionContextState permissions = PermissionContextState.builder()
 .mode(PermissionMode.DEFAULT)
 .addAllowRule(
 "safe_read",
 new PermissionRule(
 "safe_read", null,
 PermissionBehavior.ALLOW, "projectSettings"))
 .addAskRule(
 "dangerous_delete",
 new PermissionRule(
 "dangerous_delete", null,
 PermissionBehavior.ASK, "projectSettings"))
 .addDenyRule(
 "drop_table",
 new PermissionRule(
 "drop_table", null,
 PermissionBehavior.DENY, "projectSettings"))
 .build();

可以把权限上下文交给底层 ReActAgent：

ReActAgent agent = ReActAgent.builder()
 .name("controlled_agent")
 .sysPrompt("先检查，再操作")
 .model(model)
 .permissionContext(permissions)
 .build();

若使用 Harness，应在构建 Harness 的 delegate/permission 配置位置应用同一上下文；具体 Builder 入口以 2.0.0 文档和当前模块为准，不要从 RC 版博客复制包名。

规则来源 projectSettings、userSettings、session 或 suggested 应进入审计日志。由用户在一次 ASK 中接受的 suggested rule，可能影响后续相同调用，UI 必须明确告诉用户这是“一次允许”还是“以后允许”。

五、自定义不可绕过的工具检查

静态规则不一定能识别业务语义。比如同一个 restart_service 工具，测试环境可以自动执行，生产环境必须审批。自定义 Tool 可覆盖 checkPermissions：

import io.agentscope.core.permission.PermissionDecision;
import io.agentscope.core.tool.ToolBase;
import io.agentscope.core.tool.ToolExecutionContext;
import java.util.Map;
import reactor.core.publisher.Mono;

public final class RestartServiceTool extends ToolBase {

 public RestartServiceTool() {
 super(ToolBase.builder()
 .name("restart_service")
 .description("重启指定环境中的服务")
 .readOnly(false));
 }

 @Override
 public Mono<PermissionDecision> checkPermissions(
 Map<String, Object> input,
 ToolExecutionContext context) {

 String environment = String.valueOf(input.get("environment"));
 if (environment.startsWith("prod")) {
 return Mono.just(PermissionDecision.ask(
 "目标是生产环境，需要人工批准：" + environment));
 }

 return Mono.just(PermissionDecision.passthrough(
 "非生产环境，继续按 rules/mode 判断"));
 }
}

PASSTHROUGH 不是 ALLOW，它表示把决定权交回规则和模式。对明确禁止的目标可直接返回 deny(...)。

框架还内置危险路径保护，例如 .ssh/、.git/、.aws/、.kube/、.env 和凭据文件。命中危险路径时会强制 ASK；自定义 Tool 也可以增加危险文件和目录。

六、ASK 后怎样暂停与恢复

权限结果为 ASK 时，Agent 不执行工具，而是以 GenerateReason.PERMISSION_ASKING 暂停。返回消息中包含状态为 ASKING 的 ToolUseBlock，调用方应：

把工具名和脱敏后的参数展示给用户；
让用户选择拒绝、仅本次允许或接受建议规则；
构造 ConfirmResult；
使用相同 (userId, sessionId) 恢复 Agent。

核心确认对象如下：

ConfirmResult confirm = new ConfirmResult(
 true, // confirmed
 toolCall, // 本次待确认调用
 toolCall.getSuggestedRules() // 仅在用户明确接受时传入
);

生产 UI 不应只放一个模糊的“确认”按钮。至少显示：

工具名称与风险级别；
目标环境、资源 ID、路径；
是否产生副作用；
建议规则会影响一次还是后续调用；
session、用户和过期时间。

确认结果必须由服务端绑定当前用户和待审批记录，不能接受客户端随意提交另一个 toolCall。

七、流式事件让执行过程可观察

Harness 可以输出统一事件流：

agent.streamEvents(
 new UserMessage("分析日志；如果需要修改配置先请求批准"), ctx)
 .doOnNext(event -> {
 switch (event.getType()) {
 case TEXT_BLOCK_DELTA ->
 System.out.print(((TextBlockDeltaEvent) event).getDelta());
 case TOOL_CALL_START ->
 System.out.println("[tool] "
 + ((ToolCallStartEvent) event).getToolCallName());
 default -> { }
 }
 })
 .blockLast();

事件流可驱动 Web UI、飞书/钉钉 Channel 或审计平台。注意不要把所有原始参数直接写日志；命令、Prompt 和工具结果可能包含 Token、路径或客户数据。

八、Workspace、Sandbox 和权限各管一层

三者不能互相替代：

Workspace 组织文件、Memory、Skills 和子 Agent 工作上下文；
Permission 决定某次工具调用是否允许、拒绝或询问；
Sandbox 限制已经获准的代码实际能访问哪些系统资源。

即使权限系统批准 rm temp.txt，Sandbox 仍应阻止进程读取宿主机 SSH 密钥。反过来，Docker 隔离也不能代替业务审批：容器里的工具可能仍持有生产 API 凭据。

可按风险逐级部署：

开发：专用本地目录 + DEFAULT
测试：Docker Sandbox + ACCEPT_EDITS
生产交互：Kubernetes Sandbox + DEFAULT + HITL
生产无人值守：最小工具集 + DONT_ASK + 服务端白名单

每个 Sandbox 还应配置 CPU、内存、进程数、超时、只读根文件系统和网络出口策略。

九、可恢复执行的正确边界

AgentScope Java 2.0 支持 Redis、MySQL、PostgreSQL、OSS/COS 等分布式 session 和 memory 后端，并面向跨副本 session 恢复。但“恢复 Agent 状态”仍不等于“业务操作恰好一次”。

经典故障窗口：

工具成功重启服务
 -> 进程在保存工具结果前崩溃
 -> 恢复后模型再次请求重启

解决方案在工具层：

record OperationRequest(String operationId, String service, String environment) {}

operationId 由可信服务端生成；
业务库对它建立唯一约束；
重复请求返回第一次结果，而不是再次执行；
checkpoint 记录 operationId 与状态；
外部系统也尽可能使用幂等键。

userId + sessionId 用于隔离会话，operationId 用于隔离副作用，二者不要混为一谈。

十、生产部署清单

默认使用 DEFAULT 或 EXPLORE，不把 BYPASS 当省事开关；
无人值守任务使用 DONT_ASK，未明确允许的调用直接拒绝；
生产、凭据和危险路径在 Tool 内做不可绕过检查；
ASK 绑定用户、session、调用参数摘要和过期时间；
Suggested Rule 的持久化范围对用户透明；
Sandbox 有资源限制、网络出口策略和短期凭据；
所有写工具都有幂等键与审计记录；
使用共享状态后端，并测试滚动发布和跨副本恢复；
对每种工具做 ALLOW、ASK、DENY 和恢复故障测试；
日志和事件流经过脱敏。

十一、常见问题

Agent 一直要求确认

检查规则的 toolName 和 ruleContent 是否真的匹配调用；若默认 DEFAULT 且没有 ALLOW 规则，询问是预期行为。不要直接切到 BYPASS，先补齐最小权限规则。

定时任务卡在 ASK

无人值守场景改用 DONT_ASK，并显式允许安全工具。ASK 会转成 DENY，从而让任务失败得可观察，而不是永久等待不存在的用户。

工作区恢复后找不到文件

本地 Workspace 不适合多副本。使用共享存储或远程文件系统，并保证所有副本使用一致的路径映射、租户隔离和版本策略。

已有 Sandbox，为什么还要权限系统

Sandbox 限制“能破坏多大范围”，权限系统限制“此刻是否应该执行”。前者是隔离，后者是意图授权，必须叠加。

总结

AgentScope Java 2.0 的核心价值不是又实现了一次 ReAct，而是把 Agent 当成一个需要治理的长期运行系统：

权限系统在每次工具调用前作出 ALLOW、ASK 或 DENY；
Tool 的 Built-in Check 能根据真实参数建立不可绕过的业务安全线；
HITL 用同一 session 暂停和恢复，而不是只在 Prompt 里“请求确认”；
Workspace 管上下文，Sandbox 管隔离，分布式后端管恢复；
幂等和业务事实仍由工具与数据库负责。

如果你的 Agent 会改文件、执行命令或触碰生产资源，先设计权限、审批、隔离和恢复，再讨论模型是否更聪明。生产 Agent 最重要的能力，不是永远做对，而是做错时被阻止、失败后可恢复、重试时不重复造成损失。

参考资料

Google ADK Java 实战：用 Code-first 方式编排多 Agent 工作流

Thu, 23 Jul 2026 00:00:00 +0800

Google Agent Development Kit（ADK）Java 是一个代码优先的 Agent 工具包：Agent 的角色、工具和编排直接写在 Java 中，可以进入版本控制、单元测试和部署流程。它不是只能调用 Gemini 的聊天 SDK，而是提供 LlmAgent、Sequential/Parallel/Loop Agent、Session/State、Dev UI 和 A2A 集成。

本文基于 Google ADK Java 1.7.0，实现一个“研究—审查—成稿”的顺序多 Agent 工作流，并说明工具、Session State、Dev UI 以及 A2A 与 MCP 的分工。

截至 2026-07-23，官方 README 仍将 ADK Java 标记为 Preview / Pre-GA，并说明相关能力按 “as is” 提供、支持可能有限。它适合学习、PoC 和可控试点；关键生产系统上线前必须锁版本、做回归测试并准备替代路径。

一、ADK 的 Code-first 是什么

代码优先不只是“不写 YAML”，而是把 Agent 系统的重要结构放进类型化代码：

BaseAgent
├── LlmAgent 模型驱动，能调用工具或委派
├── SequentialAgent 按顺序执行子 Agent
├── ParallelAgent 并行执行独立子 Agent
└── LoopAgent 在条件下重复执行

LLM 适合处理语义判断和非结构化内容；Sequential/Parallel/Loop 则提供确定性控制。一个可靠系统往往混用二者，而不是让一个大模型临场规划全部步骤。

本文流程是：

用户主题
 -> researcher：形成事实清单，写入 research_notes
 -> reviewer：检查证据与风险，写入 review_notes
 -> writer：读取前两步结果，形成文章提纲

三个专业 Agent 可以使用不同 Prompt，输出通过 Session State 传递。

二、依赖、凭据与版本状态

Maven 依赖：

<properties>
 <maven.compiler.release>17</maven.compiler.release>
 <adk.version>1.7.0</adk.version>
</properties>

<dependencies>
 <dependency>
 <groupId>com.google.adk</groupId>
 <artifactId>google-adk</artifactId>
 <version>${adk.version}</version>
 </dependency>

 <dependency>
 <groupId>com.google.adk</groupId>
 <artifactId>google-adk-dev</artifactId>
 <version>${adk.version}</version>
 </dependency>
</dependencies>

google-adk-dev 用于本地开发 UI，不建议不加区分地打进生产镜像。

使用 Google AI Studio / Gemini API 时，凭据名称和认证方式应以当前 ADK 官方文档为准，常见本地配置是：

export GOOGLE_API_KEY="你的密钥"

如果使用 Vertex AI，还需要 Google Cloud Project、区域和 ADC 等配置。不要把服务账号 JSON 放进源码或容器镜像。

三、先实现一个可验证的 FunctionTool

ADK 可以把静态 Java 方法包装成工具。下面的工具只返回受控的本地资料，便于无外部搜索依赖地验证调用链：

import com.google.adk.tools.Annotations.Schema;
import java.util.Map;

public final class ResearchTools {

 public static Map<String, String> lookupFrameworkFact(
 @Schema(
 name = "framework",
 description = "框架名称，例如 Spring AI Alibaba 或 AgentScope Java")
 String framework) {

 return switch (framework.toLowerCase()) {
 case "spring ai alibaba" -> Map.of(
 "status", "success",
 "fact", "面向 Java 的 Agent、Workflow 与 Multi-Agent 框架");
 case "agentscope java" -> Map.of(
 "status", "success",
 "fact", "面向分布式、生产级、长时间运行 Agent 的 Java 框架");
 default -> Map.of(
 "status", "not_found",
 "fact", "本地资料中没有该框架");
 };
 }
}

包装为 FunctionTool：

import com.google.adk.tools.FunctionTool;

var factTool = FunctionTool.create(
 ResearchTools.class,
 "lookupFrameworkFact");

工具参数用 @Schema 写清名称和描述，返回值使用结构化 Map 或 POJO。模型可以决定是否调用，但 Java 方法必须独立完成参数校验、鉴权、超时和幂等。

四、定义三个专业 LlmAgent

1. Researcher

import com.google.adk.agents.LlmAgent;

LlmAgent researcher = LlmAgent.builder()
 .name("researcher")
 .description("查找并整理主题相关事实")
 .model("gemini-2.0-flash")
 .instruction("""
 根据用户主题整理事实清单。
 可调用 lookupFrameworkFact；找不到的内容明确标为待核验，禁止编造。
 输出简洁 Markdown 要点。
 """)
 .tools(factTool)
 .outputKey("research_notes")
 .build();

outputKey 会把 Agent 最终输出写入 Session State，供后续 Agent 使用。

2. Reviewer

LlmAgent reviewer = LlmAgent.builder()
 .name("reviewer")
 .description("审查研究事实、缺口与风险")
 .model("gemini-2.0-flash")
 .instruction("""
 阅读 session state 中的 research_notes。
 分成：已确认、证据不足、可能过时三类；
 不得把推测升级成事实，给出下一步核验建议。
 """)
 .outputKey("review_notes")
 .build();

3. Writer

LlmAgent writer = LlmAgent.builder()
 .name("writer")
 .description("把研究和审查结果组织成文章提纲")
 .model("gemini-2.0-flash")
 .instruction("""
 使用 research_notes 和 review_notes 生成中文技术文章提纲。
 对证据不足的结论保留警示；不输出版本发布稿，强调可复用原理与实践。
 """)
 .outputKey("article_outline")
 .build();

Prompt 应告诉 Agent 从 State 读取哪些键、输出写到哪里。否则三个 Agent 虽然按顺序运行，却不一定有效协作。

五、用 SequentialAgent 显式编排

import com.google.adk.agents.BaseAgent;
import com.google.adk.agents.SequentialAgent;
import java.util.List;

public final class ArticleWorkflow {

 public static final BaseAgent ROOT_AGENT = SequentialAgent.builder()
 .name("article_workflow")
 .description("研究、审查并生成文章提纲")
 .subAgents(List.of(researcher, reviewer, writer))
 .build();
}

顺序编排的价值是依赖关系明确：Reviewer 不会在 Researcher 之前运行，Writer 也不会绕过审查。它比让一个“主管 Agent”自行决定顺序更容易测试。

何时用其他类型：

ParallelAgent：两个子任务互不依赖，例如同时查官方文档和运行基准；
LoopAgent：审查不通过就重写，但必须设置退出条件和最大轮数；
LlmAgent + subAgents：让模型按语义把任务委派给专业 Agent。

不要把有先后依赖的任务硬塞进 Parallel，也不要创建没有最大次数的 Loop。

六、启动 Dev UI

ADK Java 自带开发 UI，可用于交互、查看事件和调试 Agent。最简单入口：

import com.google.adk.web.AdkWebServer;

public class Main {
 public static void main(String[] args) {
 AdkWebServer.start(ArticleWorkflow.ROOT_AGENT);
 }
}

启动后在本地页面输入：

比较 Java Agent 框架在工具权限和恢复方面的差异

开发 UI 适合：

看模型是否调用了工具；
检查专业 Agent 的执行顺序；
观察 State 中输出键；
保存用于演示和人工回归的会话。

它不是生产认证网关。上线时仍需自己的 API 层、身份系统、限流、审计和 Secret 管理。

七、Session、State 与 Artifact

ADK 中要区分：

概念	用途
Session	某用户/某次连续交互的容器
State	小型结构化状态，如研究摘要、审核结论
Event	用户、模型、工具与 Agent 运行过程
Artifact	文件、报告、图片等较大对象

outputKey 写入的是 State，不应把大文件或整份日志塞进去。大对象应使用 Artifact 服务，并在 State 中只保存引用和摘要。

生产环境还要决定 Session Service 的持久化实现。进程内 Session 适合 Demo；多实例部署需要共享后端，并测试并发更新、过期、迁移和恢复。

即使 Session 能恢复，工具副作用仍要幂等。流程崩溃可能发生在外部 API 已成功、结果尚未写回 Event/State 的窗口。

八、确定性 Workflow 与 LLM 路由怎样选择

优先确定性编排的情况：

合规审批顺序固定；
后一步依赖前一步产物；
需要精确控制成本和最大循环；
每个阶段都要测试和审计。

适合 LLM 路由的情况：

用户意图类别多，规则难以穷举；
多个专业 Agent 能力边界清楚；
选错路由的损失低，且可以回退；
工具和 Agent 都没有越权能力。

常用组合是：顶层确定性 Workflow 控制阶段，某个阶段内部用 LlmAgent 选择工具或子 Agent。

九、A2A 与 MCP 的分工

ADK 官方重点支持 A2A，用于远程 Agent 之间的能力发现和通信。MCP 则主要面向工具、资源和 Prompt 的互操作。

文章 Agent
 --A2A--> 独立部署的法务审查 Agent
 --MCP--> 搜索、数据库、文件等工具服务器

二者不是替代关系：

协议	对端	典型能力
A2A	另一个自治 Agent	委派任务、跟踪远程任务、交换结果
MCP	工具/资源服务器	调函数、读资源、获取 Prompt

跨进程后要验证认证、超时、取消、流式、重试和版本协商。协议兼容不代表安全策略自动兼容。

十、Preview 阶段怎样控制风险

官方 1.7.0 已发布到 Maven Central，但 README 仍标记 Preview / Pre-GA，且部分评测能力仍在演进。工程上应：

锁定 1.7.0，不使用动态版本；
用自己的 AgentWorkflow 接口包住 ADK 类型；
保存固定输入、工具调用和状态输出作为回归集；
将模型与工具封装在可替换适配层；
不把 Dev UI 暴露到公网生产环境；
对每次升级验证 Session schema、事件格式和工具调用；
为迁移到其他工作流引擎保留业务层边界。

“1.x”不自动等于 GA，官方发布阶段声明比版本号更重要。

十一、常见问题

后续 Agent 读不到前一步输出

确认前一步设置 outputKey，后续 Prompt 使用同一个 State 键；还要确认 Workflow 使用同一 Session，而不是为每步创建新会话。

模型不调用 FunctionTool

检查方法是否为可反射调用的静态方法、名称是否传给 FunctionTool.create、参数 Schema 是否明确，以及具体模型是否支持工具调用。

ParallelAgent 结果互相覆盖

每个并行 Agent 使用唯一 outputKey，汇总 Agent 再读取多个键。不要让并行分支写同一个 State 字段。

LoopAgent 不停运行

增加确定性退出条件和最大迭代数，同时记录每轮结果。不要只靠 Prompt 中“完成后停止”。

本地成功，上云后丢 Session

本地 Dev UI 常使用进程内服务。生产要配置共享 Session/Artifact 后端，并验证多副本路由、过期和并发更新。

十二、生产清单

明确标记 ADK Java 为 Preview / Pre-GA，并锁定精确版本；
工作流顺序由代码控制，LLM 只处理需要语义判断的节点；
每个 State Key 有唯一写入者或明确合并规则；
Artifact 与 State 分开保存；
工具有鉴权、幂等、超时和结构化错误；
Loop 有最大次数，Parallel 分支避免写冲突；
Dev UI 只用于受控开发环境；
A2A 和 MCP 分别设计认证与审计；
升级前运行固定 Agent/Tool/State 回归集；
多实例环境使用共享 Session 服务。

总结

Google ADK Java 最有价值的地方，是让 Java 开发者在同一套代码中组合两类控制：

LlmAgent 处理语义、工具选择和非结构化内容；
Sequential、Parallel、Loop 等 Workflow Agent 提供确定性控制；
outputKey、Session State 和 Artifact 负责阶段间传递；
Dev UI 降低本地调试成本；
A2A 连接独立 Agent，MCP 连接工具和资源。

在 Preview 阶段，建议从边界明确的内部工作流开始，而不是立刻替换关键核心系统。Code-first 的真正收益不只是代码看起来清晰，而是工作流能进入代码审查、测试、版本管理和故障演练。

参考资料

LangChain4j 实战：用 AI Services 与 Tool Calling 构建可控 Java Agent

Thu, 23 Jul 2026 00:00:00 +0800

LangChain4j 最容易被误解成“Python LangChain 的 Java 移植版”。实际上，它更强调 Java 接口、POJO、注解、类型安全和依赖注入。开发者可以把大模型能力定义成一个普通 Java Service，再组合 Chat Memory、RAG、@Tool 和 MCP。

本文使用 LangChain4j 1.18.0 和 JDK 17，实现一个订单查询与退款申请助手。模型可以读取订单，但退款属于副作用操作，必须先创建待审批申请，不能让模型直接完成退款。这个案例能说明：Tool Calling Agent 的重点不在“模型会调用函数”，而在于怎样让工具接口、状态和权限保持可控。

LangChain4j 的核心 AI Services、Tool Calling 与模型集成已经广泛使用；但官方明确说明整个 langchain4j-agentic 高层模块仍属于 experimental。本文先使用稳定的 AI Services + Tools 路线，不把实验性多 Agent API 当作生产前提。

一、Agent 的最小闭环

一个最小 Tool Calling Agent 包含：

用户消息
 -> AI Service 组装系统消息和历史
 -> ChatModel 判断是否调用工具
 -> LangChain4j 执行 @Tool 方法
 -> 工具结果回到模型
 -> 模型生成最终回答

这已经具备“观察—行动—再观察”的基本能力。只有当任务需要多个专业 Agent、共享工作区和复杂编排时，才有必要引入更高层 Agentic 模块。

在工程上，Agent 由三部分构成：

部分	责任
AI Service 接口	定义输入输出、系统约束和会话边界
ChatModel	生成回答与工具调用请求
Tool 对象	在 Java 可信边界内访问业务系统

模型提出调用，Java 工具决定什么能够真正执行。

二、依赖和模型

LangChain4j 1.18.0 的最低 JDK 是 17。使用 OpenAI 兼容模型时可先引入：

<properties>
 <maven.compiler.release>17</maven.compiler.release>
 <langchain4j.version>1.18.0</langchain4j.version>
</properties>

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>dev.langchain4j</groupId>
 <artifactId>langchain4j-bom</artifactId>
 <version>${langchain4j.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

<dependencies>
 <dependency>
 <groupId>dev.langchain4j</groupId>
 <artifactId>langchain4j</artifactId>
 </dependency>
 <dependency>
 <groupId>dev.langchain4j</groupId>
 <artifactId>langchain4j-open-ai</artifactId>
 </dependency>
</dependencies>

BOM 中部分扩展模块仍可能采用 beta 版本号。生产项目要看实际依赖树，而不能只看到 BOM 是 1.18.0 就认为所有模块都达到相同稳定级别。

模型配置示例：

import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;

ChatModel model = OpenAiChatModel.builder()
 .apiKey(System.getenv("OPENAI_API_KEY"))
 .modelName("gpt-4.1-mini")
 .temperature(0.1)
 .build();

具体模型名和 Tool Calling 能力以提供商当前文档为准。若接入 OpenAI-compatible 服务，还需设置 baseUrl，并实测结构化参数、并行工具调用和流式行为，而不能只验证普通聊天。

三、用 Java 接口定义 AI Service

import dev.langchain4j.service.MemoryId;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;

public interface OrderAssistant {

 @SystemMessage("""
 你是订单售后助手。
 查询订单前必须获得明确订单号；不得猜测订单状态。
 退款只能创建待审批申请，不能声称退款已经到账。
 最终回答要区分：查询结果、待审批、已拒绝和已完成。
 """)
 String chat(
 @MemoryId String userId,
 @UserMessage String message);
}

接口有两个值得注意的边界：

@MemoryId 只是选择会话记忆的键，不应直接作为业务身份凭据；
String 返回值适合聊天，业务系统若需要可靠状态，应从工具/数据库读取，而不是解析模型自然语言。

真实 HTTP 服务应该从认证上下文得到 userId，不能让客户端任意指定其他用户的 Memory ID。

四、设计只读工具与副作用工具

先定义订单对象和仓库：

public record Order(
 String orderId,
 String ownerId,
 String status,
 BigDecimal paidAmount) {}

public interface OrderRepository {
 Optional<Order> findById(String orderId);
}

查询工具只读，但仍要做归属校验：

import dev.langchain4j.agent.tool.P;
import dev.langchain4j.agent.tool.Tool;

public final class OrderTools {
 private final OrderRepository orders;
 private final RefundRequestRepository refunds;
 private final CurrentUser currentUser;

 public OrderTools(OrderRepository orders,
 RefundRequestRepository refunds,
 CurrentUser currentUser) {
 this.orders = orders;
 this.refunds = refunds;
 this.currentUser = currentUser;
 }

 @Tool("查询当前登录用户的订单状态和实付金额")
 public OrderView getOrder(
 @P("订单号，例如 O-20260725-001") String orderId) {
 Order order = orders.findById(orderId)
 .orElseThrow(() -> new IllegalArgumentException("订单不存在"));
 requireOwner(order);
 return new OrderView(order.orderId(), order.status(), order.paidAmount());
 }

 private void requireOwner(Order order) {
 if (!order.ownerId().equals(currentUser.id())) {
 throw new SecurityException("无权访问该订单");
 }
 }
}

副作用工具不要直接叫 refund，而是创建待审批申请：

@Tool("为当前用户的订单创建退款审批申请；不会直接退款")
public RefundRequestView prepareRefund(
 @P("订单号") String orderId,
 @P("退款原因，必须来自用户明确表达") String reason,
 @P("本次操作幂等键") String operationId) {

 Order order = orders.findById(orderId)
 .orElseThrow(() -> new IllegalArgumentException("订单不存在"));
 requireOwner(order);

 if (!order.status().equals("PAID")) {
 throw new IllegalStateException("只有 PAID 订单可申请退款");
 }

 return refunds.findByOperationId(operationId)
 .orElseGet(() -> refunds.createPending(
 operationId, currentUser.id(), orderId, reason));
}

这里有三条硬规则：

身份来自 CurrentUser，不作为 Tool 参数暴露给模型；
Java 代码再次校验订单状态和归属；
operationId 建立唯一约束，使模型重试不会创建重复申请。

真正执行退款的 approveAndExecuteRefund(approvalId) 应放在后台审批服务中，不注册给该 Agent。

五、绑定模型、Memory 和 Tools

import dev.langchain4j.memory.chat.MessageWindowChatMemory;
import dev.langchain4j.service.AiServices;

OrderAssistant assistant = AiServices.builder(OrderAssistant.class)
 .chatModel(model)
 .chatMemoryProvider(memoryId ->
 MessageWindowChatMemory.withMaxMessages(20))
 .tools(orderTools)
 .build();

调用方式和普通 Java Service 相似：

String answer = assistant.chat(
 authenticatedUser.id(),
 "帮我查订单 O-20260725-001；如果已支付，"
 + "以 operationId=refund-7f24 创建退款申请，原因是重复下单");

System.out.println(answer);

模型可能先调用 getOrder，观察状态后再调用 prepareRefund，最后告知用户“已创建待审批申请”。它没有真正退款的工具，因此即使 Prompt 被忽略，也无法跨过审批边界。

六、Chat Memory 不是业务数据库

MessageWindowChatMemory 只保留有限消息窗口，适合控制上下文长度。它不保证：

永久保存历史；
多实例共享；
业务事实可审计；
工具副作用 exactly-once；
用户身份安全。

应区分：

数据	应放在哪里
最近对话与 Tool Result	Chat Memory Store
订单和退款状态	业务数据库
用户身份与租户	认证上下文
幂等键和审批状态	业务数据库唯一约束
长文档知识	向量库/RAG，而不是无限消息窗口

Memory 里即使写着“退款成功”，也不能作为事实。下一轮回答前，应通过只读工具重新查询业务状态。

七、工具描述决定模型能否正确使用

LangChain4j 支持两层工具 API：底层 ChatModel + ToolSpecification，以及高层 AI Services + @Tool。大多数业务从高层开始即可。

工具描述要回答：

什么情况下调用；
每个参数代表什么；
是否有副作用；
返回值是什么状态；
哪些前置条件必须满足。

反例：

@Tool("处理订单")
String process(String input)

模型既不知道是查询、取消还是退款，也无法稳定生成参数。

改进：

@Tool("只查询当前用户订单；无副作用")
OrderView getOrder(@P("完整订单号") String orderId)

返回值优先使用 record/POJO，而不是拼接含糊字符串。工具错误也要映射为有限错误码，避免把数据库堆栈或敏感信息原样送回模型。

八、如何对工具做测试

Agent 测试要分层：

1. 纯 Java 工具测试

@Test
void duplicateOperationReturnsSameRefundRequest() {
 var first = tools.prepareRefund("O-1", "重复下单", "op-123");
 var second = tools.prepareRefund("O-1", "重复下单", "op-123");
 assertEquals(first.requestId(), second.requestId());
}

这层不调用模型，验证鉴权、状态机、幂等和异常。

2. 模型工具选择测试

准备固定请求集，记录模型是否：

缺订单号时先追问；
未查询状态就申请退款；
编造不存在的 Tool；
把“咨询退款政策”误判成创建退款；
在工具失败后声称成功。

3. 端到端故障测试

模拟超时、429、工具异常和进程重启，确认不会重复副作用，最终状态来自数据库。

不要只凭一条成功 Demo 判断 Agent 可用。

九、MCP 什么时候加入

如果工具和 Agent 在同一进程、都是 Java Bean，直接注册 @Tool 最简单。以下情况再考虑 MCP：

工具由独立团队维护，需要跨语言/跨进程提供；
多个 Agent 客户端需要共享同一工具目录；
希望统一发现工具、资源和 Prompt；
工具生命周期与业务应用不同。

引入 MCP 后，仍要保留认证、租户隔离、超时、幂等和审批。MCP 解决互操作，不自动解决工具可信问题。

十、实验性 Agentic 模块应该怎样用

langchain4j-agentic 提供 @Agent、AgenticScope、Sequential、Parallel、Loop、Supervisor 等模式。官方文档明确写着 whole module experimental。

适合：

技术验证；
内部工具；
固定版本的 PoC；
可以承担 API 变化成本的项目。

生产采用前应：

锁定精确依赖版本；
给编排层包一层自己的接口；
用回归集验证共享变量、错误传播和工具副作用；
不让实验 API 渗透整个业务代码；
为升级准备迁移测试。

若需求只是一个 Agent 调用几个工具，不必为了“多智能体”标签提前引入实验模块。

十一、常见问题

模型从不调用工具

确认具体模型支持 Tool Calling；检查工具描述是否清楚、参数是否可生成，并把温度调低。OpenAI-compatible 不代表工具协议完全兼容，要抓取请求响应做实测。

同一用户的对话串到一起

检查 @MemoryId 是否使用稳定、不可伪造且带租户命名空间的键。多实例还需要共享 ChatMemoryStore；进程内 Memory 不会自动同步。

退款工具被重复调用

不要试图只靠 Prompt 阻止。使用服务端生成的 operationId、数据库唯一约束和“重复请求返回原结果”的工具语义。

Tool 抛出异常后模型仍说成功

让工具返回结构化 status/errorCode，在 AI Service 外再查询业务事实。高风险接口不要把最终成功判定交给自然语言。

换模型后效果明显变化

统一 API 只能统一调用方式，不能抹平模型在 Tool Calling、结构化输出、并行调用和上下文窗口上的差异。每个模型都要跑相同回归集。

十二、生产清单

API Key 只从环境变量或 Secret Manager 读取；
@MemoryId 与认证用户绑定并包含租户命名空间；
只读和写工具分离，Agent 默认只获得最小工具集；
身份、金额、角色不允许由模型自由填写；
所有写工具使用幂等键和唯一约束；
高风险动作只生成待审批请求；
工具返回结构化结果与有限错误码；
模型、工具、token、延迟和 operationId 可关联追踪；
使用固定测试集比较模型与版本；
若采用 Agentic 模块，明确标记 experimental 并隔离 API。

总结

使用 LangChain4j 构建可控 Agent 的关键，不是让一个 Java 接口看起来像魔法，而是保持职责边界：

AI Services 负责消息、Memory 和模型交互；
@Tool 负责把有限业务能力暴露给模型；
Java 服务负责身份、权限、状态机和参数校验；
数据库负责事实、审批与幂等；
高层 langchain4j-agentic 只有在确实需要复杂编排、并接受实验性 API 风险时再引入。

从“只读查询 + 创建待审批申请”开始，远比直接把退款、删库或发邮件工具交给模型可靠。Agent 可以拥有选择工具的自由，但不应该拥有绕过业务规则的自由。

参考资料

Node.js 事件循环与 nextTick / microtask：原理、阶段与工程实践

Thu, 23 Jul 2026 00:00:00 +0800

HTTP 服务偶发“全站卡住几秒”、定时器比预期晚很多、setTimeout(0) 和 setImmediate 顺序飘忽不定、同步校验回调却读到未初始化变量——这些现象往往不是“Node 慢”，而是对 事件循环（Event Loop）阶段、nextTick 队列、微任务队列、Worker Pool 理解不到位。

本文基于 Node.js 官方 Learn 文档 The Node.js Event Loop、Don’t Block the Event Loop，以及 API 文档 process.nextTick / Timers，把调度机制讲清楚，并给出可复现实验与排障清单。

一、问题背景：单线程 JS 为何能扛大量并发

官方对事件循环的定位很直接：

The event loop is what allows Node.js to perform non-blocking I/O operations — despite the fact that a single JavaScript thread is used by default — by offloading operations to the system kernel whenever possible.

也就是说：

应用层 JS 默认跑在一条线程（Event Loop / main thread）。
能丢给内核的非阻塞 I/O（如多数网络 I/O）完成后，内核通知 Node，相关回调进入 poll 等队列等待执行。
不便做成纯非阻塞的昂贵工作（部分 fs、dns.lookup、crypto.pbkdf2、zlib 等）会提交到 libuv 的 Worker Pool，做完再回到事件循环。

Don’t Block the Event Loop 给出的工程拇指法则是：

Node.js is fast when the work associated with each client at any given time is “small”.

线程少、上下文切换少，是 Node 能用较少资源服务大量连接的原因；代价是：任意一次过长的同步回调，都会让其他客户端得不到轮转——既伤吞吐，也构成 DoS 面（恶意大输入、灾难性正则等）。

线程类型	跑什么	阻塞后果
Event Loop	初始化、JS 回调、`await`/`then` 续体、网络等非阻塞 I/O 编排	所有请求排队；定时器/I/O 回调整体延迟
Worker Pool	昂贵任务（多数 `fs`、部分 DNS/Crypto/Zlib、C++ 提交的任务）	池子被占满时同类任务排队；回压到业务

二、核心模型：阶段队列 + 阶段外的 nextTick

1. 启动与相位图

进程启动后会：初始化事件循环 → 执行入口脚本（其中可调异步 API、定时器、process.nextTick()）→ 再进入循环迭代。

官方简化相位（每个 box 是一个 phase）：

 ┌───────────────────────────┐
 │ timers │ setTimeout / setInterval
 └─────────────┬─────────────┘
 v
 ┌───────────────────────────┐
┌─>│ pending callbacks │ 延迟到下一轮的部分系统 I/O 回调
│ └─────────────┬─────────────┘
│ v
│ idle, prepare （内部使用）
│ v
│ poll 取新 I/O 事件；执行 I/O 回调
│ v
│ check setImmediate 回调
│ v
│ close callbacks 如 socket.on('close')
│ v
└───────────── timers ──────────┘

一般规则：进入某 phase 后，先做该 phase 专属操作，再 FIFO 执行队列回调，直到队列耗尽或达到系统相关的上限，再进入下一 phase。

文档还强调：

timers 指定的是“阈值（threshold）之后尽早可执行”，不是精确闹钟；OS 调度与其它回调都会让它推迟。
从 libuv 1.45.0（Node.js 20） 起，每个事件循环迭代中 timers 在 poll 之后运行；为兼容，进入循环前仍会跑一轮 timers。这会影响某些场景下 setImmediate 与定时器的相对时序。
每一轮事件循环之间，若不再等待任何异步 I/O 或定时器，进程可干净退出。

2. 各 phase 在工程上的含义

Phase	主要职责	工程注意
timers	`setTimeout` / `setInterval` 到期回调	阈值语义；可能被长回调推迟
pending callbacks	部分系统操作延迟回调（如某些 TCP `ECONNREFUSED`）	平台差异存在，但日常业务少直接依赖
poll	检索新 I/O；执行几乎所有 I/O 回调（除 close、定时器、`setImmediate`）	空队列时可能阻塞等待；有 `setImmediate` 时可能结束 poll 进入 check
check	`setImmediate`	“poll 完成后立即跑一轮脚本”的专用相位
close callbacks	如 `socket.destroy()` 触发的 `'close'`	否则 close 也可能经 `nextTick` 发出

3. `process.nextTick` 不在相位图里

官方明确：

process.nextTick() is not technically part of the event loop. Instead, the nextTickQueue will be processed after the current operation is completed, regardless of the current phase.

任意 phase 里调用 nextTick，都会在当前操作结束后、事件循环继续前进前排空 nextTick 队列。因此递归 nextTick 可以 饿死 I/O（永远到不了 poll）——这是合法但危险的行为。

process API 进一步说明：

nextTick(callback) 把回调放进 next tick queue；当前 JS 栈操作结束后、事件循环继续前完全排空该队列。
稳定性标注为 Legacy，多数用户代码更推荐 queueMicrotask()。
每次 next tick 队列排空后，会立即再排空 microtask 队列（Promise 的 then/catch/finally、queueMicrotask）。
模块系统差异（官方示例）：
- CJS：通常 nextTick → Promise/queueMicrotask
- ESM：模块求值本身已在 microtask 路径上，常见顺序是 Promise/queueMicrotask → nextTick

// CJS 常见输出：nextTick → resolve → microtask
const { nextTick } = require('node:process');
Promise.resolve().then(() => console.log('resolve'));
queueMicrotask(() => console.log('microtask'));
nextTick(() => console.log('nextTick'));

// ESM 常见输出：resolve → microtask → nextTick
import { nextTick } from 'node:process';
Promise.resolve().then(() => console.log('resolve'));
queueMicrotask(() => console.log('microtask'));
nextTick(() => console.log('nextTick'));

4. `setImmediate` vs `setTimeout(0)`

API	语义（官方）	典型落点
`setImmediate(fn)`	poll 阶段结束后执行脚本	check phase
`setTimeout(fn, 0)`	至少等待阈值（0ms）后尽早执行	timers phase

主模块顶层同时调度两者：顺序不确定，取决于进程性能与调度。
在 I/O 回调内（例如 fs.readFile 回调里）同时调度：官方保证 setImmediate 总是先于 timers，与 timers 数量无关。

官方也坦言命名历史包袱：nextTick 比 setImmediate 更“立即”，名字几乎应互换；但为兼容 npm 生态不会改名。一般推荐优先用 setImmediate 推理成本更低；nextTick 留给“必须在调用栈展开后、循环前进前”的场景。

三、实践：可复现实验

实验 A：I/O 周期内 immediate 恒先于 timeout(0)

// save as io-order.js (CJS)
const fs = require('node:fs');

fs.readFile(__filename, () => {
 setTimeout(() => console.log('timeout'), 0);
 setImmediate(() => console.log('immediate'));
});

node io-order.js
# 期望：
# immediate
# timeout

实验 B：nextTick 在“当前操作后”插入，早于进入下一 phase

// nexttick-vs-immediate.js
const fs = require('node:fs');

fs.readFile(__filename, () => {
 setImmediate(() => console.log('immediate'));
 process.nextTick(() => console.log('nextTick'));
 Promise.resolve().then(() => console.log('promise'));
});

在 I/O 回调这个“当前操作”末尾，会先排空 nextTick，再处理 microtask，然后事件循环才能推进到后续 phase（check 中的 immediate）。你应看到 nextTick 先于 immediate；CJS 下 nextTick 通常也先于 promise。

实验 C：为何 API 必须“全同步或全异步”

官方反例：签名像异步、实际同步调用回调，调用方无法判断后续语句与回调的先后：

// BAD：可能同步也可能异步
function maybeSync(arg, cb) {
 if (arg) {
 cb();
 return;
 }
 require('node:fs').stat('file', cb);
}

推荐：同步路径也 nextTick(cb)（或统一走 Promise），保证“总是异步”：

const { nextTick } = require('node:process');
const fs = require('node:fs');

function definitelyAsync(arg, cb) {
 if (arg) {
 nextTick(cb);
 return;
 }
 fs.stat('file', cb);
}

构造函数里 emit 同理：应 nextTick(() => this.emit('event'))，让调用方先挂上监听器。

实验 D：同步计算堵死循环（对照）

// block-loop.js
const http = require('node:http');

http.createServer((req, res) => {
 if (req.url.startsWith('/block')) {
 const end = Date.now() + 3000;
 while (Date.now() < end) {} // 同步忙等 3s
 res.end('blocked\n');
 return;
 }
 res.end('ok\n');
}).listen(3456, () => console.log('listen 3456'));

开两个终端：

# 终端 1：触发阻塞
curl -sS http://127.0.0.1:3456/block &
# 终端 2：立即请求轻量路径
time curl -sS http://127.0.0.1:3456/

会观察到轻量请求也被拖慢——因为 Event Loop 被同一线程的同步代码占满。

四、常见坑与排查

现象	可能机制	处理方向
全站偶发卡顿、延迟尖刺	同步 CPU 重活 / 大 JSON / 灾难正则 / 长循环	限制输入；分区 yield；`worker_threads` / 子进程卸载
`setTimeout(100)` 变成 105ms+	poll 长回调占住队列；阈值语义 + 其它回调	缩短 poll 回调；避免在 I/O 回调里做重计算
顶层 `setTimeout(0)` 与 `setImmediate` 顺序随机	主模块非 I/O 周期，时序依赖性能	需要稳定顺序时放到 I/O 回调，或只用一种调度 API
递归 `nextTick` 后 I/O 永不完成	nextTick 队列饿死 poll	改 `setImmediate` / 批处理 + yield
CJS/ESM 下 Promise 与 nextTick 顺序不一致	官方文档写明的队列次序差异	不要依赖跨模块类型的微次序；业务用明确的 async 编排
`fs`/`crypto` 变慢但 CPU 不高	Worker Pool 打满	评估 `UV_THREADPOOL_SIZE`、减少同步 `*Sync`、合并小 I/O
同步 API 伪装异步	调用方竞态	统一异步边界；错误路径也 `nextTick`/`queueMicrotask`

不要阻塞 Event Loop 的检查清单（摘自官方思路）：

每个回调的计算复杂度是否随用户输入线性/超线性膨胀？是否有上限校验？
是否存在嵌套量词正则（REDOS）？简单包含用 indexOf/includes。
大对象是否在主线程 JSON.parse / stringify？能否限制体积或卸载到 Worker？
是否误用 *Sync 文件/加密 API 于请求路径？
需要“下一轮再继续”时，默认优先 setImmediate / queueMicrotask，慎用无限 nextTick。

分区（Partitioning）示例思路：把 O(n) 求和拆成多步，每步 O(1)，用 setImmediate/queueMicrotask 让出循环，避免单次回调霸占主线程。更重的任务则应 Offloading 到 Worker（worker_threads、独立进程或 C++/N-API 任务），而不是只靠在主循环里切片。

五、总结

Node 的并发模型是 单线程 Event Loop + libuv Worker Pool：I/O 与任务要“碎、短、可让出”。
相位队列决定 timers / poll / check / close 等回调归属；nextTick 与 microtask 是阶段之间的优先通道。
I/O 回调内 setImmediate 稳定早于 setTimeout(0)；主模块顶层两者顺序不稳定。
nextTick 适合“栈展开后、循环前进前”的 API 契约；滥用会饿死 I/O。新代码多数场景优先 queueMicrotask / setImmediate。
性能与安全同一条线：限制输入、避免 REDOS、大 JSON 与 CPU 重活卸载，才能让“少线程高并发”真正成立。

把调度图画进团队约定后，再写中间件、ORM 钩子、连接池回调，会少掉一大类“玄学时序 bug”。

参考资料

The Node.js Event Loop — Node.js Learn（阶段图、poll/check/timers、setImmediate vs setTimeout、process.nextTick）
Don’t Block the Event Loop (or the Worker Pool) — Node.js Learn（Event Loop vs Worker Pool、阻塞危害、分区/卸载、REDOS/JSON）
Understanding process.nextTick() — Node.js Learn
process.nextTick / queueMicrotask 对比 — Node.js API（CJS/ESM 次序、Legacy 说明）
Timers — Node.js API（setImmediate / setTimeout、ref/unref）
源码文档镜像：nodejs/node doc/api/process.md、doc/api/timers.md

Spring AI Alibaba 实战：用 Supervisor 构建可持久化的 Java 多智能体助手

Thu, 23 Jul 2026 00:00:00 +0800

很多 Java Agent 示例只演示“模型调用一个工具”，但真实业务通常横跨多个边界：日历 Agent 理解时间并检查冲突，邮件 Agent 负责收件人和正文，协调者还要决定调用顺序、传递结果，并在失败后恢复。

本文基于 Spring AI Alibaba 官方稳定依赖线 1.1.2.2，实现一个 Supervisor + 专业子 Agent 的个人助理。重点不是某个模型的聊天接口，而是四个可复用的工程问题：如何划分 Agent 边界、怎样把子 Agent 暴露成工具、如何保存执行状态，以及如何控制有副作用的操作。

本文代码结构依据官方 examples/multiagent-patterns/supervisor 示例整理。Spring AI Alibaba 同时存在面向 Spring AI 2.0 / Spring Boot 4 的 2.0.0-M1.1 里程碑版本；生产项目不要把 milestone 与本文稳定线混用。

一、为什么需要 Supervisor

多 Agent 并不等于“把四个聊天机器人放进一个群”。一个可控系统至少要区分三层：

层次	职责	本文对应实现
决策层	拆解请求、选择能力、安排调用顺序	`personal_assistant` Supervisor
专业层	在受限领域内推理和调用工具	`schedule_event`、`manage_email`
执行层	访问日历、邮件、数据库等真实系统	Java `@Tool` 方法

用户说“下周二开评审会，并给设计组发提醒”时，Supervisor 先调用日历 Agent；拿到时间和创建结果后，再把必要信息交给邮件 Agent。专业 Agent 看不到无关工具，工具层也不承担自然语言规划。

这种设计的价值是 缩小每次模型决策的工具集合。如果把查日历、建会议、发邮件、查工单、改数据库等几十个工具全部交给一个 Agent，模型更容易选错工具，权限也难以分层。

二、环境与依赖

官方稳定示例使用 JDK 17、Spring Boot 3.5.7、Spring AI 1.1.2 和 Spring AI Alibaba 1.1.2.2：

<parent>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter-parent</artifactId>
 <version>3.5.7</version>
</parent>

<properties>
 <java.version>17</java.version>
 <spring-ai.version>1.1.2</spring-ai.version>
 <spring-ai-alibaba.version>1.1.2.2</spring-ai-alibaba.version>
</properties>

<dependencyManagement>
 <dependencies>
 <dependency>
 <groupId>org.springframework.ai</groupId>
 <artifactId>spring-ai-bom</artifactId>
 <version>${spring-ai.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 <dependency>
 <groupId>com.alibaba.cloud.ai</groupId>
 <artifactId>spring-ai-alibaba-bom</artifactId>
 <version>${spring-ai-alibaba.version}</version>
 <type>pom</type>
 <scope>import</scope>
 </dependency>
 </dependencies>
</dependencyManagement>

<dependencies>
 <dependency>
 <groupId>com.alibaba.cloud.ai</groupId>
 <artifactId>spring-ai-alibaba-starter-dashscope</artifactId>
 </dependency>
 <dependency>
 <groupId>com.alibaba.cloud.ai</groupId>
 <artifactId>spring-ai-alibaba-agent-framework</artifactId>
 </dependency>
 <dependency>
 <groupId>org.springframework.boot</groupId>
 <artifactId>spring-boot-starter</artifactId>
 </dependency>
</dependencies>

配置密钥时不要写进仓库：

spring:
 ai:
 dashscope:
 api-key: ${AI_DASHSCOPE_API_KEY}

运行前设置环境变量：

export AI_DASHSCOPE_API_KEY="你的密钥"

如果换成其他 Spring AI ChatModel，Agent 编排代码本身可以保持不变，但工具调用、结构化输出和并行调用能力仍取决于具体模型。

三、先写最窄的业务工具

工具的参数和描述会进入模型上下文。名称模糊、参数万能化，会直接降低调用准确率。下面用内存实现代替真实日历系统：

@Component
public class CalendarTools {

 @Tool(description = "检查指定 ISO-8601 起止时间内是否有空闲时段")
 public String getAvailableTimeSlots(
 @ToolParam(description = "开始时间，例如 2026-07-28T14:00:00+08:00") String start,
 @ToolParam(description = "结束时间，例如 2026-07-28T15:00:00+08:00") String end) {
 return "AVAILABLE: " + start + " ~ " + end;
 }

 @Tool(description = "创建日历事件；调用前必须已经确认时间可用")
 public String createCalendarEvent(
 @ToolParam(description = "事件标题") String title,
 @ToolParam(description = "ISO-8601 开始时间") String start,
 @ToolParam(description = "ISO-8601 结束时间") String end) {
 String id = UUID.randomUUID().toString();
 return "CREATED eventId=" + id + ", title=" + title;
 }
}

邮件工具同样保持窄接口：

@Component
public class EmailTools {

 @Tool(description = "发送邮件。仅接受已经确认的收件人、主题和正文")
 public String sendEmail(String recipient, String subject, String body) {
 return "SENT to=" + recipient + ", subject=" + subject;
 }
}

演示可以直接返回字符串，生产环境必须补上：

幂等键：重试不能创建两场相同会议或发送两封邮件；
身份鉴权：工具从服务端上下文读取租户和用户，不能信任模型传入身份；
参数校验：邮箱白名单、时间范围、正文长度均由 Java 代码强制检查；
审计日志：记录调用者、工具名、参数摘要、结果和 trace ID；
超时与熔断：模型重试不应无限放大下游故障。

四、构建两个专业 ReactAgent

ReactAgent 负责“思考—选择工具—观察结果—继续”的循环。每个专业 Agent 只注册本领域工具：

@Configuration
public class AgentConfiguration {

 @Bean
 MemorySaver memorySaver() {
 return new MemorySaver();
 }

 @Bean
 ReactAgent calendarAgent(ChatModel model, CalendarTools tools) {
 return ReactAgent.builder()
 .name("schedule_event")
 .description("检查空闲时间并创建日历事件，输入为自然语言日程请求")
 .systemPrompt("""
 你是日历助理。先把时间转换为带时区的 ISO-8601 格式，
 再检查空闲时段；只有可用时才创建事件。
 最终回答必须包含事件 ID 和确认后的起止时间。
 """)
 .model(model)
 .methodTools(tools)
 .inputType(String.class)
 .build();
 }

 @Bean
 ReactAgent emailAgent(ChatModel model, EmailTools tools) {
 return ReactAgent.builder()
 .name("manage_email")
 .description("根据明确的收件人和上下文撰写并发送邮件")
 .systemPrompt("""
 你是邮件助理。不得猜测收件地址；缺少地址就要求补充。
 发送前检查主题、正文和会议时间是否一致。
 最终回答给出发送状态，不输出敏感凭据。
 """)
 .model(model)
 .methodTools(tools)
 .inputType(String.class)
 .build();
 }
}

这里的 name 和 description 不是装饰字段。Supervisor 会根据它们决定是否调用子 Agent，因此描述要写清楚 何时调用、输入是什么、能产生什么结果。

五、把子 Agent 变成 Supervisor 的工具

Spring AI Alibaba 提供 AgentTool.getFunctionToolCallback(...)，可以把整个专业 Agent 包装成上层 Agent 可调用的工具：

@Bean
ReactAgent supervisorAgent(
 ChatModel model,
 ReactAgent calendarAgent,
 ReactAgent emailAgent,
 MemorySaver memorySaver) {

 return ReactAgent.builder()
 .name("personal_assistant")
 .systemPrompt("""
 你是任务协调者，可以安排日历和发送邮件。
 先拆解请求，再按依赖顺序调用专业工具。
 邮件依赖会议结果时，必须先完成日历操作。
 不要声称执行了未返回成功结果的操作。
 """)
 .model(model)
 .saver(memorySaver)
 .tools(
 AgentTool.getFunctionToolCallback(calendarAgent),
 AgentTool.getFunctionToolCallback(emailAgent))
 .build();
}

调用入口非常直接：

@Component
public class DemoRunner implements ApplicationRunner {
 private final ReactAgent supervisorAgent;

 public DemoRunner(ReactAgent supervisorAgent) {
 this.supervisorAgent = supervisorAgent;
 }

 @Override
 public void run(ApplicationArguments args) throws Exception {
 String request = "下周二 14:00 安排一小时设计评审，"
 + "然后给 design@example.com 发一封提醒邮件";

 AssistantMessage result = supervisorAgent.call(new UserMessage(request));
 System.out.println(result.getText());
 }
}

一次典型执行链是：

User
 -> Supervisor
 -> schedule_event
 -> get_available_time_slots
 -> create_calendar_event
 -> manage_email
 -> send_email
 -> 汇总最终结果

子 Agent 是工具，但它内部仍然可以执行多轮 ReAct。这样既保留自治能力，又把自治限制在专业边界内。

六、状态持久化不等于聊天记忆

示例中的 MemorySaver 适合本地开发和单进程验证。它保存的是图执行所需的 checkpoint，使 Agent 能围绕同一线程继续运行；它不是生产级共享数据库，也不能替代业务幂等。

工程上要区分三类状态：

状态	示例	推荐存储
会话上下文	用户偏好、已确认的时间	Chat Memory / 会话库
Agent checkpoint	当前节点、工具结果、待恢复位置	持久化 Saver
业务事实	已创建会议、邮件发送记录	业务数据库，带唯一约束

即便 checkpoint 恢复成功，若工具在崩溃前已经写入业务系统、但结果还没写回 checkpoint，恢复后仍可能重复调用。因此可靠流程要让工具接受 operationId，并在业务库建立唯一约束。

七、给副作用加一道人工确认

会议和邮件都属于有副作用操作。最稳妥的方式不是只在 Prompt 中写“请先确认”，而是在工具层建立状态机：

DRAFT -> WAITING_APPROVAL -> EXECUTING -> SUCCEEDED / FAILED

Agent 第一次调用只生成草稿并返回 approvalId；API 层收到用户确认后，才调用真正的发送方法。这样即使模型忽略提示，也没有直接执行权限。

还可以进一步拆成两个工具：

prepare_email(...)：任何 Agent 都能调用，只生成草稿；
send_approved_email(approvalId)：不接受正文，只执行服务端已经批准且未过期的草稿。

这比让模型把 approved=true 当参数传进来安全得多。

八、常见问题与排查

1. 子 Agent 从不被调用

检查 name、description 是否明确，并确认模型支持 Tool Calling。描述不要只写“邮件助手”，而要说明输入和使用时机。

2. 依赖冲突或类找不到

不要混用 Spring AI 1.1.x、Spring AI Alibaba 1.1.x 与 2.0 milestone。使用 BOM 统一版本，并执行：

mvn dependency:tree

重点检查 spring-ai-* 是否出现多条不兼容版本线。

3. 时间被理解错

“明天下午”必须结合用户时区和当前日期解析。生产系统应把当前时间、时区作为可信上下文注入，并在工具层拒绝无时区或已经过期的时间。

4. 重启后任务消失

MemorySaver 只在进程内。多实例部署需要共享持久化 Saver，同时工具仍要做幂等；二者缺一不可。

5. 最终回答说成功，业务却没有记录

只信工具返回的结构化结果，不信模型自行生成的成功话术。建议工具返回包含 status、operationId、errorCode 的对象，并在最终输出前增加确定性校验节点。

九、什么时候不用多 Agent

如果任务只有一个模型、三个简单只读工具和一次调用，单个 ReactAgent 往往更便宜、更快，也更容易测试。只有出现以下情况，多 Agent 才真正有价值：

不同领域需要不同 Prompt、工具权限或模型；
任务能拆成可独立测试的专业能力；
子任务需要并行、路由或多阶段交接；
某些 Agent 必须运行在隔离环境或独立服务中；
团队希望分别维护日历、邮件、工单等能力。

不要用 Agent 替代确定性代码。固定审批顺序、金额阈值和权限检查应该写进 Java 与工作流，而不是交给 LLM 临场决定。

总结

Spring AI Alibaba 的 Supervisor 模式可以概括为：上层 Agent 负责选择和协调，下层 Agent 负责专业推理，Java 工具负责可信执行，Saver 负责恢复上下文。

真正决定系统能否进入生产的并不是 Agent 数量，而是边界是否清楚：

每个专业 Agent 只看到必要工具；
有副作用操作经过服务端审批和幂等保护；
checkpoint、会话记忆与业务事实分开保存；
版本通过 BOM 锁定，不混用稳定线和 milestone；
最终成功状态由真实工具结果而不是模型话术决定。

在这个基础上，再引入 ParallelAgent、RoutingAgent、Graph 条件边、A2A 或 Nacos，复杂度才是可控增长，而不是把一个不可预测的大 Agent 拆成一群不可预测的小 Agent。

参考资料

Python asyncio 事件循环与 Task 取消：原理、API 与工程实践

Mon, 20 Jul 2026 00:00:00 +0800

高并发 HTTP 客户端、WebSocket 网关、爬虫调度、微服务侧车——Python 侧大量 IO 密集型场景会落到 asyncio。写得不好时，常见症状是：协程“创建了却从不调度”、后台 Task 被 GC 悄悄干掉、超时后资源不释放、CancelledError 被误吞导致 TaskGroup / timeout 行为异常。

本文基于官方文档 asyncio — Asynchronous I/O、Coroutines and Tasks、Runners、Developing with asyncio，以及 PEP 492，把 事件循环协作调度、Task 生命周期、结构化并发、取消与超时 讲清楚，并给出可复现的写法与排障清单。

一、问题背景：并发不等于多线程

asyncio 的定位很明确：

asyncio is a library to write concurrent code using the async/await syntax.
asyncio is often a perfect fit for IO-bound and high-level structured network code.

它解决的是“大量等待网络/磁盘时如何让 CPU 去干别的活”，而不是用多核并行跑 CPU 密集计算。事件循环通常跑在 一个线程 内：某个 Task 在执行同步代码时，同线程的其他 Task 无法推进；只有执行到 await，当前 Task 挂起，循环才调度下一个。

若把 time.sleep、同步 requests、重型 JSON/CPU 计算直接塞进协程，等价于堵死整条事件循环。官方开发指南的原则是：阻塞工作放到线程池（asyncio.to_thread / loop.run_in_executor），循环线程只做非阻塞 IO 与调度。

概念	含义	工程后果
协程函数 `async def`	调用后得到协程对象，不会自动运行	只写 `foo()` 而不 `await`/`create_task` 会 RuntimeWarning
Awaitable	可被 `await` 的对象	三类主路径：协程、Task、Future
Event loop	调度 Task/回调、做网络 IO、跑子进程	应用层优先用 `asyncio.run`，少直接操作 loop
Task	被调度执行的协程包装	可取消、可聚合、可命名/追踪

二、核心模型：协作式调度 + 弱引用 Task

1. 必须“跑起来”，而不能只“创建”

import asyncio

async def main():
 print("hello")
 await asyncio.sleep(1)
 print("world")

asyncio.run(main())

官方示例同时强调反例：

>>> main()
<coroutine object main at 0x...>

单纯调用协程不会把它排进事件循环。入口应使用 asyncio.run(coro)：它负责创建/关闭循环、收尾异步生成器、关闭默认 executor。同一线程已有运行中的 loop 时不能再调用 asyncio.run（嵌套场景用 asyncio.Runner 或上层框架提供的生命周期）。

2. 并发来自 Task，不是“多写几个 await”

串行：

await say_after(1, "hello")
await say_after(2, "world") # 总耗时约 3s

并发：

task1 = asyncio.create_task(say_after(1, "hello"))
task2 = asyncio.create_task(say_after(2, "world"))
await task1
await task2 # 总耗时约 2s

create_task 把协程包成 Task 并立即调度。一个极易踩坑的细节（官方明确写出）：

The event loop only keeps weak references to tasks. A task that isn’t referenced elsewhere may get garbage collected at any time, even before it’s done.

“发后不管”的后台任务必须放进集合，并在 done 回调里移除：

background_tasks: set[asyncio.Task] = set()

def spawn(coro):
 task = asyncio.create_task(coro)
 background_tasks.add(task)
 task.add_done_callback(background_tasks.discard)
 return task

3. 结构化并发：优先 `TaskGroup`（3.11+）

asyncio.TaskGroup 把“创建 + 等待全部结束”绑在异步上下文管理器里：

async def main():
 async with asyncio.TaskGroup() as tg:
 tg.create_task(say_after(1, "hello"))
 tg.create_task(say_after(2, "world"))
 # 退出 with 时，组内任务均已结束

组内若有任务抛出非 CancelledError 的异常，会汇总为 ExceptionGroup / BaseExceptionGroup 再抛出。相对“手写 create_task + 忘记 await”，TaskGroup 更不容易留下孤儿任务。

API	典型用途	注意点
`create_task`	灵活并发、需要 Task 句柄	保持强引用；自行处理汇合
`TaskGroup`	结构化并发、统一收口	异常变为 ExceptionGroup；依赖取消语义正确
`gather(*aws, return_exceptions=False)`	固定一批 awaitable 一起等	默认某任务异常会影响整体策略；结果顺序与入参一致
`wait(aws, return_when=...)`	需要 `done/pending` 集合或 FIRST_COMPLETED	入参必须是 Future/Task 集合，不能是裸协程习惯用法

gather 适合“固定 N 路、要按入参顺序拿结果”：

results = await asyncio.gather(
 fetch(u1),
 fetch(u2),
 fetch(u3),
 return_exceptions=True, # 单个失败不中断其余；结果里可能是 Exception 实例
)

return_exceptions=False（默认）时，任一 awaitable 以异常结束，gather 会把该异常传播给调用方（其余任务的收尾策略仍需按版本与场景理解，工程上更稳妥的是用 TaskGroup 明确“有错就结构化失败”）。wait 则返回 (done, pending)，并可用 FIRST_COMPLETED / FIRST_EXCEPTION / ALL_COMPLETED 控制返回时机，适合“谁先完成谁处理、其余取消”的竞态选路。

三、取消与超时：CancelledError 是协作信号

1. 取消发生在“下一次机会”

task.cancel() 请求取消后，目标 Task 会在 下一次可取消点（通常是 await）注入 asyncio.CancelledError。官方建议：

用 try/finally 做资源清理（关连接、放回连接池、落盘状态）；
若显式 except CancelledError，清理完成后 一般应继续抛出；
CancelledError 直接继承 BaseException，因此普通 except Exception 抓不到它——这是刻意设计。

吞掉取消会破坏结构化并发组件：

asyncio.TaskGroup and asyncio.timeout() are implemented using cancellation internally and might misbehave if a coroutine swallows asyncio.CancelledError.

2. 超时：`wait_for` 与 `timeout` 上下文

# 超时后取消 awaitable，并抛 TimeoutError
try:
 await asyncio.wait_for(long_job(), timeout=5)
except TimeoutError:
 ...

wait_for 在超时路径会取消目标任务；为避免取消可包 shield（见下）。函数会等到取消真正完成，因此总等待可能略大于 timeout。

3.11+ 更推荐上下文管理器写法：

async def main():
 try:
 async with asyncio.timeout(10):
 await long_running_task()
 except TimeoutError:
 # TimeoutError 只能在 with 之外捕获
 ...

timeout 会取消 当前 Task，内部把 CancelledError 转成 TimeoutError。timeout_at(when) 用绝对 deadline，适合与外部截止时间对齐。

3. `shield`：挡外层取消，不挡内层自杀

res = await asyncio.shield(critical_section())

外层 Task 被取消时，critical_section 对应 Task 不一定 被取消；但从调用方看，await 仍会抛 CancelledError。若 critical_section 自己取消自己，shield 挡不住。完全“无视取消”通常不推荐——多数场景应清理后退出。

4. 可复现小实验：串行 vs 并发 vs 超时取消

把下面脚本存为 asyncio_lab.py，用本机 Python 3.11+ 直接跑，对照耗时与异常类型：

import asyncio
import time

async def work(name: str, delay: float, fail: bool = False):
 print(f"{name}: start")
 try:
 await asyncio.sleep(delay)
 if fail:
 raise RuntimeError(f"{name} failed")
 print(f"{name}: done")
 return name
 finally:
 print(f"{name}: cleanup")

async def demo_serial():
 t0 = time.perf_counter()
 await work("A", 1)
 await work("B", 1)
 print("serial_sec=", round(time.perf_counter() - t0, 2))

async def demo_concurrent():
 t0 = time.perf_counter()
 async with asyncio.TaskGroup() as tg:
 tg.create_task(work("A", 1))
 tg.create_task(work("B", 1))
 print("concurrent_sec=", round(time.perf_counter() - t0, 2))

async def demo_timeout_cancel():
 try:
 async with asyncio.timeout(0.3):
 await work("slow", 2)
 except TimeoutError:
 print("got TimeoutError as expected")

async def demo_swallow_cancel_bad():
 async def bad():
 try:
 await asyncio.sleep(10)
 except asyncio.CancelledError:
 print("swallowed cancel — TaskGroup/timeout 可能异常")
 # 反例：清理后应 re-raise
 return "oops"

 task = asyncio.create_task(bad())
 await asyncio.sleep(0.05)
 task.cancel()
 print("bad_result=", await asyncio.gather(task, return_exceptions=True))

async def main():
 await demo_serial()
 await demo_concurrent()
 await demo_timeout_cancel()
 await demo_swallow_cancel_bad()

if __name__ == "__main__":
 asyncio.run(main())

预期现象：

串行约 2s，并发约 1s，说明 await 串接 ≠ 并发；
超时路径打印 cleanup 后得到 TimeoutError（timeout 上下文在内部完成 CancelledError 转换）；
吞掉 CancelledError 会让任务“以普通返回值结束”，外层若误以为已取消，容易泄漏后续逻辑。

四、工程实践：从入口到排障

1. 入口与生命周期

async def app():
 # 创建共享资源：连接池、httpx.AsyncClient 等
 async with lifespan():
 await serve()

if __name__ == "__main__":
 asyncio.run(app(), debug=False) # 开发可 debug=True

需要在同一 loop 多次跑顶层协程时，用 asyncio.Runner 上下文，而不是嵌套 asyncio.run。

2. 阻塞调用迁出事件循环

def blocking_io():
 # 同步 SDK / 磁盘 / 旧库
 return open("/etc/hosts").read()

async def handler():
 data = await asyncio.to_thread(blocking_io)
 return data

to_thread 会传播 contextvars，适合 IO 型阻塞；CPU 密集可考虑进程池 executor。

3. 取消友好的业务骨架

async def fetch_with_cleanup(session, url):
 resp = None
 try:
 resp = await session.get(url)
 return await resp.text()
 finally:
 if resp is not None:
 await resp.aclose()

原则：

所有可能长时间 await 的路径都假定可被取消；
持有的锁、文件、连接在 finally 释放；
不要用裸 except Exception: pass 包住整段协程。

4. 并发扇出模板

async def fan_out(urls: list[str], limit: int = 20):
 sem = asyncio.Semaphore(limit)

 async def one(url: str):
 async with sem:
 return await fetch(url)

 async with asyncio.TaskGroup() as tg:
 tasks = [tg.create_task(one(u)) for u in urls]
 return [t.result() for t in tasks]

限流用 Semaphore，汇合用 TaskGroup，超时可在外层 async with asyncio.timeout(...) 包住整组或单个 one。

5. 调试开关

开发期打开 debug mode（任选其一）：

环境变量 PYTHONASYNCIODEBUG=1
asyncio.run(..., debug=True)
loop.set_debug(True)

debug 能更清楚地指出 never-awaited coroutine 的创建栈，并帮助发现慢回调。配合：

import logging
logging.basicConfig(level=logging.DEBUG)

6. 与多线程协作时的边界

官方 Developing with asyncio 写得很清楚：事件循环在一个线程里跑所有回调与 Task；几乎所有 asyncio 对象都不是线程安全的。从其他 OS 线程调度回调必须用 loop.call_soon_threadsafe(...)；从其他线程提交协程用 asyncio.run_coroutine_threadsafe(coro, loop)，它返回 concurrent.futures.Future。反向地，若只是要把阻塞函数丢出循环线程，优先 asyncio.to_thread，而不是自己裸开线程再回调 loop。

工程约束可以记成：

一个 loop 绑定一个线程（通常是主线程）；
跨线程只走 threadsafe API；
业务协程里不要 threading.Lock 长时间占着不 await——锁竞争会放大“假死”表象。

7. HTTP 扇出 + 首个成功取消其余

async def first_success(coros):
 tasks = [asyncio.create_task(c) for c in coros]
 try:
 while tasks:
 done, pending = await asyncio.wait(
 tasks, return_when=asyncio.FIRST_COMPLETED
 )
 for d in done:
 if d.exception() is None:
 for p in pending:
 p.cancel()
 # 收尾 pending，避免警告
 await asyncio.gather(*pending, return_exceptions=True)
 return d.result()
 tasks = list(pending)
 raise RuntimeError("all failed")
 finally:
 for t in tasks:
 if not t.done():
 t.cancel()

这是“多副本查询取最快”的常见模式：与 Go 里 fan-out + context cancel 同构，只是取消载体从 context.Context 换成了 Task.cancel / CancelledError。

五、常见坑与排查清单

症状	可能根因	排查/修复
`RuntimeWarning: coroutine 'x' was never awaited`	写了 `x()` 却未 `await`/`create_task`	打开 debug；全文搜未 await 的调用
后台任务“跑一半消失”	只 `create_task` 未保存强引用	`set` + `add_done_callback(discard)`
整体 QPS 骤降、延迟抖动	协程内同步阻塞	火焰图/`asyncio` 慢回调日志；改 `to_thread`
超时后连接仍占满	取消路径无 `finally` 清理	统一 async context manager
`TaskGroup` / `timeout` 行为怪异	`except CancelledError: pass` 吞取消	清理后 re-raise；勿滥用 `uncancel`
Jupyter/已有 loop 报错	嵌套 `asyncio.run`	用框架提供的 loop / `Runner` / `await` 直接写
取消不及时	长段纯计算无 `await`	拆分、主动 `await asyncio.sleep(0)` 让出（治标）或迁线程/进程（治本）

快速自检脚本思路：

# 1) 开发模式跑入口
PYTHONASYNCIODEBUG=1 python app.py

# 2) 确认没有 never-awaited
# 3) 压测时观察是否仅单核打满且无网络等待（疑似阻塞循环）

六、总结

asyncio 是单线程协作式并发：await 是让出点；阻塞代码会冻住所有 Task。
协程对象 ≠ 已调度任务：入口用 asyncio.run，并发用 create_task / TaskGroup。
Task 只有弱引用：fire-and-forget 必须自管强引用集合。
取消是协作语义：CancelledError 属 BaseException；清理后应继续传播，否则破坏 TaskGroup/timeout。
超时优先结构化 API：asyncio.timeout / wait_for；关键段可 shield，但不要“永远不退出”。
阻塞 IO 迁出循环：to_thread / executor；开发期打开 debug 抓 never-awaited 与慢回调。

掌握“调度模型 + 取消契约 + 结构化汇合”，比背一长串 API 更能写出可维护的异步服务。

参考资料

Go context 取消传播与超时控制：原理、API 与工程实践

Sat, 18 Jul 2026 00:00:00 +0800

HTTP 请求被客户端断开、下游 RPC 超时、批量任务需要“先完成的取消其余副本”——这些场景的共同点是：一组协作的 goroutine 必须能收到“该停了”的信号，并在约定时间内释放资源。Go 标准库的 context 包，就是为跨 API 边界传递 截止时间（deadline）、取消信号 与 请求级值 而设计的。

本文基于 context 包源码注释、pkg.go.dev/context 文档，以及 Go 官方博客 Go Concurrency Patterns: Context、Contexts and structs，把取消树、超时、CancelFunc 泄漏、WithValue 边界与常见工程坑讲清楚，并给出可落地的写法与排查清单。

一、问题背景：为什么需要 Context

没有统一取消通道时，常见反模式是：

每个函数自建 done chan struct{}，调用链一长就无法串联；
超时只写在 HTTP Client 上，业务层仍继续跑昂贵计算；
子 goroutine 不知道请求已结束，继续访问已关闭的连接，造成泄漏或写日志噪音。

官方文档的定位非常明确：

Package context defines the Context type, which carries deadlines, cancellation signals, and other request-scoped values across API boundaries and between processes.

工程上可以记三句话：

能力	含义	典型触发
Deadline	工作最晚何时必须结束	`WithTimeout` / `WithDeadline`
Cancellation	调用方主动要求放弃	客户端断开、`cancel()`、父 context 取消
Request-scoped values	跨边界透传的请求元数据	trace id、鉴权主体（慎用）

服务入口应为入站请求创建 Context；出站调用应接收并传播同一个（或派生的）Context。中间调用链 必须向下传递，必要时用 WithCancel / WithTimeout / WithValue 派生子 Context。

二、核心模型：取消树 + Done 通道

Context 是接口，核心方法包括 Done、Err、Deadline、Value。理解取消的关键是：

Done() <-chan struct{}：通道关闭即“应停止工作”的信号；
Err()：在 Done 关闭后说明原因——context.Canceled 或 context.DeadlineExceeded；
派生形成树：父 Context 取消时，所有子 Context 一并取消；
接收方不能取消父方：Context 没有 Cancel 方法，Done 只读，避免子操作反过来取消父操作。

官方博客强调：父操作启动子操作时，子操作不应有能力取消父操作；取消权通过 WithCancel 返回的 CancelFunc 交给“拥有者”。

Background / request root
 │
 ├─ WithTimeout(2s) ──► handler 工作树
 │ │
 │ ├─ WithCancel ──► 并行查询 A
 │ └─ WithCancel ──► 并行查询 B
 │
 └─ 根取消 / 超时 / cancel()
 ⇒ 整棵子树 Done 关闭

Background() 返回永不取消、无值、无 deadline 的空 Context，适合 main、初始化、测试，以及入站请求的顶层根。TODO() 同样是空 Context，用于“暂时不清楚该用哪个 Context”的占位；不要传 nil——文档明确要求：即使函数允许 nil，也请传 context.TODO()。

三、API 速查：从根到超时

1. 取消：`WithCancel` / `WithCancelCause`

ctx, cancel := context.WithCancel(parent)
defer cancel() // 工作结束后尽快调用，释放子树与定时器资源

语义要点（源码注释）：

子 Context 的 Done 在 cancel() 被调用 或 父 Done 关闭 时关闭，谁先发生谁生效；
调用 cancel 会取消子及其后代，并断开父对子的引用、停止相关 timer；
不调用 CancelFunc 会泄漏：子 Context 及其后代会一直挂到父被取消；go vet 会检查所有控制流路径是否使用了 CancelFunc；
CancelFunc 不等待工作真正停下；可被多 goroutine 并发调用，首次之后为 no-op。

Go 1.20+ 的 cause 系列更利于排障：

ctx, cancel := context.WithCancelCause(parent)
cancel(fmt.Errorf("client disconnected: %w", err))
// ctx.Err() 仍为 context.Canceled
// context.Cause(ctx) 可取到你记录的 cause

Cause(ctx)：若通过 CancelCauseFunc(err) 取消则返回该 err；否则与 ctx.Err() 相同；未取消时返回 nil。

2. 超时与截止时间：`WithTimeout` / `WithDeadline`

// WithTimeout ≡ WithDeadline(parent, time.Now().Add(timeout))
ctx, cancel := context.WithTimeout(parent, 100*time.Millisecond)
defer cancel()
return slowOperation(ctx)

语义要点：

子 deadline 取 parent deadline 与新 deadline 中更早者；
Done 在 超时 / cancel / 父取消 三者中最先发生时关闭；
超时后 ctx.Err() 为 context.DeadlineExceeded；主动 cancel 一般为 context.Canceled；
同样必须 defer cancel()，即使操作在超时前完成，也要释放 timer 等资源。

3. 值：`WithValue`（窄场景）

type traceIDKey struct{}
ctx = context.WithValue(ctx, traceIDKey{}, "req-42")

官方硬规则：

只用于跨进程/API 传递的请求级数据，不要把可选函数参数塞进 Context；
key 必须 comparable，且 不要用内置 string 等类型当 key，避免包间碰撞；推荐自定义未导出类型，如 struct{}。

4. 进阶：`WithoutCancel` 与 `AfterFunc`（Go 1.21+）

API	用途	注意
`WithoutCancel(parent)`	派生一个不随父取消的 Context；无 Deadline/Err，Done 为 nil	父 nil 会 panic；适合“请求已结束但仍要落盘审计”的短尾工作，且必须自建超时
`AfterFunc(ctx, f)`	ctx 取消后在独立 goroutine 跑 `f`；已取消则立即调度	返回 `stop`；`stop` 不等待 `f` 结束；多次 `AfterFunc` 彼此独立

四、实践：HTTP 处理中的超时与协作取消

func handleSearch(w http.ResponseWriter, r *http.Request) {
 // 入站请求：以 r.Context() 为根（客户端断开时通常会取消）
 parent := r.Context()

 // 业务总预算：2s（与网关/客户端超时对齐，略留余量）
 ctx, cancel := context.WithTimeout(parent, 2*time.Second)
 defer cancel()

 q := r.URL.Query().Get("q")
 result, err := searchBackends(ctx, q)
 if err != nil {
 if errors.Is(err, context.DeadlineExceeded) {
 http.Error(w, "search timeout", http.StatusGatewayTimeout)
 return
 }
 if errors.Is(err, context.Canceled) {
 // 客户端已走，通常无需再写完整响应
 return
 }
 http.Error(w, err.Error(), http.StatusBadGateway)
 return
 }
 // ... 写响应
}

func searchBackends(ctx context.Context, q string) (string, error) {
 // 扇出：任一成功可取消其余；或全部失败返回
 ctx, cancel := context.WithCancel(ctx)
 defer cancel()

 type res struct {
 v string
 err error
 }
 ch := make(chan res, 2)

 for _, ep := range []string{"a.example", "b.example"} {
 ep := ep
 go func() {
 v, err := callOne(ctx, ep, q) // 内部必须监听 ctx.Done()
 ch <- res{v, err}
 }()
 }

 var last error
 for i := 0; i < 2; i++ {
 select {
 case <-ctx.Done():
 return "", context.Cause(ctx) // 或 ctx.Err()
 case r := <-ch:
 if r.err == nil {
 cancel() // 提前结束兄弟 goroutine
 return r.v, nil
 }
 last = r.err
 }
 }
 return "", last
}

func callOne(ctx context.Context, ep, q string) (string, error) {
 req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://"+ep+"/s?q="+url.QueryEscape(q), nil)
 if err != nil {
 return "", err
 }
 resp, err := http.DefaultClient.Do(req)
 if err != nil {
 return "", err
 }
 defer resp.Body.Close()
 // ... 读 body，同样尊重 ctx
 return "ok", nil
}

协作取消的正确姿势：

叶子操作用支持 Context 的 API（NewRequestWithContext、QueryContext、gRPC ctx 等）；
纯计算循环用 select 或周期性检查 ctx.Err()；
取消是 建议性（advisory） 的：库必须真正监听 Done，否则 cancel() 只是“通知了空气”。

五、不要把 Context 塞进结构体

官方文档与 Contexts and structs 博客一致：

Do not store Contexts inside a struct type; instead, pass a Context explicitly to each function that needs it. The Context should be the first parameter, typically named ctx.

六、常见坑与排查

症状	可能原因	处理
goroutine / timer 泄漏	创建了 `WithCancel`/`WithTimeout` 却没 `cancel`	立刻 `defer cancel()`；跑 `go vet`
超时不生效	底层调用未绑定 ctx（旧 `http.Get`、忽略 Done 的循环）	换 `*Context` API；手写 `select`
`Err` 总是 Canceled 难排查	未区分超时与主动取消	用 `errors.Is`；需要细节时用 Cause 系列
请求结束后仍用原 ctx 写库	父 ctx 已取消导致落库失败	短尾任务用新的 `WithTimeout(context.Background(), …)` 或审慎使用 `WithoutCancel` + 自有超时
值取不到 / 键冲突	string key 跨包碰撞或类型断言错误	私有 key 类型 + 统一 accessor
把可选参数塞进 Value	隐式依赖、难测	显式函数参数
传递 `nil` context	派生时 panic 或行为未定义	`TODO()` / `Background()`

最小实验建议：

A. WithTimeout(50ms) + time.Sleep(200ms) 并 select ctx.Done()
 期望：DeadlineExceeded

B. 父 WithCancel，子 WithTimeout(1s)，父先 cancel
 期望：子立刻 Done，Err 为 Canceled（父取消优先于子 timer）

C. WithTimeout 成功路径忘记 defer cancel
 观察：高频调用下 timer/子节点滞留（pprof / 泄漏检测）

D. Worker 存 ctx vs 每方法传 ctx
 对比：后者可为单次调用设更短 deadline

七、工程约定（可直接用于 Code Review）

ctx 永远是第一个参数，命名 ctx；不放结构体字段。
入站用框架/request 的 Context；出站必须向下传，禁止“半路换成 Background”除非有书面理由（如与请求脱钩的异步任务）。
每个 WithCancel / WithTimeout / WithDeadline 成对 defer cancel()。
超时预算 自上而下递减：网关 3s → 服务 2s → 下游 RPC 800ms，避免子超时大于父。
WithValue 仅 trace/auth 等横切元数据；业务输入走参数。
错误判断用 errors.Is(err, context.Canceled) / DeadlineExceeded，不要比字符串。
取消后仍需完成的短工作：新建带超时的独立 Context，并限队列，防止雪崩。
并发扇出时明确策略：全部完成 / 先胜出取消其余 / 错误阈值，并保证兄弟 goroutine 能收到取消。

八、总结

context 不是“多传一个参数”的仪式，而是 Go 并发里 跨边界的截止时间与取消协议：

取消沿 父子树 向下传播；子不能取消父；
WithTimeout / WithDeadline 用更紧的 deadline 保护尾延迟；
CancelFunc 必须调用，否则泄漏到父取消为止；
协作取消要求叶子真正监听 Done；
Context 作参数传递，不进结构体；Value 只承载请求级元数据。

把“谁拥有 cancel、超时预算如何切分、叶子是否尊重 Done”三件事写进设计与 Code Review，线上超时与 goroutine 泄漏类问题会少一个数量级。

参考资料

Go 标准库文档 — context package（Overview、WithCancel/WithTimeout/WithValue/WithoutCancel/AfterFunc/Cause、编程约定）
Go 源码 — src/context/context.go（包注释与 API 语义、Canceled/DeadlineExceeded、CancelFunc 行为）
Go Blog — Go Concurrency Patterns: Context（Context 接口、派生树、Background、服务端示例动机）
Go Blog — Contexts and structs（为何不要把 Context 存进结构体、按调用传参的生命周期清晰性）

OceanBase 从零开始：核心概念、上手路径，以及和 MySQL 的关键差异

Fri, 17 Jul 2026 01:00:00 +0800

如果你已经会 MySQL，第一次接触 OceanBase 时，最容易卡住的不是“SQL 怎么写”，而是：

它看起来很像 MySQL，为什么连接方式、资源模型、高可用和运维概念完全不是一回事？

本文面向零基础到 MySQL 初中级同学，用一条从概念到上手的路径讲清楚：

OceanBase 是什么
和 MySQL 在架构、租户、连接、兼容性上的核心差异
从连接、建库建表到基础 SQL 的最小实践
什么场景该把 OceanBase 当“更强的 MySQL”，什么场景不能这么想

说明：本文以 OceanBase 社区版（MySQL 模式） 为主。官方文档明确：社区版仅提供 MySQL 模式；企业版还支持 Oracle 模式。

一、先建立正确心智模型

1. MySQL 的常见心智模型

很多人对 MySQL 的默认理解是：

一台机器 / 一个 mysqld 实例
 └── 多个 database
 └── 多个 table

连接通常很直接：

mysql -h127.0.0.1 -P3306 -uroot -p

你连上的，基本就是“这个实例本身”。

2. OceanBase 的心智模型

OceanBase 更接近：

一个集群（Cluster）
 └── 多个节点（OBServer）
 └── 多个可用区（Zone）
 └── 多个租户（Tenant） ← 应用视角下更像“数据库实例”
 └── 多个 database
 └── 多个 table / 分区

关键变化只有一句话：

在 OceanBase 里，应用通常不是“连一台 MySQL 机器”，而是“连某个租户”。

官方文档把租户定义为：集群内互相隔离的数据库“实例”。对应用来说，一个租户近似一个独立数据库实例；租户之间数据、权限、资源隔离。

二、OceanBase 是什么

OceanBase 是蚂蚁集团开源的分布式关系型数据库，基于 Paxos 类共识协议与分布式架构，提供高可用和水平扩展能力，可运行在普通服务器集群上。

官方强调的关键能力包括：

水平扩展
高可用（RPO=0、RTO 秒级恢复目标）
MySQL 兼容，便于迁移
HTAP（同一套系统同时服务事务与分析负载）
多租户资源隔离

你可以把“上手阶段”理解成两层：

层	你感受到的
SQL 层	很像 MySQL：`CREATE DATABASE` / `CREATE TABLE` / `SELECT`
系统层	更像分布式数据库：集群、Zone、租户、Unit、副本、OBProxy

三、和 MySQL 的核心差异总览

维度	MySQL（常见单机/主从）	OceanBase
基本部署单元	实例（mysqld）	集群 + 租户
应用连接对象	实例	租户（经直连或 OBProxy）
默认端口（常见）	`3306`	直连 `2881`，经 ODP/OBProxy 常见 `2883`
用户写法	`root`	`root@tenant` 或 `user@tenant#cluster`
扩展方式	垂直扩容 / 读写分离 / 分库分表	原生分区、多节点、副本扩展
高可用机制	主从复制、MGR 等	基于 Multi-Paxos 的多副本日志流
多业务隔离	多实例 / 多库 + 权限	原生多租户 + 资源池
存储引擎模型	InnoDB 等可插拔引擎	自研分布式存储与事务体系
SQL 兼容	原生 MySQL	MySQL 模式兼容 5.7/8.0 大部分能力，但非 100%
社区版模式	MySQL	仅 MySQL 模式

一句话：

MySQL 更像“一台关系库”；OceanBase 更像“一个可多租户的分布式数据库平台”。

四、架构差异：为什么它不像单机 MySQL

1. Shared-Nothing 集群

官方系统架构文档指出，OceanBase 常用无共享（Shared-Nothing）模式：

节点对等
每个节点都有自己的 SQL / 存储 / 事务能力
表可水平拆分为多个分区（Partition）
分区数据落在 Tablet，修改通过日志流（Log Stream）持久化
主从副本通过 Multi-Paxos 保持一致性

这意味着：

数据天然可分布到多节点
故障切换依赖副本选举，而不是简单“切到另一台 mysqld”
建表时的分区设计，会直接影响数据分布与扩展性

2. 多租户：最容易被 MySQL 同学忽略的概念

在 OceanBase 中：

集群初始化后会有系统租户 sys
sys 保存集群元数据，本身也是 MySQL 兼容模式租户
业务一般应在普通租户里建库建表，而不是把所有业务都堆在 sys

创建业务租户的典型顺序是：

Unit Config（资源规格）
 → Resource Pool（资源池）
 → Tenant（租户）

这和 MySQL 里“直接 CREATE DATABASE”完全不同。
MySQL 的 database 更像命名空间；OceanBase 的 tenant 更像独立实例边界。

3. OBProxy / ODP：应用如何“像访问单机库一样”访问分布式库

为了让应用尽量少感知分区和副本分布，OceanBase 提供 ODP（OceanBase Database Proxy，又称 OBProxy）：

应用通常连代理
代理把 SQL 路由到合适节点
对应用更接近“连一个入口地址”

这对应 MySQL 生态里的 proxy / 中间件角色，但在 OceanBase 里它更常作为标准访问路径出现。

五、连接差异：最容易踩坑的地方

1. Docker 体验环境（最简单）

快速体验可用官方镜像：

docker run -p 2881:2881 --name oceanbase-ce -e MODE=mini -d oceanbase/oceanbase-ce
docker logs oceanbase-ce | tail -1 # 期望 boot success!

连接示例：

# 系统租户 root
docker exec -it oceanbase-ce obclient -h127.0.0.1 -P2881 -uroot

# 或宿主机 mysql 客户端
mysql -h127.0.0.1 -P2881 -uroot
mysql -h127.0.0.1 -P2881 -uroot@test

2. 正式连接写法：用户名里有租户

官方文档给出两类常见连接：

直连 OBServer（默认端口常为 2881）

mysql -h<observer_ip> -P2881 -u用户名@租户名 -p

注意：

直连时 -u 应是 用户名@租户名
不要在直连用户名里带集群名，否则可能报错
普通租户直连时，目标节点上需要有该租户资源

通过 ODP/OBProxy（默认端口常为 2883）

mysql -h<odp_ip> -P2883 -u用户名@租户名#集群名 -p

用户名还可能写成：

集群名:租户名:用户名
集群名-租户名-用户名
集群名.租户名.用户名

这和 MySQL 的 root@'%' 完全不是同一套语义。

3. 客户端选择

可用 obclient
也可用 MySQL 客户端连接 MySQL 模式租户
官方文档提到当前支持的 MySQL 客户端版本包括 5.5 / 5.6 / 5.7（以你使用版本的文档为准）

六、从零上手：MySQL 同学 10 分钟路径

下面假设你已经能连上一个 MySQL 模式租户。

1. 看有哪些库

SHOW DATABASES;

体验环境里常见会看到 oceanbase、test、information_schema、mysql 等。

2. 创建业务库

CREATE DATABASE demo DEFAULT CHARACTER SET utf8mb4 READ WRITE;
USE demo;

这和 MySQL 非常像。

3. 建表、写入、查询

CREATE TABLE users (
 id INT PRIMARY KEY,
 name VARCHAR(64) NOT NULL,
 created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO users (id, name) VALUES
 (1, 'alice'),
 (2, 'bob');

SELECT id, name FROM users WHERE id = 1;
UPDATE users SET name = 'alice2' WHERE id = 1;
DELETE FROM users WHERE id = 2;

官方 MySQL 模式基础文档也覆盖了：

CREATE DATABASE / SHOW DATABASES
CREATE TABLE / SHOW TABLES / SHOW CREATE TABLE
ALTER TABLE
INSERT / UPDATE / DELETE / TRUNCATE
多表查询、聚合、EXPLAIN 等

4. 看建表细节时的“OceanBase 味道”

在 OceanBase 里执行：

SHOW CREATE TABLE users\G

你可能会看到比 MySQL 更“重”的表属性，例如副本数、压缩、Tablet 相关参数等。
这说明：SQL 表面兼容，元数据与存储参数并不等同于 InnoDB。

七、兼容性：像 MySQL，但不是 100% MySQL

官方《与 MySQL 兼容性对比》说明：

OceanBase 的 MySQL 模式兼容 MySQL 5.7/8.0 的绝大部分功能和语法；因架构差异或需求优先级，部分功能未支持。

1. 相似度高的部分

通常对应用最友好的部分：

常见数值 / 时间 / 字符 / JSON 等数据类型
SELECT / INSERT / UPDATE / DELETE
多表连接、子查询、聚合分组
存储过程、函数、触发器等大部分 PL 能力
information_schema、mysql 中的大量视图（但不是逐列完全等价）

因此：

很多基于 MySQL 协议的驱动可直接连
简单 CRUD 业务迁移门槛较低
你会有“这不就是 MySQL 吗”的错觉

2. 必须注意的差异

官方明确提到的差异方向包括：

类别	差异点
SQL 语法	例如不支持 `SELECT ... FOR SHARE ...`
TRUNCATE	不支持在事务处理与表锁定过程中操作
系统视图	不保证所有视图/列含义都与 MySQL 相同
存储引擎	不是 InnoDB 插件体系，而是自研分布式存储事务体系
优化器	执行计划与优化策略不同
分区 / 备份恢复	能力模型与操作路径不同
架构相关功能	因分布式架构，部分单机 MySQL 习惯不能照搬

3. 实战迁移建议

从 MySQL 迁到 OceanBase 时，不要只做“能不能连上”：

先验证协议层：驱动、连接池、ORM
再验证 SQL 层：慢 SQL、锁、事务边界、分页、HINT
再验证运维层：备份恢复、监控指标、扩缩容、租户资源
最后验证边界语法：冷门函数、系统表、复制相关特性、特定锁语法

一句话：

兼容的是“MySQL 使用体验”，不是“MySQL 内核实现”。

八、对象模型对比：database 相同，边界不同

MySQL

Instance
 └── Database
 └── Table / View / Procedure

权限、连接、资源，常常都围绕“实例 + 账号”展开。

OceanBase

Cluster
 └── Tenant（资源与权限边界更强）
 └── Database
 └── Table / Index / Procedure
 └── sys 租户（集群元数据）

对 MySQL 同学最实用的迁移记忆：

你在 MySQL 想做的事	在 OceanBase 更常见的对应
新建一个业务实例	新建一个业务租户
在实例里建库	在租户里 `CREATE DATABASE`
给业务分配 CPU/内存	调整 Unit Config / Resource Pool
连业务库	连 `user@tenant`
做高可用	规划 Zone / 副本 / 主备切换，而不是只配主从

九、一个最小对比实验（帮助真正理解差异）

实验 A：同一套 CRUD

在 OceanBase MySQL 模式租户执行：

CREATE DATABASE shop DEFAULT CHARACTER SET utf8mb4;
USE shop;

CREATE TABLE orders (
 order_id BIGINT PRIMARY KEY,
 user_id BIGINT NOT NULL,
 amount DECIMAL(10,2) NOT NULL,
 status VARCHAR(16) NOT NULL
);

INSERT INTO orders VALUES
 (1001, 1, 19.90, 'PAID'),
 (1002, 2, 39.00, 'CREATED');

SELECT * FROM orders WHERE status = 'PAID';

你会发现：
如果只看 SQL，这和 MySQL 几乎没区别。

实验 B：连接串差异

MySQL：

mysql -h127.0.0.1 -P3306 -uroot -p shop

OceanBase 直连某租户：

mysql -h127.0.0.1 -P2881 -uroot@test -p shop

OceanBase 经 ODP：

mysql -h127.0.0.1 -P2883 -uroot@test#cluster_name -p shop

你会发现：
真正拉开差距的，是“你连到了哪里”和“资源边界在哪里”。

实验 C：多租户隔离

在 sys 中创建两个业务租户后：

root@tenant1 里建表
root@tenant2 里看不到那张表

官方多租户示例正是用这种方式证明：
租户之间资源、数据、权限隔离。

这比 MySQL 里“两个 database 互相授权”要更接近“两个实例”。

十、什么时候适合用 OceanBase，什么时候继续 MySQL

更适合考虑 OceanBase 的场景

需要水平扩展，单机 MySQL + 分库分表成本高
需要更强的金融级高可用与多副本一致性
希望一套系统兼顾 TP 与部分 AP
多业务要强隔离，但又想统一运维平台（多租户）
已有大量 MySQL 协议应用，希望降低改造成本

更适合继续 MySQL 的场景

单机或轻量业务，数据量和可用性要求不高
团队只熟悉传统 mysqld 运维，短期不想引入分布式复杂度
深度依赖某些 MySQL 专有行为 / 插件 / 生态工具且未验证兼容
本地开发只需要极轻量依赖（虽然也可用 OceanBase Docker，但 MySQL 更轻）

十一、学习路线建议

如果你是 MySQL 背景，建议按这个顺序学：

先跑起来：Docker / obd demo
先会连：user@tenant、2881 / 2883
先当 MySQL 用：建库建表 CRUD
再学租户与资源：Unit / Resource Pool / sys 与普通租户
再学分布式：分区、副本、Zone、OBProxy 路由
最后做迁移评估：兼容性清单 + 压测 + 备份恢复演练

配套阅读：

本站另一篇：OceanBase 多平台搭建教程
官方 MySQL 兼容性文档
官方系统架构与多租户文档

十二、速查对照表

主题	MySQL	OceanBase
默认连接	`root@host:3306`	`root@tenant@host:2881` 或经 ODP `2883`
业务隔离	database / 多实例	tenant
管理入口	实例管理员	常先登 `sys` 做集群与租户管理
扩展	加配 / 分库分表	分区 + 多节点 + 资源单元
高可用	复制拓扑	Multi-Paxos 多副本
SQL 习惯	原生 MySQL	高度兼容，但要做差异验证
社区版模式	MySQL	仅 MySQL 模式

总结

OceanBase 对 MySQL 同学并不“难在 SQL”，而难在换模型：

把“实例”理解升级成“集群 + 租户”
把“连上 mysqld”升级成“连上正确的租户入口”
把“兼容 MySQL”理解成“协议与常用 SQL 友好，不等于内核相同”
先用 CRUD 建立信心，再用租户、分区、副本理解它的分布式能力

掌握这四步后，你就不会再把 OceanBase 误当成“换了皮的 MySQL”，也能更准确判断它该用在什么地方。

参考资料

OceanBase 官方仓库 README（中英文，MySQL 兼容与快速开始）：https://github.com/oceanbase/oceanbase
OceanBase 官方文档：系统架构（oceanbase-doc / V4.3.5）
OceanBase 官方文档：与 MySQL 兼容性对比
OceanBase 官方文档：SQL 基础操作（MySQL 模式）
OceanBase 官方文档：体验多租户特性
OceanBase 官方文档：通过 MySQL 客户端连接 OceanBase 租户
OceanBase Docker 镜像：https://hub.docker.com/r/oceanbase/oceanbase-ce
OceanBase 中文文档中心：https://www.oceanbase.com/docs/oceanbase-database-cn

Spring 事务传播机制：REQUIRED、REQUIRES_NEW 与嵌套事务工程实践

Fri, 17 Jul 2026 00:00:00 +0800

业务代码里最容易“看起来对、跑起来却不对”的一类问题，就是 事务边界。方法上贴了 @Transactional，并不等于“想回滚就一定回滚、想独立提交就一定独立提交”。真正决定行为的，是 传播行为（propagation）、物理事务 vs 逻辑事务、以及 Spring 默认的 代理拦截模型。

本文基于 Spring Framework 官方事务文档，把 REQUIRED / REQUIRES_NEW / NESTED 等传播语义、回滚规则与常见工程踩坑讲清楚，并给出可落地的写法与排查清单。

一、先分清：物理事务 vs 逻辑事务

Spring 管理事务时，不能只看“有没有 @Transactional”，而要区分两层：

概念	含义	工程直觉
物理事务（physical）	底层资源上真正开启的事务（如一条 JDBC Connection 上的 `begin/commit/rollback`）	能不能真正提交/回滚、锁何时释放
逻辑事务（logical）	每个被 Spring 事务拦截的方法作用域	该方法能否单独标记 `rollback-only`

传播行为决定的是：外层方法与内层方法之间，逻辑作用域如何映射到物理事务。
这正是很多“内层抛异常后外层还以为自己 commit 成功了”的根源。

二、七种传播行为速查

@Transactional(propagation = …) 对应 TransactionDefinition 中的常量。按“有没有外层事务”理解最稳：

传播行为	无外层事务时	有外层事务时	典型用途
`REQUIRED`（默认）	新建物理事务	加入外层同一物理事务	服务门面 + 多仓储同事务
`SUPPORTS`	非事务执行	加入外层事务	查询既可独立也可参与写事务
`MANDATORY`	抛异常	加入外层事务	强制调用方必须已开事务
`REQUIRES_NEW`	新建物理事务	挂起外层，新建独立物理事务	审计日志、独立提交的状态点
`NOT_SUPPORTED`	非事务执行	挂起外层，非事务执行	长耗时/远程调用不想占连接
`NEVER`	非事务执行	抛异常	明确禁止在事务中调用
`NESTED`	等同 `REQUIRED` 新建	同一物理事务内建 savepoint	内层可局部回滚，外层可继续

日常工程里真正高频的是：REQUIRED、REQUIRES_NEW、NESTED。下面展开它们的语义差异。

三、REQUIRED：默认正确，但要懂 UnexpectedRollbackException

1. 语义

PROPAGATION_REQUIRED 会 强制存在物理事务：

当前没有事务 → 为本方法新建；
已有外层事务 → 参与该外层物理事务（同一连接、同一提交点）。

这很适合：一个 Service 编排多个 Repository，要求“要么一起成功，要么一起失败”。

2. 逻辑作用域仍是独立的

即便映射到同一物理事务，Spring 仍会为每个 REQUIRED 方法创建 逻辑事务作用域。每个作用域可以独立设置 rollback-only。

关键后果（官方明确描述）：

内层逻辑事务标记了 rollback-only；
外层自己没有决定回滚，仍尝试 commit；
物理事务最终回滚，外层会收到 UnexpectedRollbackException。

这不是“Spring 抽风”，而是保护调用方 绝不能误以为已经提交成功。

3. 内层 isolation / timeout / readOnly 默认会被忽略

参与外层事务时，内层声明的隔离级别、超时、只读标志 默认静默忽略，以外层特征为准。
若希望“内层要求与外层不一致时直接失败”，可在事务管理器上打开 validateExistingTransaction=true（非宽松模式也会拒绝只读/读写不匹配）。

// 伪配置示意：开启后，内层 isolation/readOnly 与外层冲突会拒绝加入
// PlatformTransactionManager 具体实现上设置 validateExistingTransaction = true

四、REQUIRES_NEW：真正的“独立事务”

1. 语义

PROPAGATION_REQUIRES_NEW 总是开启独立物理事务：

有外层事务 → 挂起外层，内层用新资源事务；
内层 commit/rollback 不影响外层事务的提交结果；
内层结束后，其持有的锁会尽快释放；
内层可使用自己的 isolation / timeout / readOnly。

2. 适合什么

操作日志 / 审计记录：业务主事务回滚，日志仍要留下；
状态机“已到达某检查点”的独立落库；
需要更短锁持有时间、且允许与外层最终结果不一致的写路径。

3. 连接池风险（必须重视）

官方明确警告：外层事务仍绑定着资源时，内层还要再拿 新的数据库连接。若连接池偏小，可能出现：

连接池耗尽；
多线程都在外层事务中等待内层连接 → 死锁式等待。

实践建议：

连接池最大连接数要 大于并发线程数（官方表述：至少比并发线程数多 1，实际应按峰值嵌套深度留余量）；
不要在循环体里高频 REQUIRES_NEW；
先问自己：真的需要“独立提交”，还是只是想“内层失败不要拖死外层”——后者可能 NESTED 更合适。

@Service
public class OrderService {

 private final AuditService auditService;
 private final OrderRepository orderRepository;

 @Transactional // 默认 REQUIRED
 public void placeOrder(OrderCmd cmd) {
 Order order = orderRepository.save(Order.create(cmd));
 // 审计希望独立提交：业务失败也不丢“尝试下单”痕迹
 auditService.recordAttempt(order.getId(), "PLACE_ORDER");
 // ... 后续业务可能抛异常导致外层回滚
 orderRepository.markPaid(order.getId());
 }
}

@Service
public class AuditService {

 @Transactional(propagation = Propagation.REQUIRES_NEW)
 public void recordAttempt(Long orderId, String action) {
 // 独立物理事务：这里的提交不会被外层回滚“带走”
 }
}

五、NESTED：同一物理事务上的 savepoint

1. 语义

PROPAGATION_NESTED：

一个物理事务；
内层通过 savepoint（保存点） 支持局部回滚；
内层回滚到 savepoint 后，外层仍可继续并最终 commit/rollback。

它通常映射到 JDBC savepoint，因此：

依赖 JDBC 资源事务；
与 DataSourceTransactionManager 一类管理器配合最常见；
不是所有事务管理器/资源都支持嵌套语义。

2. 与 REQUIRES_NEW 的选型

维度	`REQUIRES_NEW`	`NESTED`
物理事务	独立两条	仍是一条
内层回滚	不影响外层提交决策	只回滚到 savepoint，外层可继续
内层提交可见性	内层结束即可对外可见（独立提交）	仍受外层最终 commit 约束
连接占用	可能额外占连接	一般不另开连接
资源支持	广泛	依赖 savepoint 支持

口诀：

要“内层 真正提交，外层怎么回滚都保留” → REQUIRES_NEW；
要“内层失败可局部撤销，但最终仍跟外层同生共死” → NESTED。

六、回滚规则：默认只认 RuntimeException / Error

声明式事务的默认策略（官方 @Transactional 默认值）：

传播：REQUIRED
隔离：ISOLATION_DEFAULT（交给底层数据源默认）
读写：可写
超时：底层默认 / 无
回滚触发：RuntimeException 与 Error
默认不回滚：受检异常（checked Exception）

这解释了一个经典坑：业务方法 throws BusinessException extends Exception，调用方 catch 后发现 数据居然提交了。

可显式配置：

@Transactional(rollbackFor = Exception.class)
public void transfer(Long from, Long to, long amount) throws BusinessException {
 // 受检业务异常也会触发回滚
}

@Transactional(noRollbackFor = InventoryNotEnoughException.class)
public void reserveStock(Long skuId, int n) {
 // 某些“预期内”的运行时异常不希望回滚时使用（务必非常克制）
}

也可在 catch 后程序化标记：

try {
 // ...
} catch (NoProductInStockException ex) {
 TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();
}

官方仍建议优先用声明式 rollbackFor / noRollbackFor，少用手写 setRollbackOnly()。

七、代理模型：自调用为什么“注解失效”

默认 proxy 模式（非 AspectJ 编织）下：

只有 通过代理进来的外部调用 才会被拦截；
同类自调用（this.otherTxMethod()）不会走代理 → 内层 @Transactional 不生效；
初始化阶段（如 @PostConstruct）也不应依赖事务代理；
Spring Framework 6.0 起，基于类的代理默认可对 protected / 包可见方法生效；但 基于接口的 JDK 代理 仍要求方法在接口中且为 public。

@Service
public class PayService {

 @Transactional
 public void pay(Long id) {
 // 错误：自调用，markPaid 上的 REQUIRES_NEW 不会生效
 this.markPaid(id);
 }

 @Transactional(propagation = Propagation.REQUIRES_NEW)
 public void markPaid(Long id) {
 // ...
 }
}

常见修法：

把需要独立传播的方法拆到 另一个 Spring Bean，通过注入调用；
注入自身代理（@Lazy 自注入 / AopContext.currentProxy()，后者需暴露代理）；
切换到 AspectJ 模式（成本更高，团队要统一约定）。

八、可复现的排查清单

当“事务行为不符合预期”时，按下面顺序收敛：

是不是自调用？ 打断点看调用栈是否经过 TransactionInterceptor。
异常类型是否触发默认回滚？ checked vs runtime；是否被上层吞掉。
传播是否是你以为的那个？ REQUIRED 加入外层 ≠ REQUIRES_NEW 独立提交。
是否出现 UnexpectedRollbackException？ 说明内层已 rollback-only，外层还在 commit。
连接池是否在 REQUIRES_NEW 下打满？ 看获取连接耗时与 active connections。
只读事务是否被误用于写？ 以及是否开启了 validateExistingTransaction。
多数据源 / 非 DataSourceTransactionManager 场景 下 NESTED 是否根本不被支持。

最小实验建议（单测或本地）：

场景 A：outer REQUIRED → inner REQUIRED 抛 RuntimeException
 期望：整体回滚；外层若吞异常仍可能 UnexpectedRollbackException

场景 B：outer REQUIRED → inner REQUIRES_NEW 成功后 outer 回滚
 期望：inner 已提交数据仍在；outer 变更回滚

场景 C：同类 this.inner() 且 inner 标 REQUIRES_NEW
 期望（proxy 默认）：inner 注解不生效，与 outer 同一逻辑路径

九、工程建议（可直接落到 Code Review）

默认用 REQUIRED，不要到处 REQUIRES_NEW。
REQUIRES_NEW 只用于“必须独立提交”的窄路径，并评估连接池。
需要局部回滚且最终仍同事务提交 → 优先评估 NESTED，并确认 JDBC savepoint 支持。
业务异常若走 checked，统一 rollbackFor = Exception.class 或统一业务异常基类为 runtime。
事务边界放在 应用服务层，Repository 保持细粒度；避免 Controller 直接开事务导致边界失控。
长耗时远程调用不要包在大事务里；必要时 NOT_SUPPORTED 或先缩短事务再调外部。
Code Review 必问：谁提交？谁回滚？失败时用户看到的状态与 DB 是否一致？

十、总结

Spring 事务传播不是注解装饰，而是 逻辑作用域如何映射到物理资源事务 的规则：

REQUIRED：共享物理事务，内层 rollback-only 会拖垮外层提交预期；
REQUIRES_NEW：独立物理事务，能独立提交，但要付连接与一致性代价；
NESTED：同一物理事务上的 savepoint，适合“局部失败、整体仍可继续”的路径；
回滚默认只盯 RuntimeException/Error；
代理模式下 自调用不走事务拦截。

把这五件事吃透，线上大部分“事务没生效 / 该回没回 / 不该提交却提交”的问题都能快速定位。

参考资料

Spring Framework Reference — Transaction Propagation（REQUIRED / REQUIRES_NEW / NESTED 语义与 UnexpectedRollbackException、连接池警告）
Spring Framework Reference — Rolling Back a Declarative Transaction（默认 RuntimeException/Error 回滚、rollbackFor/setRollbackOnly）
Spring Framework Reference — Using @Transactional（默认传播/隔离/回滚规则、proxy 自调用限制、可见性）
Spring Framework Javadoc — TransactionDefinition（七种 PROPAGATION_* 常量定义）

HTTP 条件请求与缓存协商：ETag、Last-Modified 与 Cache-Control 工程实践

Wed, 15 Jul 2026 00:00:00 +0800

很多系统的“慢”并不在业务逻辑，而在重复传输不变的响应体。浏览器、CDN、反向代理都可能持有一份旧副本；真正关键的是：这份副本还能不能直接用？如果不能直接用，能否只问服务器“变了没有”？

HTTP 把这件事拆成两层：

新鲜度（freshness）：缓存还在不在有效期内，决定要不要立刻回源；
验证（validation）：过期或必须再确认时，用条件请求做协商，成功则返回 304 Not Modified，避免再次传输实体。

本文基于 HTTP 语义规范（RFC 9110）与 HTTP 缓存规范（RFC 9111），结合 Nginx 能力，讲清楚 Cache-Control、ETag / Last-Modified、If-None-Match / If-Modified-Since 的协作关系，以及可落地的配置与排错方法。

一、先分清：存下来 ≠ 可以直接用

RFC 9111 把缓存决策大致分成：

阶段	问题	关键概念
存储（store）	响应能不能进缓存	方法、状态码、`no-store`、`private`、`Authorization` 等
新鲜度（fresh）	已存副本是否仍 fresh	`max-age` / `s-maxage` / `Expires` / Age
验证（validate）	stale 后能否复用	条件请求 + 校验器（validator）
复用（reuse）	最终回什么	200 全量、304 无 body、或回源新响应

常见误解：

no-cache 不是“禁止缓存”。它表示：可以用存储副本，但必须先成功验证后才能拿去满足其他请求。
no-store 才是“不要存”。缓存不得存储该请求/响应的任何部分，也不能拿它去满足别的请求。
private 不是“浏览器也不能缓存”。它限制的是共享缓存（CDN、公司代理）：响应面向单个用户；私有缓存（浏览器）仍可在规则允许下存储。

把语义说清楚，后面的工程配置才不会互相打架。

二、新鲜度：Cache-Control 的核心指令

1. 响应侧最常用指令

指令	含义（工程视角）
`max-age=N`	响应在 age > N 秒后视为 stale
`s-maxage=N`	只对共享缓存覆盖 `max-age`/`Expires`；并带有必须再验证后才能复用 stale 的语义
`public`	明确允许缓存（例如带 `Authorization` 的响应在共享缓存中的场景）
`private`	禁止共享缓存存储（或限定字段）
`no-cache`	使用前必须验证
`no-store`	不要存储
`must-revalidate`	一旦 stale，不得在未验证成功前复用；断连时更应报错而不是偷偷给 stale

一个可记的分层：

# 静态资源：可公开、长期缓存（内容指纹化后）
Cache-Control: public, max-age=31536000, immutable

# HTML 入口：可缓存但每次用前确认
Cache-Control: no-cache

# 登录态 API：不要被中间层存
Cache-Control: private, no-store

# 对一致性要求高的共享缓存内容
Cache-Control: public, max-age=60, must-revalidate

2. Age 与“看起来刚生成”

响应里的 Age 表示估计已在缓存中停留的秒数。共享缓存命中时，客户端看到的“年龄”往往不是 0。排查“为什么我设了 max-age=60，却总在提前回源”时，要同时看：

源站给出的 Cache-Control / Expires
中间层是否改写了头
响应是否已有较大 Age

3. 启发式新鲜度：别依赖“没写过期时间也碰巧能缓存”

没有显式过期信息时，部分缓存会用启发式算法估算 fresh 时间。这在不同实现间差异大，生产环境应显式给出 freshness，不要赌默认行为。

三、校验器：ETag 与 Last-Modified

验证阶段依赖表示元数据（representation metadata），最常见两类：

1. `Last-Modified`

源站认为所选表示最后修改的时间（HTTP-date）。例如：

Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT

优点：实现简单，文件系统/对象存储天然具备 mtime。
局限：

秒级精度，一秒内多次变更可能撞车；
时钟回拨、多副本 mtime 不一致会误判；
内容没变但元数据变了时，语义可能不够准。

2. `ETag`（实体标签）

ETag 是源站为某个表示分配的不透明标签：

ETag: "xyzzy"
ETag: W/"xyzzy"

强校验器（strong）：表示数据（以及会影响 200 内容的关键元数据）变化时标签应变化。适合字节级精确比较。
弱校验器（weak，W/ 前缀）：语义等价即可，即使字节不完全相同。生成成本更低，但比较能力更弱。

RFC 9110 明确：在不便存修改时间、一秒精度不够、或修改时间维护不一致时，ETag 通常比 Last-Modified 更可靠。

工程上常见生成策略：

策略	适用	注意
内容哈希（SHA-256 截断）	静态文件、构建产物	强 ETag，成本随体积上升
版本号 / 修订号	业务资源、CMS	发布流程必须保证“内容变则版本变”
inode + size + mtime	传统文件服务器	迁移/复制后可能变，跨机一致性差
弱 ETag（模板渲染摘要）	HTML 片段语义不变	不要拿去当字节级一致性保证

四、条件请求：如何问“变了没有”

1. `If-None-Match`（优先，基于 ETag）

客户端/缓存带上已存表示的 ETag：

GET /app.js HTTP/1.1
Host: example.com
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

源站比较当前 ETag：

匹配（表示未变）→ 304 Not Modified，通常无 body；
不匹配 → 200 OK + 新表示（含新的 ETag）。

对 If-None-Match，规范要求使用弱比较函数：即使只有弱 ETag，也可用于缓存验证。

2. `If-Modified-Since`（基于时间）

GET /style.css HTTP/1.1
If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT

若所选表示的修改时间不比该日期更新，则不必再传实体。

3. 两者同时出现时谁说了算？

RFC 9110 规定：若请求里带了 If-None-Match，接收方必须忽略 If-Modified-Since——因为实体标签被认为是更准确的替代条件。两者同时出现多是兼容历史客户端；服务端实现应按规范优先级处理。

4. `304 Not Modified` 到底省了什么

304 表示：若没有条件约束，这次本应是 200；但条件为假（未修改），客户端应继续使用本地已存表示。

源站仍应带上在同等 200 中会发送的关键头（如 ETag、Date、Content-Location 等），以便缓存刷新元数据（freshen），而不只是“空响应”。

流量层面：

首次：200 + 完整 body（例如 800KB）
之后未变更：304 + 几乎无 body（通常几百字节头）

对静态资源、移动端弱网、跨境回源，收益非常明显。

五、一张图串起完整路径

Client/CDN 本地有副本？
 |
 | 无 -----> 普通 GET -----> 200 + body + Cache-Control + ETag/LM
 |
 | 有且 fresh -----> 直接复用（不回源）
 |
 | 有但 stale / 或 no-cache
 v
 条件请求：If-None-Match / If-Modified-Since
 |
 +--> 未变：304（刷新头，复用旧 body）
 |
 +--> 已变：200（新 body + 新校验器）

记住两句话：

fresh 解决“要不要问”；
validator 解决“问了以后要不要传 body”。

只有 max-age 没有校验器，过期后往往只能全量回源；只有 ETag 没有合理 freshness，会变成“每次都协商”，仍然浪费 RTT。

六、工程实践：按资源类型给策略

1. 带内容哈希的静态资源（最推荐）

构建后文件名含 hash，例如 app.3f2a1c.js：

location /static/ {
 # 文件名已指纹化，可大胆长缓存
 expires 365d;
 add_header Cache-Control "public, max-age=31536000, immutable";
}

要点：

URL 变 = 内容变，可用超长 max-age；
immutable 提示浏览器在 freshness 内不必做启发式再验证（支持情况因客户端而异，但不妨碍给出）；
旧 URL 自然失效，无需纠结主动 purge 每一个文件。

2. HTML / 入口文档

入口常引用带 hash 的静态资源，自身却要尽快看到新版本：

Cache-Control: no-cache
ETag: "html-rev-42"

或短 max-age + 强制再验证：

Cache-Control: max-age=0, must-revalidate
ETag: "html-rev-42"

这样浏览器/边缘仍可存副本，但使用前会走条件请求；HTML 未变则 304，变了才下新文档。

3. 个性化或含凭证的 API

Cache-Control: private, no-store

原因：

private 避免 CDN 把用户 A 的响应给用户 B；
no-store 进一步降低敏感信息落盘风险。

注意：no-store 不是完备隐私方案（恶意或失控缓存可能不遵守），敏感数据仍要靠鉴权、最小化返回字段和传输安全。

4. 可被 CDN 缓存的公共 API / 配置

Cache-Control: public, s-maxage=30, max-age=10
ETag: "cfg-20260715-1"

浏览器短缓存（max-age）；
CDN 稍长（s-maxage）；
过期后用 ETag 协商，降低源站带宽。

Nginx 反代缓存可配合：

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:50m inactive=10m;

location /api/public/ {
 proxy_cache api_cache;
 proxy_cache_valid 200 30s;
 # 过期后用条件请求回源校验
 proxy_cache_revalidate on;
 # 更新期间允许短暂提供 stale，降低源站抖动影响
 proxy_cache_use_stale updating error timeout http_500 http_502 http_503;
 proxy_pass http://upstream;
}

proxy_cache_revalidate on 的作用，正是在缓存过期后启用 If-Modified-Since / If-None-Match 条件回源——这与 RFC 里的 validation 模型一致。

七、服务端如何正确实现条件 GET

以伪代码说明最小正确逻辑：

def handle_get(request, resource):
 etag = resource.strong_etag() # 例如 '"%s"' % sha256(body)[:16]
 last_mod = resource.last_modified_http_date()

 # 1) 优先处理 If-None-Match
 inm = request.headers.get("If-None-Match")
 if inm:
 if etag_matches(inm, etag): # 按弱比较规则实现
 return response_304(etag=etag, last_modified=last_mod)
 return response_200(resource, etag=etag, last_modified=last_mod)

 # 2) 否则再看 If-Modified-Since
 ims = request.headers.get("If-Modified-Since")
 if ims and not resource.modified_after(ims):
 return response_304(etag=etag, last_modified=last_mod)

 return response_200(resource, etag=etag, last_modified=last_mod)

实现清单：

同一表示的 ETag 必须稳定：相同内容不要每次随机；
内容变更必须换 ETag：漏更新会造成“改了却一直 304”；
Vary 要配对：若响应随 Accept-Encoding / Authorization / 自定义头变化，必须正确 Vary，否则缓存会串内容；
压缩前后一致性：对 gzip/br 内容，ETag 策略要与表示选择一致，避免“协商错表示”；
不要手动拼错弱标记：W/ 大小写敏感，格式为 W/"tag"。

八、常见坑与排查清单

坑 1：`no-cache` 和 `no-store` 用反

想“每次确认后再用本地副本” → no-cache（或 max-age=0, must-revalidate）+ ETag；
想“别存敏感响应” → no-store（通常再加 private）。

坑 2：只配了长缓存，没有内容指纹

Cache-Control: max-age=31536000 配在固定 URL 的 app.js 上，发版后用户会长时间用旧脚本。正确做法是 hash 文件名 或主动缩短 freshness 并保证能 purge。

坑 3：ETag 在多实例间不一致

滚动发布时实例 A/B 对同一文件算出不同 ETag（例如混入了进程启动时间），客户端会在 200/304 间抖动，缓存命中率暴跌。校验器生成必须内容决定论。

坑 4：中间层剥掉了校验器或改写了 Cache-Control

排查命令：

# 看源站
curl -sI https://origin.example.com/static/app.js | sed -n '1,20p'

# 看经 CDN/Nginx 后
curl -sI https://www.example.com/static/app.js | sed -n '1,20p'

# 模拟条件请求
ETAG='"abc123"'
curl -sI -H "If-None-Match: $ETAG" https://www.example.com/static/app.js | sed -n '1,15p'

对比：ETag、Cache-Control、Age、CF-Cache-Status/X-Cache 等是否符合预期。第二次应看到 304（在 ETag 仍匹配时）。

坑 5：API 被共享缓存误缓存

带 cookie/authorization 的响应若缺少 private/no-store，再叠加错误的 public，可能把用户数据缓存到边缘。对用户相关响应默认保守，对真正公共的 GET 再显式放开。

坑 6：304 后客户端仍像“没更新样式”

常见是 HTML 长缓存，或 Service Worker / 应用内二次缓存。协议层 304 只保证这一跳 HTTP 缓存协商；还要检查：

HTML 的 Cache-Control；
SW 的 cache.addAll 策略；
应用本地 localStorage 里的资源清单。

九、选型小结

目标	推荐组合
最大化静态资源性能	内容哈希 URL + 长 `max-age` + `public`
入口文档尽快更新	`no-cache` 或短 max-age + ETag + 304
公共只读 API 降源站负载	`s-maxage` + ETag + CDN `proxy_cache_revalidate`
用户私有数据	`private, no-store`，默认不进共享缓存
过期后仍要强一致	`must-revalidate` / `proxy-revalidate` / `s-maxage` 语义

原则：

用 freshness 控制回源频率；
用 validator 控制回源体积；
用 private/no-store 控制安全边界；
用 URL 指纹解决“长缓存与发布”的矛盾。

总结

HTTP 缓存不是“加一个 Redis”或“在 Nginx 里 proxy_cache on”这么简单，它是一套有严格语义的协议机制：

Cache-Control 回答能不能存、能存多久、过期后能不能直接用；
ETag / Last-Modified 回答如何证明表示是否变化；
If-None-Match / If-Modified-Since 与 304 回答如何在确认未变时省略 body。

把这三层设计对齐后，静态站点、前后端分离入口、CDN 边缘缓存和公共 API 都能在带宽、延迟、一致性之间取得可解释的平衡。下次再看到“用户一直是旧页面”或“源站带宽无故升高”，先把响应头和一次条件请求抓出来——答案通常就在 Cache-Control 与校验器的协作里。

参考资料

IETF RFC 9111：HTTP Caching（新鲜度、验证、Cache-Control 指令语义）
IETF RFC 9110：HTTP Semantics（ETag、Last-Modified、If-None-Match、If-Modified-Since、304 Not Modified）
MDN：HTTP caching
MDN：ETag
MDN：If-None-Match
MDN：Cache-Control
Nginx 文档：ngx_http_headers_module（expires / add_header）
Nginx 文档：ngx_http_proxy_module（proxy_cache_revalidate、proxy_cache_use_stale、proxy_cache_valid）

Redis 缓存穿透、击穿与雪崩：原理、场景与工程解法

Mon, 13 Jul 2026 00:00:00 +0800

在高并发系统里，Redis 常常被放在数据库前面做读加速。一旦缓存设计不当，问题往往不是“Redis 慢一点”，而是数据库被瞬间打穿。工程上最常见、也最容易被混为一谈的三类故障是：缓存穿透、缓存击穿和缓存雪崩。

这三类问题听起来相似，根因却不同：

问题	典型特征	直接伤害
缓存穿透	查的是不存在的数据，缓存和 DB 都没有	恶意或异常请求反复打到 DB
缓存击穿	某个热点 key 刚好过期	同一时刻大量请求打到 DB
缓存雪崩	大量 key 同时失效，或缓存层整体不可用	系统级读流量直接压垮 DB

本文从现象、根因、可落地方案三层拆开，并结合 Redis 官方能力（SET 的 NX/EX、EXPIRE、淘汰策略、分布式锁模式）给出可复用实践。

一、先把请求路径画清楚

一个典型读路径是：

Client -> App -> Redis -> (miss) -> Database -> write back Redis -> response

缓存层的价值在于：

把高频读从数据库剥离出来；
用更低延迟响应热点数据；
给数据库争取容量和稳定性。

因此，任何“绕过缓存直接打 DB”的路径，都要被当成故障设计点来处理。

二、缓存穿透：查不存在的数据

1. 现象

请求的 key 在业务上不存在，例如：

用户 ID -1
商品 ID 999999999
被爬虫扫出来的非法参数

此时 Redis 没有缓存，数据库也查不到记录。如果应用只在“查到结果时才写缓存”，那么每次请求都会落到数据库。

2. 根因

穿透的本质不是“缓存过期”，而是：

空结果没有被负缓存（negative caching）保护。

3. 解法

方案 A：缓存空对象（最常用）

查库为空时，也写入一个短 TTL 的空值标记：

# 伪命令：空结果缓存 60 秒
SET product:999999999 __NULL__ EX 60

应用读到 __NULL__ 时直接返回“不存在”，不再访问数据库。

注意：

TTL 不要太长，避免真实数据刚创建后长时间读不到；
空值要有统一约定，避免和正常业务值冲突；
对写路径做缓存失效/更新，保证最终一致。

方案 B：布隆过滤器（Bloom Filter）前置拦截

对“可能存在”的 ID 集合做布隆过滤器：

数据写入时同步/异步加入过滤器；
查询前先判断“一定不存在还是可能存在”；
一定不存在则直接拒绝，不打 Redis/DB。

适合海量 ID、爬虫扫描、开放查询接口。代价是：

有极低误判率（把不存在判断成可能存在）；
需要维护过滤器更新与扩容。

方案 C：参数与权限校验前置

很多穿透其实是脏流量：

非数字 ID
超范围分页
未登录却访问私有资源

在网关/应用入口直接拦截，比把压力交给缓存更划算。

三、缓存击穿：热点 key 刚好失效

1. 现象

某个非常热的 key（首页配置、秒杀库存视图、热门商品详情）在某一瞬间过期。
下一毫秒，成千上万请求同时看到 miss，一起去查数据库，形成“单点热点打穿”。

2. 根因

击穿关注的是：

单个热点 key 过期窗口内的并发回源。

它和穿透不同：数据本来存在，只是缓存刚好空了。

3. 解法

方案 A：互斥重建（singleflight / 分布式锁）

只有一个请求负责回源重建，其他请求等待或短暂失败重试。

Redis 官方 SET 支持原子条件写入，可用 NX + EX 做互斥：

# 抢重建锁，5 秒自动过期，防止进程崩溃后死锁
SET rebuild:lock:product:1001 1 NX EX 5

流程：

读缓存 miss；
SET lock NX EX 抢锁；
抢到锁的请求查 DB，写回缓存，释放锁；
没抢到锁的请求短暂 sleep/重试读缓存，或返回旧兜底。

官方文档明确：SET key value NX EX seconds 是设置值并带过期时间的常用原子写法；SETNX 在新代码中更推荐用 SET ... NX 替代。

方案 B：逻辑过期（logical expire）

缓存 value 内嵌业务过期时间，物理 key 不过期或过期很久：

{
 "data": {"id": 1001, "price": 99},
 "expireAt": 1720857600
}

读取时：

未逻辑过期：直接返回；
已逻辑过期：返回旧数据，同时异步触发重建。

优点是用户几乎无感 miss；代价是要接受短暂脏读，并做好异步重建失败补偿。

方案 C：热点 key 永不过期 + 主动更新

对真正的超级热点，不依赖 TTL 被动失效，而由写路径/定时任务主动更新。
TTL 更适合普通数据；热点数据更适合“写时更新 + 监控”。

四、缓存雪崩：大面积失效或缓存层故障

1. 现象

两类雪崩最常见：

过期雪崩：大量 key 在同一时间点过期；
可用性雪崩：Redis 集群故障、网络分区、连接打满，导致缓存层整体不可用。

结果都是数据库在短时间内接到远超容量的读请求。

2. 根因

雪崩的核心不是某一个 key，而是：

缓存保护面在同一时间失效，流量失去缓冲层。

3. 解法

方案 A：TTL 加随机抖动

不要让同类数据使用完全相同的过期时间：

ttl = base_ttl + random(0, jitter)
# 例如 3600 + random(0, 300)

这样可以把过期曲线打散，避免整点集体回源。

方案 B：多级缓存与本地缓存

本地 Caffeine/Guava Cache 挡住进程内重复读；
Redis 作为分布式缓存；
DB 作为最终数据源。

本地缓存 TTL 更短，可显著降低 Redis 抖动对 DB 的传导。

方案 C：限流、熔断、降级

缓存层异常时，应用不能无脑回源：

对回源 QPS 做令牌桶/漏桶限流；
数据库错误率升高时熔断；
非核心接口返回兜底页/默认配置；
核心读接口优先返回短暂旧数据。

方案 D：正确使用 Redis 内存淘汰策略

当 Redis 用作缓存时，官方建议配置最大内存和淘汰策略，以便内存触顶时按策略驱逐 key，而不是写失败或无规划崩溃。常见策略包括：

allkeys-lru / allkeys-lfu：在全部 key 中淘汰；
volatile-lru / volatile-lfu / volatile-ttl：只在设置了过期时间的 key 中淘汰。

关键点：

缓存场景应显式设置 maxmemory；
按业务选择 LRU/LFU；
监控 evicted_keys、命中率、内存使用，避免“默默淘汰关键数据”却无人知晓。

淘汰策略解决的是内存压力下的可持续性，不能替代业务层的穿透/击穿防护，但能降低缓存层自身失控概率。

五、一套可落地的组合策略

真实系统很少只选一种方案，更常见的是分层组合：

1. 入口校验：挡住非法参数
2. 布隆过滤器/存在性索引：挡住明显不存在的 key
3. Redis 读：命中则返回
4. miss 时：
 - 热点 key：互斥重建或逻辑过期
 - 普通 key：允许有限并发回源
5. DB 空结果：写短 TTL 空缓存
6. DB 有结果：写缓存，TTL 加抖动
7. 全链路：限流 + 熔断 + 监控告警

伪代码示例

def get_product(product_id: str):
 if not valid_id(product_id):
 return None

 if bloom and not bloom.might_contain(product_id):
 return None

 cached = redis.get(f"product:{product_id}")
 if cached == "__NULL__":
 return None
 if cached is not None:
 return decode(cached)

 # 热点互斥重建
 locked = redis.set(f"rebuild:lock:product:{product_id}", "1", nx=True, ex=5)
 if not locked:
 time.sleep(0.05)
 return get_product(product_id) # 简化：重试读缓存

 try:
 row = db.query_product(product_id)
 if row is None:
 redis.set(f"product:{product_id}", "__NULL__", ex=60)
 return None
 redis.set(f"product:{product_id}", encode(row), ex=3600 + random.randint(0, 300))
 return row
 finally:
 redis.delete(f"rebuild:lock:product:{product_id}")

说明：

SET ... NX EX 用于短锁，避免击穿时并发回源；
空值缓存用于防穿透；
TTL 抖动用于打散过期，降低雪崩概率。

六、排查清单：线上怎么快速判断是哪一种

1. 先看指标

Redis 命中率是否骤降
Redis 连接数/超时是否升高
数据库 QPS、慢查询、连接池是否打满
是否集中在某几个 key，还是大面积 key

2. 判断路径

观察	更可能是
大量非法/不存在 ID，DB 查空很多	穿透
单个热 key 流量尖峰，过期瞬间 DB 飙升	击穿
整点或批次任务后大面积 miss	过期雪崩
Redis 超时/主从切换/集群异常同时发生	可用性雪崩

3. 临时止血

对异常查询参数限流；
对热点 key 预热并临时延长 TTL；
打开空值缓存；
给 DB 回源加总开关/配额；
非核心读降级。

七、设计原则总结

缓存不是数据库的影子，是保护层。 任何 miss 路径都要有预算。
空结果也是结果。 不做负缓存，就容易被穿透。
热点不能靠“碰巧没过期”。 要有互斥重建、逻辑过期或主动更新。
过期时间要工程化。 相同 TTL 是雪崩温床，抖动是基本操作。
缓存故障要有降级。 没有限流和熔断的缓存架构，只是把风险延后到数据库。
可观测性比“感觉很快”更重要。 命中率、回源 QPS、淘汰数、锁竞争都要可监控。

八、什么时候不该过度设计

不是所有系统都要上布隆过滤器 + 逻辑过期 + 多级缓存：

读 QPS 不高、数据几乎都存在：做好空值缓存和基础 TTL 即可；
写极少、读极多的配置类数据：适合主动更新 + 较长 TTL；
强一致要求极高的余额/库存：缓存只能做辅助，核心以数据库/专用组件为准，并明确一致性模型。

架构选择应匹配流量模型和一致性要求，而不是堆名词。

总结

缓存穿透、击穿、雪崩并不是三个神秘黑话，而是三条清晰的失败路径：

穿透：不存在的数据反复打穿 DB；
击穿：热点 key 失效瞬间被并发打穿；
雪崩：保护面大面积失效，流量失去缓冲。

把问题定义清楚后，解法会自然收敛到：入口校验、空值缓存、互斥重建、TTL 抖动、淘汰策略、限流熔断与监控。
Redis 提供了 SET NX/EX、EXPIRE、内存淘汰和分布式锁模式等基础能力，但真正决定系统稳不稳的，是你有没有把这些能力嵌进完整的读路径设计里。

参考资料

Redis 官方文档：SET 命令（含 NX / EX 等选项）
Redis 官方文档：EXPIRE 命令
Redis 官方文档：SETNX 命令
Redis 官方文档：Key eviction 内存淘汰策略
Redis 官方文档：Distributed locks 分布式锁模式

后端 on 吾爱主机

Redis 分布式锁：互斥、安全释放与续期工程实践

一、问题背景：分布式互斥要什么

二、核心机制：单实例正确加解锁

2.1 原子加锁：SET key token NX PX ttl

2.2 为什么 value 必须是随机 token

2.3 安全解锁：条件删除，而不是裸 DEL

2.4 锁有效期（lock validity time）的双重含义

三、主从复制为什么不够“天然安全”

四、Redlock 概要：多数派 + 耗时校验

4.1 续期（lock extension）

4.2 时钟与一致性免责声明（官方 disclaimer）

五、工程增强：Fencing Token 与临界区设计

六、可复现实验（单实例）

6.1 互斥：第二个客户端抢不到

6.2 安全解锁 vs 危险 DEL

6.3 续期：仅持有者可延长

6.4 伪代码骨架（语言无关）

七、常见坑与排查清单

八、选型建议（务实版）

九、总结

参考资料

Go channel 与 select：阻塞语义、关闭规则与工程实践

一、问题背景：共享内存锁 vs 通道通信

二、核心模型：无缓冲握手与有缓冲队列

1. 创建与零值

2. 发送 / 接收何时可推进

3. 关闭、ok 与 range

三、select：多路就绪与非确定性选择

工程模式

四、可复现实验：阻塞、关闭与 select

五、管道：关闭传播与 done 取消

六、常见坑与排查清单

七、总结

参考资料

AgentScope Java 2.0 实战：构建带权限审批与可恢复执行的生产级 Agent

一、ReActAgent 与 HarnessAgent 的分工

二、依赖和模型配置

三、权限系统如何做决策

四、配置 ALLOW、ASK 与 DENY 规则

五、自定义不可绕过的工具检查

六、ASK 后怎样暂停与恢复

七、流式事件让执行过程可观察

八、Workspace、Sandbox 和权限各管一层

九、可恢复执行的正确边界

十、生产部署清单

十一、常见问题

Agent 一直要求确认

定时任务卡在 ASK

工作区恢复后找不到文件

已有 Sandbox，为什么还要权限系统

总结

参考资料

Google ADK Java 实战：用 Code-first 方式编排多 Agent 工作流

一、ADK 的 Code-first 是什么

二、依赖、凭据与版本状态

三、先实现一个可验证的 FunctionTool

四、定义三个专业 LlmAgent

1. Researcher

2. Reviewer

3. Writer

五、用 SequentialAgent 显式编排

六、启动 Dev UI

七、Session、State 与 Artifact

八、确定性 Workflow 与 LLM 路由怎样选择

九、A2A 与 MCP 的分工

十、Preview 阶段怎样控制风险

十一、常见问题

后续 Agent 读不到前一步输出

模型不调用 FunctionTool

ParallelAgent 结果互相覆盖

LoopAgent 不停运行

本地成功，上云后丢 Session

十二、生产清单

总结

参考资料

LangChain4j 实战：用 AI Services 与 Tool Calling 构建可控 Java Agent

一、Agent 的最小闭环

二、依赖和模型

三、用 Java 接口定义 AI Service

2.1 原子加锁：`SET key token NX PX ttl`

2.3 安全解锁：条件删除，而不是裸 `DEL`

6.2 安全解锁 vs 危险 `DEL`

3. `process.nextTick` 不在相位图里

4. `setImmediate` vs `setTimeout(0)`

3. 结构化并发：优先 `TaskGroup`（3.11+）

2. 超时：`wait_for` 与 `timeout` 上下文

3. `shield`：挡外层取消，不挡内层自杀