ShopXO 中的 PSR-7 HTTP Message 接口规范解析:psr/http-message 包版本演进与 ThinkPHP8 落地实践
ShopXO 中的 PSR-7 HTTP Message 接口规范解析:psr/http-message 包版本演进与 ThinkPHP8 落地实践
本文围绕当前仓库中 vendor/psr/http-message/CHANGELOG.md 这份版本变更记录展开,系统梳理 PSR-7 规范在
psr/http-message包 1.0.0 → 1.0.1 演进过程中的关键修正,并结合仓库内该包完整的 7 个接口源码、官方使用文档,以及 ShopXO 所依赖的 ThinkPHP8 框架源码,说明这套「HTTP 消息抽象层」在真实电商项目中的依赖关系与落地调用链。读完本文,你将掌握 PSR-7 七大接口的职责划分、全部核心方法签名与不可变性设计原则,并能在 ShopXO 中定位 PSR-7 响应对象是如何被 ThinkPHP 转换与消费的。
一、先看这份 CHANGELOG 讲了什么
vendor/psr/http-message/CHANGELOG.md 是 PHP-FIG 组织发布的 psr/http-message 组件的官方变更记录,按时间倒序记载了该包两个正式版本的全部变化:
| 版本 | 日期 | 性质 |
|---|---|---|
| 1.0.1 | 2016-08-06 | 对 1.0.0 的注解(annotation)修正版 |
| 1.0.0 | 2016-05-18 | 首个稳定版,标志着 PSR-7 规范被正式接受 |
两个版本均无新增(Added)、废弃(Deprecated)或移除(Removed)内容,1.0.1 的全部变更集中在 Fixed(修复) 一类,共 5 项,全部是对接口文档注解的修正,而非运行时行为变更。这充分说明 psr/http-message 是纯接口定义包——正如其 README.md 所强调的:"This is not a HTTP message implementation of its own. It is merely an interface that describes a HTTP message."(它本身不是 HTTP 消息的实现,仅仅是描述 HTTP 消息的接口)。
1.0.1 的五项注解修复逐条解读
- 接口中所有
@return self注解统一改为@return static:这是语义更精确的修正。self指"当前类",而static指"调用时的实际类"。PSR-7 的with*系列方法要求返回"保留原消息内部状态、携带新状态的新实例",当实现类被继承时,用static才能准确表达返回类型是子类实例。这一修正更贴合规范语义。 MessageInterface::getHeaders()的返回注解改为string<a href="https://link.gitcode.com/i/2ba4e967757d9000570afeb1fe99dea3" target="_blank">][]:明确表达该方法返回的是"字符串的嵌套数组"——外层是header 名 => 值数组的关联数组,内层每个值是字符串数组。这一点在 [MessageInterface.php 的源码注释中也有对应描述。RequestInterface::withRequestTarget()的@link注解修正指向 RFC 7230 的正确章节:该方法与 HTTP 请求目标(request-target)的四种形式(origin-form、absolute-form、authority-form、asterisk-form)相关,规范出处是 RFC 7230 第 5.3 节,修正后的链接更精确。ServerRequestInterface::withUploadedFiles()的参数注解补充参数名$uploadedFiles:原本只有类型提示array,补齐参数名后文档更完整。- 修正
UploadedFileInterface::moveTo()的@throws注解:此前注解中引用了错误的参数名,现更正为正确引用方法参数。
可以看出,1.0.1 是一次「文档精确性」维护版本。它不改变任何接口方法签名,但让 IDE 提示、静态分析与开发者查阅时的体验大幅提升——这也解释了为何
psr/http-message从 2016 年 1.0.1 发布至今一直保持稳定,成为整个 PHP 生态 HTTP 抽象的基石。
二、PSR-7 七大接口:职责划分与继承关系
psr/http-message 包通过 Composer 的 PSR-4 自动加载(见 composer.json),将命名空间 Psr\Http\Message\ 映射到 src/ 目录,共定义了 7 个接口。仓库自带的接口速查表 PSR7-Interfaces.md 给出了完整方法清单,这里结合源码逐一展开。
接口总览
| 接口 | 职责 | 源码文件 |
|---|---|---|
MessageInterface |
HTTP 消息(请求与响应的公共部分) | src/MessageInterface.php |
RequestInterface |
客户端发出的请求(继承 MessageInterface) |
src/RequestInterface.php |
ServerRequestInterface |
服务端接收到的请求(继承 RequestInterface) |
src/ServerRequestInterface.php |
ResponseInterface |
服务端发出的响应(继承 MessageInterface) |
src/ResponseInterface.php |
StreamInterface |
数据流抽象 | src/StreamInterface.php |
UriInterface |
URI 值对象 | src/UriInterface.php |
UploadedFileInterface |
HTTP 请求中上传的文件值对象 | src/UploadedFileInterface.php |
核心继承关系(源码中可直接验证):
RequestInterface extends MessageInterface(RequestInterface.php)ServerRequestInterface extends RequestInterface(ServerRequestInterface.php)ResponseInterface extends MessageInterface(ResponseInterface.php)
正如文档所述:Request 与 Response 本质上都是 HTTP 消息,因此 RequestInterface、ServerRequestInterface、ResponseInterface 都继承自 MessageInterface;使用 ServerRequestInterface 时,RequestInterface 与 MessageInterface 的方法同样可用。
2.1 MessageInterface:HTTP 消息的公共契约
HTTP 消息 = 协议版本 + 头部 + 消息体。该接口定义了 10 个方法,全部集中在 src/MessageInterface.php:
| 方法 | 说明 | 返回/参数要点 |
|---|---|---|
getProtocolVersion() |
获取 HTTP 协议版本 | 仅含版本号字符串,如 "1.1"、"1.0" |
withProtocolVersion(string $version) |
返回带指定协议版本的新实例 | 不可变:保留原状态,返回新实例 |
getHeaders() |
获取全部头部 | 返回 string[][]:名称 => 字符串值数组,保留原始大小写 |
hasHeader(string $name) |
按名称(不区分大小写)判断头部是否存在 | 返回 bool |
getHeader(string $name) |
获取单个头部的值数组 | 不存在时返回空数组 |
getHeaderLine(string $name) |
获取单个头部的逗号拼接字符串 | 不存在时返回空字符串;不适合逗号拼接的头部请改用 getHeader() |
withHeader(string $name, $value) |
替换指定头部为新值 | $value 可为字符串或字符串数组;头部名不区分大小写但保留原大小写 |
withAddedHeader(string $name, $value) |
向指定头部追加值 | 已存在则追加,不存在则新建 |
withoutHeader(string $name) |
移除指定头部 | 大小写不敏感 |
getBody() |
获取消息体 | 返回 StreamInterface |
withBody(StreamInterface $body) |
返回带新消息体的实例 | 消息体必须是流对象 |
2.2 RequestInterface:客户端请求
在 MessageInterface 基础上新增 4 个方法(src/RequestInterface.php):
| 方法 | 说明 |
|---|---|
getRequestTarget() |
获取请求目标,默认是 URI 的 origin-form;无 URI 且未指定时返回 "/" |
withRequestTarget(string $requestTarget) |
返回带指定请求目标的实例,支持 absolute-form、authority-form、asterisk-form |
getMethod() |
获取 HTTP 方法(GET、POST、PUT 等,方法名大小写敏感) |
withMethod(string $method) |
返回带指定方法的实例,非法方法抛 InvalidArgumentException |
getUri() |
获取 URI 实例(UriInterface) |
withUri(UriInterface $uri, bool $preserveHost = false) |
返回带新 URI 的实例;默认根据新 URI 的 host 更新 Host 头,$preserveHost=true 时保留原 Host 头 |
值得注意的规范细节:构造请求时,若未提供 Host 头,实现必须尝试从 URI 中设置它;URI 无 host 时,原有 Host 头会被保留。
2.3 ServerRequestInterface:服务端接收的请求
它把 PHP 超级全局变量($_SERVER、$_COOKIE、$_GET、$_POST、$_FILES)以及请求派生的属性封装成统一接口(src/ServerRequestInterface.php):
| 方法 | 对应数据来源 | 说明 |
|---|---|---|
getServerParams() |
$_SERVER |
服务端参数,不可变,规范不提供修改方法 |
getCookieParams() / withCookieParams(array) |
$_COOKIE |
Cookie 数据;withCookieParams() 不得改动请求的 Cookie 头 |
getQueryParams() / withQueryParams(array) |
$_GET |
反序列化的查询参数;设置参数不得改变 URI 与 server params |
getUploadedFiles() / withUploadedFiles(array) |
$_FILES |
返回 UploadedFileInterface 实例组成的规范化树 |
getParsedBody() / withParsedBody($data) |
$_POST / 反序列化请求体 |
仅接受数组、对象或 null;JSON 请求体可借此注入反序列化结果 |
getAttributes() / getAttribute($name, $default = null) / withAttribute() / withoutAttribute() |
派生数据(路由匹配结果、解密 Cookie 等) | 属性可变的请求级数据容器 |
2.4 ResponseInterface:服务端响应
只新增 3 个方法(src/ResponseInterface.php):
| 方法 | 说明 |
|---|---|
getStatusCode() |
3 位整数状态码 |
withStatus(int $code, string $reasonPhrase = '') |
返回带状态码的新实例;未提供原因短语时可使用 RFC 7231 / IANA 推荐默认值 |
getReasonPhrase() |
获取状态码关联的原因短语,无则返回空字符串 |
2.5 StreamInterface:数据流抽象
消息体不再是普通字符串,而是一个可读写、可定位的流对象(src/StreamInterface.php),方法如下:
| 方法 | 说明 |
|---|---|
__toString() |
从流头读到流尾并返回字符串(可能占用大量内存) |
close() |
关闭流及底层资源 |
detach() |
分离底层资源 |
getSize() |
已知则返回字节数,未知返回 null |
tell() / eof() |
当前指针位置 / 是否到达流尾 |
isSeekable() / seek($offset, $whence = SEEK_SET) / rewind() |
定位能力;seek() 的 $whence 取值与 PHP fseek() 一致(SEEK_SET/SEEK_CUR/SEEK_END) |
isWritable() / write($string) |
写入能力,返回写入字节数 |
isReadable() / read($length) |
读取能力 |
getContents() |
返回剩余内容字符串 |
getMetadata(?string $key = null) |
流元数据,键与 stream_get_meta_data() 一致 |
2.6 UriInterface:URI 值对象
遵循 RFC 3986 的不可变值对象(src/UriInterface.php):
- 读取方法:
getScheme()(小写归一化、不含冒号)、getAuthority()([user-info@]host[:port]格式)、getUserInfo()、getHost()(小写)、getPort()(标准端口返回null)、getPath()、getQuery()(不含?)、getFragment()(不含#)、__toString()(按 RFC 3986 拼接为 URI reference)。 - 写入方法(全部不可变、返回新实例):
withScheme()、withUserInfo($user, $password = null)、withHost()、withPort(?int)、withPath()、withQuery()、withFragment()。所有路径/查询/片段均需百分号编码且不重复编码;端口超出 TCP/UDP 范围必须抛异常。
2.7 UploadedFileInterface:上传文件值对象
封装 $_FILES 中的单个文件(src/UploadedFileInterface.php):
| 方法 | 说明 |
|---|---|
getStream() |
返回代表上传文件的 StreamInterface;moveTo() 调用后再次调用必须抛异常 |
moveTo(string $targetPath) |
移动文件到新位置(move_uploaded_file() / rename() 的跨环境替代);重复调用必须抛异常 |
getSize() |
文件字节数,未知返回 null |
getError() |
返回 PHP UPLOAD_ERR_XXX 常量之一 |
getClientFilename() |
客户端提交的文件名(不可信任,可能有恶意内容) |
getClientMediaType() |
客户端提交的媒体类型(同样不可信任) |
三、核心设计原则:消息不可变性(Immutability)
贯穿全部 7 个接口的最重要设计原则是不可变性。在 MessageInterface.php 的源码注释中明确写道:
Messages are considered immutable; all methods that might change state MUST be implemented such that they retain the internal state of the current message and return an instance that contains the changed state.
即:所有 with* 方法不得修改原实例,而是保留原实例内部状态、返回一个携带新状态的新实例。RequestInterface、ResponseInterface、ServerRequestInterface、UriInterface、UploadedFileInterface 的注释中都有同样的不可变声明。
这一设计带来的工程收益:
- 线程/协程安全:消息对象可在请求处理流程中安全共享,不存在中途被改坏的问题;
- 可追溯性:每个中间件产生的新消息都是独立对象,原消息保持不变,便于日志与调试;
- 行为可预期:
$response->withHeader(...)不会修改$response,返回值才是新响应——这是下面使用部分频繁强调"接收返回值"的原因。
四、PSR-7 实战用法:头部与消息体操作
仓库自带的 PSR7-Usage.md 提供了一份可直接运行的实操指南。PSR-7 规范的意义在于:所有遵循该规范的实现行为一致,因此下面示例可运行于任何 PSR-7 实现(如 guzzlehttp/psr7、zendframework/zend-diactoros 等)。示例约定 $request 是 RequestInterface 对象,$response 是 ResponseInterface 对象。
4.1 头部(Header)操作
// 向响应添加头部(返回新响应,需接收返回值)
$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(响应上有)
// 获取逗号拼接的头部值(请求、响应通用)
$request->getHeaderLine('Content-Type'); // 返回:"text/html; charset=UTF-8"
$response->getHeaderLine('My-Custom-Header'); // 返回:"My Custom Message; The second message"
// 获取头部值的数组形式
$request->getHeader('Content-Type'); // 返回:["text/html", "charset=UTF-8"]
$response->getHeader('My-Custom-Header'); // 返回:["My Custom Message", "The second message"]
// 移除头部(不区分大小写)
$request = $request->withoutHeader('Content-MD5'); // 移除过时的 Content-MD5
$response = $response->withoutHeader('Content-Length'); // 浏览器将无法预知流大小,会持续下载到流结束
注意 with* / without* 方法返回的是新实例,务必用返回值赋值,这正是不可变性原则的实战体现。
4.2 消息体(Body)操作:两种姿势
方式一:先取出 Body 对象单独操作(推荐)——只需调用一次 getBody(),避免 $response->write() 之类的误用:
$body = $response->getBody();
// 对 body 进行 read / write / seek 等操作
// ...
$response = $response->withBody($body); // 该语句可选:对象引用本身未变
方式二:直接在响应上链式操作——适合操作较少的场景:
$response->getBody()->write('hello');
4.3 读取消息体内容:指针位置是坑
流有内部指针,getContents() 只返回剩余内容,因此读取前必须先复位指针:
$body = $response->getBody();
$body->rewind(); // 或 $body->seek(0);
$bodyText = $body->getContents();
若先 $body->seek(1) 再 getContents(),首个字符会被跳过——因为起始指针是 1 而非 0,因此规范强烈建议使用 rewind()。
4.4 追加与前置内容
追加(append):直接 write() 即可:
$response->getBody()->write('Hello');
$body = $request->getBody(); // StreamInterface
$body->write('xxxxx');
前置(prepend):流的写入行为是在当前指针位置覆盖写入,因此必须先复制原内容再写入:
// 假设响应体初始为空,先写入 "abcd"
$body = $response->getBody();
$body->write('abcd');
// 回到流头,再写入 'ef' —— 此时流内容为 "efcd"(覆盖前两个字符)
$body->seek(0);
$body->write('ef');
更稳妥的前置方案——分两步重写:
// 假设响应体仅含 "abcd"
$body = $response->getBody();
$body->rewind();
$contents = $body->getContents(); // "abcd"
$body->rewind(); // 必须再次复位,否则 write() 会追加导致 "abcdefabcd"
$body->write('ef'); // "efcd"
$body->write($contents); // "efabcd"
关键坑点:
getContents()在读取过程中会推进流指针,若不再次rewind(),后续write()会以追加方式写入,导致结果变为abcdefabcd。
字符串拼接方式(最简单):
$body = $response->getBody();
$body->rewind();
$contents = $body->getContents(); // "efabcd"
$contents = 'ef' . $contents;
$body->rewind();
$body->write($contents);
五、在 ShopXO / ThinkPHP8 中的实际落地
psr/http-message 不仅是抽象规范,它在 ShopXO 的依赖树中有真实且可验证的落地场景。
5.1 依赖关系:ThinkPHP8 强制依赖
ShopXO 根目录的 composer.json 声明 "topthink/framework": "*",而 ThinkPHP8 框架的 composer.json 中明确声明 "psr/http-message": "^1.0"——即本仓库 vendor/psr/http-message 下的 1.0.x 包正是满足该约束的版本。也就是说,ShopXO 经由 ThinkPHP8 框架间接依赖并实际携带了这套 PSR-7 接口定义。
5.2 源码级调用链:路由调度中的 PSR-7 响应转换
最直接的消费证据位于 ThinkPHP 的路由调度器 vendor/topthink/framework/src/think/route/Dispatch.php:
- 文件第 15 行
use Psr\Http\Message\ResponseInterface;引入 PSR-7 响应接口; autoResponse()方法(第 60-83 行)对路由执行结果做类型分流:
protected function autoResponse($data): Response
{
if ($data instanceof Response) {
$response = $data;
} elseif ($data instanceof ResponseInterface) {
// 关键分支:识别 PSR-7 响应对象
$response = Response::create((string) $data->getBody(), 'html', $data->getStatusCode());
foreach ($data->getHeaders() as $header => $values) {
$response->header([$header => implode(", ", $values)]);
}
} elseif (!is_null($data)) {
// 默认自动识别响应输出类型
$type = $this->request->isJson() ? 'json' : 'html';
$response = Response::create($data, $type);
} else {
// ...
}
return $response;
}
这段代码清晰地展示了 PSR-7 接口在框架中的适配器模式:当控制器/中间件返回一个实现了 Psr\Http\Message\ResponseInterface 的对象时,ThinkPHP 通过 getBody()、getStatusCode()、getHeaders() 三个接口方法将其内容转换为 ThinkPHP 自己的 Response 对象,头部值数组经 implode(", ", $values) 拼成逗号分隔字符串后批量注入。你可以借此验证本文第二部分接口方法清单的返回值语义:getHeaders() 确实是 string[][],getHeaderLine() 的逗号拼接行为在这里被框架直接复用。
从源码结构可以推断:只要实现了 PSR-7 接口,任何第三方 HTTP 客户端/中间件返回的响应对象都能无缝接入 ThinkPHP 的响应管线——这正是接口抽象带来的跨实现互操作性。
5.3 生态衔接:psr/http-factory 与 guzzlehttp/psr7
仓库中还携带了与 PSR-7 配套的工厂接口包 vendor/psr/http-factory(提供 RequestFactoryInterface、ResponseFactoryInterface、StreamFactoryInterface、UriFactoryInterface 等,用于在不绑定具体实现的前提下创建 PSR-7 对象),而 ThinkPHP8 的开发依赖中亦引入了 PSR-7 的具体实现 guzzlehttp/psr7(见 vendor/topthink/framework/composer.json)。完整的依赖链条是:
ShopXO (composer.json)
└── topthink/framework (composer.json)
├── psr/http-message ^1.0 → 接口定义(本仓库 vendor/psr/http-message)
└── (dev) guzzlehttp/psr7 ^2.1.0 → 具体实现
这套「接口(psr/http-message)+ 工厂(psr/http-factory)+ 实现(guzzlehttp/psr7)」的分层结构,正是 PHP-FIG 标准化生态的标准组合方式:业务代码面向接口编程,具体实现可随时替换。
六、继续深入:仓库内可查阅的资料
- 接口方法速查表:vendor/psr/http-message/docs/PSR7-Interfaces.md(含本文全部方法清单及 RFC 出处)
- 实操使用指南:vendor/psr/http-message/docs/PSR7-Usage.md
- 七个接口的完整源码注释(含规范 MUST/SHOULD 约束):vendor/psr/http-message/src/ 目录下的
MessageInterface.php、RequestInterface.php、ServerRequestInterface.php、ResponseInterface.php、StreamInterface.php、UriInterface.php、UploadedFileInterface.php - 包声明与自动加载配置:vendor/psr/http-message/composer.json
- 版本变更记录(本文主题):vendor/psr/http-message/CHANGELOG.md
- ThinkPHP8 中的实际消费代码:vendor/topthink/framework/src/think/route/Dispatch.php(
autoResponse()方法) - 框架依赖声明:vendor/topthink/framework/composer.json
结语
psr/http-message 的 CHANGELOG 虽然只有两个版本、一次注解修正,但它背后是 PHP 生态最重要的 HTTP 消息抽象标准。通过本文,你不仅掌握了 1.0.0 → 1.0.1 的 5 项文档修正细节,更可以从 ShopXO 仓库的源码与依赖声明中看到:这 7 个接口如何通过"接口-工厂-实现"三层结构支撑起 ThinkPHP8 框架的响应管线,以及不可变性设计如何保证 HTTP 消息在复杂请求流程中的安全传递。理解这套抽象,是阅读任何现代 PHP 框架中间件、HTTP 客户端与微服务网关源码的基础。