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

现代 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，再考虑“优化”。

迭代循环：

1. 选择一个边界（如日志）
2. 引入相应的 PSR 接口与适配器
3. 把内部实现替换成兼容 PSR 的实现
4. 度量替换耗时、耦合计数与性能
5. 对 HTTP 消息、容器、中间件重复上述过程

要点速览

• PSR-3、PSR-7、PSR-11、PSR-15 标准化了关键边界：日志、HTTP、DI 与管道
• 面向接口编程，用薄适配器与工厂保持实现可替换
• 从边界（控制器与基础设施）开始，逐步向内推进
• 接受 PSR-7 的不可变性；使用 with*() 时要重赋值
• 容器止步于边界；用 PSR-11，在领域中注入依赖
• 中间件承载横切关注点，用 PSR-15 保持跨框架可移植
• 用“替换耗时、耦合计数、适配器测试”来量化可移植性提升
• 不要盲从标准；只在它们能降低风险与成本的地方使用

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

本作品采用《CC 协议》，转载必须注明作者和本文链接