PHP PSR-7 请求体怎样重复读取

我第一次在 PSR-7 中遇到“请求体第二次读取为空”，是在同一个请求里先做签名校验、再交给 JSON 解析器的时候。问题通常不在 JSON，而在于请求体是一个带游标的 StreamInterface：前一个消费者把游标读到了末尾，后一个消费者自然只能拿到剩余的空内容。

结论很简单：先取出 $request->getBody()，判断 isSeekable()；可回退就用 rewind() 或 seek(0)，不可回退就把第一次读到的字节放进新的 PSR-7 流，再通过 withBody() 交给下游。不要把每个流都当成可以无限次回到开头的字符串。

规范地址：https://www.php-fig.org/psr/psr-7/

PSR-7 的请求体为什么会读空

PSR-7 的消息对象和流对象是两层概念。getBody() 返回的是 StreamInterface，流有可读、可写、可回退等能力，并且维护当前指针位置。getContents() 读取的是“当前位置到末尾”的剩余内容，不是每次都重新读取整个请求体。

因此下面两次调用的结果不同：第一次把指针推进到末尾，第二次没有剩余字节。这里的“不可重复”说的是当前流位置，不是 PSR-7 请求对象本身不可用；请求对象可以通过 withBody() 返回一个替换了流的新实例。

先分清 getContents、__toString 和 rewind

getContents() 适合读取当前剩余部分，调用后游标继续向前。rewind() 要求流可寻址，并把位置退回开头；seek(0) 表达的是同一个意图。PSR-7 还定义了 __toString()，规范要求实现尝试从开头读取完整内容，但它可能把大请求体全部放进内存，而且非可回退流不应被当成安全的缓存方案。

isReadable()) {
        throw new \RuntimeException('请求体不可读');
    }

    // 不可回退的流无法恢复已经被前一个消费者读走的字节。
    if (!$body->isSeekable()) {
        return $body->getContents();
    }

    $body->rewind();
    return $body->getContents();
}

这个函数的边界要说清楚：如果流不可回退，它只能读取“从当前游标开始的剩余部分”。想让日志、签名和业务解析都拿到完整内容，缓存动作必须发生在第一个消费者读取之前。

可回退流和不可回退流怎么选

把 isSeekable() 当成能力判断，而不是把某个具体实现的经验当成 PSR-7 保证。内存流、临时文件流通常可以寻址；网络管道、回调流或某些适配器可能只能顺序读取。

可回退时，最小做法是把一次读取夹在两次游标定位之间：

getBody();
if (!$body->isSeekable()) {
    throw new \RuntimeException('当前请求体不能重复读取');
}

$body->rewind();
$raw = $body->getContents();

// 签名校验或日志读取结束后，把游标恢复到开头。
$body->rewind();
$requestForHandler = $request;
$payload = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);

不可回退时，不要调用一个注定失败的 rewind()。在第一个读取点把原始字节复制到 php://temp 或库提供的内存/临时文件流，再把这个新流放回消息对象。

getBody();
    if (!$body->isReadable()) {
        throw new \RuntimeException('请求体不可读');
    }

    // 该函数应放在第一个消费者之前；不可回退时只能保存尚未读取的内容。
    $raw = $body->getContents();
    $replacement = Utils::streamFor($raw);

    // withBody() 返回新消息，后续中间件必须继续使用这个返回值。
    return [$request->withBody($replacement), $raw];
}

这里的 Utils::streamFor() 是 Guzzle PSR-7 的工厂示例；如果项目使用 Nyholm、Laminas 或其他实现，应换成对应的 StreamFactory。关键不是工厂名称，而是把缓存后的字节重新包装成真正的 StreamInterface。

中间件怎样约定“谁负责回退”

最容易出错的是多个中间件各自读取，却没有约定游标责任。实践中可以选择一种明确策略：小请求体由第一个边界中间件缓存一次，然后把带新流的请求继续传下去；大请求体尽量只让一个组件流式消费，日志只记录长度、摘要或已经解析出的字段；需要签名校验时，校验必须发生在业务解析前，并在可回退条件成立时恢复游标。

还要注意 PSR-7 消息的大多数变更方法遵循不可变约定，withBody() 会返回新消息，不能只调用而丢掉返回值。流本身却可能改变游标，所以“请求对象不可变”不等于“请求体流不可变”。

回归检查与迁移清单

• 第一次读取前是否确认了 isReadable() 和 isSeekable()？
• 是否把 getContents() 误当成从开头读取？
• 调用 withBody() 后，后续代码是否使用了返回的新请求？
• 是否避免对大请求体无条件使用 __toString()？
• 签名、日志、JSON 解析之间是否只有一个明确的缓存或回退责任人？

对我来说，最稳妥的判断顺序是：先看流能力，再看当前游标，最后决定回退还是复制。只要把这三个状态写进中间件约定，PSR-7 请求体“第二次为空”的问题通常就能在代码评审阶段被发现。

相关问题

为什么第二次 getContents() 是空字符串？ 因为第一次读取已经把游标推进到了末尾；可回退流先执行 rewind()，不可回退流需要在第一次读取时缓存。

getBody() 会返回字符串吗？ 不会，PSR-7 要求它返回 StreamInterface。是否能回退、是否能完整放入内存，要看具体流实现和请求大小。

withBody() 会修改原请求吗？ 它应返回带新 body 的消息实例，调用方必须接住返回值；原请求变量不会因为丢弃返回值而自动替换。