PHP 接口幂等提交实战：Redis Key + MySQL 唯一索引防重复下单

在订单、支付、发券、积分扣减这类接口里，“用户多点了一次按钮”不是小问题。前端可以禁用按钮，但网络超时、客户端重试、网关重放、用户刷新页面都会让同一笔业务请求再次打到服务端。服务端必须自己保证：同一个业务意图只处理一次，后续重复请求返回第一次的结果。

本文用一个 PHP 订单提交接口做例子，完整拆解一套可落地的幂等方案：客户端传入 Idempotency-Key，PHP 先用 Redis 快速拦截重复请求，再用 MySQL 唯一索引兜底，保证 Redis 抖动或并发穿透时仍然不会写出重复订单。

摘要

核心思路很简单：幂等 Key 表示“一次业务意图”，Redis 负责性能层面的快速判重，数据库唯一索引负责最终一致性兜底。不要只依赖前端防抖，也不要只依赖 Redis 锁，真正稳的接口要把幂等约束落到业务表或幂等表里。

适合人群

适合正在写 PHP 接口、订单系统、支付回调、消息消费或任务重试逻辑的开发者。示例使用 PHP 8、PDO、Redis 扩展和 MySQL，代码可以按你的框架封装到 Service 层。

目录

1. 为什么订单接口必须做幂等
2. 请求链路设计：Idempotency-Key 怎么流转
3. PHP + Redis 的第一道防线
4. MySQL 唯一索引兜底
5. 完整接口示例
6. 常见坑和排查方式

一、为什么订单接口必须做幂等

重复下单通常不是因为代码“明显写错”，而是因为真实链路里存在不可控重试：

• 用户连续点击提交按钮；
• 移动网络抖动，客户端认为请求失败后自动重试；
• Nginx、网关或队列消费者发生重放；
• 服务端处理成功，但响应在返回途中超时。

这些情况的共同点是：第二次请求的业务含义和第一次一样。服务端不能再创建一笔新订单，而应该识别出它是重复请求，并返回第一次的处理结果。

二、请求链路设计：Idempotency-Key 怎么流转

推荐让客户端在每次进入提交页或生成支付意图时创建一个唯一 Key，例如 UUID、雪花 ID 或后端下发的 nonce。提交订单时把它放到请求头或请求体里：

POST /api/orders HTTP/1.1
Content-Type: application/json
Idempotency-Key: 4b5f1f45-8e0b-45a5-9c60-9df8c3f41a21

{
  "sku_id": 10001,
  "quantity": 1,
  "address_id": 90001
}

服务端拿到 Key 后，不要直接相信它。至少要同时绑定当前用户、接口名和业务动作，拼成服务端内部使用的幂等键，避免不同用户或不同接口之间发生误判。

三、PHP + Redis 的第一道防线

Redis 适合做快速判重。关键命令是 SET key value NX EX seconds：只有 Key 不存在时才写入，并自动设置过期时间。PHP 里可以这样封装：

set($key, 'processing', ['nx', 'ex' => $ttl]);
}

$clientKey = $_SERVER['HTTP_IDEMPOTENCY_KEY'] ?? '';
if ($clientKey === '') {
    http_response_code(400);
    echo json_encode(['message' => 'missing Idempotency-Key'], JSON_UNESCAPED_UNICODE);
    exit;
}

$lockKey = buildIdempotencyKey($currentUserId, $clientKey);
if (!acquireIdempotencyLock($redis, $lockKey, 60)) {
    $cached = $redis->get('result:' . $lockKey);
    if ($cached) {
        echo $cached;
        exit;
    }

    http_response_code(409);
    echo json_encode(['message' => 'request is processing'], JSON_UNESCAPED_UNICODE);
    exit;
}

这里有两个状态需要区分：如果结果缓存已经存在，说明第一次请求已经完成，直接返回旧结果；如果只有锁没有结果，说明第一次请求还在处理中，可以返回 409 或让客户端稍后查询。

四、MySQL 唯一索引兜底

Redis 是性能防线，不是最终防线。Redis 可能重启、超时、误删 Key，也可能因为锁 TTL 设置太短导致请求还没处理完锁就过期。因此订单表里要保存幂等 Key，并建立唯一索引：

ALTER TABLE orders
  ADD COLUMN idempotency_key VARCHAR(100) NOT NULL DEFAULT '' COMMENT '幂等键',
  ADD UNIQUE KEY uk_user_idem (user_id, idempotency_key);

唯一索引的意义是：即使两个请求同时绕过 Redis，数据库也只允许一条记录成功插入。另一个请求捕获唯一键冲突后，查询已存在订单并返回即可。

五、完整接口示例

下面是一个省略鉴权和参数校验后的核心流程。实际项目里建议把 Redis、PDO、日志和异常处理封装进框架容器。

set($idemKey, 'processing', ['nx', 'ex' => 60])) {
        $cached = $redis->get($resultKey);
        if ($cached) {
            return json_decode($cached, true, 512, JSON_THROW_ON_ERROR);
        }

        return ['code' => 409, 'message' => '订单正在处理中，请勿重复提交'];
    }

    try {
        $pdo->beginTransaction();

        $stmt = $pdo->prepare(
            'INSERT INTO orders (user_id, sku_id, quantity, amount, status, idempotency_key, created_at)
             VALUES (:user_id, :sku_id, :quantity, :amount, :status, :idempotency_key, NOW())'
        );
        $stmt->execute([
            ':user_id' => $userId,
            ':sku_id' => (int) $payload['sku_id'],
            ':quantity' => (int) $payload['quantity'],
            ':amount' => calculateAmount($payload),
            ':status' => 'created',
            ':idempotency_key' => $clientKey,
        ]);

        $orderId = (int) $pdo->lastInsertId();
        $pdo->commit();

        $result = ['code' => 0, 'order_id' => $orderId, 'status' => 'created'];
        $redis->setex($resultKey, 600, json_encode($result, JSON_UNESCAPED_UNICODE));
        return $result;
    } catch (PDOException $e) {
        if ($pdo->inTransaction()) {
            $pdo->rollBack();
        }

        if ($e->errorInfo[1] === 1062) {
            $stmt = $pdo->prepare(
                'SELECT id, status FROM orders WHERE user_id = :user_id AND idempotency_key = :idempotency_key LIMIT 1'
            );
            $stmt->execute([':user_id' => $userId, ':idempotency_key' => $clientKey]);
            $order = $stmt->fetch(PDO::FETCH_ASSOC);

            return [
                'code' => 0,
                'order_id' => (int) $order['id'],
                'status' => $order['status'],
                'replayed' => true,
            ];
        }

        $redis->del($idemKey);
        throw $e;
    }
}

六、常见坑和排查方式

1. 幂等 Key 只放 Redis，不落库

这是最常见的风险。Redis 适合挡流量，不适合承担最终约束。涉及资金、订单、库存、发券等业务时，一定要用数据库唯一索引兜底。

2. 锁 TTL 设置过短

如果业务平均耗时 3 秒，锁只设置 2 秒，并发请求可能在第一次请求未提交时重新进入。TTL 要覆盖接口最大合理处理时间，并且慢接口要拆出异步任务或状态查询。

3. 重复请求返回空结果

只存“处理中”状态不够。接口成功后要缓存结果，或者从订单表查询结果返回。客户端真正需要的是“我这次提交到底有没有成功”。

4. 幂等 Key 没绑定用户

不要直接把客户端传来的 Key 当成 Redis Key 或唯一索引值。至少绑定用户 ID、接口名和业务动作，避免 Key 冲突造成串单。

七、总结

PHP 接口幂等的重点不是某一行 Redis 命令，而是完整的分层约束：客户端生成业务意图 Key，服务端用 Redis 快速拦截重复请求，业务表用唯一索引做最终兜底，成功后保存并返回可复用的处理结果。这样即使用户重复点击、网络超时重试、Redis 短暂异常，也能把重复下单风险控制住。