深入解读 PSR-7 与中间件架构的落地实践

PSR-7 不是一顶帽子，而是中间件生态的地基

很多 PHPer 第一次接触 PSR-7 时，脑子里冒出的第一个念头是：这不就是定义了 Request 和 Response 两个接口吗？有什么好深入的？练手项目里写两行 `new Request()` 就完事了，压根没体会到它真正的价值。

但等到你开始接手大型项目，或者尝试自己封装一套框架、给现有系统加个独立的 API 网关时，才会发现——PSR-7 的真正威力不在接口本身，而在它为中间件架构提供了标准化的“消息传递协议”。谈 PSR-7 而不谈中间件，就像买了把好螺丝刀只用来撬瓶盖，可惜了。

不可变性：中间件链条中最重要的安全设计

先看一个很多人忽略的细节：PSR-7 规范要求 Request 和 Response 对象必须是不可变的。

这意味着什么？意味着你不能 `$request->setHeader('X-Foo', 'bar')`，而必须 `$request = $request->withHeader('X-Foo', 'bar')`。每次修改都返回一个新的对象实例，原对象纹丝不动。

这个设计在单次请求处理的场景下看似“多此一举”，甚至有点啰嗦。但在中间件架构里，它几乎是安全性的基石。想象一下：你的中间件栈里有日志中间件、鉴权中间件、路由中间件、业务 Controller。如果 Request 是可变的，任何一个中间件都能偷偷改写请求体或堆叠 Header，后续中间件拿到的内容就不可信了——排查问题的时候，你根本不知道是哪一环动了手脚。

有了不可变性，每个中间件只能基于当前快照派生新状态，链条里的每一步都有了“操作记录”。这在调试、日志追踪和并发场景下价值巨大。

中间件的本质：请求的“过路费”与“接力棒”

很多人对中间件的理解停留在“在 Controller 之前跑一段代码”的层面。其实中间件和装饰器模式一脉相承，它的形式化定义是：

public function process(Request $request, RequestHandler $handler): Response

你把请求“交给”中间的某个处理层，它执行自己的逻辑，然后调用 `$handler->handle($request)` 把接力棒传给下一个处理者。返回的 Response 又会沿着原路返回，逐层经过每个中间件的“归程”。

这就是著名的洋葱模型——请求从外层穿到内层，响应从内层回到外层。中间件队列不仅是前置处理，它的后置能力同样重要（比如给响应统一追加 CORS Header、记录响应耗时）。这也给了非入侵式的横切关注点提供了绝佳的生存空间——日志、限流、缓存、鉴权、跨域、请求 ID 追踪，都能写成与业务无关的独立中间件，想装就装，想卸就卸。

落地实践：从一个简单鉴权中间件说起

我们在现网项目中用 Slim 4 作为基础框架，整个中间件栈跑得明明白白。这里给一个精简的鉴权中间件实现示例：

class JwtAuthMiddleware implements MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        // 不需要鉴权的白名单路径，直接放行
        $path = $request->getUri()->getPath();
        if (in_array($path, ['/api/login', '/api/health'])) {
            return $handler->handle($request);
        }

        $token = $request->getHeaderLine('Authorization');
        try {
            $payload = (new JwtDecoder())->decode($token);
            // 关键：使用 withAttribute 把解析出的用户信息挂到 Request 上
            $request = $request->withAttribute('userId', $payload->sub);
        } catch (\Exception $e) {
            return new JsonResponse(['error' => 'Unauthorized'], 401);
        }

        // 放行到下一层
        return $handler->handle($request);
    }
}

看到 `withAttribute` 了吗？这就是 PSR-7 留给中间件通信的“后门”——不在消息本体上动刀，而是携带上下文信息。Controller 里直接取用：

$userId = $request->getAttribute('userId');

干净、无侵入、可测试。整个请求流转链路清晰可追踪，中间件增删不影响业务代码。

落地的几个坑：别被图纸上的完美骗了

实践了这些年，几个现实问题必须提醒：

第一，**PSR-7 的接口设计更偏向 Server 端，没有流式 body 支持，处理上传大文件时不能体面地流式落地**。如果要在消息层面传输大量数据，建议还是使用 PSR-7 作为“传输壳”，真正的大文件读写走 `php://memory` 或 `tmpfile` 迁移，不要把整个大 body 直接 load 进 `getBody()`。

第二，框架兼容性陷阱。PSR-7 是接口规范，不是实现。很多框架自带实现（比如 Laravel 的 Request 是基于 Symfony 组件的），实际迁移时需要注意是否原生兼容，不走代理适配层的话，容易在类型约束上报一堆错。

第三，在中间件里做重逻辑（比如调用外部 API、运行大模型推理）会让整个链路变得不可控，超时和错误处理要放在中间件自身层内捕获，别指望后续层帮你兜底。中间件栈可以被理解为“管道”，流量急转弯的结果就是管道炸裂。

总结

PSR-7 看似只是几个接口定义，但它用“不可变消息”的方式，规范了中间件架构中数据流的标准形态。真正把中间件落地到项目里的时候，你会发现：它不是某些框架的专属特性，而是一种基于标准协议的架构思想——每个组件只做一件事，通过标准化的消息传递互相协作，业务逻辑与横切关注点彻底解耦，系统的可维护性和可扩展性都有了质的飞跃。

如果你还在重复地在 Controller 里复制粘贴鉴权、CORS、日志代码——是时候重新审视 PSR-7 和中间件架构了。