当前位置：首页 > news >正文

一文读懂 PHP PSR 接口 PSR-3、PSR-7、PSR-11、PSR-15 完整指南

news 2026/7/3 1:46:41

现代 PHP 的选择很多。这本来是好事，但一到升级框架、替换 Logger，或在团队间统一服务时，你会发现：看不见的耦合（类型、方法签名、约定）会把小改动变成大手术。

本文用通俗的话讲清四个关键标准——PSR-3（日志）、PSR-7（HTTP 消息）、PSR-11（容器）和 PSR-15（HTTP 中间件）——如何在代码里建立稳定的边界（seams）。入门读者能拿到清晰定义和可直接复用的示例；进阶读者可以参考迁移策略、取舍与度量方法。

你将学到

用直白语言解释这些标准到底是什么
如何按小步引入，每个 PSR 都附带可直接落地的代码
一个小案例：低成本替换第三方库或框架
常见坑（不可变性、过度适配、性能顾虑）以及哪些场景不该用 PSR
一份检查清单与轻量指标，帮你证明确实降低了锁定（lock-in）

关键概念与定义

什么是 PSR？由 PHP-FIG 发布的社区标准，侧重接口与规范。它只约定“契约”，不规定实现，因此不同库可以顺畅互通。

接口 vs 实现接口规定“做什么”，实现负责“怎么做”。代码若依赖接口，就能在不改调用点的前提下替换实现。

PSR-3（日志）

Psr\Log\LoggerInterface定义了debug()、info()、error()等方法，以及通用的log($level, $message, array $context = [])。任何符合 PSR-3 的 Logger（如 Monolog）都能满足这个契约。

PSR-7（HTTP 消息）

为 HTTP 请求、响应、流、URI、上传文件提供接口（Psr\Http\Message\*）。对象是不可变的，例如withHeader()会返回新实例；好处是行为可预测、共享安全。

PSR-11（容器）

Psr\Container\ContainerInterface是一个很小的依赖注入契约：get(string $id): mixed与has(string $id): bool。用它，框架与库之间无需绑定某个特定的 DI 实现。

PSR-15（HTTP 处理器与中间件）

Psr\Http\Server\RequestHandlerInterface与MiddlewareInterface规范了服务器端中间件如何处理ServerRequestInterface并返回ResponseInterface。这是 HTTP 管道的通用形态。

为什么是这四个？它们覆盖了多数应用的关键边界：日志、HTTP、依赖装配和跨请求的 HTTP 行为。把这些地方标准化，只需很少改动就能显著提升可移植性。

新手提示：若觉得缩写抽象，可以先看示例再回来看定义。进阶提示：这些 PSR 可分步引入，不需要大重构。

分步落地框架

第 1 步 —— 用 PSR 接口包住外部库

先改“你的代码依赖谁”，别急着动第三方库。加一层薄的适配器：业务代码只面向 PSR，适配器去对接具体库。

示例：把遗留 Logger 适配成 PSR-3

<?php use Psr\Log\LoggerInterface; use Psr\Log\LogLevel; final class LegacyToPsrLogger implements LoggerInterface { public function __construct(private LegacyLogger $legacy) {} public function emergency($message, array $context = []) { $this->log(LogLevel::EMERGENCY, $message, $context); } public function alert($message, array $context = []) { $this->log(LogLevel::ALERT, $message, $context); } public function critical($message, array $context = []) { $this->log(LogLevel::CRITICAL, $message, $context); } public function error($message, array $context = []) { $this->log(LogLevel::ERROR, $message, $context); } public function warning($message, array $context = []) { $this->log(LogLevel::WARNING, $message, $context); } public function notice($message, array $context = []) { $this->log(LogLevel::NOTICE, $message, $context); } public function info($message, array $context = []) { $this->log(LogLevel::INFO, $message, $context); } public function debug($message, array $context = []) { $this->log(LogLevel::DEBUG, $message, $context); } public function log($level, $message, array $context = []): void { $text = is_string($message) ? $message : json_encode($message); $this->legacy->write(strtoupper($level), $this->interpolate($text, $context)); } private function interpolate(string $message, array $context): string { $replace = []; foreach ($context as $key => $val) { $replace['{'.$key.'}'] = is_scalar($val) ? (string)$val : json_encode($val); } return strtr($message, $replace); } }

新手提示：继续用你现有的 Logger，只是通过适配器注入，让其他代码依赖LoggerInterface。进阶提示：把适配器集中放在Infrastructure\Bridge\VendorX命名空间，边界更清晰。

第 2 步 —— 让 HTTP 消息统一到 PSR-7

把 HTTP 作为清晰的边界。让控制器与库接受/返回Psr\Http\Message\RequestInterface与ResponseInterface，你就能在不同框架或服务器之间平滑迁移。

示例 A（上手快、具体）：Nyholm PSR-7

<?php use Nyholm\Psr7\Response; use Psr\Http\Message\ResponseInterface; final class HelloController { public function __invoke(string $name = 'world'): ResponseInterface { $response = new Response(200, ['Content-Type' => 'application/json']); $response->getBody()->write(json_encode(['message' => "Hello, {$name}!"])); return $response; } }

示例 B（更通用、与实现无关）：使用工厂。PSR-7 只定义接口；用 PSR-17 工厂来创建实例更干净（如果已有相关依赖）。

<?php use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\StreamFactoryInterface; use Psr\Http\Message\ResponseFactoryInterface; final class JsonResponder { public function __construct( private ResponseFactoryInterface $responses, private StreamFactoryInterface $streams ) {} public function ok(array $data): ResponseInterface { $body = $this->streams->createStream(json_encode($data)); return $this->responses ->createResponse(200) ->withHeader('Content-Type', 'application/json') ->withBody($body); } }

新手提示：如果“工厂”听起来复杂，先用示例 A。进阶提示：在库代码里优先使用 PSR-17，才能真正保持与框架无关。

第 3 步 —— 用 PSR-11 解耦依赖装配

让应用通过构造函数接收依赖，把容器的使用放在系统边界。

示例：PSR-11 的应用引导

<?php use Psr\Container\ContainerInterface; use Psr\Log\LoggerInterface; final class App { public function __construct(private ContainerInterface $container) {} public function run(): void { $logger = $this->container->get(LoggerInterface::class); $logger->info('App started'); // 通过容器解析处理器、路由器等 } }

新手提示：避免在领域类中直接调用容器。把它们需要的依赖注入即可。进阶提示：用接口名绑定（如LoggerInterface::class），在引导阶段用别名映射到实现。

第 4 步 —— 用 PSR-15 组合 HTTP 管道

鉴权、限流、缓存等横切问题应放在中间件里，而不是处理器里。

示例：耗时统计响应头中间件

<?php use Psr\Http\Message\ResponseInterface; use Psr\Http\Message\ServerRequestInterface; use Psr\Http\Server\MiddlewareInterface; use Psr\Http\Server\RequestHandlerInterface; final class TimingMiddleware implements MiddlewareInterface { public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface { $start = microtime(true); $response = $handler->handle($request); $elapsed = number_format((microtime(true) - $start) * 1000, 2); return $response->withHeader('X-Response-Time-ms', (string) $elapsed); } }

新手提示：先加一个中间件（如请求日志），再逐步扩展到完整管道。进阶提示：让中间件保持纯粹——只依赖请求/处理器/响应，避免读写全局状态。

小案例

背景：你维护一套内部 API，基于某个框架 X。它使用自研 Logger、框架私有的 Request/Response 类型和专有中间件。你想降低锁定，为将来迁移到 Slim 或 Mezzio 做准备。

目标：用四个小步（可回滚）降低耦合，不打断日常迭代。

动作 1 —— 在边界采用 PSR-3：把控制器/服务中对CustomLogger的直接引用改为Psr\Log\LoggerInterface，加上第一步的适配器，旧 Logger 仍在背后运行。结果：代码不再依赖旧 Logger；切到 Monolog 只需在装配处改一行。
动作 2 —— 在处理器采用 PSR-7：入口把框架 Request 转成 PSR-7 对象并向内传递；应用层返回 PSR-7 Response；最外层再转回框架类型。结果：核心逻辑只依赖 PSR-7。
动作 3 —— 在引导采用 PSR-11：以Psr\Container\ContainerInterface暴露容器；应用代码通过构造函数接收依赖（优先接口）。结果：以后换容器只影响引导配置。
动作 4 —— 管道采用 PSR-15：把现有过滤器/中间件包成 PSR-15 适配器；新中间件直接按 PSR-15 编写。结果：管道逻辑可移植；换框架时可复用同一批中间件。

切换：当你采用新框架时，只需重写最外层的适配器（请求/响应转换、路由装配）。领域、处理器和中间件保持不变。

常见坑与规避

把 PSR 当“魔法”。接口治不了设计问题。让领域逻辑独立于框架与容器，把转换放在边界。
忘记 PSR-7 的不可变性。withHeader()会返回新对象。要链式调用或重赋值，不要指望原地修改。
让供应商类型“漏进来”。入口若收 PSR 类型，却在某个 Helper 返回供应商类型，就把耦合带回来了。请在边界内外都用 PSR。
过度工程化的适配器。没必要处处加适配器，先从热点（日志、HTTP、管道、容器）下手。
适配器不写测试。桥接层容易出现细节问题（Header 大小写、Stream 读写位置）。围绕适配器写小而专注的测试。
没数据支撑的性能担忧。多几个对象带来的开销通常比不上 I/O。如果出现回归，先 Profile 再优化（复用响应原型、Stream 工厂）。
盲目“拿来主义”。若某个边界几乎不会变化，强行上 PSR 只会增加复杂度。标准是工具，不是教条。

示例和一些小的案例

PSR-3：Monolog；很多框架自带兼容 PSR-3 的 Logger
PSR-7：Laminas Diactoros、Nyholm/psr7、Guzzle PSR-7
PSR-11：PHP-DI、Laminas ServiceManager、Symfony 容器（兼容 PSR-11）、League Container
PSR-15：Slim（中间件管道）、Mezzio（Laminas）、Relay、middlewares/ 生态
找出供应商类型渗透的位置（日志、HTTP、DI、管道）
把这些缝合线的方法签名改成 PSR 接口
加最小化适配器，确保旧代码仍能跑
写针对性的测试：状态行、Header、Body 流、Middleware 顺序
逐步把内部实现替换成 PSR 兼容的实现
跟踪“替换耗时”和“耦合计数”

PSR-3 在领域服务中的用法

final class UserService { public function __construct(private Psr\Log\LoggerInterface $logger) {} public function register(string $email): void { $this->logger->info('Registering user', ['email' => $email]); // ... } }

PSR-15 处理器示例

final class HelloHandler implements Psr\Http\Server\RequestHandlerInterface { public function handle(Psr\Http\Message\ServerRequestInterface $request): Psr\Http\Message\ResponseInterface { $name = $request->getQueryParams()['name'] ?? 'world'; $res = new Nyholm\Psr7\Response(200); $res->getBody()->write("Hello, {$name}!"); return $res->withHeader('Content-Type', 'text/plain'); } }

如何度量与迭代

你需要证据来证明标准化确实有帮助。追踪简单且有意义的信号：

替换耗时（Swap time）：替换一个 Logger 或 HTTP 客户端要多久？合理目标是“分钟到小时”，而不是“几天”。
耦合计数（Coupling score）：在代码库里 grep 供应商类型（如框架的 Request/Response）。随着 PSR 替换，它们的数量应当逐步下降。
边界测试覆盖率：为适配器的状态行、Header、Stream、Middleware 顺序编写测试。
上手摩擦：新同学只看接口就能理解流程。核心代码里供应商概念越少，上手越快。
运行时健康：采用 PSR-7/15 后观察延迟与内存。如有回归，先 Profile，再考虑“优化”。

迭代循环：