ShowDoc 依赖解析:psr/http-message 与 PSR-7 接口规范实战指南

原创2026-09-22 16:40:541,746 阅读
文章标签:后端文档知识管理

ShowDoc 依赖解析:psr/http-message 与 PSR-7 接口规范实战指南

本指南以 ShowDoc 仓库内 server/vendor/psr/http-message 组件的 CHANGELOG.md 为核心骨架,系统梳理 PSR-7 HTTP 消息接口的演进脉络、七大接口的完整方法清单与典型用法,并结合 ShowDoc 后端(Slim 4 + slim/psr7 实现)的真实调用场景,帮助读者理解 HTTP 消息抽象在文档 API 服务中的落地方式。读完本文,你将掌握 PSR-7 接口的检索清单、不可变对象操作范式,以及 ShowDoc 中文件上传、Mock 服务等模块如何消费这套标准接口。

一、组件定位:一份"纯接口"契约,而非实现

psr/http-message 是 PHP-FIG(PHP Framework Interop Group)官方发布的 PSR-7 接口包。从 README.md 可以明确它的定位:

This repository holds all interfaces/classes/traits related to PSR-7. Note that this is not a HTTP message implementation of its own. It is merely an interface that describes a HTTP message.

也就是说,这个包只定义接口,不提供任何 HTTP 消息的具体实现。真正的实现(如 guzzlehttp/psr7、slim/psr7、zendframework/zend-diactoros 等)由各框架自行提供。所有遵循 PSR-7 的应用在接口层面行为一致,这正是它成为中间件与框架互操作基石的原因。

在 ShowDoc 项目中,根目录 composer.json 中声明了 "slim/slim": "^4.0" 与 "slim/psr7": "^1.6",即采用 Slim 框架自带的 PSR-7 实现,而接口契约则统一来自本包。包内 composer.json 要求 PHP ^7.2 || ^8.0,并通过 PSR-4 将 Psr\Http\Message\ 命名空间映射到 src/ 目录。

二、CHANGELOG 解读:1.0.0 与 1.0.1 的演进要点

2.1 1.0.0 — 初始稳定版(2016-05-18)

首个稳定版本,标志着 PSR-7 规范正式定稿。此版本完整反映了被接受的 PSR-7 规范,定义了七项核心接口:

  • MessageInterface — HTTP 消息的通用表示
  • RequestInterface — 客户端发出的请求
  • ServerRequestInterface — 服务端接收的请求
  • ResponseInterface — 服务端返回的响应
  • StreamInterface — 数据流抽象
  • UriInterface — URI 值对象
  • UploadedFileInterface — 上传文件值对象

2.2 1.0.1 — 文档注解修正版(2016-08-06)

从 CHANGELOG 可以看到,1.0.1 是一次纯文档(annotation)层面的修订,不涉及任何运行时行为变更,五项 Fixed 内容分别是:

  1. @return self 全部改为 @return static:更贴近规范语义——with* 系列方法返回的是"当前调用类的实例",用 static 能让 IDE 与静态分析工具推导出更精确的类型,例如对 ServerRequestInterface 调用 withHeader() 后仍识别为 ServerRequestInterface,而不是退化为 MessageInterface。
  2. MessageInterface::getHeaders() 返回注解修正为 string[][]:明确其格式为"字符串的嵌套数组",即每个 header 名对应一个字符串值数组。
  3. RequestInterface::withRequestTarget() 的 @link 指向修正:更正为 RFC 7230 的正确章节。
  4. ServerRequestInterface::withUploadedFiles() 补上参数名 $uploadedFiles。
  5. UploadedFileInterface::moveTo() 的 @throws 注解修正:此前引用了错误的参数名,现正确指向 $targetPath。

这些修订印证了接口包对"契约可读性"的重视。对照源码可以看到,当前版本中 MessageInterface.php 的 getHeaders() 确实标注为 @return string<a href="https://link.gitcode.com/i/a14986cbdaa822bce6664790494ecd1f" target="_blank">][],且所有 with* 方法均使用 @return static(见 [MessageInterface.php、RequestInterface.php),UploadedFileInterface::moveTo() 的 @throws \InvalidArgumentException if the $targetPath specified is invalid 也印证了 1.0.1 的修订成果(见 UploadedFileInterface.php)。

三、PSR-7 接口速查清单

包内 docs/PSR7-Interfaces.md 提供了一份面向日常开发的接口方法速查表,以下为核心内容。

3.1 MessageInterface — 所有消息的基座

RequestInterface、ServerRequestInterface、ResponseInterface 均继承自 MessageInterface(因为请求与响应本质都是 HTTP 消息):

方法 说明
getProtocolVersion() 获取 HTTP 协议版本(如 1.0、1.1)
withProtocolVersion($version) 返回设置新协议版本的新实例
getHeaders() 获取全部请求头,返回 string[][]
hasHeader($name) 判断指定请求头是否存在
getHeader($name) 获取单个请求头的值数组
getHeaderLine($name) 获取单个请求头的逗号拼接字符串
withHeader($name, $value) 返回设置/覆盖请求头的新实例
withAddedHeader($name, $value) 返回追加请求头值的新实例
withoutHeader($name) 返回移除请求头的新实例
getBody() 获取消息体,返回 StreamInterface 对象
withBody(StreamInterface $body) 返回设置消息体的新实例

3.2 RequestInterface — 客户端请求

在 MessageInterface 基础上增加请求目标、方法与 URI 相关操作:

方法 说明
getRequestTarget() 获取请求目标(origin-form、absolute-form、authority-form、asterisk-form,见 RFC 7230)
withRequestTarget($requestTarget) 返回设置请求目标的新实例
getMethod() 获取 HTTP 方法(GET/POST/PUT/DELETE 等,见 RFC 7231;PATCH 见 RFC 5789)
withMethod($method) 返回设置 HTTP 方法的新实例
getUri() 获取 URI 实例
withUri(UriInterface $uri, $preserveHost = false) 返回设置 URI 的新实例,$preserveHost 决定是否保留原 Host 头

3.3 ServerRequestInterface — 服务端请求

在 RequestInterface 基础上增加服务端特有数据:

方法 说明
getServerParams() 服务端参数,通常派生自 $_SERVER
getCookieParams() / withCookieParams(array $cookies) 获取/设置 Cookie
withQueryParams(array $query) 设置查询字符串参数
getUploadedFiles() 获取规范化后的上传文件数据
withUploadedFiles(array $uploadedFiles) 设置上传文件
getParsedBody() / withParsedBody($data) 获取/设置解析后的请求体参数
getAttributes() 获取请求派生属性
getAttribute($name, $default = null) 获取单个派生属性
withAttribute($name, $value) 设置派生属性(用于路由参数、中间件数据传递)
withoutAttribute($name) 移除派生属性

3.4 ResponseInterface — 服务端响应

在 MessageInterface 基础上增加状态码操作:

方法 说明
getStatusCode() 获取响应状态码
withStatus($code, $reasonPhrase = '') 返回设置状态码(可选原因短语)的新实例
getReasonPhrase() 获取状态码关联的原因短语

3.5 StreamInterface — 数据流

描述可读写的数据流,覆盖读取、写入、定位与元数据:

__toString()(从头到尾读全部数据)、close()、detach()、getSize()、eof()、isSeekable()、seek($offset, $whence = SEEK_SET)、rewind()、isWritable()、write($string)、isReadable()、read($length)、getContents()、getMetadata($key = null)。

3.6 UriInterface — URI 值对象

提供 URI 各组成部分的读取与不可变修改:getScheme()、getAuthority()、getUserInfo()、getHost()、getPort()、getPath()、getQuery()、getFragment(),以及对应的 withScheme()、withUserInfo($user, $password = null)、withHost()、withPort()、withPath()、withQuery()、withFragment(),最后通过 __toString() 还原完整 URI 引用。

3.7 UploadedFileInterface — 上传文件

方法 说明
getStream() 获取表示上传文件的流
moveTo($targetPath) 将上传文件移动到新位置
getSize() 获取文件大小
getError() 获取上传错误码
getClientFilename() 获取客户端发送的文件名
getClientMediaType() 获取客户端发送的媒体类型

使用 ServerRequestInterface 时,RequestInterface 与 MessageInterface 的全部方法同样适用(因为接口是逐级继承的)。

四、PSR-7 典型用法与不可变对象陷阱

psr/http-message 的接口契约蕴含了一个核心设计:所有 with* 方法都返回新实例,原实例保持不变。包内 docs/PSR7-Usage.md 给出了一系列实用示例。

4.1 操作 HTTP 头

// 添加响应头
$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"
// 获取头值数组
$response->getHeader('My-Custom-Header'); // ["My Custom Message", "The second message"]
// 移除头(例如移除废弃的 Content-MD5)
$request = $request->withoutHeader('Content-MD5');
// 移除 Content-Length 后浏览器将流式下载直到结束
$response = $response->withoutHeader('Content-Length');

4.2 操作消息体

两种典型姿势:

// 方式一:先取出流对象,反复操作(只调用一次 getBody())
$body = $response->getBody();
// 读写、定位……
$response = $response->withBody($body);

// 方式二:直接链式操作(仅少量操作时更简洁)
$response->getBody()->write('hello');

读取流内容前必须回绕指针,否则会因指针停在末尾而读到空内容:

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

注意:若在 getContents() 前调用 $body->seek(1),首字符会被跳过,因为起始指针是 1 而非 0,所以推荐 rewind()。

4.3 流的"前插"行为

流对象是有指针状态的,直接写入会覆盖当前位置内容而非整体前插:

$body = $response->getBody();
$body->write('abcd');
$body->seek(0);
$body->write('ef'); // 此时流内容为 "efcd"

正确的前插做法是:先读出全部内容 → 回绕 → 写入前缀 → 再写入原内容:

$body = $response->getBody();
$body->rewind();
$contents = $body->getContents(); // abcd
$body->rewind();
$body->write('ef');          // 流内容 "efcd"
$body->write($contents);     // 流内容 "efabcd"

或者干脆用字符串拼接后整体重写:

$body = $response->getBody();
$body->rewind();
$contents = $body->getContents();
$contents = 'ef' . $contents;
$body->rewind();
$body->write($contents);

五、ShowDoc 中的 PSR-7 实战印证

作为纯契约包,psr/http-message 的价值体现在消费方。ShowDoc 后端大量控制器直接以 PSR-7 类型声明路由回调参数,以下是三个典型印证。

5.1 Mock 服务:响应构建与 JSON 头设置

MockController.php 中明确导入 Psr\Http\Message\ServerRequestInterface as Request 与 Psr\Http\Message\ResponseInterface as Response(见第 11-12 行)。在 infoByKey、infoByPath 等 Mock 响应方法中,用 $response->getBody()->write(...) 写入 JSON 字符串,再通过 withHeader('Content-Type', 'application/json') 返回设置了正确媒体类型的新响应实例(见 MockController.php):

$response->getBody()->write(json_encode($json, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_HEX_TAG | JSON_HEX_AMP | JSON_HEX_APOS | JSON_HEX_QUOT));
return $response->withHeader('Content-Type', 'application/json');

这正是 getBody()->write() 与 withHeader() 两个接口方法在真实业务中的组合使用。

5.2 文件上传:getUploadedFiles() 全链路

UploadedFileInterface 在 ShowDoc 的附件与文档导入模块中有完整应用。以 AttachmentController.php 为例(第 157-196 行):

$uploadedFiles = $request->getUploadedFiles();
if (empty($uploadedFiles['editormd-image-file'])) { /* ... */ }
$uploadedFile = $uploadedFiles['editormd-image-file'];
$originalName = $uploadedFile->getClientFilename();
// ...
$uploadedFile->moveTo($tmpFile);
// ...
'type' => $uploadedFile->getClientMediaType(),
'size' => $uploadedFile->getSize(),

即通过 getUploadedFiles() 获取 UploadedFileInterface 对象数组,再依次调用 getClientFilename()、moveTo()、getClientMediaType()、getSize()。ImportPostmanController.php 中导入 Postman 集合时也使用同样的 $request->getUploadedFiles()<a href="https://link.gitcode.com/i/de65f2bc6c7849b286a8545e4e410c58" target="_blank">'file'] 模式(见 [ImportPostmanController.php)。文件流后续交由 OfficeImporter.php 等助手类消费。

5.3 依赖拓扑:Slim 4 的 PSR-7 栈

从根目录 composer.json 的 require 段可以看出 ShowDoc 的 HTTP 层依赖链:slim/slim: ^4.0 + slim/psr7: ^1.6,而 slim/psr7 又依赖本包 psr/http-message 提供的接口。因此控制器方法签名里的 Request $request / Response $response(Slim 路由回调自动注入)本质上就是 Psr\Http\Message\ServerRequestInterface 与 ResponseInterface 的实例。理解这套契约,就能在不依赖具体框架文档的情况下,直接看懂 ShowDoc 任意控制器中请求读取与响应组装代码。

六、结语

psr/http-message 虽然是一个体积小巧的接口包,却是整个 PHP HTTP 生态互操作的基石。通过 CHANGELOG.md 可以看到它从 1.0.0 定稿到 1.0.1 打磨文档注解的严谨过程;通过 docs/PSR7-Interfaces.md 与 docs/PSR7-Usage.md 可以快速掌握七大接口的全部方法与不可变操作范式。而 ShowDoc 中 Mock 服务、附件上传、Postman 导入等模块对这套接口的直接消费,则是"接口契约 + 具体实现"这一组合在生产项目中的最佳注脚——掌握 PSR-7,你便掌握了阅读与编写现代 PHP HTTP 服务的通用语言。

登录后查看全文
showdoc