phpmac/financial-security-middleware

资金操作安全中间件模式

适用范围

本 skill 描述的是框架无关的多层防护方法论. 三层防御架构 (中间件拦截 -> 业务校验 -> 数据层保障) 的设计思路适用于任何 Web 框架.

当前 examples/ 目录下的示例基于 Laravel 框架 (Cache::lock, DB::transaction, lockForUpdate). 应用到其他框架时, 需替换为对应机制:

| 防护层 | Laravel | Next.js / Node.js | |--------|---------|-------------------| | HTTP并发锁 | Cache::lock (Redis) | Redis SETNX / Redlock | | 业务锁 | Cache::lock | Redis 分布式锁 | | 事务 | DB::transaction | Prisma $transaction / mongoose session | | 行锁 | lockForUpdate (MySQL) | MongoDB findOneAndUpdate / Prisma乐观锁 | | 参数校验 | $request->validate | zod / joi | | 身份验证 | 自定义 2FA | next-auth / middleware |

核心原则

资金操作必须采用多层防护, 每层职责独立:

HTTP请求
  |
  ├─ 第1层: 中间件 (HTTP层拦截)
  │    ├─ IP白名单 (可选, 从配置读取)
  │    ├─ 并发锁 (同一用户同时只能有一个请求)
  │    └─ 频率限制 (可选)
  │
  ├─ 第2层: 控制器/Handler (业务层校验)
  │    ├─ 参数校验
  │    ├─ 身份验证 (2FA等)
  │    └─ 业务前置检查 (余额/状态)
  │
  └─ 第3层: 数据操作 (数据层保障)
       ├─ 分布式锁 (业务锁, 防重复处理)
       ├─ 数据库事务 (原子性)
       └─ 行锁/乐观锁 (防并发修改)

第1层: 中间件

并发锁 (HTTP层)

同一用户同一时间只能有一个资金操作请求在处理. 使用 Cache::lock 在中间件层拦截.

实现要点:

• 锁key命名: {操作名}_concurrent_{user_id}
• 锁时长: 10秒 (根据业务调整)
• 获取锁失败: 抛自定义异常 FinancialOperationLockException, 返回 HTTP 429
• 请求完成后: 必须用 try/finally 释放锁, 防止异常路径死锁

锁释放异常安全 (必须):

// 正确: try/finally 保证任何路径都释放
$lock = Cache::lock("{$operation}_concurrent_{$user->id}", 10);
throw_if(! $lock->get(), FinancialOperationLockException::class, $user->id, $operation);

try {
    return $next($request);
} finally {
    $lock->release();
}

// 错误: 异常时锁不释放, 导致死锁
$lock = Cache::lock("...", 10);
throw_if(! $lock->get(), '...');
$response = $next($request); // 若抛异常, release() 永不执行
$lock->release();

自定义异常 (必须)

禁止 throw_if($cond, '裸字符串'). 资金/安全操作必须使用自定义异常类:

class FinancialOperationLockException extends Exception
{
    public readonly array $context;

    public function __construct(
        public readonly int $userId,
        public readonly string $operation,
    ) {
        $this->context = [
            'user_id' => $userId,
            'operation' => $operation,
            'ip' => request()->ip(),
            'user_agent' => request()->userAgent(),
            'url' => request()->fullUrl(),
        ];
        parent::__construct(
            "[并发锁定] [操作:{$operation}] "
            . json_encode($this->context, JSON_UNESCAPED_UNICODE)
        );
    }

    public function render(): JsonResponse
    {
        return response()->json([
            'message' => '有请求正在处理中, 请稍后再试',
        ], 429);
    }
}

异常设计规范:

• 构造函数自动抓取请求上下文 (ip/userAgent/url)
• 携带业务参数 (userId/operation)
• render() 返回语义化 HTTP 状态码 (429/403 等), 不是默认 500
• 日志消息包含结构化上下文, 便于追溯

IP白名单 (可选)

适用于所有资金操作接口. 从应用配置中读取白名单, 任一应用配置了白名单则强制限制.

实现要点:

• 查询用户关联的所有应用, 提取 IP 字段
• 逗号分隔的 IP 需要拆分并 trim
• 白名单非空时, 请求 IP 必须在白名单内
• 白名单为空时, 不限制

注册方式

在 bootstrap/app.php 注册别名, 在路由文件挂载:

// bootstrap/app.php
$middleware->alias([
    'financial' => FinancialOperationMiddleware::class,
]);

// routes/api.php
Route::post('/withdraw', [WithdrawController::class, 'withdraw'])
    ->middleware('financial:withdraw');

中间件交付 = 创建文件 + 注册别名 + 挂载路由, 缺一不可.

第2层: 控制器

控制器负责业务级校验, 不重复中间件已做的检查.

典型流程

1. 参数校验 ($request->validate)
2. 身份验证 (2FA等)
3. 业务前置检查 (余额/状态/权限)
4. 进入第3层数据操作

第3层: 数据操作

业务锁 + 事务 + 行锁

三者配合使用, 缺一不可:

实现要点:

• 分布式锁: 防止同一笔业务被重复处理 (key与中间件不同, 使用业务级粒度)
• 数据库事务: 保证原子性, 全部成功或全部回滚
• 行锁/乐观锁: 锁定关键数据行, 防止并发读写
• 余额检查必须在锁内判断, 确保读到最新值
• 异常时回滚事务并释放锁, 确保不遗留死锁

中间件 vs 控制器锁的区别

| 维度 | 中间件锁 | 控制器锁 | |------|----------|----------| | 作用 | 拒绝并发请求 (429) | 保证业务原子性 | | 锁粒度 | 用户级 | 业务级 | | 锁时长 | 请求处理期间 | 事务执行期间 | | 失败响应 | HTTP 429 | 业务错误信息 | | 是否必须 | 是 (防刷) | 是 (防并发) |

三层锁的必要性分析

中间件锁 (HTTP层)

• 有效: 阻止同一用户的并发 HTTP 请求 (返回 429)
• 有效: 防刷/防重放攻击
• 局限: 只管 HTTP 入口, 队列/CLI 绕过
• 局限: 请求结束后锁释放, 不保护后续事务
• 结论: 第一道防线, 必须有, 但不够

业务锁 (业务层)

• 有效: 保护业务逻辑原子性 (余额检查+扣减)
• 有效: 配合数据库事务保证完整
• 锁粒度: 业务级 (如按用户/按资源)
• 结论: 核心防线, 防止同一笔业务被重复处理

数据库锁 (数据层)

• 有效: 行级锁, 防止并发读写同一行
• 必须: 在事务内使用
• 场景: 余额扣减/状态变更等关键数据
• 结论: 最后防线, 保证数据一致性

结论

三层缺一不可. 中间件锁是第一道关卡, 但真正防并发要靠控制器+数据库层. 即使中间件锁被绕过 (如队列/命令行), 控制器和数据库层仍然能保证数据正确.

新增资金操作检查清单

新增任何资金操作接口时, 必须确认:

• [ ] 是否已挂载安全中间件 (IP白名单+并发锁)
• [ ] 业务层是否有分布式锁
• [ ] 是否在数据库事务内执行
• [ ] 余额/关键数据是否使用行锁/乐观锁
• [ ] 异常时是否回滚事务并释放锁
• [ ] 测试是否覆盖并发场景 (锁持有/释放/不同用户/异常路径)

示例

examples/ 目录下的示例基于 Laravel 框架, 展示具体实现方式:

• @examples/middleware.php: 中间件完整实现 (并发锁 + try/finally + 自定义异常)
• @examples/exception.php: 自定义异常完整实现 (自动请求上下文 + render 429)
• @examples/controller.php: 控制器数据操作层实现 (业务锁 + 事务 + 行锁)
• @examples/route.php: 路由注册方式 (financial:withdraw 参数用法)
• @examples/test.php: 并发控制测试用例 (虚拟路由隔离 + 异常路径)

应用到其他框架时, 将 Laravel 特定 API 替换为对应实现即可, 方法论不变.

参考实现 (Laravel)

• 资金操作中间件: app/Http/Middleware/FinancialOperationMiddleware.php
• 并发锁定异常: app/Exceptions/FinancialOperationLockException.php
• 提现控制器: app/Http/Controllers/WithdrawController.php
• 测试用例: tests/Feature/FinancialOperationMiddlewareTest.php