Store（存储）

该 存储 接口为 socketio4j 定义了每会话的键值存储抽象。 它允许传输、命名空间和用户代码持久化会话范围的小片元元数据，例如用户 ID、身份验证令牌、连接状态或房间成员提示——独立于实际的后端存储实现。

关键特性

• 会话范围存储 — 每个已连接的客户端会话存在一个存储实例

• 键值语义 — 任意对象与字符串键关联

• 与后端无关 — 实现可使用内存、Hazelcast、Redis 或其他数据存储

• 生命周期感知 — 在底层客户端断开连接时被销毁

• 类型安全的检索 — 返回值可以被转换或使用泛型类型

工作原理

• 设置 在会话生命周期内将一个值与一个键关联

• 获取 返回存储的值，或 空 如果不存在

• 存在 在不加载值的情况下检查键是否存在

• 删除 移除单个键值条目

• 销毁 移除所有条目，使存储实例失效

使用场景

案例	示例
认证	存储 "userId", "tenant", "tokenClaims"
重连提示	存储 "rooms" 或自定义元数据
自定义握手参数	持久化来自升级/握手的用户元数据
命名空间逻辑	附加仅在当前会话期间需要的状态

优点

👍 在集群和独立模式下工作一致 👍 将会话元数据隔离到每个连接 👍 允许在不更改用户代码的情况下切换存储后端 👍 支持单节点部署的轻量内存操作

限制

ℹ️ 不适用于大型对象或二进制存储 ℹ️ 本身不是分布式数据模型 — 分布性取决于实现 ℹ️ 除了会话生命周期外没有内置的 TTL 或过期机制 ℹ️ 除非由共享存储作为后端，否则不会在会话之间共享

---

后端行为

后端	持久性	可见性	特性
内存中	短暂，断开或 JVM 重启时清除	仅本地	最快，最适合单节点
Hazelcast / Redis(redis, valkey, dragonflydb)	分布式（基于后端配置）	跨节点可访问	推荐用于多节点部署

---

生命周期保证

一个 Store 实例的存在与恰好一个客户端会话一致，并在会话结束时被销毁。 在调用 destroy()之后，不得再次访问该存储。

在客户端断开连接时自动调用。

示例

server.addEventListener("storeDemo", String.class,
        (client, data, ackSender) -> {

    // ----- 设置 -----
    client.getStore().set("key1", data);
    log.info("SET key1 = {}", data);

    // ----- 获取 -----
    String value = client.getStore().get("key1");
    log.info("GET key1 = {}", value);

    // ----- 是否存在 -----
    boolean existsBefore = client.getStore().has("key1");
    log.info("HAS key1 (before delete) = {}", existsBefore);

    // ----- 删除 -----
    client.getStore().del("key1");
    log.info("DEL key1");

    // ----- 再次检查是否存在 -----
    boolean existsAfter = client.getStore().has("key1");
    log.info("HAS key1 (after delete) = {}", existsAfter);

});