ThinkPHP 8中间件深度实战：构建可插拔的API限流与审计管道

一、理解ThinkPHP 8中间件的执行流水线

ThinkPHP 8的中间件彻底拥抱了PSR-15风格，围绕 `handle` 方法和 `Request` 对象构建了一条可配置的管道。当一个请求进来时，它依次穿过全局中间件、路由中间件和控制器中间件，前一个中间件的返回结果会流入下一个中间件，整个链条就像一条工厂流水线。更重要的是，中间件可以在请求到达控制器之前做事情，也可以在控制器处理完准备返回响应时再做一层包裹，这个“可以挂在前和后”的能力正是构建日志和限流的基础。

与旧版相比，一个明显的改进是中间件不再依赖继承某个特定基类，只要实现 `thinkmiddleware` 接口或者直接用一个闭包就可以。这给了开发者很大的自由度——你可以把中间件写得非常轻量，也能在构造函数里注入各种服务，完全看需求而定。

二、第一个中间件：滑动窗口限流器

API网关最基础的保障就是别被突发流量打穿。之前我们用过一个粗糙的固定窗口计数器，但因为时间窗口边界上的突变问题，经常出现“这一秒正常下一秒被限”的误伤。这次借助Redis的 `zset` 实现一个简单的滑动窗口限流，把它封装成一个中间件，可以按路由灵活挂载。

先定义中间件类，放在 `app/middleware` 目录下：

<?php
namespace appmiddleware;

use thinkRequest;
use thinkResponse;
use thinkfacadeCache;

class RateLimit
{
    // 窗口宽度，单位秒
    protected $window = 60;
    // 窗口内最大请求数
    protected $maxRequests = 100;

    public function handle(Request $request, callable $next): Response
    {
        // 用客户端IP加路由标识作为限流key，更精细的话可以用用户ID
        $key = 'rate_limit:' . $request->ip() . ':' . $request->baseUrl();
        $now = time();
        $windowStart = $now - $this->window;

        // 使用Redis有序集合，member用微秒时间戳保证唯一，score为秒级时间戳
        $redis = Cache::store('redis')->handler();
        // 移除窗口外的记录
        $redis->zRemRangeByScore($key, 0, $windowStart);
        // 统计当前窗口内的请求数量
        $currentCount = $redis->zCard($key);

        if ($currentCount >= $this->maxRequests) {
            // 触发限流，返回429状态码
            return Response::create([
                'code' => 429,
                'msg'  => '请求频率过高，请稍后重试',
                'data' => null
            ], 'json', 429);
        }

        // 记录本次请求，score用当前时间，member用微秒时间戳防止并发冲撞
        $redis->zAdd($key, $now, $now . '.' . microtime(true));
        // 给key设置过期时间，避免冷数据占用内存
        $redis->expire($key, $this->window + 10);

        // 继续执行后续中间件和控制器
        return $next($request);
    }
}

这里的核心逻辑是每次请求时，先把当前滑动窗口以外的旧记录删掉，然后统计剩下的请求数量。如果数量超过阈值就直接返回一个429响应，后续的中间件和控制器都不会再执行。这种在“前”阶段就决定是否放行的模式，非常适合做安全拦截。

需要注意的是，我使用了 `Cache::store(‘redis’)->handler()` 来获取原生的 Redis 连接对象，因为 `zRemRangeByScore` 这类高级指令没被框架默认的缓存类直接包装。在项目里确保 `config/cache.php` 中配置好了 redis 连接即可。

三、第二个中间件：自动审计日志

旧系统里有一项需求是记录所有修改类接口的请求参数和响应摘要，最初是在每个控制器方法末尾手动调用一个 `LogService`。随着接口数量增加，这个调用经常被遗漏，导致审计数据不完整。有了中间件管道，可以把审计逻辑从业务代码里彻底剥离出来，而且利用“后”阶段的能力，可以在响应返回之前自动捕获需要的信息。

<?php
namespace appmiddleware;

use thinkRequest;
use thinkResponse;
use thinkfacadeDb;

class AuditLog
{
    public function handle(Request $request, callable $next): Response
    {
        // 记录请求开始时间，用于计算耗时
        $startTime = microtime(true);
        // 获取请求原始数据（注意文件上传等特殊情况）
        $rawInput = $request->getInput();

        // 先执行后续处理，拿到响应
        $response = $next($request);

        // 只记录非查询类请求，结合路由或请求方法判断
        if (in_array($request->method(), ['POST', 'PUT', 'DELETE'])) {
            $endTime = microtime(true);
            Db::table('audit_logs')->insert([
                'url'         => $request->baseUrl(),
                'method'      => $request->method(),
                'request_ip'  => $request->ip(),
                'input'       => $rawInput,
                'http_status' => $response->getCode(),
                'duration_ms' => round(($endTime - $startTime) * 1000, 2),
                'created_at'  => date('Y-m-d H:i:s'),
            ]);
        }

        return $response;
    }
}

这里的妙处在于，`$next($request)` 会一直往下执行到控制器并返回 `Response` 对象，我们在这个点上既拿到了请求信息，又拿到了最终的响应状态码。然后顺势写入数据库，整个过程对控制器完全透明。因为写日志用的是 `Db` 类的同步写入，如果担心性能，可以换成异步投递到消息队列，但核心结构不变。

四、管道编排：让中间件各就其位

两个中间件写好了，接下来就是把它们组合成一条有效的管道。ThinkPHP 8 可以在全局、路由和控制器三个层面挂载中间件，排列顺序就是执行顺序。对于我们的场景，限流要尽量靠前，减少无用资源消耗；审计日志理论上应该在最外层包裹，这样才能记录到完整的请求和响应，但它又要在内部所有逻辑执行完之后再记录，所以适合放在管道靠后的位置，但仍在路由中间件中。

在路由定义文件 `route/app.php` 里，为需要保护的接口组统一配置：

<?php
use thinkfacadeRoute;

Route::group('api/v1', function () {
    // 内部路由定义
    Route::post('users', 'User/save');
    Route::put('users/:id', 'User/update');
    Route::delete('users/:id', 'User/delete');
    Route::get('users', 'User/index');
})->middleware([
    appmiddlewareRateLimit::class,
    appmiddlewareAuditLog::class,
    appmiddlewareAuth::class, // 假设还有一个鉴权中间件
]);

按照这个顺序，请求会先经过 `RateLimit` 检查，如果触发限流就直接返回，不会继续走到后面的审计和鉴权。限流放行后，`AuditLog` 启动计时并调用 `$next`，将请求转给 `Auth` 鉴权，再转给控制器，最后控制器的响应原路返回到 `AuditLog` 完成日志记录。整个流程行云流水。

五、踩过的两个坑与绕过方法

第一个坑：中间件中抛出的异常被全局异常处理器拦截后，审计日志可能缺失。因为我们的审计日志是在 `$next($request)` 返回后才执行的，如果下游中间件或控制器抛了异常，`AuditLog` 里的写库代码就不会运行。解决办法是在 `AuditLog` 里用 try-catch 包裹 `$next`，捕获到异常后先记录日志（包括异常信息），再把异常重新抛出，交给全局处理器：

try {
    $response = $next($request);
} catch (Throwable $e) {
    // 记录异常时审计日志
    Db::table('audit_logs')->insert([... 'exception' => $e->getMessage() ...]);
    throw $e; // 继续抛出，保持原有错误处理流程
}

第二个坑：限流中间件在多实例部署下需要共享状态。上面用 Redis 做计数器自然解决了这个问题，但如果一开始用的是文件缓存或进程内存，换成多容器部署时就会完全失效。因此建议从一开始就选择集中式存储来维护限流状态，Redis 是最常见的选择。

六、让中间件可配置：从硬编码到参数化

当前限流中间件的窗口大小和最大请求数都写死在类属性里，不同接口可能需要不同的限流策略。ThinkPHP 8 支持在路由中给中间件传参，我们可以利用这个特性让限流值变成可动态配置的。

修改 `RateLimit` 中间件，通过构造函数接收参数：

protected $window;
protected $maxRequests;

public function __construct(int $window = 60, int $maxRequests = 100)
{
    $this->window = $window;
    $this->maxRequests = $maxRequests;
}

然后在路由中指定参数：

Route::post('users', 'User/save')->middleware([
    appmiddlewareRateLimit::class . ':30:50', // 30秒窗口最多50次
]);

参数用冒号分隔，自动传入构造函数。这种参数化能力让同一个中间件类可以以不同的面孔出现在不同的路由上，复用性大大提升。

七、总结

这次从5.1跳到8.0，中间件管道的改造是让我感觉“赚到了”的最大因素之一。横切关注点被整齐地装进不同的中间件类里，路由配置一目了然地展示了每个接口经过了哪些拦截器，审计和限流这两个曾经最让我头疼的模块终于变成了可拆卸的组件。后续如果老板说“加上一个防重复提交的机制”，我只需要再写一个中间件，往管道里一插就行了。

如果你的ThinkPHP项目还在用老方法处理请求拦截，不妨拿一个不那么核心的模块试试管道模式。哪怕只把日志记录剥离成一个中间件，你也能立刻体会到那种“洋葱皮一层层剥开”的秩序感。