响应报文解析接口文档

接口概述

该接口用于解析服务端返回的响应报文（包括正确响应和错误响应），将十六进制格式的报文转换为结构化JSON数据。支持自动识别报文类型（成功/错误），并提取处理结果、错误信息等关键内容，便于终端设备或调试工具验证服务端处理状态。

接口信息

• 接口地址：wuhan.gishub.com.cn:4100/position-server/response/parse
• 请求方法：POST
• 请求格式：纯文本（十六进制报文字符串）
• 响应格式：JSON
• 接口标签：响应报文解析接口
• 功能说明：同时支持解析服务端返回的正确响应报文和错误响应报文，自动区分报文类型并返回对应结构化数据

请求参数说明

参数名	类型	是否必传	描述	示例值
十六进制报文	String	是	待解析的服务端响应报文（不含空格）	正确响应：FF0000002F02...FF 错误响应：FE02E697A0...FE

响应参数说明

通用响应结构

所有响应均包含以下一级字段：

字段名	类型	描述
success	Boolean	解析操作是否成功（与业务结果无关）
responseType	String	报文类型：SUCCESS（正确响应）或ERROR（错误响应）
message	String	解析结果描述
parsedData	Object	解析后的报文详情（根据类型不同结构不同）

1. 正确响应报文解析结果（responseType: "SUCCESS"）

parsedData 子字段	类型	描述	示例值
packetLength	Integer	报文总长度（字节，包含帧头帧尾）	47
version	String	协议版本号（十六进制）	0x02
terminalId	String	终端ID（BCD编码转换后）	1234567890000000000
handleResult	String	服务端处理结果	成功（0x00）或失败（非0x00）
serverTimestamp	Long	服务端处理时间戳（毫秒级Unix时间）	1690000000000
serverTime	String	服务端处理时间（可读格式）	Fri Jul 21 10:00:00 CST 2023
reserved	String	预留字段说明	预留字段（10字节）

2. 错误响应报文解析结果（responseType: "ERROR"）

parsedData 子字段	类型	描述	示例值
errorCode	Byte	错误代码（标识错误类型）	2
errorMessage	String	错误描述信息（UTF-8编码）	无效的坐标类型
originalPacket	String	导致错误的原始报文片段（最多128字节）	FF00000065020A0A...（截断的原始报文）

3. 解析失败结果（success: false）

字段名	类型	描述	示例值
success	Boolean	解析操作是否成功	false
message	String	解析失败的原因描述	帧头或帧尾不匹配

接口解析逻辑

1. 输入校验：检查十六进制字符串是否为空、长度是否合法。
2. 报文类型识别：
   • 正确响应：帧头0xFF + 帧尾0xFF
   • 错误响应：帧头0xFE + 帧尾0xFE
3. 逆转义处理：
   • 将0xFE00还原为0xFF
   • 将0xFE01还原为0xFE
4. 字段解析：
   • 正确响应：按协议提取包长、版本号、终端ID等字段（多字节字段按小端序解析）。
   • 错误响应：提取错误代码、错误描述、原始报文片段。
5. 结果组装：返回包含解析状态、报文类型和详情的JSON。

调用示例

示例1：解析正确响应报文

请求报文（十六进制）：

FF0000002F023132333435363738390000000000000000000000000000000000000000000000000000000000FF

响应结果：

{
  "success": true,
  "responseType": "SUCCESS",
  "message": "正确响应报文解析成功",
  "parsedData": {
    "packetLength": 47,
    "version": "0x02",
    "terminalId": "1234567890000000000000000000000000000",
    "handleResult": "成功",
    "serverTimestamp": 1690000000000,
    "serverTime": "Fri Jul 21 10:00:00 CST 2023",
    "reserved": "预留字段（10字节）"
  }
}

示例2：解析错误响应报文

请求报文（十六进制）：

FE 0B E5 9D 90 E6 A0 87 E7 B1 BB E5 9E 8B E4 B8 8D E4 B8 BA 31 E3 80 81 32 E3 80 81 33 46 46 20 36 33 20 30 30 20 30 30 20 30 30 20 30 32 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 31 20 32 33 20 34 35 20 36 37 20 38 39 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 31 20 39 33 20 38 31 20 32 33 20 31 38 20 36 35 20 33 35 20 31 38 20 36 34 FE 

响应结果：

{
   "responseType": "ERROR",
   "success": true,
   "parsedData": {
      "errorMessage": "坐标类型不为1、2、3FF 63 00 00 00 02 00 00 00 00 00 00 0",
      "errorCode": 11,
      "originalPacket": "0 00 00 00 00 00 00 00 01 23 45 67 89 00 00 00 00 00 00 00 00 00 01 93 81 23 18 65 35 18 64"
   },
   "message": "错误响应报文解析成功"
}

示例3：解析失败（帧头帧尾不匹配）

请求报文（十六进制）：

FE 01 E6 9C AA E6 A3 80 E6 B5 8B E5 88 B0 30 78 46 46 E5 B8 A7 E5 B0 BE 46 46 20 36 33 20 30 30 20 30 30 20 30 30 20 30 32 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 31 20 32 33 20 34 35 20 36 37 20 38 39 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 30 20 30 31 20 39 33 20 38 31 20 32 33 20 31 38 20 36 35 20 33 35 20 31 38 20 36 34 FE 

响应结果：

{
   "responseType": "ERROR",
   "success": true,
   "parsedData": {
      "errorMessage": "未检测到0xFF帧尾FF 63 00 00 00 02 00 00 00 00 00 00 00 00",
      "errorCode": 1,
      "originalPacket": "00 00 00 00 00 00 01 23 45 67 89 00 00 00 00 00 00 00 00 00 01 93 81 23 18 65 35 18 64"
   },
   "message": "错误响应报文解析成功"
}

错误码说明

错误信息	可能原因	解决方案
请传入十六进制响应报文	请求体为空或仅含空格	检查请求体是否包含有效的十六进制字符串
报文长度不足（至少包含帧头和帧尾）	报文字节数小于2（无法包含帧头和帧尾）	确认报文是否完整
未知报文类型：帧头或帧尾不匹配	帧头/帧尾不符合规范（正确响应需为0xFF，错误响应需为0xFE）	检查报文是否为服务端返回的有效响应帧
十六进制字符串长度必须为偶数	输入的十六进制字符串长度为奇数	补充或修正十六进制字符，确保长度为偶数
错误报文内容为空	错误响应报文去除帧头帧尾后无内容	确认错误报文是否完整

注意事项

1. 报文必须包含完整帧结构（帧头+内容+帧尾），否则会识别为“未知报文类型”。
2. 输入的十六进制字符串需去除空格、0x等分隔符（如FFA1B2而非0xFF 0xA1）。
3. 正确响应中的多字节字段（如packetLength、serverTimestamp）按小端序解析，与协议保持一致。
4. 错误响应的errorMessage和originalPacket采用UTF-8编码，若解析出现乱码，需检查原始报文编码是否正确。
5. 接口返回的success字段仅表示“解析操作是否成功”，不代表业务处理结果（业务结果需看handleResult或errorCode）。