通用接口开放平台设计与实现——（9）消息服务总体设计

概要说明

如果只有API服务，调用方因无法得知物流系统中数据产生或变更何时发生，从而需要进行定时轮询。定时轮询一方面做不到实时交互，另一方面，对双方的服务器都会产生一定的额外负担。
基于上述因素，物流接口平台通过消息服务，将数据变动情况主动通知调用方，调用方收到消息通知后，再调用相应的API服务来查询数据即可，从而规避定时轮询。
消息服务基于Socket技术，调用方系统与物流系统建立长连接，实时推送消息通知。

总体架构

1.消息服务中心启动
2.物流系统LMS与应用系统（如承运商运输管理系统TMS）分别发起登录请求
3.消息服务中心进行身份认证，发送登录响应
4.LMS产生业务消息，如委托单创建，发送到消息中心，消息中心发送响应消息给LMS
5.消息中心处理该消息，转发给对应的TMS，TMS发送响应消息给消息中心

交互技术

交互方式：WebSocket
消息传输协议：TCP
通信机制：异步
数据编码格式：UTF-8
数据传输格式：JSON

请求消息

请求消息有7个属性，如下表：

属性编码	属性类型	说明
id	string	消息ID，全局唯一标识符，通过雪花算法产生
topic	string	消息主题
publishAppCode	string	消息发布者编码，由物流系统分配，同API服务中的AppCode
publishTime	string	消息发布时间，格式yyyy-MM-dd HH:mm:ss
messageType	string	消息类型，REQUEST 请求消息，RESPONSE 响应消息
sign	string	签名
content	string	消息内容

前面6个为系统参数，不能为空，主要用于鉴权及安全控制。
最后1个参数为业务参数，所有跟业务相关的数据都封装在该参数中。

响应消息

属性编码	属性类型	说明
id	string	消息ID，全局唯一标识符，通过雪花算法产生
topic	string	消息主题
publishAppCode	string	消息发布者编码，由物流系统分配，同API服务中的AppCode
publishTime	string	消息发布时间，格式yyyy-MM-dd HH:mi:ss
messageType	string	消息类型，REQUEST 请求消息，RESPONSE 响应消息
requestMessageId	string	请求消息ID
result	string	执行结果，SUCCESS 成功，ERROR 失败
errorCode	string	错误编码
errorMessage	string	错误信息
sign	string	签名
content	string	消息内容

执行结果如为SUCCESS ，则代表成功，可进一步从业务数据字段content获取返回的业务数据，如为ERROR ，则代表接口执行出错， errorCode和errorMessage字段中存放错误编码和错误信息。

安全控制

同API

签名算法

同API

错误定义

系统级错误定义如下:

错误编码	错误信息
S001	消息ID不能为空
S002	消息主题不能为空
S003	消息发布者不能为空
S004	发布时间不能为空
S005	发布时间格式不正确
S006	消息签名不能为空
S101	消息主题不存在
S102	消息主题不可用
S201	应用标识无效
S202	应用被停用
S301	应用无权限
S401	发布时间超出合理范围
S501	签名无效
S999	未定义错误+具体异常信息

业务级错误定义参见各具体的消息服务。

心跳保持

应用系统与消息服务中心建立的是WebSocket长连接，需通过心跳保持机制检测连接的有效性。
心跳包由客户端系统发送，发送内容为PingWebSocketFrame，消息服务中心收到该心跳包后，会立即响应，内容PongWebSocketFrame。
应用系统设置心跳响应超时时间，如超过指定时间，则认为连接失效，执行重连操作。
心跳包发送频率及心跳响应超时时间，由应用系统视具体情况进行设置。

粘包处理

发送方在消息结尾追加字符串“\r\n”(即windows系统下的回车换行），接收方根据该字符串进行粘包的分离。

消息重发与去重

消息服务通信机制为异步，为保证消息传输的可靠性，需实现以下机制：
a)发送方重发机制：消息发送方对未收到响应的消息进行重发，重发时保证消息内容不变
b)接收方消息去重机制：消息接收方依据消息的唯一性ID，对收到的消息进行验证，判断是否已处理过，如已处理过则不再进行处理

开源平台资料

平台名称：一二三开发平台
简介： 企业级通用低代码开发平台
设计资料：CSDN专栏
开源地址：Gitee
开源协议：MIT
欢迎收藏、点赞、评论，你的支持是我前行的动力。