各位同学，大家好！欢迎来到今天的“React 动作安全研讨会”。我是你们的讲师，一个在代码世界里摸爬滚打多年，头发虽然稀疏但发际线依然坚挺的资深工程师。
今天我们不讲那些“Hello World”的入门教程，也不聊什么组件拆分的“祖传架构”。我们要聊的是一个非常现实、非常棘手，甚至能让你在深夜里对着屏幕发出“这怎么可能？”的哀嚎的问题——幂等性。
具体来说，就是当你在 React Server Components (RSC) 的世界里，用 Server Actions 处理表单时，如何防止用户手滑点两下，或者网络抖动导致服务器收到两个请求，最后让你的数据库里多出两份一模一样的垃圾数据。
准备好了吗？我们开始吧。
第一章：手滑的代价——为什么我们需要幂等性？
想象一下这个场景：你正在开发一个支付页面，或者一个“创建订单”的页面。用户按下“提交订单”按钮。
通常情况下，浏览器会发送一个请求到服务器。服务器处理，返回成功。这是理想状态。
但在现实世界里，网络是有延迟的。用户的手指是有抖动的。也许就在你按下按钮的那一毫秒，网络稍微卡顿了一下。用户心想：“哎呀，没反应，我多按一下。”于是，他又点了一次。
结果呢？服务器收到了两个请求。它以为这是两个独立的用户在同时操作。于是，它创建了两条订单记录，扣了两次款。
这时候，客服来了，用户炸毛了，你的老板在背后推着你的脖子。这就是非幂等性带来的灾难。
幂等性，简单来说，就是数学上的“多退少补”的反义词。如果对同一个操作执行两次，和执行一次的结果是一样的。就像你按电梯按钮，按一百次和按一次，电梯都会来。再比如，你给服务器转账 100 块，转两次和转一次，你账户里的钱不应该变两次。
在 React Server Actions 中，我们处理的是服务端的逻辑，而客户端的表单提交往往是异步的，这就给幂等性带来了巨大的挑战。
第二章：乐观 UI——“先斩后奏”的艺术
在解决这个问题之前，我们得先学会一个高阶技巧，它能解决 90% 的“手滑”问题。这就是乐观 UI (Optimistic UI)。
什么是乐观 UI？顾名思义，就是“乐观”。就是我们要欺骗用户，告诉他们“你的操作已经成功了”，但实际上服务器可能还在处理中。
为什么这么做？
因为等待服务器响应是痛苦的。如果你在点击按钮后显示一个转圈圈的 Loading 状态，用户会焦虑，会以为网络断了，然后疯狂地点击按钮。
怎么实现？
React 18 引入了 startTransition 和 useOptimistic。这简直是神器。
让我们看一段代码。假设我们有一个简单的表单，用于创建一个待办事项。
// app/actions.ts
'use server'
export async function createTodo(formData: FormData) {
const title = formData.get('title') as string;
// 这里是真实的数据库操作
await db.todo.create({ data: { title } });
}
// app/page.tsx
'use client'
import { useFormState, startTransition } from 'react-dom';
import { createTodo } from './actions';
export default function TodoForm() {
const [state, formAction] = useFormState(createTodo, { message: null });
const [isPending, startTransition] = useTransition();
const handleSubmit = (formData: FormData) => {
// 关键点：在这里进行乐观更新
startTransition(() => {
formAction(formData);
});
};
return (
<form action={handleSubmit}>
<input name="title" placeholder="写点什么..." required />
<button type="submit" disabled={isPending}>
{isPending ? '保存中...' : '提交'}
</button>
{state.message && <p>{state.message}</p>}
</form>
);
}这里发生了什么？
当你点击提交时，startTransition 会立即执行 formAction。在 React 的眼中，表单状态瞬间变成了“成功”。如果这个操作非常快，用户甚至感觉不到延迟。
但是，如果服务器实际上失败了怎么办？React 会把状态回滚到之前的状态。这就好比你在谈恋爱，你先告诉对方“我爱你”，对方也回应了“我也爱你”，结果过了一会儿对方告诉你“其实我是个骗子”。这种体验虽然有点尴尬，但至少避免了“两个人同时向对方表白”的混乱局面。
乐观 UI 是第一道防线。它通过消除用户的焦虑，从源头上减少了重复点击。
第三章：客户端的“门卫”——防抖与节流
虽然乐观 UI 很好，但它不能解决所有问题。比如，如果服务器真的挂了，乐观 UI 也会回滚，但此时用户可能已经看到了成功的提示，或者还在继续点击。
这时候，我们需要在客户端加一把锁。这就是防抖。
防抖的意思是：如果你在一秒钟内连续点击了两次按钮，第二次点击会被拦截，直到第一次点击完全结束。
import { useState, useEffect } from 'react';
function useDebouncedSubmit(callback: () => void, delay: number = 500) {
const [isPending, setIsPending] = useState(false);
const debouncedCallback = () => {
setIsPending(true);
setTimeout(() => {
callback();
setIsPending(false);
}, delay);
};
return [isPending, debouncedCallback] as const;
}
// 在组件中使用
export default function TodoForm() {
const [isPending, handleSubmit] = useDebouncedSubmit(submitAction, 800);
return (
<form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
<button type="submit" disabled={isPending}>
{isPending ? '请稍候...' : '提交'}
</button>
</form>
);
}这就好比你在公司楼下等电梯。电梯来了，你进去了一半，结果电梯门关了。这时候你肯定不能再次按按钮，否则会引发两次关门操作。
防抖能有效防止用户因为网络慢而进行的“连续点击”，但这只是治标不治本。如果用户刷新了页面，或者使用了浏览器的“后退”按钮，防抖机制就会失效。这时候，我们必须把希望寄托在服务器端。
第四章：服务器端的“守门人”——检查后写入
这是最传统，也是最稳健的方法。在执行写入操作之前，先进行查询。
逻辑是这样的：
- 用户提交表单。
- 服务器收到请求。
- 先查数据库：这条数据已经存在了吗？
- 如果存在：返回错误信息（例如“数据已存在”）。
- 如果不存在：执行插入操作。
这听起来很简单，对吧？但在高并发场景下，这会带来一个致命的问题——竞态条件。
竞态条件：两个大脑同时思考
假设有两个用户，同时提交了一个创建订单的请求。
- 时刻 T1：用户 A 的请求到达。服务器查询数据库，发现没有这个订单，准备插入。
- 时刻 T2：用户 B 的请求也到达。服务器查询数据库，发现……等等，因为网络延迟，用户 A 的插入操作还没完成，所以服务器查到数据不存在，也准备插入。
- 时刻 T3：用户 A 的插入完成。
- 时刻 T4：用户 B 的插入完成。
结果：两条订单被创建。数据不一致。
所以，单纯的“检查后写入”在 React Server Actions 中并不安全。我们需要更强的武器。
第五章：数据库的唯一约束——物理防线
在数据库层面，设置唯一约束是解决竞态条件的终极手段。
假设我们的表有一个 email 字段，我们希望它是唯一的。在 PostgreSQL 中，我们这样建表：
CREATE TABLE users (
id SERIAL PRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT NOW()
);或者 MySQL：
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
email VARCHAR(255) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);当用户 B 的请求尝试插入一条重复的 email 时，数据库会直接抛出一个错误（例如 UniqueViolation 或 DuplicateKeyException）。
但是！React Server Actions 默认会吞掉错误！
是的，你没听错。默认情况下，Server Actions 的返回值只有 Result 类型，错误会被静默处理。这意味着，如果数据库抛出唯一性错误，React 会收到一个 null 或 undefined，表单会认为操作成功，但数据实际上并没有插入成功。
这就像是门卫告诉你“你可以进去了”，但门实际上是锁着的。用户看到的是成功的提示，但什么都没发生。
解决方案：捕获数据库错误并返回给 UI。
我们需要在 Server Action 中捕获这个错误，并将其作为结果返回。
'use server'
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()
export async function createUser(formData: FormData) {
const email = formData.get('email') as string
try {
const user = await prisma.user.create({
data: { email }
})
return { success: true, user }
} catch (error) {
// 捕获 Prisma 的唯一性约束错误
if (error instanceof Prisma.PrismaClientKnownRequestError) {
if (error.code === 'P2002') {
return { success: false, error: '该邮箱已被注册' }
}
}
// 处理其他错误
return { success: false, error: '服务器内部错误' }
}
}现在，当数据库拒绝重复数据时，我们的 Server Action 会返回一个 { success: false, error: '该邮箱已被注册' }。在客户端，我们可以根据这个状态来显示错误提示。
这就是幂等性！
不管用户点击多少次，只要邮箱是重复的，服务器都会返回同样的错误信息，而不会重复创建数据。
第六章：幂等键——Ticketing System
还有一种更高级的幂等性方案，叫做幂等键。这就像电影院的门票，或者航班的登机牌。每一张票都是唯一的，即使你丢了，重新买一张，系统也能识别出来。
原理：
- 客户端生成一个唯一的 ID（UUID）。
- 客户端将这个 ID 随着表单数据一起发送给服务器。
- 服务器在接收到请求后，检查这个 ID 是否已经处理过。
- 如果处理过，直接返回上一次的结果（忽略重复提交）。
- 如果没处理过，执行业务逻辑，并记录这个 ID 为“已处理”。
为什么这么做？
有时候，我们需要处理的数据是非幂等的。比如，创建一个订单，订单号是自增的，每次创建都不一样。如果用数据库唯一约束，我们只能约束订单号，但业务上我们希望订单号是唯一的。
或者，我们有一个复杂的业务流程，比如“支付回调”。支付宝可能会在几秒钟内发送 10 次相同的回调通知。如果我们不使用幂等键，这 10 次回调都会触发扣款操作。
代码示例：
// app/actions.ts
'use server'
import { v4 as uuidv4 } from 'uuid'; // 假设你安装了 uuid 库
// 模拟一个存储已处理 ID 的内存缓存（生产环境应该用 Redis）
const processedIds = new Set<string>();
export async function processPayment(formData: FormData) {
const idempotencyKey = formData.get('idempotencyKey') as string;
// 1. 检查幂等键
if (processedIds.has(idempotencyKey)) {
console.log(`检测到重复请求: ${idempotencyKey}, 直接返回上一次结果`);
return { status: 'already_processed' };
}
// 2. 执行业务逻辑
const amount = formData.get('amount');
// ... 扣款逻辑 ...
// 3. 标记为已处理
processedIds.add(idempotencyKey);
return { status: 'success', amount };
}// app/page.tsx
'use client'
import { useFormState } from 'react-dom';
import { processPayment } from './actions';
export default function PaymentForm() {
// 客户端生成幂等键
const idempotencyKey = crypto.randomUUID();
const [state, formAction] = useFormState(processPayment, null);
return (
<form action={formAction}>
<input type="hidden" name="idempotencyKey" value={idempotencyKey} />
<input name="amount" type="number" placeholder="金额" />
<button type="submit">支付</button>
</form>
);
}注意：
上面的代码使用了内存 Set 来存储。这在生产环境中是万万不可用的。如果服务器重启，Set 里的数据就丢了，幂等性就失效了。你需要使用 Redis 或者数据库表来持久化这个 idempotencyKey。
第七章：并发与竞态条件的终极对决
让我们回到最棘手的问题：高并发下的竞态条件。
场景：用户 A 和用户 B 同时点击“购买”按钮。他们购买的是同一个库存商品（库存剩 1 个）。
如果使用乐观 UI：
- 用户 A 点击，乐观更新库存为 0。
- 用户 B 点击，乐观更新库存为 -1。
- 服务器 A 的请求先到达，扣减 1，库存 0，成功。
- 服务器 B 的请求到达，查询库存为 0，准备扣减，但发现库存不足？或者乐观更新覆盖了服务器 A 的结果？
- 这取决于你的乐观更新逻辑。如果乐观更新只是 UI 的假象，服务器查询库存，那么服务器 B 会因为库存不足而失败。这是安全的。
- 如果乐观更新直接修改了服务器端的缓存状态，那就出问题了。
如果使用数据库唯一约束：
- 服务器 A 和 B 同时插入订单。
- 数据库约束拦截其中一个（比如 B）。
- A 成功，B 失败。
- 但是！ 用户 B 的客户端收到了什么？如果是乐观 UI，用户 B 可能已经看到“购买成功”了，现在服务器告诉它“失败”。这会非常糟糕。
解决方案：客户端乐观更新与服务器端验证的配合。
客户端乐观更新必须要有“回滚”机制。如果服务器返回失败，UI 必须立即恢复到之前的状态。
import { useOptimistic, useTransition } from 'react';
export default function BuyButton() {
const [isPending, startTransition] = useTransition();
const [optimisticStock, setOptimisticStock] = useState(1);
const handleBuy = () => {
// 乐观更新 UI
setOptimisticStock(prev => prev - 1);
startTransition(async () => {
try {
await buyProduct(); // 调用 Server Action
} catch (error) {
// 回滚 UI
setOptimisticStock(prev => prev + 1);
alert('购买失败，库存不足');
}
});
};
return (
<button disabled={isPending} onClick={handleBuy}>
购买 (库存: {optimisticStock})
</button>
);
}第八章：实战演练——一个完整的、幂等的表单处理方案
好了，理论讲得差不多了。让我们把所有东西串起来，写一个完整、健壮的 Server Action 处理方案。这个方案将包含：
- 客户端：防抖、乐观 UI、生成幂等键。
- 服务端：数据库唯一性约束、错误捕获、幂等键检查。
第一步：数据库 Schema
CREATE TABLE orders (
id BIGSERIAL PRIMARY KEY,
user_id INT NOT NULL,
product_id INT NOT NULL,
status VARCHAR(50) DEFAULT 'pending',
created_at TIMESTAMP DEFAULT NOW()
);
-- 唯一约束：防止同一用户对同一商品在短时间内重复下单（简化版）
CREATE UNIQUE INDEX idx_orders_user_product ON orders(user_id, product_id);第二步：Server Action
'use server'
import { PrismaClient } from '@prisma/client'
const prisma = new PrismaClient()
export async function createOrder(formData: FormData) {
const userId = parseInt(formData.get('userId') as string);
const productId = parseInt(formData.get('productId') as string);
// 1. 幂等键检查 (使用 Redis 或数据库记录)
const idempotencyKey = formData.get('idempotencyKey') as string;
if (await checkIfProcessed(idempotencyKey)) {
return { success: true, message: '订单已处理' };
}
try {
// 2. 创建订单
// 数据库的唯一约束会在这里拦截并发请求
const order = await prisma.order.create({
data: { userId, productId }
});
// 3. 标记幂等键为已处理
await markAsProcessed(idempotencyKey);
return { success: true, order };
} catch (error) {
if (error instanceof Prisma.PrismaClientKnownRequestError) {
if (error.code === 'P2002') {
return { success: false, error: '您已经购买过该商品了' };
}
}
return { success: false, error: '系统繁忙，请重试' };
}
}第三步：Client Component
'use client'
import { useState } from 'react';
import { useFormState } from 'react-dom';
import { createOrder } from './actions';
export default function OrderForm() {
const [isPending, startTransition] = useTransition();
const [optimisticCount, setOptimisticCount] = useState(10); // 假设库存是 10
const [formState, formAction] = useFormState(createOrder, { message: null });
// 生成幂等键
const idempotencyKey = crypto.randomUUID();
const handleSubmit = () => {
// 乐观更新库存
setOptimisticCount(prev => prev - 1);
startTransition(async () => {
const result = await formAction(new FormData());
// 如果服务器返回失败，回滚乐观更新
if (!result.success) {
setOptimisticCount(prev => prev + 1);
alert(result.error);
}
});
};
return (
<div>
<p>当前库存: {optimisticCount}</p>
<form action={handleSubmit}>
<input type="hidden" name="idempotencyKey" value={idempotencyKey} />
<input type="hidden" name="userId" value="123" />
<input type="hidden" name="productId" value="456" />
<button type="button" onClick={handleSubmit} disabled={isPending || optimisticCount <= 0}>
{isPending ? '处理中...' : `购买 (${optimisticCount})`}
</button>
</form>
{formState.error && <p style={{ color: 'red' }}>{formState.error}</p>}
</div>
);
}第九章：总结与思考
在这场关于 React Actions 幂等性的讲座中，我们不仅仅是讨论了代码。我们讨论的是信任。
信任用户不会手滑（乐观 UI + 防抖）。
信任网络不会乱搞（幂等键）。
信任数据库是最终真理（唯一约束）。
在实际开发中，你需要根据业务场景组合使用这些技术。对于简单的表单，乐观 UI 足够了；对于支付、下单这种高价值操作，必须上数据库唯一约束和幂等键。
最后，送给大家一句话：幂等性不是一种选择，而是现代 Web 开发的底线。 如果你的代码不能保证重复请求不会导致数据错误，那它就是不安全的。
好了，今天的讲座就到这里。希望大家在下次写 formAction 的时候，脑子里能多想一层：“如果用户按了两次，服务器会怎么反应？” 祝大家编码愉快，Bug 远离！
（下课！）