AI Agent / 系统课时
让重复执行的副作用保持幂等
让重复执行的副作用保持幂等
可恢复工作流会重放节点或重试任务,因此“代码又跑了一次”必须与“业务副作用又发生一次”区分开。本节用稳定操作 ID 和数据库唯一约束,把重复写入折叠为同一次业务操作,并说明发消息等外部副作用如何套用同一原则。
学习目标
- 理解中断恢复与失败重试为什么会让副作用代码再次进入
- 能为一次业务操作设计稳定的幂等键
- 能用唯一约束、Upsert 或外部服务的 idempotency key 阻止重复副作用
幂等边界不是“不要重试”
LangGraph 的恢复能力依赖重新进入未完成的执行路径。含有 interrupt() 的节点在恢复时会从节点开头重新执行;任务如果已经开始却没有成功完成,也可能再次运行。问题不在于重试本身,而在于副作用是否能识别“这是同一次业务操作”。([Docs by LangChain][3])
稳定幂等键应来自业务输入,例如订单号加动作类型、消息任务 ID 或预先生成并持久化的操作 ID。不要在每次节点执行时重新调用随机 UUID 或当前时间生成键,否则重放会得到新键,去重机制形同虚设。

用唯一操作 ID 折叠重复写入
下面故意把一次数据库写入放在 interrupt() 之前,以演示恢复时节点确实会再次进入。表上的主键与 ON CONFLICT DO NOTHING 保证同一个 operation_id 只能产生一条记录。
import sqlite3
from typing import TypedDict
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph import END, START, StateGraph
from langgraph.types import Command, interrupt
class State(TypedDict, total=False):
operation_id: str
text: str
status: str
db = sqlite3.connect(":memory:")
db.execute(
'''
CREATE TABLE outbox (
operation_id TEXT PRIMARY KEY,
text TEXT NOT NULL,
status TEXT NOT NULL
)
'''
)
def prepare_message(state: State) -> State:
# 恢复后这一段会再次运行,但相同操作 ID 不会插入第二行。
db.execute(
'''
INSERT INTO outbox(operation_id, text, status)
VALUES (?, ?, 'pending')
ON CONFLICT(operation_id) DO NOTHING
''',
(state["operation_id"], state["text"]),
)
db.commit()
decision = interrupt({
"action": "send_message",
"operation_id": state["operation_id"],
})
if decision != "approve":
return {"status": "rejected"}
db.execute(
"UPDATE outbox SET status = 'ready' WHERE operation_id = ?",
(state["operation_id"],),
)
db.commit()
return {"status": "ready"}
builder = StateGraph(State)
builder.add_node("prepare_message", prepare_message)
builder.add_edge(START, "prepare_message")
builder.add_edge("prepare_message", END)
graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "idem-demo"}}
graph.invoke(
{"operation_id": "msg-42", "text": "Build passed"},
config=config,
)
print(db.execute(
"SELECT operation_id, status FROM outbox"
).fetchall())
graph.invoke(Command(resume="approve"), config=config)
print(db.execute(
"SELECT operation_id, status FROM outbox"
).fetchall())预期输出
[('msg-42', 'pending')]
[('msg-42', 'ready')]恢复时 prepare_message 会从头执行,第二次 INSERT 仍使用 msg-42,因此数据库不会新增重复记录。这里的 outbox 也把“准备发送”和“真正调用消息服务”拆开,便于独立重试与审计。
把同一原则扩展到外部副作用
数据库写入优先使用唯一约束配合 Upsert,而不是先查询“有没有”再插入;后者在并发下仍可能竞态。调用支付、邮件或消息 API 时,如果服务支持幂等键,就把稳定的 operation_id 作为 idempotency key 传给对方。
如果外部服务不支持幂等键,可以采用事务 Outbox:业务事务只写一条带唯一操作 ID 的待发送记录,独立 worker 负责投递,并记录发送状态。这样 LangGraph 的恢复负责“继续做”,数据库或外部服务负责“同一次操作只生效一次”。
在 LangGraph 中,还应尽量把 API 调用、文件写入、发消息等副作用封装为独立 task 或独立节点,让结果能够被检查点记录;即使如此,副作用本身仍应设计为幂等,因为任务在“已开始但未成功完成”的边界上仍可能重试。([Docs by LangChain][3])