ThinkPHP 8 订单接口实战:幂等锁、事务边界与验证器场景的六个坑

2026-11-16 0 534

大促那天中午,客服群里炸了。同一个用户下了五笔一模一样的订单,库存扣了五次,财务那边对账对到一半发现金额对不上。翻了日志才知道,移动端网络抖动,用户连点了两下,前端防抖没拦住,请求打到后端生成了两条记录;后面支付回调又因为超时重试了一次,再扣一遍。

那天之后我把下单接口重构了一遍。前端防抖加了,但更关键的是后端得自己扛住——因为网络重试、回调重放、用户手动刷新,这些场景前端根本管不到。这篇文章就是那次重构的完整思路,代码在 ThinkPHP 8 上跑,涉及中间件、事务、验证器几个部分,我把趟过的坑都写出来。

环境和前提

ThinkPHP 8 要求 PHP 8.0 起步,我这边用的是 PHP 8.2。Redis 扩展和 think-redis 都要装上,幂等锁靠它。

composer create-project topthink/think order-demo
cd order-demo
composer require topthink/think-redis

数据库里两张表,sku 和 order。后者除了常规字段,需要一个 idem_key 唯一索引,这个索引是最后一道兜底,后面会讲为什么不能只靠 Redis。

CREATE TABLE `order` (
  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
  `order_no` varchar(32) NOT NULL,
  `sku_id` int unsigned NOT NULL,
  `qty` int unsigned NOT NULL,
  `amount` decimal(10,2) NOT NULL,
  `idem_key` varchar(64) DEFAULT NULL,
  `status` tinyint NOT NULL DEFAULT 0,
  `create_time` datetime NOT NULL,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_idem` (`idem_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

验证器:场景写法的两个细节

先做参数层。ThinkPHP 8 的验证器跟 6.x 差别不大,场景机制还在,但有两处容易写错。

<?php
namespace appvalidate;

use thinkValidate;

class OrderValidate extends Validate
{
    protected $rule = [
        'sku_id'   => 'require|integer|gt:0',
        'qty'      => 'require|integer|between:1,99',
        'idem_key' => 'require|alphaDash|length:16,64',
    ];

    protected $message = [
        'sku_id.require'   => '商品不能为空',
        'qty.between'      => '单次购买数量 1-99',
        'idem_key.require' => '缺少幂等键',
    ];

    protected $scene = [
        'create' => ['sku_id', 'qty', 'idem_key'],
    ];
}

第一处细节:length:16,64 这个规则在 ThinkPHP 8 里对字符串是字节长度还是字符长度?实测是字符长度,中文场景没问题,但幂等键一般是 UUID 或者雪花 ID,不会有中文,这里影响不大。真正要注意的是 alphaDash 会把下划线放行、把斜杠拦掉,如果你们的幂等键用了 Base64 编码(可能含 + / =),得改成 regex。

第二处细节,也是我花了半小时才找出来的:场景一旦定义,验证器只会校验场景里列出的字段,不在场景里的字段即使传了也不会被校验,更不会报错。我一开始把 coupon_id 写进了 rule 但忘了加进 scene,接口收到的 coupon_id 是一个字符串 "abc",直接进了数据库的 int 字段,变成 0,优惠券白送了。

控制器里的调用:

$validate = new appvalidateOrderValidate();
if (!$validate->scene('create')->check($params)) {
    throw new thinkexceptionValidateException($validate->getError());
}

注意 scene() 必须写在 check() 之前,反过来写不生效,也不报错。这个顺序在文档里是隐藏的,踩过一次就记住了。

中间件:幂等锁的核心

幂等锁的规则很简单:同一个幂等键,在有效期内只允许一个请求进入业务逻辑。剩下的要么等,要么直接返回上次的结果。我这里用的是最简单的一种——不等待,直接告诉调用方”正在处理中”,让前端稍后重试。

<?php
namespace appmiddleware;

use thinkfacadeCache;

class Idempotent
{
    public function handle($request, Closure $next, $ttl = 30, $prefix = 'idem:')
    {
        $key = $request->header('X-Idem-Key', '');
        if ($key === '') {
            return json(['code' => 4001, 'msg' => '缺少幂等键'], 400);
        }

        $redis  = Cache::store('redis')->handler();
        $lockKey = $prefix . md5($key);
        $token  = bin2hex(random_bytes(8));

        $ok = $redis->set($lockKey, $token, ['nx', 'ex' => (int)$ttl]);
        if (!$ok) {
            return json(['code' => 4009, 'msg' => '请求正在处理中,请稍后'], 409);
        }

        try {
            return $next($request);
        } finally {
            // 只删自己加的锁,防止误删别人的
            $script = "if redis.call('get', KEYS[1]) == ARGV[1] "
                    . "then return redis.call('del', KEYS[1]) else return 0 end";
            $redis->eval($script, [$lockKey, $token], 1);
        }
    }
}

这段代码里有四个容易出问题的地方,我一一展开。

坑一:释放锁必须比对 value

如果我直接把 del($lockKey) 写在 finally 里,会出现这种情况:A 请求处理超时了,锁 30 秒过期,B 请求进来抢到了锁,这时候 A 的 finally 执行,把 B 的锁删了。C 请求又来,直接闯进去。三个人同时改库存。

用 random_bytes 生成一次性 token 当 value,释放的时候对比一下,只删自己的,这个经典方案不能省。Lua 脚本是保证”读”和”删”原子,不然对比完到删除之间还是可能被过期打断。

坑二:Middleware 参数不是这样传的

我的 handle 签名的第三、四个参数能收到值,前提是路由上这么写:

Route::post('order', 'Order/create')
    ->middleware(appmiddlewareIdempotent::class, '30', 'idem:order:');

参数按逗号分隔,依次传给 handle 的第三个及以后的形参,都是字符串。$ttl 要 (int) 转一下,直接用会出问题。如果你有多个中间件串在一条路由上,->middleware(A::class, 'x')->middleware(B::class, 'y') 这样写,参数不会串。

另外,Cache::store('redis')->handler() 返回的是原生 Redis 实例,set 的第三个参数用数组形式 ['nx', 'ex' => 30],这是 phpredis 扩展的写法。如果是 predis 驱动,这个签名不一样,得改成 set($key, $value, ['nx', 'ex' => $ttl]) 或者用 setex 配合 exists,具体看你装的驱动。我这边是 phpredis,上面的写法能跑。

坑三:锁释放的时机

这是最容易忽略的。上面代码里 finally 在 $next($request) 返回之后执行,而 $next 里如果包了 Db::transaction,事务提交是在 $next 返回之前完成的,所以顺序没问题。

但如果你的写法是”在中间件里开事务,在控制器里提交”,那就有坑了。锁释放发生在事务提交之前,当这个窗口很短、调用方又很快重试的时候,新请求进来读到的还是未提交前的旧数据,判断逻辑可能出错。我的做法是事务全部收在控制器(或者 Service)内部,让 $next 的返回就代表”业务彻底完成”,锁在这个时候释放才安全。

坑四:唯一索引兜底不能省

Redis 挂了、锁过期了、双机房网络分区了,这些情况都会让锁失效。所以数据库那一层必须有一个唯一索引 uk_idem,幂等键作为字段写进去。插入失败就说明重复,捕获异常返回”订单已存在”。

try {
    $order = Order::create($data);
} catch (thinkdbexceptionPDOException $e) {
    if (str_contains($e->getMessage(), 'uk_idem')) {
        throw new appexceptionBizException('该请求已处理,请勿重复提交');
    }
    throw $e;
}

用字符串匹配异常信息来判断唯一索引冲突,这个做法不优雅但可用。更稳的是判断 $e->getCode() 是不是 23000,但这个错误码在 MySQL 里对应所有完整性约束冲突,分不出是主键还是唯一索引。折中方案是:先 find 一下这个 idem_key,查到就直接返回,查不到再插入,插入冲突再返回。多一次查询,换代码可读性。

事务边界和库存扣减

下单最关键的是库存。这里我踩过两个坑。

坑五:事务里不能吞异常

ThinkPHP 的 Db::transaction 靠异常来触发回滚。如果你在里面写了 try-catch 把异常吃了,或者返回 false,事务不会回滚,该扣的库存扣了一半,该建的订单没建上。

Db::transaction(function () use ($skuId, $qty) {
    $affected = Db::name('sku')
        ->where('id', $skuId)
        ->where('stock', '>=', $qty)
        ->dec('stock', $qty)
        ->update();

    if ($affected === 0) {
        throw new appexceptionBizException('库存不足');
    }
    // ... 建订单
});

$affected === 0 表示 where 条件没命中,要么库存不够,要么商品不存在。这里必须抛异常,不能 return false,否则事务认为一切正常,提交了空操作。

坑六:多商品订单要按 sku_id 排序

这个坑我是在压测中撞上的。当一笔订单包含多个 SKU 时,如果扣减顺序是”按加入购物车的顺序”,两个并发请求 A(商品1、商品2)和 B(商品2、商品1)会分别持有商品1、商品2的行锁,然后互相等对方释放,直接死锁。MySQL 检测到死锁会回滚其中一个,但用户看到的是”下单失败,请重试”,体验很差。

办法很简单,批量扣减之前按 sku_id 升序排一遍:

usort($items, fn($a, $b) => $a['sku_id'] <=> $b['sku_id']);

foreach ($items as $item) {
    $affected = Db::name('sku')
        ->where('id', $item['sku_id'])
        ->where('stock', '>=', $item['qty'])
        ->dec('stock', $item['qty'])
        ->update();

    if ($affected === 0) {
        throw new appexceptionBizException("商品 {$item['sku_id']} 库存不足");
    }
}

所有人按同一顺序加锁,循环等待的条件就被破坏了。压测里死锁从每秒几十次降到零。

统一返回与异常处理

有了 BizException 和 ValidateException,还需要在 app/ExceptionHandle.php 里统一转成 JSON,不然前端会收到一堆 HTML 错误页。

public function render($request, Throwable $e)
{
    if ($request->isJson() || $request->isAjax()) {
        if ($e instanceof appexceptionBizException) {
            return json(['code' => $e->getCode() ?: 4000, 'msg' => $e->getMessage()]);
        }
        if ($e instanceof thinkexceptionValidateException) {
            return json(['code' => 4001, 'msg' => $e->getMessage()], 400);
        }
        // 生产环境不要把原始信息返回给前端
        $msg = app()->isDebug() ? $e->getMessage() : '服务繁忙,请稍后再试';
        return json(['code' => 5000, 'msg' => $msg], 500);
    }
    return parent::render($request, $e);
}

注意 app()->isDebug() 这一行。.env 里 APP_DEBUG = true 的时候返回真实异常信息便于排查,上线前一定要关掉。我见过有项目直接 return json(['msg' => $e->getMessage()]),结果 SQL 报错把表名、字段名、甚至部分连接信息暴露给前端了。

完整流程串一遍

把上面的东西拼起来,控制器大概长这样:

<?php
namespace appcontroller;

use appmodelOrder;
use appvalidateOrderValidate;
use thinkfacadeDb;
use thinkRequest;

class OrderController
{
    public function create(Request $request)
    {
        $params = $request->only(['sku_id', 'qty', 'coupon_id']);

        $validate = new OrderValidate();
        if (!$validate->scene('create')->check($params)) {
            throw new thinkexceptionValidateException($validate->getError());
        }

        $idemKey = $request->header('X-Idem-Key');

        $order = Db::transaction(function () use ($params, $idemKey) {
            $affected = Db::name('sku')
                ->where('id', $params['sku_id'])
                ->where('stock', '>=', $params['qty'])
                ->dec('stock', $params['qty'])
                ->update();

            if ($affected === 0) {
                throw new appexceptionBizException('库存不足', 4002);
            }

            $sku = Db::name('sku')->where('id', $params['sku_id'])->find();

            return Order::create([
                'order_no'   => date('YmdHis') . mt_rand(1000, 9999),
                'sku_id'     => $params['sku_id'],
                'qty'        => $params['qty'],
                'amount'     => bcmul((string)$sku['price'], (string)$params['qty'], 2),
                'idem_key'   => md5($idemKey),
                'status'     => 0,
                'create_time'=> date('Y-m-d H:i:s'),
            ]);
        });

        return json(['code' => 0, 'msg' => 'ok', 'data' => ['order_no' => $order->order_no]]);
    }
}

金额那里用 bcmul 而不是直接乘,是因为 decimal(10,2) 字段从数据库读出来是字符串,19.99 * 3 在 PHP 里是 59.97 但浮点可能有尾差。虽然 ThinkPHP 的 decimal 类型默认会转 float,但金额相关的运算我建议一律走 bc 系列,两位小数 bcmul 一次搞定。

压测结果和最后的取舍

本地用 ab 跑了 2000 个并发请求到同一个幂等键上,配置是 4 核 8G 的机器加单机 Redis:

  • 未加幂等锁:成功创建订单 2000 条,库存扣减 2000 次,数据完全错乱;
  • 加 Redis 锁:成功 1 条,其余 1999 条返回 409,平均响应 12ms;
  • 加 Redis 锁 + 唯一索引:结果同上,但多了一个兜底,Redis 挂掉时靠唯一索引还能拦住 99% 的重复;
  • 去掉排序的多商品扣减:死锁报错率约 3%;加排序后归零。

有一点要说明:上面这套是”直接拒绝”策略,前端收到 409 之后需要提示用户”处理中,请稍等”。如果业务上不能接受这个提示,就得改成”等待重入”——锁冲突时不直接返回,而是轮询一小段时间,等前一个请求处理完直接把结果读出来返回。后者的实现复杂不少,还得考虑锁续期、结果缓存、失败重试,不在这次重构范围里。

还有一点,幂等键的有效期($ttl)设多长要看业务。我做的是 30 秒,因为下单接口本身最慢也就三五秒,30 秒足够覆盖网络重试的一个周期。如果设置得太长,用户修改了购物车、想重新下单,会被幂等锁挡住,得换一个新的幂等键。所以幂等键的生成时机也有讲究——应该在用户点击”提交订单”那一刻生成,而不是在页面加载时生成。

最后一句:ThinkPHP 8 这套中间件、验证器、事务的组合,能解决的问题其实很有限。真正的幂等要在数据库层面有唯一约束、要在业务层面想清楚重复请求应该返回什么(报错?返回上次结果?),不是加个 Redis 锁就完事。我见过有项目在中间件里加了锁,然后控制器里又写了一遍”查一下有没有重复的订单”,两套逻辑不一致,出了一次线上问题,最后还得把中间件那边拆掉。

ThinkPHP 8 订单接口实战:幂等锁、事务边界与验证器场景的六个坑
收藏 (0) 打赏

感谢您的支持,我会继续努力的!

打开微信/支付宝扫一扫,即可进行扫码打赏哦,分享从这里开始,精彩与您同在
点赞 (0)

版权声明:
本站资源有的来自互联网收集整理,本站纯免费分享提供学习使用,如果侵犯了您的合法权益,请发送邮件1506151422@qq.com联系,将会及时下架删除。
本站资源仅供研究、学习交流之用,免费开源项目不代表完全可商用,若商业用途请先咨询开发企业能否商用,否则产生的一切后果将由下载用户自行承担。
原创板块未经允许不得转载,否则将追究法律责任。

淘吗网 thinkphp ThinkPHP 8 订单接口实战:幂等锁、事务边界与验证器场景的六个坑 https://www.taomawang.com/server/thinkphp/3023.html

下一篇:

已经没有下一篇了!

常见问题

相关文章

猜你喜欢
发表评论
暂无评论
官方客服团队

为您解决烦忧 - 24小时在线 专业服务