AI Agent / 系统课时

让重复执行的副作用保持幂等

让重复执行的副作用保持幂等

可恢复工作流会重放节点或重试任务,因此“代码又跑了一次”必须与“业务副作用又发生一次”区分开。本节用稳定操作 ID 和数据库唯一约束,把重复写入折叠为同一次业务操作,并说明发消息等外部副作用如何套用同一原则。

学习目标

  • 理解中断恢复与失败重试为什么会让副作用代码再次进入
  • 能为一次业务操作设计稳定的幂等键
  • 能用唯一约束、Upsert 或外部服务的 idempotency key 阻止重复副作用

幂等边界不是“不要重试”

LangGraph 的恢复能力依赖重新进入未完成的执行路径。含有 interrupt() 的节点在恢复时会从节点开头重新执行;任务如果已经开始却没有成功完成,也可能再次运行。问题不在于重试本身,而在于副作用是否能识别“这是同一次业务操作”。([Docs by LangChain][3])

稳定幂等键应来自业务输入,例如订单号加动作类型、消息任务 ID 或预先生成并持久化的操作 ID。不要在每次节点执行时重新调用随机 UUID 或当前时间生成键,否则重放会得到新键,去重机制形同虚设。

中断恢复下的幂等副作用

用唯一操作 ID 折叠重复写入

下面故意把一次数据库写入放在 interrupt() 之前,以演示恢复时节点确实会再次进入。表上的主键与 ON CONFLICT DO NOTHING 保证同一个 operation_id 只能产生一条记录。

python
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())

预期输出

text
[('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])

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

让重复执行的副作用保持幂等

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通