easy-notification 通知中间件设计

easy-notification 是独立部署的实时通知中间件（fatjar，自带 main 入口），基于 easy-socketio 组件构建。组件层提供服务器装配、握手鉴权 SPI、三级房间协议、Redis 分布式房间；本中间件只包含业务层——推送门面 NotificationPusher 与 chat 事件示例。

• 一、背景与重写动机
• 二、定位与边界
• 三、总体架构
• 四、核心 API
• 五、部署形态
• 六、关键设计决策
• 七、已知问题

一、背景与重写动机

旧版 easy-notification（io.matrix.pushing，netty-socketio 1.7.19）存在三类问题：

重写后：基础设施全部下沉到 easy-socketio，中间件回归”业务层 + 独立部署形态”，netty 冲突根源（1.7.19 直接依赖）消除。

二、定位与边界

定位：面向产品的实时通知中心服务——多端（Web / App）长连接接入、房间订阅、服务端推送。

三、总体架构

flowchart TD
    subgraph "easy-notification 业务层"
        P1["NotificationPusher<br/>toUser / toProduct / broadcast / toRoom"]
        C1["ChatEventHandler<br/>topic=chat 房间广播"]
        A1["NotificationApplication<br/>main 入口 fatjar"]
        A2["SocketioClusterConfiguration<br/>cluster.enabled 开关"]
    end

    subgraph "easy-socketio 组件层"
        B1["ServerAdapter<br/>SmartLifecycle + FactoryBean"]
        B2["AuthListener SPI<br/>握手鉴权 + canSubscribe"]
        B3["RoomAdmin<br/>user:/product:/broadcast 三级房间"]
        B4["RedisStoreFactory<br/>单机 Memory / 集群 Redis 自适应"]
    end

    subgraph "客户端"
        K1["Web / App<br/>socket.io client EIO4"]
    end

    A1 --> B1
    A2 --> B4
    P1 -- "resolveNamespace + getRoomOperations" --> B3
    C1 --> B1
    B2 --> B3
    K1 --> B1
    B4 -- "cluster.enabled=true" --> R["Redis Pub/Sub"]

四、核心 API

4.1 NotificationPusher（服务端 → 客户端）

@Autowired NotificationPusher pusher;

pusher.toUser("u-1001", "order.paid", payload);   // user:u-1001 个人房间
pusher.toProduct("PRD-001", "status", payload);   // product:PRD-001 订阅房间
pusher.broadcast("notice", payload);              // broadcast 全员
pusher.toRoom("custom-room", "event", payload);   // 协议外自定义房间

内部统一经 ServerAdapter.resolveNamespace() 获取命名空间（规避 socket.io 默认命名空间 / 在 netty-socketio 内部名为空串的监听/投递错位陷阱），再向房间 sendEvent。

4.2 ChatEventHandler（客户端 → 服务端示例）

客户端 emit("chat", { room, nickname, content }) → 服务端向 room 房间广播同 topic 事件。私聊（receiver 定向）暂未实现，可经 toUser 补齐。

五、部署形态

# 构建 fatjar
mvn package -pl middlewares/easy-notification

# 单机
java -jar easy-notification.jar

# 集群（多实例 + Redis 房间同步）
java -jar easy-notification.jar \
  --socketio.cluster.enabled=true \
  --spring.data.redis.host=<redis-host>

无 web 容器（spring-boot-starter 不含 web），socketio.port 即服务端口。冒烟验证：Started NotificationApplication in 2.443s + SocketIO server started at port。

六、关键设计决策

七、已知问题