幂等且感知副作用的工具
让重复调用安全且可预测。
幂等且感知副作用的工具 是 CoddyKit 上的免费 MCP Academy 课时。 这是第 3 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 MCP Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 MCP Academy 课程共包含 4 节课。
模型可能会调用两次
AI 客户端可能在超时或连接中断后重试工具。对于用户原本只想执行一次的操作，您的工具可能会运行两次。
幂等性的含义
如果使用相同输入再次调用工具不会产生任何进一步变化，那么该工具就是幂等的。第二次调用可以安全地不执行任何操作。
读取操作天然安全
纯粹的读取工具，例如获取记录，本身已经具备幂等性。重复调用只会返回相同答案，不会造成损害。
@mcp.tool()
def get_user(id: int) -> dict:
return db.find(id)写入操作需要谨慎
会创建内容或收取费用的工具，重复执行可能很危险。盲目重试可能新增重复记录，或导致重复扣款。
使用客户端提供的键
要求调用方提供一个幂等性键。如果您已经处理过该键，就返回已存储的结果，而不是再次执行操作。
if key in seen:
return seen[key]
seen[key] = do_work()优先使用插入或更新
插入或更新会根据稳定 ID 写入或更新数据，因此运行两次只会留下一条记录，而不是两条。它会将重试合并为一个状态。
INSERT ... ON CONFLICT (id)
DO UPDATE SET ...明确声明副作用
在工具描述中说明它是否会修改数据。模型知道调用具有破坏性后，就能做出更明智的决定。
分离读取工具和写入工具
将查询工具和变更工具保持区分，而不是让一个工具有时执行写入。清晰的边界可以减少意外修改。
让结果具有确定性
在可能的情况下，对于相同输入返回相同的输出。可预测的结果有助于客户端缓存，并理解您的工具行为。
执行前先检查
执行写入前，确认目标当前的状态。如果变更已经应用，就直接报告成功，不要再次执行。
if order.status == "shipped":
return "already shipped"将多步工作放入事务
如果工具会操作多条记录，请在一个事务中执行。这样重试时要么全部应用，要么全部回滚，绝不会只完成一部分。
快速检查
对于会创建记录的 MCP 工具，幂等性为什么重要？
回顾：安全地重复执行
使用键或插入更新操作让写入保持幂等，声明副作用，分离读取与写入，并使用事务。下一节：版本控制。♻️
常见问题解答
「幂等且感知副作用的工具」课时是免费的吗？
是的 — 「幂等且感知副作用的工具」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 MCP Academy 课程的其余内容，请升级到 CoddyKit PRO。 MCP Academy 课程共包含 4 节课。
「幂等且感知副作用的工具」这节课中我会学到什么？
让重复调用安全且可预测。 你通过在浏览器中直接运行的动手代码来练习 MCP Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 MCP Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 MCP Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 3 节课，共 4 节。
「幂等且感知副作用的工具」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 MCP Academy 课中编写并运行代码吗？
能。每节 MCP Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。
此课程中的所有课时
- 分层服务器架构
- 通过环境配置设置与机密信息
- 幂等且感知副作用的工具
- 工具与模式的版本管理