Java接口幂等性设计：全局ID防重与数据库索引兜底

本文深入剖析了Java接口幂等性设计的核心实践，强调真正可靠的幂等保障不能依赖前端生成的易碰撞ID或简单的时间戳拼接，而应采用服务端可控的全局唯一ID（如去横线UUID或正确配置的Snowflake），并将校验逻辑严格前置到Service层入口；同时指出唯一索引只是关键兜底手段，需优先选用ON DUPLICATE KEY UPDATE而非INSERT IGNORE以确保行为可感知，并通过独立幂等表、状态机（pending/success/failed）与带分布式锁的安全清理机制，实现高并发、重试密集及分布式事务场景下的强一致性防护——幂等不是加个ID和索引就万事大吉，而是校验时机、状态流转与清理边界三者严丝合缝的工程闭环。

接口重复提交时，idempotentId 字段怎么生成才可靠

靠前端时间戳或随机数生成的 idempotentId 极易碰撞，尤其在高并发或重试密集场景下。真正能用的必须全局唯一、服务端可控、且不依赖外部系统（比如 Redis 临时不可用就崩）。

• 推荐用 UUID.randomUUID().toString().replace("-", "") —— 简单、无依赖、碰撞概率可忽略，但注意别直接存原始 UUID（带短横线），数据库索引效率略低
• 如果对长度和可读性有要求，可用 SnowflakeIdGenerator.nextId()（如 Twitter Snowflake 或百度 UidGenerator），但得确保机器 ID / 工作节点配置正确，否则会重复
• 千万别用 System.currentTimeMillis() + 计数器拼接 —— 多线程下计数器不同步，同一毫秒内多个请求拿到相同 ID

校验逻辑放在 Controller 还是 Service 层更合适

必须放在 Service 层入口，Controller 层只做参数解析和基础校验。原因很实际：Controller 可能被绕过（比如直调 FeignClient、内部 RPC），而幂等校验一旦漏掉，数据库就可能写入重复数据。

• Controller 层只提取并透传 idempotentId，不做任何存储或比对
• Service 方法开头立即查库：select count(1) from idempotent_record where idempotent_id = ? and status = 'success'，命中则直接 return
• 查不到再继续执行业务逻辑，成功后必须原子化插入记录：insert into idempotent_record (idempotent_id, status, created_at) values (?, 'success', now())，不能先 insert 再执行业务 —— 中间失败会导致脏数据

INSERT IGNORE 和 ON DUPLICATE KEY UPDATE 在唯一索引兜底时的区别

两者都能防重复插入，但行为差异直接影响幂等结果的可靠性。唯一索引只是兜底，不是主校验手段，但兜底失效就会出事。

• 用 INSERT IGNORE：遇到重复键直接静默忽略，不报错也不返回影响行数 —— 你无法知道这次是“真插入”还是“被忽略”，后续逻辑容易误判
• 用 ON DUPLICATE KEY UPDATE status = status（或更新一个无关字段如 updated_at = now()）：能保证 SQL 总是成功，且 update 操作会返回影响行数为 2（insert 1 行 + update 1 行），可用于判断是否重复
• 唯一索引字段必须包含 idempotent_id，且最好单独建表（如 idempotent_record），不要复用业务表 —— 避免锁表、降低耦合、方便清理过期记录

超时重试 + 分布式事务下，幂等记录怎么清理才安全

不清理会堆积，清理太早会误删正在处理中的记录。关键不是“什么时候删”，而是“删之前能不能确认它已失效”。

• 别用固定时间（比如 24 小时）硬删除 —— 长流程任务（如调第三方支付回调）可能耗时远超预期
• 建议加状态字段 status（'pending'/'success'/'failed'），只清理 status = 'pending' 且 created_at < now() - INTERVAL 30 MINUTE 的记录
• 清理操作本身要加分布式锁（如用 SELECT ... FOR UPDATE 锁住一批待清理记录），否则多个实例并发清理可能删掉刚写入的 pending 记录

真正难的不是生成 ID 或加索引，而是把「校验时机」「状态流转」「清理边界」三者对齐 —— 少一个环节，幂等就变成幻觉。

好了，本文到此结束，带大家了解了《Java接口幂等性设计：全局ID防重与数据库索引兜底》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！