Message Pusher项目WebSocket API及消息状态查询详解

胡霆圣

于 2025-06-12 09:11:15 发布

阅读量384

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00317/article/details/148602532

Message Pusher项目WebSocket API及消息状态查询详解

message-pusher 搭建专属于你的消息推送服务，支持多种消息推送方式，支持 Markdown，基于 Golang 仅单可执行文件，开箱即用项目地址: https://gitcode.com/gh_mirrors/me/message-pusher

项目概述

Message Pusher是一个轻量级的消息推送服务，提供了WebSocket接口和RESTful API，允许开发者构建实时消息推送系统。本文将深入解析该项目的核心API功能，包括WebSocket客户端连接协议和消息状态查询机制。

WebSocket客户端接入指南

连接建立

Message Pusher采用标准的WebSocket协议实现实时消息推送功能。客户端连接时需要注意以下几点：

连接地址格式：
- 非加密连接：ws://<域名>:<端口>/api/register_client/<用户名>?secret=<密钥>
- 加密连接(HTTPS)：将协议头改为wss://
认证参数：
- secret参数必须使用用户在后台配置的"服务器连接密钥"
- 注意区分"服务器连接密钥"和"推送token"，这是两个不同的凭证
连接限制：
- 系统采用单连接机制，同一用户同一时间只能保持一个活跃连接
- 新连接建立时，旧连接会被自动断开

消息格式解析

服务端推送的消息采用JSON格式，包含以下核心字段：

{
  "title": "消息标题",
  "description": "消息摘要",
  "content": "原始内容",
  "html_content": "HTML格式内容", 
  "url": "相关链接"
}

实际使用中可能会包含额外字段，客户端应具备良好的兼容性，忽略无法识别的字段。

连接保活机制

为确保连接稳定性，系统实现了完善的保活机制：

服务端每56秒发送一次ping探测
客户端必须在60秒内回复pong响应
客户端主动发送的ping也会得到服务端的即时响应

这种设计既考虑了网络延迟，又避免了不必要的连接断开。建议客户端实现时内置自动重连逻辑，以应对网络波动等情况。

消息状态查询API

接口说明

Message Pusher提供了通过消息UUID查询发送状态的API：

端点：https://<域名>:<端口>/api/message/status/<uuid>
特点：基于UUID查询，无需额外鉴权
返回格式：JSON

响应示例

{
  "success": true,
  "message": "",
  "status": 2
}

字段详解

success：布尔值，表示请求是否成功处理
message：错误信息，成功时为空白字符串
status：消息状态码，具体含义如下：

| 状态码 | 常量名称 | 说明 | |--------|--------------------|----------------------| | 0 | MessageSendStatusUnknown | 未知状态 | | 1 | MessageSendStatusPending | 处理中 | | 2 | MessageSendStatusSent | 已发送 | | 3 | MessageSendStatusFailed | 发送失败 | | 4 | MessageSendStatusAsyncPending | 异步处理中 |