easy-socketio 实时推送组件设计

本文档描述 easy-socketio 组件的设计与实现。该组件基于 netty-socketio 2.0.14 做 Spring Boot 封装，解决三个问题：SocketIOServer 生命周期托管、握手鉴权与房间协议的统一约定、分布式部署下复用 spring-data-redis 的轻量 Store 扩展。组件默认关闭（socketio.enabled=true 才装配），未配置的服务零影响。

• 一、背景与问题
• 二、组件定位与边界
• 三、总体架构
• 四、核心 API 草图
• 五、包结构与核心类
• 六、关键设计决策
• 七、已知问题与待改进

一、背景与问题

1.1 直接使用 netty-socketio 的痛点

netty-socketio 是成熟的 Socket.IO Java 服务端实现，但原生使用方式面向手工组装，与 Spring Boot 生态存在四类摩擦：

1.2 与 easy-notification 的关系

middlewares/easy-notification 是面向产品的实时通知中心（业务语义层），easy-socketio 是它的底层长连接服务组件（能力层）。easy-notification 已基于本组件重写：服务器装配/鉴权/房间协议/Redis 分布式均复用组件层，中间件只保留推送 API（NotificationPusher）与 chat 事件业务。

二、组件定位与边界

定位：Spring Boot 下的 Socket.IO 服务端组件——自动配置 + 生命周期托管 + 握手鉴权 SPI + 房间协议 + 分布式 Store 扩展。

边界：

约束：

• 默认关闭：socketio.enabled=true 才装配，未配置的服务不启动端口、不创建 Bean
• netty 版本锁定：netty-socketio 2.0.14 依赖 netty 4.1.130.Final（HttpDecoderConfig），模块内 dependencyManagement 引入 netty-bom 防父 POM 版本管理降级导致运行时 ClassNotFoundException
• EIO4 时序：netty-socketio 2.0.14 实测 connect 回调可能先于 auth 回调执行，user 房间加入必须在 auth 回调完成
• 集群模式前提：应用已配置 RedisMessageListenerContainer + RedisTemplate，且 RedisTemplate 的 value 序列化器需保留类型信息（见 USAGE FAQ）

三、总体架构

flowchart TD
    subgraph "Auto Configuration"
        A1["EasySocketioConfiguration<br/>socketio.enabled=true 才装配"]
        A2["SocketioProperties<br/>socketio.* 配置绑定"]
        A3["RedisStoreConfiguration<br/>ConditionalOnClass(RedisMessageListenerContainer)"]
        A1 --> A2
        A3 --> A1
    end

    subgraph "Core Lifecycle"
        B1["ServerAdapter<br/>FactoryBean + SmartLifecycle"]
        B2["SocketIOServer<br/>暴露为 Spring Bean 供注入推送"]
        B3["RoomAdmin<br/>subscribe/unsubscribe 房间协议"]
        B1 --> B2
        B1 --> B3
    end

    subgraph "SPI 扩展点"
        C1["AuthListener<br/>握手鉴权 + 订阅校验"]
        C2["BaseHandler<br/>topic 事件处理器"]
    end

    subgraph "Store 扩展"
        D1["RedisStoreFactory<br/>Redis Hash 会话 + Pub/Sub 广播"]
        D2["In-Memory Store<br/>netty-socketio 默认单机模式"]
    end

    A1 --> B1
    C1 --> B1
    C2 --> B1
    A3 --> D1
    D1 --> B1
    D2 --> B2

连接建立与房间加入流程（EIO4 协议）：

flowchart TD
    A["客户端握手<br/>auth 载荷 token 或 URL token 参数"] --> B{"AuthListener.authenticate"}
    B -->|"返回 userCode"| C["client.set(userCode)<br/>加入 user:{code} 房间"]
    B -->|"返回 null 且 authRequired=true"| D["拒绝连接 unauthorized"]
    B -->|"返回 null 且 authRequired=false"| E["anonymous 只进 broadcast"]
    C --> F["连接成功<br/>加入 broadcast 房间"]
    E --> F
    F --> G["客户端 emit subscribe room"]
    G --> H{"canSubscribe 校验"}
    H -->|"通过"| I["joinRoom(product:{code})"]
    H -->|"拒绝"| J["拒绝并记日志"]

装配规则：EasySocketioConfiguration 是唯一入口；RedisStoreConfiguration 是嵌套条件配置——类路径存在 RedisMessageListenerContainer 且容器中已有该 Bean 时注册 RedisStoreFactory（集群模式），否则不注册（单机内存模式）。业务代码对两种模式零感知。

四、核心 API 草图

4.1 配置属性（SocketioProperties）

4.2 AuthListener（握手鉴权 SPI）

public interface AuthListener {
    /** 校验连接令牌，通过返回 userCode，失败返回 null */
    String authenticate(String token);

    /** 房间订阅权限校验，默认放行 */
    default boolean canSubscribe(String userCode, String room) {
        return true;
    }
}

由消费方实现并注册为 Bean（如复用 AuthorizeService）。token 来源优先级：client v4 auth 载荷 { "token": "xxx" } → URL 参数 ?token=xxx。

4.3 BaseHandler（业务事件处理器基类）

/** 一个子类对应一个客户端可调用的事件 */
public abstract class BaseHandler<E extends Event> implements DataListener<E> {
    protected BaseHandler(String topic, Class<E> eventClass);
    protected abstract void handle(SocketIOServer server, SocketIOClient client, E msg);
}

/** 事件载荷标记接口 */
public interface Event { }

/** 定向投递载荷：目标房间/客户端 + 消息体 */
public class Packet<M extends Event> {
    private Set<String> rooms;    // 目标房间
    private Set<String> clients;  // 目标客户端 sessionId
    private String sender;        // 发送方标识
    private M message;            // 消息体
}

所有 BaseHandler Bean 由 ServerAdapter 统一注册：namespace.addEventListener(topic, eventClass, handler)。

4.4 RoomAdmin（房间协议）

RoomAdmin.roomUser(userCode);      // "user:U001"
RoomAdmin.roomProduct(code);       // "product:PRD-001"
// 协议事件常量：subscribe / unsubscribe，载荷 RoomRequest { room }

4.5 命名空间解析（ServerAdapter.resolveNamespace）

/** 默认命名空间 "/" 在 netty-socketio 内部名为空串（构造时预创建） */
public static SocketIONamespace resolveNamespace(SocketIOServer server, String namespace);

推送方必须经此方法获取命名空间。直接 server.getNamespace("/") 会创建一个新命名空间，导致监听与投递错位。

4.6 SocketClient（客户端门面）

服务端到服务端通信封装（EIO4），典型用途：与独立部署的 easy-notification 交互、连通性探测、事件双向订阅：

// 连接（token 经 auth 载荷传递，对应服务端 AuthListener.authenticate；匿名传 null）
SocketClient client = SocketClient.connect("http://host:9092", token);

// 发送事件（POJO/Map 经 JsonMapper 序列化为 JSON 对象）
client.emit("chat", Map.of("room", "product:P1", "content", "hello"));

// 订阅事件（载荷自动反序列化）与连接生命周期
client.on("order.paid", OrderPaidPayload.class, payload -> ...);
client.on(Socket.EVENT_CONNECT, args -> ...);

client.close();   // 断开（自动重连由 io.socket-client 内建，默认开启）

依赖 io.socket:socket.io-client + org.json:json（均 optional，client 使用方显式引入，server 侧零负担）。

五、包结构与核心类

easy-socketio/
└── io/matrix/socketio/
    ├── autoconfig/
    │   ├── EasySocketioConfiguration.java   # 自动配置入口（enabled 门控 + Redis 嵌套条件）
    │   └── SocketioProperties.java          # socketio.* 配置属性
    ├── core/
    │   ├── ServerAdapter.java               # 生命周期适配器（FactoryBean + SmartLifecycle + 鉴权/房间/事件组装）
    │   ├── AuthListener.java                # 握手鉴权 SPI
    │   ├── RoomAdmin.java                   # 房间协议实现 + 房间名静态工具
    │   └── RoomRequest.java                 # subscribe/unsubscribe 载荷 { room }
    ├── client/
    │   └── SocketClient.java               # socket.io 客户端门面（connect/emit/on/close，服务端间通信）
    ├── handler/
    │   ├── BaseHandler.java                 # topic 事件处理器基类（自动注册）
    │   ├── Event.java                       # 事件载荷标记接口
    │   └── Packet.java                      # 定向投递载荷（rooms/clients/sender/message）
    └── store/
        ├── RedisStoreFactory.java           # 集群模式 Store 工厂
        ├── RedisPubSubStore.java            # Redis Pub/Sub 跨节点广播（nodeId 回环抑制）
        └── RedisStore.java                  # Redis Hash 会话存储（Store_{sessionId}）

依赖：

六、关键设计决策

七、已知问题与待改进