storageless使用教程：在Mezzio应用中集成无存储JWT会话的10个实战技巧-平芜编程栈

storageless使用教程：在Mezzio应用中集成无存储JWT会话的10个实战技巧

【免费下载链接】storageless:mailbox_with_mail: storage-less PSR-7 session support项目地址: https://gitcode.com/gh_mirrors/st/storageless

storageless是一个基于 PSR-7/PSR-15 规范的 PHP 会话中间件库，它把会话数据直接加密签名后存放在 Cookie 中，实现真正的"无存储"（storage-less）会话，无需数据库、Redis 或文件系统参与读写。本教程面向新手，带你用 10 个实战技巧，快速把 storageless 集成进 Mezzio 应用，用 JWT 会话替换传统的$_SESSION，摆脱粘性会话和横向扩展的烦恼。

技巧1：先搞懂无存储会话的核心原理

传统 PHP 会话把数据存在服务器端，客户端只保存一个 session_id；而 storageless 恰恰相反——会话数据以JWT（JSON Web Token）的形式整体写入名为__Secure-slsession的 Cookie 中，由用户浏览器代为"存储"。

💡 关键点：JWT 始终经过签名，客户端无法篡改；但默认未加密，所以只放非敏感数据（如用户 ID、CSRF Token）。

这套设计的核心实现在 SessionMiddleware.php，中间件解析、验证 Cookie 中的 Token，并把会话对象挂到请求属性上。收益非常直观：

传统会话	storageless
需要存储后端	零存储，零 I/O
需要粘性会话	任意节点可验证
受 PHP 反序列化攻击影响	天然免疫
依赖全局状态	完全基于 PSR-7 请求/响应

技巧2：Composer 一键安装与版本要求

安装非常简单，一条命令搞定：

composer require psr7-sessions/storageless

安装前请确认环境满足要求（详见 composer.json）：PHP 8.4+，并启用ext-sodium扩展。依赖会自动带上lcobucci/jwt（JWT 签名）、dflydev/fig-cookies（Cookie 操作）等库。

需要从源码学习或贡献？可以这样克隆仓库：

git clone https://gitcode.com/gh_mirrors/st/storageless

技巧3：在 Mezzio 中完成最快配置方法

在 Mezzio 应用里，只需把SessionMiddleware挂到中间件管道的最外层即可。这是最快配置方法——对称签名（HMAC-SHA256）只需要一把共享密钥：

use Lcobucci\JWT\Configuration as JwtConfig; use Lcobucci\JWT\Signer; use Lcobucci\JWT\Signer\Key\InMemory; use PSR7Sessions\Storageless\Http\SessionMiddleware; use PSR7Sessions\Storageless\Http\Configuration as StoragelessConfig; $app = new \Mezzio\Application(/* ... */); $app->pipe(new SessionMiddleware( StoragelessConfig::fromJwtConfiguration( JwtConfig::forSymmetricSigner( new Signer\Hmac\Sha256(), InMemory::base64Encoded('OpcMuKmoxkhzW0Y1iESpjWwL/D3UBdDauJOe742BJ5Q='), // 换成你自己的密钥 ) ) ));

技巧4：在路由处理器中读写会话数据

中间件挂载后，在任何处理器中通过请求属性即可拿到会话对象（属性名常量见 SessionMiddleware.php 的SESSION_ATTRIBUTE）：

$app->get('/get', function (ServerRequestInterface $request, ResponseInterface $response) { $session = $request->getAttribute(SessionMiddleware::SESSION_ATTRIBUTE); $session->set('counter', $session->get('counter', 0) + 1); $response->getBody()->write('Counter: ' . $session->get('counter')); return $response; });

SessionInterface（见 SessionInterface.php）提供了set / get / remove / clear / has / isEmpty / hasChanged一整套方法，和数组式操作一样顺手，但底层是不可变数据，天然线程安全。🎯

技巧5：用客户端指纹有效抵御会话劫持

会话 Cookie 被偷走就会导致会话劫持。storageless 内置了客户端指纹机制，把会话与 IP 和 User-Agent 绑定，一旦来源变化立即失效（相关配置见 ClientFingerprint/Configuration.php）：

use PSR7Sessions\Storageless\Http\ClientFingerprint\Configuration as FingerprintConfig; $app->pipe(new SessionMiddleware( StoragelessConfig::fromJwtConfiguration(/* ... */) ->withClientFingerprintConfiguration( FingerprintConfig::forIpAndUserAgent() ) ));

技巧6：反向代理环境下自定义指纹来源

如果 PHP 服务部署在 Nginx 等反向代理之后，REMOTE_ADDR可能是代理地址。此时可以实现Source接口（见 ClientFingerprint/Source.php）自定义取值逻辑，例如读取X-Real-IP请求头：

FingerprintConfig::forSources(new class implements Source { public function extractFrom(ServerRequestInterface $request): string { return $request->getHeaderLine('X-Real-IP'); } })

技巧7：非对称签名让读写节点分离

多服务器场景下，更推荐非对称签名（如 EdDSA）：只有持有私钥的服务器能签发会话，其余节点仅凭公钥即可验签，实现"写节点受限、读节点开放"的安全架构：

$config = (new StoragelessConfig( JwtConfig::forAsymmetricSigner( new Signer\Eddsa(), InMemory::base64Encoded($privateKey), // 签名密钥 InMemory::base64Encoded($publicKey) // 验证密钥 ) ));

技巧8：调整会话有效期与刷新频率

storageless 提供了两个超时配置（默认值定义在 Configuration.php）：

withIdleTimeout(秒)：闲置超时，默认43200 秒（12 小时）
withRefreshTime(秒)：Token 刷新周期，默认60 秒

$config = $config ->withIdleTimeout(1200) // 20 分钟无操作即失效 ->withRefreshTime(60); // 每 60 秒重新签发 Token

🕒 注意：Token 只在超过刷新周期后才重新生成，避免每个请求都重写 Cookie，大幅降低网络开销。

技巧9：本地开发环境关闭 Secure 标记

默认 Cookie 名为__Secure-slsession且强制 HTTPS（Secure标记），本地http://localhost无法使用。开发环境可以这样覆盖（⚠️ 仅限本地，切勿上线！）：

use Dflydev\FigCookies\SetCookie; $config = $config->withCookie( SetCookie::create('slsession') ->withSecure(false) ->withHttpOnly(true) ->withPath('/') );

想快速跑通示例？进入 examples 目录执行php -S localhost:9999 index.php，浏览器访问http://localhost:9999，你会看到每次刷新计数器都在递增，这就是一个完整的无存储会话演示。