单个表单防重逻辑在跨表单场景下失效，因其前端状态（isSubmitting、pending、localStorage临时key）绑定单页生命周期，用户新开标签页、清缓存、无痕模式或回退重开均导致状态丢失，后端收到“全新”请求；幂等key必须跨会话、跨设备、跨页面复现，由用户标识、表单类型、关键输入指纹三要素稳定哈希生成，并持久化存储以支持重试复用。
为什么单个表单的防重逻辑在跨表单场景下会失效
跨表单提交（比如用户在 A 表单填完跳转到 B 表单、再回退或新开页重复操作）会让前端 isSubmitting 状态、pending 标记、localStorage 中的临时 key 全部失效——因为这些状态都绑定在单页生命周期内。用户新开标签页、清缓存、用无痕模式，甚至只是关掉又重开页面，都会导致后端收到“全新”的请求，但业务上它和前一次完全一致。
常见错误是把幂等 key 设为 crypto.randomUUID() 后不持久化，或只存在内存 Map 里；结果服务端看到两个不同 key，就当两笔独立订单处理。
- 幂等 key 必须能跨会话、跨设备、跨页面复现，否则无法识别“这是同一用户对同一业务动作的重复触发”
- 不能只靠 URL 或 action 路径判断，多个表单可能 POST 到同一个接口（如
/api/submit） - 用户登录态变化（如 token 过期后重登）会导致 session_id 改变，所以不能单靠 session 绑定
如何生成真正可复用的幂等 key
安全的跨表单幂等 key 不是随机数，而是由三要素稳定哈希而成：当前用户标识（非 session）、表单语义类型、关键输入指纹。例如注册表单，key 应包含用户手机号（脱敏后哈希）+ 表单类型字符串 + 非空字段排序后的 SHA256。
实操建议：
立即学习“前端免费学习笔记（深入）”；
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
- 前端用
crypto.subtle.digest('SHA-256', new TextEncoder().encode(inputStr))计算哈希，兼容现代浏览器；降级方案用sha256npm 包（需注意不暴露明文密码） - 关键字段指业务强约束字段：如订单表单用
userId+cartId+paymentMethod；登录表单用email（非密码） - 避免包含时间戳、随机数、
Math.random()等不可复现因子 - 将最终 key 作为请求头
X-Idempotency-Key发送，不要放 query 或 body —— CDN 和日志系统可能截断或清洗
后端校验必须拒绝“已成功但未返回”的请求
跨表单场景下最危险的是：第一次请求已写库并返回 200，但因网络抖动用户没收到响应，于是重试。此时后端若只查“有没有这个 key”，发现没有就执行，就会造成双写。
正确做法是：Redis 或数据库中不仅存 key，还要存完整状态记录，含 status（processing/success/failed）、response_body（成功时缓存原始响应体）、created_at 和 expires_at（建议 24h）。
- 收到请求时先查 key：若状态为
success，直接返回缓存的响应体（HTTP 200 + 原始 payload） - 若为
processing，返回 409 Conflict 或 425 Too Early，前端据此轮询或提示“请勿重复提交” - 若不存在，用
SETNX+EX原子写入processing状态，再执行业务逻辑，最后更新为success - 禁止用
INSERT ... ON CONFLICT DO NOTHING后直接返回 201 —— 它不保证你读到的是上次成功的结果
前端重试时怎么避免生成新 key
用户点击“重试”按钮时，如果重新计算幂等 key，就等于放弃幂等性。必须从本地存储中恢复原始 key，而不是新建。
实操要点：
- 首次提交前，把生成的 key 和表单数据一起存入
localStorage.setItem(`idempotent-${key}`, JSON.stringify({ data, timestamp })) - 重试逻辑触发时，先遍历
localStorage找出所有以idempotent-开头的项，过滤出timestamp在 24 小时内的，选最新一条复用其 key - 重试请求必须携带原 key，并加请求头
X-Retry: true，方便后端区分“首次提交”和“明确重试” - 若 localStorage 被清空，降级为用用户 ID + 表单类型 + 当前时间窗口（如
2026-11）拼接，虽不精确但至少能拦截明显短时重复
跨表单幂等最难的不是生成 key，而是让 key 的生命周期脱离页面、绑定到用户意图。一旦 key 丢失或错配，后端就只能靠业务字段兜底（比如订单号唯一索引），但那已是最后一道防线，不是设计起点。
