API 文档

本文档介绍服务的三个核心接口：/ws、/feign/publish、/feign/getOnlineUsers。

/ws 建立 WebSocket 连接

• 方法：GET
• 路径：/ws?code=<临时code>
• 认证：通过 verify-uri 校验 code，返回 userId 后允许连接。
• 来源校验：allowed-origins 支持白名单或 *。
• 连接限流：max-connections 超出直接拒绝。

示例：

ws://host:port/ws?code=abc123

连接成功后：

• 心跳与超时：按配置 pong-timeout、heartbeat-content 保持连接。
• 客户端上行：当 accept-client-message=true，服务可接收客户端消息并（可选）写入 MQ。

发布消息

• 方法：POST
• 路径：/feign/publish
• 请求体：

{
"targetType": "all|user|temp_user|channel",
  "target": "用户ID或频道名，all可为空",
  "data": "字符串消息体"
}

• 行为：
  • 当 cluster-enabled=true：消息写入 MQ（Kafka/RabbitMQ），由各实例消费后分发。
  • 当 cluster-enabled=false：直接推送到本地连接。

响应：

{
    "code": 0,
    "successful": true,
    "msg": null,
    "data": "发布成功(集群)",
    "encrypt": false
}

查询在线用户

• 方法：GET
• 路径：/feign/getOnlineUsers
• 响应：当前实例内所有在线 userId 列表。

{
    "code": 0,
    "successful": true,
    "msg": null,
    "data": ["u1", "u2"],
    "encrypt": false
}

临时链接与临时用户

• 定义：临时链接是与某个 userId 绑定但被标记为“临时”的 WebSocket 连接，适合用于短期会话（如二次校验、一次性互动）。
• 建立：通过 /ws?temp=1&code=<临时code> 建立连接，服务端在校验 code 后决定是否标记为“临时”，并可设置最大存活时长。
• 生命周期：临时链接在达到配置的最大存活时长后自动关闭；到期前可以正常接收服务端推送。
• 广播行为：当发布接口 targetType 为 temp_user 时，仅向该用户的“临时链接”推送消息，不会投递到该用户的“正常链接”。
• 在线统计：/feign/getOnlineUsers 仅统计正常链接的在线用户，不包含临时链接。
• 集群兼容：cluster-enabled=true 时，temp_user 消息同样经由 MQ 广播，各实例只向其本地临时链接分发；cluster-enabled=false 时直接本地分发，行为一致。

示例：仅向临时链接推送消息

POST /feign/publish
Content-Type: application/json

{
  "targetType": "temp_user",
  "target": "user-123",
  "data": "仅临时链接可见的提示或验证码"
}

错误码与返回结构

• 成功：{"code":0,"successful":true,"data":...}
• 失败：{"code":非0,"successful":false,"message":"错误信息"}