OpenCart 中的 PSR-7 接口契约：psr/http-message 版本演进与 HTTP 消息接口体系解析

• 电商
• 后端

导读：本文围绕 OpenCart 仓库内 vendored 的psr/http-message组件的 CHANGELOG.md 展开，梳理该组件 1.0.0 到 1.0.1 的版本演进细节，并结合仓库内的接口源码与使用文档，完整解析 PSR-7 定义的 HTTP 消息接口体系（MessageInterface、RequestInterface、ServerRequestInterface、ResponseInterface、StreamInterface、UriInterface、UploadedFileInterface）。读者读完可以理解 PSR-7 接口契约的不可变设计原则、接口方法语义，以及在 OpenCart 的 vendor 依赖链中该组件所扮演的"纯接口定义"角色。

一、组件定位：只定义契约，不提供实现

psr/http-message是 PHP-FIG（PHP Framework Interop Group）发布的 PSR-7 标准接口包。在 OpenCart 仓库中，它位于upload/system/storage/vendor/psr/http-message/目录下，是 Composer 依赖树中的一员。

从该组件的 README.md 可以明确它的定位：

该仓库持有与 PSR-7 相关的全部接口/类/trait。注意，它不是一个 HTTP 消息的具体实现，仅仅是对 HTTP 消息的接口描述（interface）。具体行为由各实现包负责。

也就是说，psr/http-message本身不包含Request、Response等可实例化类，它只提供一组规范了"HTTP 消息长什么样"的接口。任何符合 PSR-7 的实现（如 Guzzle 的guzzlehttp/psr7、Slim 框架等）都必须实现这组接口，从而保证中间件、框架与 HTTP 客户端之间可以互相协作。

从 composer.json 可以看到该包的元信息：

{ "name": "psr/http-message", "description": "Common interface for HTTP messages", "keywords": ["psr", "psr-7", "http", "http-message", "request", "response"], "license": "MIT", "require": { "php": "^7.2 || ^8.0" }, "autoload": { "psr-4": { "Psr\\Http\\Message\\": "src/" } } }

• PHP 版本要求：^7.2 || ^8.0，即支持 PHP 7.2 及以上、包含 PHP 8.x；
• 自动加载：采用 PSR-4 规范，命名空间Psr\Http\Message\映射到src/目录。

二、版本演进全记录：从 1.0.0 初始稳定版到 1.0.1 注解修复

CHANGELOG.md 按时间倒序记录了该项目的重要变更，目前包含两个版本。

2.1 1.0.1（2016-08-06）：以文档注解修正为主的补丁版本

1.0.1是一次典型的"接口语义文档修正"版本，没有新增或移除任何方法（CHANGELOG 中 Added / Deprecated / Removed 均为 "Nothing"），全部改动集中在 Fixed 部分：

从源码看 1.0.1 的实际影响：以 MessageInterface.php 为例，withProtocolVersion()的文档块明确写着"此方法必须保持消息的不可变性（immutability），并返回一个带有新协议版本的实例"，返回类型注解为@return static。这正是 1.0.1 要传达的契约：任何with*方法都不修改原对象，而是返回一个携带变更状态的新实例。

getHeaders()的返回结构在源码中有明确示例（MessageInterface.php）：

// 将头信息表示为字符串 foreach ($message->getHeaders() as $name => $values) { echo $name . ": " . implode(", ", $values); } // 逐条发送头信息 foreach ($message->getHeaders() as $name => $values) { foreach ($values as $value) { header(sprintf('%s: %s', $name, $value), false); } }

这里印证了string[][]的含义：键是头名称，值是字符串数组（同一个头可以携带多个值）。

2.2 1.0.0（2016-05-18）：初始稳定发布

1.0.0是该项目首个稳定版本，对应被正式接受的 PSR-7 规范（"Initial stable release; reflects accepted PSR-7 specification"）。从该版本起，7 个 HTTP 消息接口的契约被固定下来，成为 PHP 生态中 HTTP 中间件互操作的基础。

三、PSR-7 接口体系全景：7 个接口的分工与继承关系

src/目录下共 7 个接口文件，构成了完整的 PSR-7 契约。核心继承关系为：

MessageInterface（HTTP 消息的公共部分） ├── RequestInterface（客户端发出的请求）＋ 请求目标/方法/URI │ └── ServerRequestInterface（服务端收到的请求）＋ 服务端参数/属性/上传文件 └── ResponseInterface（服务端返回的响应）＋ 状态码/原因短语

另有两个独立的值对象/流接口：UriInterface（URI 值对象）与StreamInterface（数据流），以及一个UploadedFileInterface（上传文件值对象）。正如 PSR7-Interfaces.md 所强调的：RequestInterface、ServerRequestInterface、ResponseInterface都继承自MessageInterface，因为请求与响应本质上都是 HTTP 消息。

3.1 MessageInterface：消息的公共契约

MessageInterface.php 定义了 HTTP 消息共有的 12 个方法，覆盖协议版本、头信息与消息体三块：

3.2 RequestInterface：客户端请求

RequestInterface.php 在MessageInterface基础上追加 4 个方法：

• getRequestTarget(): string：获取请求目标。多数情况下是 URI 的 origin-form；若无 URI 且未显式指定，必须返回"/"；
• withRequestTarget(string $requestTarget)：为绝对形式（absolute-form）、权威形式（authority-form）或星号形式（asterisk-form）等非 origin-form 场景显式设置请求目标（RFC 7230 5.3 节）；
• getMethod(): string：获取 HTTP 方法（GET、HEAD、POST、PUT、DELETE、CONNECT、OPTIONS、TRACE、PATCH 等）。注意方法名区分大小写，实现方不应改写；
• getUri(): UriInterface/withUri(UriInterface $uri, bool $preserveHost = false)：获取/设置 URI。withUri()默认会用新 URI 的 host 更新 Host 头；当$preserveHost = true时，只要原 Host 头存在且非空，就保留原 Host 头，仅当 Host 头缺失/为空时才可能用 URI 的 host 回填。

3.3 ServerRequestInterface：服务端请求

ServerRequestInterface在RequestInterface之上补充了服务端视角的数据（PSR7-Interfaces.md 有完整方法清单）：

3.4 ResponseInterface：服务端响应

ResponseInterface.php 定义了 3 个方法：

• getStatusCode(): int：3 位数字的状态码；
• withStatus(int $code, string $reasonPhrase = '')：设置状态码与可选的原因短语。若未提供原因短语，实现方可采用 RFC 7231 / IANA 注册表推荐值；非法状态码抛\InvalidArgumentException；
• getReasonPhrase(): string：获取原因短语（如 "OK"、"Not Found"），不存在时返回空字符串。

3.5 StreamInterface：消息体流抽象

StreamInterface.php 描述了一个数据流，通常包装底层 PHP 流（如php://input、文件句柄、内存流）。方法包括：

• 读取：__toString()、read($length)、getContents()、eof()、getSize()；
• 指针操作：tell()、seek($offset, $whence = SEEK_SET)、rewind()；
• 写入：write($string)；
• 状态/元数据：isSeekable()、isWritable()、isReadable()、getMetadata($key = null)；
• 资源管理：close()、detach()。

其中__toString()会尝试从头读取整个流直到结束，因此可能把大量数据载入内存（源码文档块明确警告了这一点），且为保证 PHP 字符串强转语义不得抛异常。

3.6 UriInterface 与 UploadedFileInterface

• UriInterface：URI 值对象，提供getScheme()、getAuthority()、getUserInfo()、getHost()、getPort()、getPath()、getQuery()、getFragment()及对应的with*方法，并有__toString()输出 URI 引用字符串；
• UploadedFileInterface：上传文件值对象，提供getStream()、moveTo($targetPath)（其@throws注解正是 1.0.1 的修正对象）、getSize()、getError()、getClientFilename()、getClientMediaType()。

四、不可变性：PSR-7 最核心的设计原则

在 MessageInterface.php 的类文档块中，PSR-7 明确要求：

消息被视为不可变（immutable）；所有可能改变状态的方法都必须保留当前消息的内部状态，并返回一个包含变更后状态的新实例。

这一原则带来的直接编码习惯是：with*方法的返回值必须被接收，否则变更不生效：

// 错误：丢弃了返回值，原消息没有任何变化 $response->withHeader('X-Foo', 'bar'); // 正确：接收新实例 $response = $response->withHeader('X-Foo', 'bar');

这也是 1.0.1 把@return self修正为@return static的动机——static更准确地表达了"返回的是当前实现类型的新实例"这一语义，便于 IDE 补全与静态分析。

五、与流对象配合的实战用法：头部与消息体操作

仓库内 PSR7-Usage.md 提供了可直接照搬的实操示例，这些示例同样适用于任何 PSR-7 实现（需搭配实现包，如guzzlehttp/psr7等）。

5.1 头部操作

// 添加头部 $response = $response->withHeader('My-Custom-Header', 'My Custom Message'); // 追加头部值（已有则追加，没有则新建） $response = $response->withAddedHeader('My-Custom-Header', 'The second message'); // 判断头部是否存在 $request->hasHeader('My-Custom-Header'); // false $response->hasHeader('My-Custom-Header'); // true // 取逗号拼接的字符串值 $response->getHeaderLine('My-Custom-Header'); // "My Custom Message; The second message" // 取值数组 $response->getHeader('My-Custom-Header'); // ["My Custom Message", "The second message"] // 移除头部 $request = $request->withoutHeader('Content-MD5'); // 移除 Content-Length 的后果：浏览器无法预知流长度，将下载直到流结束 $response = $response->withoutHeader('Content-Length');

注意：getHeaderLine()的逗号拼接并不适合所有头部（如Set-Cookie），此时应改用getHeader()自行决定分隔符——这是MessageInterface源码文档块中明确给出的提示。

5.2 消息体操作

方式一：先取出 body 再操作（适合频繁读写，避免$response->write()这类误用）：

$body = $response->getBody(); // 对 body 进行 read / write / seek 等操作 $response = $response->withBody($body); // 可选：body 是对象，引用同一实例

方式二：直接链式操作（适合少量操作）：

$response->getBody()->write('hello');

读取全部内容时必须先回绕指针：

$body = $response->getBody(); $body->rewind(); // 或 $body->seek(0); $bodyText = $body->getContents();

原因是流指针停在末尾时，getContents()只会读到末尾（\0）之后的空内容；如果先seek(1)再读，则会丢掉第一个字符。

前置写入（prepend）示例——流不是可随意插入的数据结构，前置必须"先读后写"：

// 假设 body 流当前内容为 "abcd" $body = $response->getBody(); $body->rewind(); $contents = $body->getContents(); // "abcd" $body->rewind(); $body->write('ef'); // 流内容变为 "efcd" $body->write($contents); // 流内容变为 "efabcd" // 更稳妥：直接在字符串层面拼接后整体回写 $contents = 'ef' . $contents; $body->rewind(); $body->write($contents);

若第二次写入前不做rewind()，write()会从当前位置继续，最终得到abcdefabcd——这正是 PSR-7 流语义中最容易踩的坑。

六、在 OpenCart 中的位置与依赖关系

psr/http-message在 OpenCart 中属于第三方依赖，被上层 HTTP 客户端库引用。在upload/system/storage/vendor/aws/aws-sdk-php/composer.json中可以看到依赖声明：

"psr/http-message": "^1.0 || ^2.0"

即 AWS SDK for PHP 要求psr/http-message提供 1.0 或 2.0 版本。SDK 内部大量以use Psr\Http\Message\ResponseInterface;、use Psr\Http\Message\StreamInterface;的方式消费这些接口（例如src/Api/Parser/AbstractParser.php、src/Api/ErrorParser/AbstractErrorParser.php等），以此解析 AWS 服务返回的响应体、错误 XML/JSON 等。

由此可以推断组件在 OpenCart 生态中的角色：OpenCart 通过 Composer 引入 AWS SDK 等库，而 SDK 依赖 PSR-7 接口契约来抽象 HTTP 传输层——OpenCart 本身并不直接实例化psr/http-message中的任何类，因为该包只定义接口，真正的消息实现由 SDK 依赖链中的实现包提供。

七、小结与阅读路径

psr/http-message的 CHANGELOG 虽然只有两个版本记录，但恰好浓缩了 PSR-7 契约的定型过程：1.0.0锚定规范本身，1.0.1则通过注解修正把"不可变 + 返回static新实例"、getHeaders()的string[][]结构、RFC 7230 请求目标形式等语义精确化。对于在 OpenCart 上做扩展开发、或者需要对接 AWS SDK 等依赖 PSR-7 的库的开发者，理解这组接口是理解 HTTP 中间件与传输层抽象的前提。

进一步阅读建议（均在本仓库内）：

• 接口速查表：PSR7-Interfaces.md
• 实战用法示例：PSR7-Usage.md
• 7 个接口源码：src/
• 包元信息与依赖约束：composer.json
• 依赖方示例：aws-sdk-php/composer.json

• 电商
• 后端