接口超时后的写入一致性：用幂等键避免重复创建

接口超时后的写入一致性：用幂等键避免重复创建

在待办清单、工单或订单应用中，用户点击一次提交后遇到超时，最难判断的往往是：服务端到底有没有保存成功？请求可能尚未到达，也可能已经提交数据库，只是响应没有回到客户端。下面用“创建任务”这个普通场景讨论一种设计方法。本文是方案分析，不代表已在真实云环境完成部署或压测。

一、把超时视为结果未知

客户端等不到响应，只能证明等待结束，不能证明服务器没有执行。此时直接换一个新标识重试，可能产生两条业务记录。界面可以提示“结果待确认”，保留本次操作标识，并允许查询状态或按同一标识重试。用户需要看见明确状态，避免连续点击造成新的逻辑请求。

二、让幂等键代表一次业务意图

可以由客户端在首次提交前生成随机请求标识，后续重试继续携带相同值。不同任务必须使用不同标识，同一任务的修改则应另建操作标识。服务端应把幂等键与已认证用户、操作类型和请求内容摘要共同关联。只接受客户端传来的键而不绑定归属，可能导致不同用户之间互相影响；同一键对应不同内容时，应返回清楚的冲突结果。

三、依靠数据库约束处理并发

“先查是否存在，再插入”在并发请求下仍可能同时通过检查。应当用唯一约束承担最后一道防线，例如把用户标识、操作类型与幂等键组成唯一键，并在同一事务里写入业务记录和处理结果。重复请求命中约束后读取既有结果，而不是再创建一条任务。不要简单地把所有重复键都变成覆盖更新，否则一次重试可能意外改写已经完成的业务状态。

四、区分处理中、成功和可重试失败

幂等记录至少需要表达处理状态。请求已经成功时，返回首次成功的业务标识和可重建的响应；仍在处理中时，让客户端稍后查询；校验失败时，说明错误原因。若进程在业务提交后、结果记录前崩溃，需要通过事务边界、持久化任务或补偿查询避免永久卡在处理中。设计时应先说明哪些数据能原子提交，哪些外部副作用需要单独处理。

五、同步游标也要考虑删除和同一时刻更新

增量同步不能只返回仍然存在的记录，否则另一台设备永远不知道某条任务已删除。可以返回删除标记，并明确保留期限。仅用更新时间作为游标时，还要处理相同时间戳的多条记录与分页边界；一种方法是使用“更新时间加稳定记录标识”的复合游标，另一种方法是使用服务端生成的递增变更序号。具体选择取决于数据库、写入规模和一致性要求。

六、验证时覆盖失败发生的位置

有意义的检查包括：数据库提交前断开连接、提交后丢失响应、同一键并发提交、同一键不同内容、同一键不同用户，以及幂等记录过期后的再次提交。检查结果应同时记录接口响应和数据库中的业务记录数量。若还包含邮件、通知或第三方调用，也要观察它们是否重复触发；数据库里只有一条记录，并不能保证外部副作用只发生一次。

幂等机制需要明确作用范围和保留时间。对一条“创建任务”请求来说，目标是让同一次业务意图的重试得到一致结果，同时让不同意图仍能独立执行。把这个约定写进接口文档，客户端、服务端和测试人员才有共同的判断依据。