陷阱一：用 try/catch 偷偷吃掉中断信号

问题本质

这是最隐蔽也最常见的错误。很多人不知道：Interrupt 根本不是普通的函数返回，它本质上是通过抛出一个专门的异常来实现暂停的。

LangGraph 引擎就是靠捕获这个异常，来中止节点执行、保存状态并等待外部输入。如果你在代码里用 try/catch 把这个异常兜住了，就等于把引擎本该收到的暂停信号“截胡”了。

结果就是：

图不会暂停
人类输入界面永远不会出现
程序自顾自往下跑
你对着代码看三个小时，也想不通为什么 interrupt() 不工作

正确做法

最佳实践：永远把 interrupt 放在 try/catch 块外面

async function approvalNode(state: State) {
  // ✅ interrupt 直接执行，不被任何 catch 包裹
  const approved = interrupt("是否通过本次申请？");

  // 后面的业务逻辑可以正常用 try/catch
  try {
    await updateDatabase(state);
  } catch (err) {
    console.error("数据库更新失败", err);
  }

  return { approved };
}

如果确实需要在同一个 try 块里处理业务异常，一定要把未知异常原样抛回去：

async function approvalNode(state: State) {
  try {
    const approved = interrupt("是否通过本次申请？");
    await updateDatabase(state);
  } catch (err) {
    // 只处理你明确知道的错误类型
    if (err instanceof DatabaseError) {
      console.error("数据库错误", err);
    }
    // ✅ 必须重新抛出所有其他异常，包括 interrupt 异常
    throw err;
  }

  return { approved };
}

绝对不要这么写

async function approvalNode(state: State) {
  try {
    const approved = interrupt("是否通过本次申请？");
  } catch (err) {
    // ❌ 全量捕获，吃掉了中断信号
    console.error(err);
  }
  return state;
}

陷阱二：动态改变 interrupt 的调用顺序和数量

问题本质

当一个节点里有多个 interrupt 时，LangGraph 会在内部维护一个按顺序存储的回答列表。每次恢复执行时，节点会从头重新运行，然后按 interrupt 出现的顺序，依次从列表里取对应的值。

也就是说：第一个 interrupt 永远取第一个回答，第二个永远取第二个，完全基于索引匹配，和问题内容无关。

如果你的代码逻辑让 interrupt 的执行顺序或数量发生了变化，那么回答和问题的对应关系就会彻底错位，产生极其魔幻的运行结果。

正确做法

保证同一个节点内，interrupt 的执行顺序和数量永远固定不变

async function userInfoNode(state: State) {
  // ✅ 无论执行多少次，顺序和数量都完全一致
  const name = interrupt("请输入姓名？");
  const age = interrupt("请输入年龄？");
  const city = interrupt("请输入城市？");

  return { name, age, city };
}

绝对不要这么写

错误1：在条件分支中使用 interrupt

async function userInfoNode(state: State) {
  const name = interrupt("请输入姓名？");

  // ❌ 条件分支会导致 interrupt 数量动态变化
  if (state.needsAge) {
    const age = interrupt("请输入年龄？");
  }

  const city = interrupt("请输入城市？");
}

第一次执行不需要问年龄，第二次又需要，那么系统会把城市的回答当成年龄的回答，彻底错位。

错误2：在循环中使用动态长度的 interrupt

async function batchApprovalNode(state: State) {
  const results = [];

  // ❌ 动态列表会导致 interrupt 数量和顺序都可能变化
  for (const item of state.itemsToApprove) {
    const approved = interrupt(`是否批准 ${item}？`);
    results.push({ item, approved });
  }

  return { results };
}

只要上游节点修改了 state.itemsToApprove 的长度或顺序，所有后续的回答都会对应到错误的问题上，而且完全不会报错，调试难度极大。

陷阱三：在 interrupt 中传递复杂值

问题本质

当你调用 interrupt 时，LangGraph 会把当前的所有状态和中断信息序列化后保存到 Checkpoint（内存、文件、Redis 等）。未来恢复执行时，再反序列化重建上下文。

这个序列化过程，绝大多数实现都是基于 JSON 的。这意味着：

字符串、数字、布尔值、普通对象和数组可以安全传递
函数、类实例、数据库连接、流对象等无法被正确序列化

如果你强行传递这些复杂值，它们要么在序列化时丢失信息，要么直接抛出异常，而且不同的 Checkpoint 实现行为还不一样，导致代码在本地能跑，一部署就挂。

正确做法

只传递可 JSON 序列化的简单值或结构化配置

async function formNode(state: State) {
  // ✅ 传递结构化的表单配置，完全可序列化
  const userInput = interrupt({
    question: "请填写用户信息",
    fields: ["name", "email", "phone"],
    required: ["name", "email"],
    initialValues: state.user || {}
  });

  return { user: userInput };
}

如果需要用到复杂对象，只传递配置，恢复执行后再重新创建实例：

async function processNode(state: State) {
  // ✅ 只传递配置，不传递实例本身
  const config = interrupt({
    question: "请输入处理参数",
    processorConfig: { mode: "strict", timeout: 3000 }
  });

  // 恢复执行后，再重新创建处理器实例
  const processor = new DataProcessor(config.processorConfig);
  const result = processor.process(state.data);

  return { result };
}

绝对不要这么写

function validateEmail(value: string) {
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
}

async function formNode(state: State) {
  const userInput = interrupt({
    question: "请输入邮箱",
    // ❌ 函数无法被序列化
    validator: validateEmail,
    // ❌ 类实例无法被正确序列化
    processor: new DataProcessor()
  });

  return { userInput };
}

陷阱四：interrupt 前的副作用不具备幂等性

问题本质

这是最容易被忽略的一个陷阱。很多人以为：中断后恢复执行，会从 interrupt 那一行继续往下跑。

但实际上：每次恢复执行时，节点函数都会从头开始重新运行一遍。

也就是说，在第一个 interrupt 之前的所有代码，会因为中断和恢复，被执行 N 次。如果你在这段区域做了“插入数据库、发送邮件、记录日志”之类的非幂等操作，就会产生大量重复的副作用。

什么是幂等性？ 一个操作无论执行多少次，最终效果都和执行一次完全相同。 ✅ 幂等操作：UPDATE users SET status = 'pending' WHERE id = 1 ❌ 非幂等操作：INSERT INTO logs (message) VALUES ('请求审批')

正确做法

方案1：interrupt 前只做幂等操作

async function approvalNode(state: State) {
  // ✅ 使用 upsert 而不是 insert，保证幂等
  await db.users.upsert({
    where: { id: state.userId },
    update: { status: "pending_approval" },
    create: { id: state.userId, status: "pending_approval" }
  });

  const approved = interrupt("是否通过审批？");
  return { approved };
}

方案2：把所有副作用放到 interrupt 之后

这是最稳妥、最推荐的写法：

async function approvalNode(state: State) {
  const approved = interrupt("是否通过审批？");

  // ✅ 副作用放在 interrupt 之后，只会执行一次
  if (approved) {
    await db.logs.create({
      userId: state.userId,
      action: "approved",
      timestamp: new Date()
    });
    await sendApprovalEmail(state.userId);
  }

  return { approved };
}

方案3：把中断和副作用拆成两个独立节点

// 只负责中断和获取用户输入
async function getApprovalNode(state: State) {
  const approved = interrupt("是否通过审批？");
  return { approved };
}

// 只负责处理副作用
async function postApprovalNode(state: State) {
  if (state.approved) {
    await sendApprovalEmail(state.userId);
    await db.logs.create({ action: "approved" });
  }
  return state;
}

绝对不要这么写

async function approvalNode(state: State) {
  // ❌ 每次恢复都会插入一条新的日志
  await db.logs.create({
    userId: state.userId,
    action: "requested_approval"
  });

  const approved = interrupt("是否通过审批？");
  return { approved };
}

这个节点每中断恢复一次，数据库里就会多一条重复的日志，最后你会看到同一个用户请求了10次审批的魔幻结果。

总结：Interrupt 最佳实践速记

不吞异常：永远不要用 try/catch 全量包裹 interrupt，捕获业务异常后必须重新抛出
顺序固定：同一个节点内，interrupt 的执行顺序和数量必须永远不变
值要简单：只传递可 JSON 序列化的简单值或配置，不要传函数和类实例
副作用后移：所有非幂等操作，尽量放到 interrupt 之后或拆成独立节点

LangGraph Interrupt 中断陷阱