前端表单重复提交防护工作流：从按钮状态到请求取消和幂等键

前端表单重复提交是很常见的线上问题：用户连续点击保存按钮、网络变慢时又点了一次、页面返回后再次提交，最后可能产生重复订单、重复工单或多条相同配置。只靠“用户不要连点”显然不可靠。

这篇文章整理一套可落地的防护工作流：从按钮状态和加载提示开始，到请求取消、幂等键、错误恢复和上线后的复查指标。重点是把一次提交变成可控流程，而不是只在按钮上加一个 disabled。

目标和边界：重复提交要防到什么程度

重复提交防护要解决三类问题：同一页面连续点击、同一请求重复发送、同一业务动作重复落库。前端能解决前两类的大部分体验问题，但关键业务最好配合后端幂等校验。

本文默认场景是新增、保存、支付前确认、导入、审批这类提交按钮。普通搜索、分页、筛选可以只做防抖或取消旧请求，不一定需要幂等键。

全流程总览：从点击到结果确认

先说结论：一次可靠提交应该是单向流程。用户点击后，页面进入提交中状态；请求层绑定取消控制；关键业务带上幂等键；接口返回后统一恢复 UI，并记录提交结果。

阶段 1：前端先建立提交状态

目标：让页面在一次提交期间进入明确状态。不要等接口返回后才处理按钮状态，应该在发请求前就切换。

关键动作：

• 提交前检查 isSubmitting，已经提交中就直接返回。
• 按钮禁用，同时显示“保存中”或加载图标。
• 提交结束后在 finally 中恢复状态。
• 保留表单输入，失败时不要清空用户已填内容。

let isSubmitting = false;

async function submitForm(formData) {
  if (isSubmitting) {
    return;
  }

  isSubmitting = true;
  setButtonLoading(true);

  try {
    const result = await saveOrder(formData);
    showSuccess(result.message);
  } catch (error) {
    showError("保存失败，请检查后重试");
  } finally {
    isSubmitting = false;
    setButtonLoading(false);
  }
}

检查点：打开浏览器网络面板，连续快速点击按钮 5 次，应该只看到一次保存请求。

阶段 2：请求层处理取消和超时

目标：避免旧请求影响新页面状态。比如用户提交后立刻切换路由，旧请求返回时不应该再改当前页面。

关键动作：

• 为提交请求创建 AbortController。
• 页面卸载或切换时取消未完成请求。
• 超时时给出明确提示，不让按钮一直转圈。
• 区分“用户取消”和“接口失败”，提示文案不要混在一起。

let submitController = null;

async function saveOrder(data) {
  submitController = new AbortController();

  const response = await fetch("/api/orders", {
    method: "POST",
    body: JSON.stringify(data),
    headers: {"Content-Type": "application/json"},
    signal: submitController.signal
  });

  if (!response.ok) {
    throw new Error("request failed");
  }

  return response.json();
}

function leavePage() {
  if (submitController) {
    submitController.abort();
  }
}

检查点：提交中切换页面，不应出现旧页面的成功提示，也不应把新页面按钮状态改掉。

阶段 3：用幂等键保护关键业务

目标：让同一业务动作即使重复到达接口，也只产生一次结果。前端按钮禁用主要保护交互层，幂等键保护业务层。

关键动作：

• 进入表单页面时生成一个提交键。
• 第一次成功后把提交键标记为已使用。
• 需要重新发起业务动作时，再生成新键。
• 后端按用户、业务类型和提交键判断是否重复。

function createSubmitKey() {
  return `${Date.now()}-${crypto.randomUUID()}`;
}

let submitKey = createSubmitKey();

async function saveOrder(data) {
  const response = await fetch("/api/orders", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key": submitKey
    },
    body: JSON.stringify(data)
  });

  return response.json();
}

检查点：用同一个提交键重复请求，后端应该返回同一个业务结果，或者明确提示重复提交，而不是创建两条记录。

阶段 4：错误恢复和用户反馈

目标：失败后让用户知道发生了什么，并能安全重试。重复提交防护不能让页面卡死，也不能把失败误报为成功。

关键动作：

• 校验失败：恢复按钮，保留表单，定位到错误字段。
• 网络失败：提示可重试，保留同一个提交键或按业务规则换新键。
• 服务端提示重复：展示已存在结果，引导用户查看详情。
• 成功提交：跳转详情页或展示结果编号，避免用户再次点保存。

检查点：断网、接口返回 500、接口返回重复提交三种情况都要测试，按钮状态不能停留在“提交中”。

推荐工作流：新表单怎么落地

1. 先判断表单是否属于关键业务，普通查询只做防抖即可。
2. 为提交按钮接入 isSubmitting 状态和加载文案。
3. 把请求封装到统一函数，处理失败、取消和超时。
4. 关键业务生成提交键，并随请求一起发送。
5. 成功后跳转结果页或锁定当前提交结果。
6. 失败后恢复按钮并保留输入，允许用户明确重试。
7. 上线后记录重复点击次数、重复请求次数和后端重复拦截次数。

容易踩坑：为什么禁用按钮还会重复

坑 1：状态更新太晚

如果先发请求，再设置提交中状态，极短时间内仍可能触发第二次点击。状态应该在请求前切换。

坑 2：多个入口共用同一动作

页面上可能有顶部保存、底部保存、快捷键保存三个入口。只禁用一个按钮不够，应该让它们共享同一个提交状态。

坑 3：前端防护代替后端幂等

刷新、回退、网络重发、脚本调用都可能绕过按钮。涉及订单、支付、审批、导入等关键业务时，后端必须参与幂等判断。

速查表：场景、做法和检查点

表单重复提交防护不是一个按钮属性，而是一条提交链路。前端负责把交互入口收住，请求层负责处理取消和失败，后端负责关键业务幂等。三层都到位，重复提交才真正可控。