x
This commit is contained in:
Home
+158
-87
@@ -2,36 +2,41 @@ from enum import IntEnum
|
||||
import struct
|
||||
import json
|
||||
import gzip
|
||||
from typing import Optional, Union, Dict, Any, List
|
||||
from typing import Optional, Union, Dict, Any, List, Tuple
|
||||
|
||||
|
||||
# -------------------------- 协议常量定义 --------------------------
|
||||
# -------------------------- 协议常量定义（与JS完全一致） --------------------------
|
||||
class ProtocolConst:
|
||||
PROTOCOL_VERSION = 0b0001 # 协议版本v1
|
||||
HEADER_SIZE = 8 # 头部固定字节数（字节1~字节8）
|
||||
MAX_BODY_SIZE = 1024 * 1024 * 10 # 最大包体大小（10MB，防止内存溢出）
|
||||
STRING_ENCODING = "utf-8" # 字符串默认编码（统一编码格式，避免乱码）
|
||||
PROTOCOL_VERSION = 0b0001 # 协议版本（4位，字节0低4位，0~15）
|
||||
HEADER_SIZE = 8 # 头部固定字节数（字节0~7）
|
||||
MAX_BODY_SIZE = 0xFFFFFF # 最大包体大小（24位，≈16MB，字节4~6存储）
|
||||
STRING_ENCODING = "utf-8" # 字符串默认编码
|
||||
|
||||
|
||||
# -------------------------- 枚举定义（业务约定） --------------------------
|
||||
# -------------------------- 枚举定义（与JS码值完全对齐） --------------------------
|
||||
class MessageType(IntEnum):
|
||||
"""消息类型（4位，字节1高4位）"""
|
||||
PING = 0b0000 # 心跳
|
||||
AUDIO_DATA = 0b0001 # 纯音频数据(pcm)
|
||||
TEXT_MESSAGE = 0b0010 # 纯文本消息
|
||||
AUDIO_TEXT_MIX = 0b0011 # 音频+文本混合数据
|
||||
"""消息类型（4位，字节0高4位，0~15）"""
|
||||
PING = 0b0001 # 心跳（支持空包体）
|
||||
AUDIO_DATA = 0b0010 # 纯音频数据(pcm)
|
||||
TEXT_MESSAGE = 0b0011 # 纯文本消息
|
||||
CONTROL_CMD = 0b0100 # 控制指令（暂停/继续等）
|
||||
# 预留12种类型（0b0100 ~ 0b1111）
|
||||
|
||||
|
||||
class SerializationType(IntEnum):
|
||||
"""序列化方式（4位，字节2高4位）"""
|
||||
RAW = 0b0000 # 原始二进制（音频等）
|
||||
JSON = 0b0001 # JSON格式（文本/指令）
|
||||
STRING = 0b0010 # 直接字符串（纯文本，UTF-8编码，无JSON包装）🔴新增类型
|
||||
"""序列化方式（3位，字节1高3位，1~8）"""
|
||||
RAW = 0b001 # 原始二进制（1）
|
||||
JSON = 0b010 # JSON格式（2）
|
||||
STRING = 0b011 # 直接字符串（3）
|
||||
# 预留5种方式（0b100 ~ 0b111）
|
||||
|
||||
|
||||
class CompressionType(IntEnum):
|
||||
"""压缩方式（4位，字节2低4位）"""
|
||||
NONE = 0b0000 # 无压缩
|
||||
GZIP = 0b0001 # gzip压缩
|
||||
"""压缩方式（3位，字节1中3位，1~8）"""
|
||||
NONE = 0b001 # 无压缩（默认值1）
|
||||
GZIP = 0b010 # gzip压缩（2）
|
||||
# 预留6种方式（0b011 ~ 0b111）
|
||||
|
||||
|
||||
class ControlCommand(IntEnum):
|
||||
"""控制指令类型（配合MessageType.CONTROL_CMD使用）"""
|
||||
@@ -40,35 +45,62 @@ class ControlCommand(IntEnum):
|
||||
RESUME = 0b0011 # 继续
|
||||
STOP = 0b0100 # 停止
|
||||
|
||||
# -------------------------- 协议工具类 --------------------------
|
||||
|
||||
# -------------------------- 协议工具类（与JS协议结构一致） --------------------------
|
||||
class ProtocolCodec:
|
||||
@staticmethod
|
||||
def pack(
|
||||
msg_type: MessageType,
|
||||
body: Union[bytes, str, Dict[str, Any], List[Any]],
|
||||
body: Union[bytes, str, Dict[str, Any], List[Any], None] = None,
|
||||
sequence: int = 0,
|
||||
serialization: Optional[SerializationType] = None,
|
||||
compression: CompressionType = CompressionType.NONE
|
||||
) -> bytes:
|
||||
"""
|
||||
封装协议包（头部 + 包体）
|
||||
封装协议包（与JS pack 方法完全兼容）
|
||||
:param msg_type: 消息类型
|
||||
:param body: 包体数据（bytes/str/dict/list）
|
||||
:param body: 包体数据（PING消息可传None/空，其他类型必填）
|
||||
:param sequence: 消息顺序号（0~65535，默认0）
|
||||
:param serialization: 序列化方式（None时自动推导）
|
||||
:param compression: 压缩方式
|
||||
:param compression: 压缩方式（默认无压缩）
|
||||
:return: 完整协议包（bytes）
|
||||
"""
|
||||
# 1. 自动推导序列化方式（优化：纯文本消息自动用STRING，复杂结构用JSON）🔴修改推导逻辑
|
||||
if serialization is None:
|
||||
# 校验顺序号范围（0~65535）
|
||||
if not isinstance(sequence, int) or not (0 <= sequence <= 0xFFFF):
|
||||
raise ValueError(f"消息顺序号必须是0~65535的整数，当前传入：{sequence}")
|
||||
|
||||
# 特殊处理：PING消息支持空包体
|
||||
if msg_type == MessageType.PING:
|
||||
# PING消息强制RAW序列化
|
||||
serialization = SerializationType.RAW
|
||||
# 空包体转为空bytes
|
||||
if body is None:
|
||||
body = b""
|
||||
if not isinstance(body, bytes):
|
||||
raise TypeError(f"PING消息仅支持空包体或bytes类型，当前传入：{type(body)}")
|
||||
else:
|
||||
# 非PING消息包体不能为空
|
||||
if body is None:
|
||||
raise ValueError(f"非PING消息（{msg_type.name}）包体不能为空")
|
||||
|
||||
# 1. 自动推导序列化方式（非PING消息）
|
||||
if serialization is None and msg_type != MessageType.PING:
|
||||
if msg_type == MessageType.AUDIO_DATA:
|
||||
serialization = SerializationType.RAW
|
||||
elif msg_type == MessageType.TEXT_MESSAGE: # 纯文本消息→STRING
|
||||
elif msg_type == MessageType.TEXT_MESSAGE:
|
||||
serialization = SerializationType.STRING
|
||||
elif msg_type in (MessageType.CONTROL_CMD, MessageType.AUDIO_TEXT_MIX): # 复杂结构→JSON
|
||||
elif msg_type == MessageType.CONTROL_CMD:
|
||||
serialization = SerializationType.JSON
|
||||
else:
|
||||
raise ValueError(f"不支持的消息类型：{msg_type}")
|
||||
|
||||
# 2. 序列化包体（新增STRING类型处理）🔴新增分支
|
||||
# 2. 校验枚举值范围
|
||||
if not (0b001 <= serialization.value <= 0b111):
|
||||
raise ValueError(f"序列化方式必须在1~8（0b001~0b111）范围内，当前传入：{serialization.value}")
|
||||
if not (0b001 <= compression.value <= 0b111):
|
||||
raise ValueError(f"压缩方式必须在1~8（0b001~0b111）范围内，当前传入：{compression.value}")
|
||||
|
||||
# 3. 序列化包体
|
||||
serialized_body: bytes
|
||||
if serialization == SerializationType.RAW:
|
||||
if not isinstance(body, bytes):
|
||||
@@ -77,7 +109,7 @@ class ProtocolCodec:
|
||||
elif serialization == SerializationType.STRING:
|
||||
if not isinstance(body, str):
|
||||
raise TypeError("STRING序列化要求body必须是str类型")
|
||||
serialized_body = body.encode(ProtocolConst.STRING_ENCODING) # 直接UTF-8编码，无JSON包装
|
||||
serialized_body = body.encode(ProtocolConst.STRING_ENCODING)
|
||||
elif serialization == SerializationType.JSON:
|
||||
if isinstance(body, str):
|
||||
serialized_body = body.encode(ProtocolConst.STRING_ENCODING)
|
||||
@@ -88,7 +120,7 @@ class ProtocolCodec:
|
||||
else:
|
||||
raise ValueError(f"不支持的序列化方式：{serialization}")
|
||||
|
||||
# 3. 压缩包体（不变）
|
||||
# 4. 压缩包体
|
||||
compressed_body: bytes
|
||||
if compression == CompressionType.GZIP:
|
||||
compressed_body = gzip.compress(serialized_body)
|
||||
@@ -97,50 +129,81 @@ class ProtocolCodec:
|
||||
else:
|
||||
raise ValueError(f"不支持的压缩方式：{compression}")
|
||||
|
||||
# 4. 校验包体大小（不变）
|
||||
# 5. 校验包体大小（24位最大支持0xFFFFFF字节）
|
||||
body_len = len(compressed_body)
|
||||
if body_len > ProtocolConst.MAX_BODY_SIZE:
|
||||
raise OverflowError(f"包体过大（{body_len}字节），最大支持{ProtocolConst.MAX_BODY_SIZE}字节")
|
||||
raise OverflowError(
|
||||
f"包体过大（{body_len}字节），最大支持{ProtocolConst.MAX_BODY_SIZE}字节（≈16MB）"
|
||||
)
|
||||
|
||||
# 5. 构造头部（不变）
|
||||
byte1 = (msg_type.value << 4) | 0x00 # 消息类型(4位) + 保留位1(4位)
|
||||
byte2 = (serialization.value << 4) | (compression.value & 0x0F) # 序列化(4位) + 压缩(4位)
|
||||
byte3_4 = struct.pack(">H", ProtocolConst.PROTOCOL_VERSION) # 协议版本(16位)
|
||||
byte5_8 = struct.pack(">I", body_len) # 包体长度(32位)
|
||||
header = bytes([byte1, byte2]) + byte3_4 + byte5_8
|
||||
# 6. 构造头部（与JS头部结构完全一致）
|
||||
# 字节0：消息类型(高4位) + 协议版本(低4位)
|
||||
byte0 = ((msg_type.value & 0x0F) << 4) | (ProtocolConst.PROTOCOL_VERSION & 0x0F)
|
||||
# 字节1：序列化方式(高3位) + 压缩方式(中3位) + 保留位(低2位)
|
||||
byte1 = ((serialization.value & 0x07) << 5) | ((compression.value & 0x07) << 2) | 0x00
|
||||
# 字节2~3：消息顺序号（16位大端序）
|
||||
byte2_3 = struct.pack(">H", sequence)
|
||||
# 字节4~6：包体长度（24位大端序）
|
||||
byte4 = (body_len >> 16) & 0xFF
|
||||
byte5 = (body_len >> 8) & 0xFF
|
||||
byte6 = body_len & 0xFF
|
||||
# 字节7：保留位（固定0x00）
|
||||
byte7 = 0x00
|
||||
|
||||
# 拼接头部
|
||||
header = (
|
||||
bytes([byte0, byte1]) +
|
||||
byte2_3 +
|
||||
bytes([byte4, byte5, byte6, byte7])
|
||||
)
|
||||
assert len(header) == ProtocolConst.HEADER_SIZE, f"头部长度错误：实际{len(header)}字节，预期{ProtocolConst.HEADER_SIZE}字节"
|
||||
|
||||
return header + compressed_body
|
||||
|
||||
@staticmethod
|
||||
def unpack(packet: bytes) -> tuple[MessageType, SerializationType, CompressionType, Any]:
|
||||
def unpack(packet: bytes) -> Tuple[MessageType, SerializationType, CompressionType, int, Any]:
|
||||
"""
|
||||
解析协议包
|
||||
解析协议包（与JS unpack 方法完全兼容）
|
||||
:param packet: 完整协议包（头部 + 包体）
|
||||
:return: (消息类型, 序列化方式, 压缩方式, 原始包体数据)
|
||||
:return: (消息类型, 序列化方式, 压缩方式, 顺序号, 原始包体数据)
|
||||
"""
|
||||
# 1. 校验包长度（不变）
|
||||
# 1. 校验包长度
|
||||
if len(packet) < ProtocolConst.HEADER_SIZE:
|
||||
raise ValueError(f"包长度过短（{len(packet)}字节），至少需要{ProtocolConst.HEADER_SIZE}字节头部")
|
||||
raise ValueError(
|
||||
f"包长度过短（{len(packet)}字节），至少需要{ProtocolConst.HEADER_SIZE}字节头部"
|
||||
)
|
||||
|
||||
# 2. 解析头部（不变）
|
||||
# 2. 解析头部
|
||||
header = packet[:ProtocolConst.HEADER_SIZE]
|
||||
body = packet[ProtocolConst.HEADER_SIZE:]
|
||||
byte1 = header[0]
|
||||
byte2 = header[1]
|
||||
|
||||
msg_type = MessageType((byte1 >> 4) & 0x0F)
|
||||
serialization = SerializationType((byte2 >> 4) & 0x0F)
|
||||
compression = CompressionType(byte2 & 0x0F)
|
||||
version = struct.unpack(">H", header[2:4])[0]
|
||||
body_len = struct.unpack(">I", header[4:8])[0]
|
||||
# 字节0：消息类型(高4位) + 协议版本(低4位)
|
||||
byte0 = header[0]
|
||||
msg_type = MessageType((byte0 >> 4) & 0x0F)
|
||||
version = byte0 & 0x0F
|
||||
|
||||
# 字节1：序列化方式(高3位) + 压缩方式(中3位) + 保留位(低2位)
|
||||
byte1 = header[1]
|
||||
serialization = SerializationType((byte1 >> 5) & 0x07)
|
||||
compression = CompressionType((byte1 >> 2) & 0x07)
|
||||
|
||||
# 字节2~3：消息顺序号（16位大端序）
|
||||
sequence = struct.unpack(">H", header[2:4])[0]
|
||||
|
||||
# 字节4~6：包体长度（24位大端序），字节7：保留位（忽略）
|
||||
body_len = (header[4] << 16) | (header[5] << 8) | header[6]
|
||||
|
||||
# 校验版本和包体长度
|
||||
if version != ProtocolConst.PROTOCOL_VERSION:
|
||||
raise ValueError(f"协议版本不匹配：收到v{version}，支持v{ProtocolConst.PROTOCOL_VERSION}")
|
||||
raise ValueError(
|
||||
f"协议版本不匹配：收到v{version}（0b{version:04b}），支持v{ProtocolConst.PROTOCOL_VERSION}（0b{ProtocolConst.PROTOCOL_VERSION:04b}）"
|
||||
)
|
||||
if len(body) != body_len:
|
||||
raise ValueError(f"包体长度不匹配：头部声明{body_len}字节，实际{len(body)}字节")
|
||||
raise ValueError(
|
||||
f"包体长度不匹配：头部声明{body_len}字节，实际{len(body)}字节"
|
||||
)
|
||||
|
||||
# 3. 解压包体（不变）
|
||||
# 3. 解压包体
|
||||
decompressed_body: bytes
|
||||
if compression == CompressionType.GZIP:
|
||||
try:
|
||||
@@ -152,13 +215,15 @@ class ProtocolCodec:
|
||||
else:
|
||||
raise ValueError(f"不支持的压缩方式：{compression}")
|
||||
|
||||
# 4. 反序列化包体（新增STRING类型处理）🔴新增分支
|
||||
# 4. 反序列化包体（空包体返回None）
|
||||
original_body: Any
|
||||
if serialization == SerializationType.RAW:
|
||||
if len(decompressed_body) == 0:
|
||||
original_body = None
|
||||
elif serialization == SerializationType.RAW:
|
||||
original_body = decompressed_body
|
||||
elif serialization == SerializationType.STRING:
|
||||
try:
|
||||
original_body = decompressed_body.decode(ProtocolConst.STRING_ENCODING) # 直接UTF-8解码，无JSON解析
|
||||
original_body = decompressed_body.decode(ProtocolConst.STRING_ENCODING)
|
||||
except UnicodeDecodeError:
|
||||
raise ValueError(f"STRING反序列化失败：{ProtocolConst.STRING_ENCODING}解码错误")
|
||||
elif serialization == SerializationType.JSON:
|
||||
@@ -166,58 +231,64 @@ class ProtocolCodec:
|
||||
original_body = json.loads(decompressed_body.decode(ProtocolConst.STRING_ENCODING))
|
||||
except UnicodeDecodeError:
|
||||
raise ValueError(f"JSON反序列化失败：{ProtocolConst.STRING_ENCODING}解码错误")
|
||||
except json.JSONDecodeError:
|
||||
raise ValueError("JSON反序列化失败：格式错误")
|
||||
except json.JSONDecodeError as e:
|
||||
raise ValueError(f"JSON反序列化失败：格式错误（{str(e)}）")
|
||||
else:
|
||||
raise ValueError(f"不支持的序列化方式：{serialization}")
|
||||
|
||||
return msg_type, serialization, compression, original_body
|
||||
return msg_type, serialization, compression, sequence, original_body
|
||||
|
||||
|
||||
# -------------------------- 使用示例（新增纯字符串消息测试） --------------------------
|
||||
# -------------------------- 使用示例（验证与JS兼容性） --------------------------
|
||||
if __name__ == "__main__":
|
||||
# 示例1：纯文本消息（自动用STRING序列化，无JSON包装）🔴测试新增类型
|
||||
text_body = "你好，这是纯字符串消息（无JSON）"
|
||||
# 示例1：PING消息（空包体，默认顺序号0）
|
||||
ping_packet = ProtocolCodec.pack(MessageType.PING)
|
||||
print(f"PING消息包长度：{len(ping_packet)}字节（仅头部）")
|
||||
msg_type1, ser1, comp1, seq1, body1 = ProtocolCodec.unpack(ping_packet)
|
||||
print(f"PING解析结果：类型={msg_type1.name}，序列化={ser1.name}，压缩={comp1.name}，顺序号={seq1}，包体={body1}\n")
|
||||
|
||||
# 示例2：纯文本消息（STRING序列化，指定顺序号）
|
||||
text_body = "Python与JS协议兼容测试（纯字符串）"
|
||||
text_packet = ProtocolCodec.pack(
|
||||
msg_type=MessageType.TEXT_MESSAGE,
|
||||
body=text_body,
|
||||
sequence=1001,
|
||||
compression=CompressionType.NONE
|
||||
)
|
||||
print(f"纯文本消息包长度：{len(text_packet)}字节")
|
||||
msg_type1, ser1, comp1, body1 = ProtocolCodec.unpack(text_packet)
|
||||
print(f"解析结果：类型={msg_type1.name}，序列化={ser1.name}，压缩={comp1.name}，内容={body1}\n")
|
||||
print(f"文本消息包长度：{len(text_packet)}字节")
|
||||
msg_type2, ser2, comp2, seq2, body2 = ProtocolCodec.unpack(text_packet)
|
||||
print(f"文本解析结果：类型={msg_type2.name}，序列化={ser2.name}，顺序号={seq2}，内容={body2}\n")
|
||||
|
||||
# 示例2：控制指令（JSON序列化，复杂结构）
|
||||
control_body = {"cmd": ControlCommand.HEARTBEAT.value, "timestamp": 1699999999}
|
||||
# 示例3：控制指令（JSON序列化）
|
||||
control_body = {"cmd": ControlCommand.PAUSE.value, "reason": "用户主动暂停"}
|
||||
control_packet = ProtocolCodec.pack(
|
||||
msg_type=MessageType.CONTROL_CMD,
|
||||
body=control_body,
|
||||
compression=CompressionType.NONE
|
||||
sequence=1002
|
||||
)
|
||||
print(f"控制指令包长度：{len(control_packet)}字节")
|
||||
msg_type2, ser2, comp2, body2 = ProtocolCodec.unpack(control_packet)
|
||||
print(f"解析结果：类型={msg_type2.name}，序列化={ser2.name}，压缩={comp2.name}，内容={body2}\n")
|
||||
msg_type3, ser3, comp3, seq3, body3 = ProtocolCodec.unpack(control_packet)
|
||||
print(f"控制指令解析结果：类型={msg_type3.name}，序列化={ser3.name}，顺序号={seq3}，内容={body3}\n")
|
||||
|
||||
# 示例3：音频数据（RAW序列化）
|
||||
# 示例4：音频数据（RAW序列化）
|
||||
audio_body = b"\x00\x01\x02\x03\x04\x05" * 100 # 模拟PCM数据
|
||||
audio_packet = ProtocolCodec.pack(
|
||||
msg_type=MessageType.AUDIO_DATA,
|
||||
body=audio_body,
|
||||
compression=CompressionType.NONE
|
||||
sequence=1003
|
||||
)
|
||||
print(f"音频数据包长度：{len(audio_packet)}字节")
|
||||
msg_type3, ser3, comp3, body3 = ProtocolCodec.unpack(audio_packet)
|
||||
print(f"解析结果：类型={msg_type3.name}，序列化={ser3.name}，压缩={comp3.name}，数据长度={len(body3)}字节\n")
|
||||
msg_type4, ser4, comp4, seq4, body4 = ProtocolCodec.unpack(audio_packet)
|
||||
print(f"音频解析结果：类型={msg_type4.name}，序列化={ser4.name}，顺序号={seq4}，数据长度={len(body4)}字节\n")
|
||||
|
||||
# 示例4：混合数据（JSON序列化）
|
||||
mix_body = {
|
||||
"audio_data": list(audio_body[:10]),
|
||||
"text_content": "混合数据仍用JSON"
|
||||
}
|
||||
mix_packet = ProtocolCodec.pack(
|
||||
msg_type=MessageType.AUDIO_TEXT_MIX,
|
||||
body=mix_body
|
||||
# 示例5：GZIP压缩测试（需JS端启用GZIP解压）
|
||||
long_text_body = "这是一段很长的文本，用于测试GZIP压缩效果" * 100
|
||||
gzip_packet = ProtocolCodec.pack(
|
||||
msg_type=MessageType.TEXT_MESSAGE,
|
||||
body=long_text_body,
|
||||
sequence=1004,
|
||||
compression=CompressionType.GZIP
|
||||
)
|
||||
print(f"混合数据包长度：{len(mix_packet)}字节")
|
||||
msg_type4, ser4, comp4, body4 = ProtocolCodec.unpack(mix_packet)
|
||||
print(f"解析结果：类型={msg_type4.name}，序列化={ser4.name}，压缩={comp4.name}，内容={body4}")
|
||||
print(f"GZIP压缩后包长度：{len(gzip_packet)}字节（原始文本长度：{len(long_text_body.encode())}字节）")
|
||||
msg_type5, ser5, comp5, seq5, body5 = ProtocolCodec.unpack(gzip_packet)
|
||||
print(f"GZIP解析结果：类型={msg_type5.name}，压缩={comp5.name}，内容前50字：{body5[:50]}...")
|
||||
@@ -5,128 +5,156 @@
|
||||
* 协议常量类：存储协议核心配置（不可修改，确保前后端一致）
|
||||
*/
|
||||
export class ProtocolConst {
|
||||
/** 协议版本：v1（4位，对应字节3~4的低4位，剩余位保留用于后续升级） */
|
||||
/** 协议版本：0~15（4位，存储在字节0低4位） */
|
||||
static readonly PROTOCOL_VERSION = 0b0001;
|
||||
|
||||
/** 头部固定长度：8字节（字节1~8，结构严格定义，不可修改） */
|
||||
/** 头部固定长度：8字节（字节0~7，结构严格定义，不可修改） */
|
||||
static readonly HEADER_SIZE = 8;
|
||||
|
||||
/** 最大包体大小：10MB（防止内存溢出，与 Python 端 MAX_BODY_SIZE 一致） */
|
||||
static readonly MAX_BODY_SIZE = 1024 * 1024 * 10;
|
||||
/**
|
||||
* 最大包体大小：16MB（3字节长度最大支持0xFFFFFF=16777215字节≈16MB）
|
||||
* 4-6字节存储（24位），最大支持16MB，满足大部分场景且避免长度字段冗余
|
||||
*/
|
||||
static readonly MAX_BODY_SIZE = 0xFFFFFF; // 16777215字节 ≈16MB
|
||||
|
||||
/** 字符串编码格式：UTF-8（统一前后端字符串编解码，避免乱码） */
|
||||
static readonly STRING_ENCODING = "utf-8" as const; // as const 固定字符串类型，避免类型拓宽
|
||||
static readonly STRING_ENCODING = "utf-8" as const;
|
||||
}
|
||||
|
||||
/**
|
||||
* 消息类型枚举（4位，存储在字节1高4位）
|
||||
* 与 Python 端 MessageType 枚举值完全对齐，支持16种类型（当前用5种，剩余预留扩展）
|
||||
* 消息类型枚举（4位，存储在字节0高4位，0~15范围）
|
||||
* 二进制标识，统一编码风格
|
||||
*/
|
||||
export enum MessageType {
|
||||
PING = 0b0000, // 心跳消息（用于检测连接存活）
|
||||
AUDIO_DATA = 0b0001, // 纯音频数据（PCM 二进制流，对应 RAW 序列化）
|
||||
TEXT_MESSAGE = 0b0010, // 纯文本消息（对应 STRING 序列化，无 JSON 包装）
|
||||
AUDIO_TEXT_MIX = 0b0011, // 音频+文本混合数据（复杂结构，对应 JSON 序列化）
|
||||
CONTROL_CMD = 0b0100, // 控制指令（暂停/继续/停止等，对应 JSON 序列化）
|
||||
PING = 0b0001, // 心跳消息（支持空包体）
|
||||
AUDIO_DATA = 0b0010, // 纯音频数据
|
||||
TEXT_MESSAGE = 0b0011, // 纯文本消息
|
||||
CONTROL_CMD = 0b0100, // 控制指令
|
||||
// 预留12种类型用于扩展（0b0100 ~ 0b1111）
|
||||
}
|
||||
|
||||
/**
|
||||
* 序列化方式枚举（4位，存储在字节2高4位）
|
||||
* 按数据类型选择最优序列化方式，减少开销
|
||||
* 序列化方式枚举（3位，存储在字节1高3位，1~8范围）
|
||||
* 二进制标识，统一编码风格（1~8对应0b001~0b111）
|
||||
*/
|
||||
export enum SerializationType {
|
||||
RAW = 0b0000, // 原始二进制（无需编解码，直接透传，适合音频等二进制数据）
|
||||
JSON = 0b0001, // JSON 格式（适合字典、列表等复杂结构，如控制指令、混合数据）
|
||||
STRING = 0b0010, // 直接字符串（UTF-8 编码，无 JSON 包装，适合纯文本消息）
|
||||
RAW = 0b001, // 原始二进制（1）
|
||||
JSON = 0b010, // JSON 格式（2）
|
||||
STRING = 0b011, // 直接字符串（3）
|
||||
// 预留5种方式用于扩展（0b100 ~ 0b111）
|
||||
}
|
||||
|
||||
/**
|
||||
* 压缩方式枚举（4位，存储在字节2低4位）
|
||||
* 按需选择压缩策略，平衡性能和传输体积
|
||||
* 压缩方式枚举（3位，存储在字节1中3位，1~8范围）
|
||||
* 二进制标识，统一编码风格（1~8对应0b001~0b111）
|
||||
*/
|
||||
export enum CompressionType {
|
||||
NONE = 0b0000, // 无压缩（小数据包如控制指令、短文本，避免压缩开销）
|
||||
GZIP = 0b0001, // GZIP 压缩（大数据包如长文本、混合数据，减少网络传输量）
|
||||
NONE = 0b001, // 无压缩（1，默认值）
|
||||
GZIP = 0b010, // GZIP 压缩（2）
|
||||
// 预留6种方式用于扩展（0b011 ~ 0b111）
|
||||
}
|
||||
|
||||
/**
|
||||
* 控制指令枚举（配合 MessageType.CONTROL_CMD 使用）
|
||||
* 定义业务层面的控制指令，与 Python 端控制指令值一致
|
||||
*/
|
||||
export enum ControlCommand {
|
||||
HEARTBEAT = 0b0001, // 心跳响应（回复 PING 消息）
|
||||
PAUSE = 0b0010, // 暂停指令（如暂停音频播放）
|
||||
RESUME = 0b0011, // 继续指令（如恢复音频播放）
|
||||
STOP = 0b0100, // 停止指令（如停止音频传输）
|
||||
HEARTBEAT = 0b0001,
|
||||
PAUSE = 0b0010,
|
||||
RESUME = 0b0011,
|
||||
STOP = 0b0100,
|
||||
}
|
||||
|
||||
/**
|
||||
* 解包返回结果接口（强类型约束，明确返回数据结构）
|
||||
* 让 IDE 提供自动提示，避免类型错误
|
||||
* 解包返回结果接口
|
||||
*/
|
||||
export interface UnpackedResult {
|
||||
msgType: MessageType; // 消息类型（枚举值，便于逻辑判断）
|
||||
msgTypeName: keyof typeof MessageType; // 消息类型名称（字符串，如 "TEXT_MESSAGE"，便于日志打印）
|
||||
serialization: SerializationType; // 序列化方式（枚举值）
|
||||
serializationName: keyof typeof SerializationType; // 序列化方式名称（字符串）
|
||||
compression: CompressionType; // 压缩方式（枚举值）
|
||||
compressionName: keyof typeof CompressionType; // 压缩方式名称（字符串）
|
||||
body: Uint8Array | string | object | unknown[]; // 解包后的原始包体（根据序列化方式动态变化）
|
||||
msgType: MessageType;
|
||||
msgTypeName: keyof typeof MessageType;
|
||||
serialization: SerializationType;
|
||||
serializationName: keyof typeof SerializationType;
|
||||
compression: CompressionType;
|
||||
compressionName: keyof typeof CompressionType;
|
||||
sequence: number; // 消息顺序号（0~65535，默认0）
|
||||
body: Uint8Array | string | object | unknown[] | null; // PING 消息可能返回 null
|
||||
}
|
||||
|
||||
/**
|
||||
* 打包入参类型别名（简化方法入参类型定义，提高可读性）
|
||||
* 打包入参类型别名（支持 PING 消息传入 null）
|
||||
*/
|
||||
// 包体支持的类型：二进制、字符串、对象、数组
|
||||
type PackBody = Uint8Array | string | object | unknown[];
|
||||
// 序列化方式可选值：枚举值、null、undefined（null/undefined 时自动推导）
|
||||
type PackBody = Uint8Array | string | object | unknown[] | null;
|
||||
type OptionalSerialization = SerializationType | null | undefined;
|
||||
|
||||
/**
|
||||
* 协议编解码工具类（静态类，无需实例化，提供 pack/unpack 静态方法）
|
||||
* 核心功能：将业务数据打包为符合协议的二进制包，或解析二进制包为业务数据
|
||||
* 特点：与 Python/JS 端完全兼容，性能高效，类型安全
|
||||
* 协议编解码工具类（支持 PING 消息空包体）
|
||||
*/
|
||||
export class ProtocolCodec {
|
||||
/**
|
||||
* 打包协议包：将业务数据按协议格式封装为二进制包
|
||||
* @param msgType 消息类型（必须指定，枚举值）
|
||||
* @param body 业务数据（根据消息类型对应不同类型，如字符串、对象、Uint8Array）
|
||||
* @param serialization 序列化方式（可选，默认自动推导：纯文本→STRING，音频→RAW，复杂结构→JSON）
|
||||
* @param compression 压缩方式（可选，默认无压缩）
|
||||
* @returns 完整协议包（Uint8Array 类型，便于网络传输）
|
||||
* @throws 类型错误、不支持的枚举值、包体过大等异常
|
||||
* 打包协议包
|
||||
* @param msgType 消息类型（二进制枚举，0~15）
|
||||
* @param body 业务数据（PING 消息可传 null/undefined，其他类型必填）
|
||||
* @param sequence 消息顺序号（0~65535，可选，默认0）
|
||||
* @param serialization 序列化方式（二进制枚举，1~8，可选，自动推导）
|
||||
* @param compression 压缩方式（二进制枚举，1~8，可选，默认NONE=0b001）
|
||||
* @returns 完整协议包
|
||||
* @throws 类型错误、范围错误、包体过大等异常
|
||||
*/
|
||||
static pack(
|
||||
msgType: MessageType,
|
||||
body: PackBody,
|
||||
body: PackBody = null, // 默认为 null，支持 PING 消息空包体
|
||||
sequence: number = 0, // 可选参数，默认0
|
||||
serialization: OptionalSerialization = null,
|
||||
compression: CompressionType = CompressionType.NONE
|
||||
): Uint8Array {
|
||||
// 1. 自动推导序列化方式（减少调用方心智负担，按消息类型默认最优解）
|
||||
if (serialization === null || serialization === undefined) {
|
||||
// 校验顺序号范围（0~65535）
|
||||
if (!Number.isInteger(sequence) || sequence < 0 || sequence > 0xFFFF) {
|
||||
throw new RangeError(`消息顺序号必须是0~65535的整数，当前传入：${sequence}`);
|
||||
}
|
||||
|
||||
// 特殊处理：PING 消息允许空包体，强制 RAW 序列化（空二进制）
|
||||
if (msgType === MessageType.PING) {
|
||||
// PING 消息忽略传入的序列化方式，强制使用 RAW（空二进制最高效）
|
||||
serialization = SerializationType.RAW;
|
||||
// 若传入空包体，统一处理为空 Uint8Array
|
||||
body = body === null || body === undefined ? new Uint8Array(0) : body;
|
||||
// PING 消息仅支持空包体或 Uint8Array（防止误传其他类型）
|
||||
if (!(body instanceof Uint8Array)) {
|
||||
throw new TypeError(`PING 消息仅支持空包体或 Uint8Array 类型，当前传入：${typeof body}`);
|
||||
}
|
||||
} else {
|
||||
// 非 PING 消息：包体必填
|
||||
if (body === null || body === undefined) {
|
||||
throw new TypeError(`非 PING 消息（${MessageType[msgType]}）包体不能为空`);
|
||||
}
|
||||
}
|
||||
|
||||
// 1. 自动推导序列化方式（非 PING 消息）
|
||||
if (serialization === null || serialization === undefined && msgType !== MessageType.PING) {
|
||||
if (msgType === MessageType.AUDIO_DATA) {
|
||||
// 音频数据→RAW 序列化（无需编解码，性能最优）
|
||||
serialization = SerializationType.RAW;
|
||||
} else if (msgType === MessageType.TEXT_MESSAGE) {
|
||||
// 纯文本消息→STRING 序列化（直接 UTF-8 编码，无冗余）
|
||||
serialization = SerializationType.STRING;
|
||||
} else if (msgType === MessageType.CONTROL_CMD || msgType === MessageType.AUDIO_TEXT_MIX) {
|
||||
// 控制指令/混合数据→JSON 序列化（支持复杂结构）
|
||||
} else if (msgType === MessageType.CONTROL_CMD) {
|
||||
serialization = SerializationType.JSON;
|
||||
} else {
|
||||
// 非法消息类型：抛出异常，提前阻断错误
|
||||
throw new Error(`不支持的消息类型：${MessageType[msgType]}（值：${msgType}）`);
|
||||
}
|
||||
}
|
||||
|
||||
// 2. 序列化包体：将业务数据转为二进制（按序列化方式处理）
|
||||
let serializedBody: Uint8Array; // 序列化后的二进制数据
|
||||
const textEncoder = new TextEncoder(ProtocolConst.STRING_ENCODING); // UTF-8 编码器
|
||||
// 2. 校验枚举值范围（3位存储，1~8即0b001~0b111）
|
||||
if (serialization < 0b001 || serialization > 0b111) {
|
||||
throw new RangeError(`序列化方式必须在1~8（0b001~0b111）范围内，当前传入：${serialization}（0b${serialization.toString(2).padStart(3, '0')}）`);
|
||||
}
|
||||
if (compression < 0b001 || compression > 0b111) {
|
||||
throw new RangeError(`压缩方式必须在1~8（0b001~0b111）范围内，当前传入：${compression}（0b${compression.toString(2).padStart(3, '0')}）`);
|
||||
}
|
||||
|
||||
// 3. 序列化包体
|
||||
let serializedBody: Uint8Array;
|
||||
const textEncoder = new TextEncoder();
|
||||
|
||||
switch (serialization) {
|
||||
case SerializationType.RAW:
|
||||
// RAW 序列化：必须传入 Uint8Array（二进制数据直接透传）
|
||||
// RAW 序列化：支持 Uint8Array（PING 消息可能是空 Uint8Array）
|
||||
if (!(body instanceof Uint8Array)) {
|
||||
throw new TypeError(`RAW 序列化要求 body 必须是 Uint8Array 类型，当前传入：${typeof body}`);
|
||||
}
|
||||
@@ -134,7 +162,7 @@ export class ProtocolCodec {
|
||||
break;
|
||||
|
||||
case SerializationType.STRING:
|
||||
// STRING 序列化：必须传入字符串，直接 UTF-8 编码（无 JSON 包装）
|
||||
// STRING 序列化：必须传入字符串（非 PING 消息已校验非空）
|
||||
if (typeof body !== "string") {
|
||||
throw new TypeError(`STRING 序列化要求 body 必须是 string 类型，当前传入：${typeof body}`);
|
||||
}
|
||||
@@ -142,12 +170,10 @@ export class ProtocolCodec {
|
||||
break;
|
||||
|
||||
case SerializationType.JSON:
|
||||
// JSON 序列化：支持字符串、对象、数组，转为 JSON 字符串后 UTF-8 编码
|
||||
// JSON 序列化：支持字符串、对象、数组（非 PING 消息已校验非空）
|
||||
if (typeof body === "string") {
|
||||
// 已为字符串，直接编码
|
||||
serializedBody = textEncoder.encode(body);
|
||||
} else if (typeof body === "object" && body !== null) {
|
||||
// 对象/数组→JSON 字符串→编码（用 JSON.stringify 序列化）
|
||||
const jsonStr = JSON.stringify(body);
|
||||
serializedBody = textEncoder.encode(jsonStr);
|
||||
} else {
|
||||
@@ -156,183 +182,197 @@ export class ProtocolCodec {
|
||||
break;
|
||||
|
||||
default:
|
||||
// 非法序列化方式：抛出异常
|
||||
throw new Error(`不支持的序列化方式：${SerializationType[serialization]}（值：${serialization}）`);
|
||||
throw new Error(`不支持的序列化方式：${SerializationType[serialization]}（值：${serialization}，0b${serialization.toString(2).padStart(3, '0')}）`);
|
||||
}
|
||||
|
||||
// 3. 压缩包体：按指定压缩方式处理（GZIP 或无压缩）
|
||||
let compressedBody: Uint8Array; // 压缩后的二进制数据
|
||||
// 4. 压缩包体
|
||||
let compressedBody: Uint8Array;
|
||||
if (compression === CompressionType.NONE) {
|
||||
// 无压缩：直接透传序列化后的二进制数据
|
||||
compressedBody = serializedBody;
|
||||
} else if (compression === CompressionType.GZIP) {
|
||||
// 若需启用GZIP，取消注释下方代码（需导入pako）
|
||||
// try {
|
||||
// compressedBody = pako.gzip(serializedBody);
|
||||
// } catch (e) {
|
||||
// throw new Error(`GZIP 压缩失败：${(e as Error).message}`);
|
||||
// }
|
||||
throw new Error("GZIP 压缩暂未启用，请导入pako库并取消对应代码注释");
|
||||
} else {
|
||||
// 非法压缩方式：抛出异常
|
||||
throw new Error(`不支持的压缩方式：${CompressionType[compression]}（值：${compression}）`);
|
||||
throw new Error(`不支持的压缩方式：${CompressionType[compression]}（值：${compression}，0b${compression.toString(2).padStart(3, '0')}）`);
|
||||
}
|
||||
|
||||
// 4. 校验包体大小：防止超过最大限制（避免内存溢出）
|
||||
const bodyLen = compressedBody.length; // 压缩后的包体长度
|
||||
// 5. 校验包体大小（24位长度最大支持0xFFFFFF=16777215字节）
|
||||
const bodyLen = compressedBody.length;
|
||||
if (bodyLen > ProtocolConst.MAX_BODY_SIZE) {
|
||||
throw new Error(
|
||||
`包体过大（${bodyLen}字节），最大支持${ProtocolConst.MAX_BODY_SIZE}字节（10MB）`
|
||||
`包体过大（${bodyLen}字节），最大支持${ProtocolConst.MAX_BODY_SIZE}字节（≈16MB）`
|
||||
);
|
||||
}
|
||||
|
||||
// 5. 构造头部：8字节固定结构（严格按协议定义，大端序，与 Python 端一致）
|
||||
const header = new Uint8Array(ProtocolConst.HEADER_SIZE); // 头部缓冲区（8字节）
|
||||
// 6. 构造头部（8字节，按最新结构）
|
||||
const header = new Uint8Array(ProtocolConst.HEADER_SIZE);
|
||||
|
||||
// 字节1：消息类型(4位) + 保留位(4位)
|
||||
// 消息类型左移4位（占高4位），保留位填0（后续扩展用）
|
||||
header[0] = (msgType << 4) | 0x00;
|
||||
// 字节0：消息类型(高4位) + 协议版本(低4位)
|
||||
header[0] = ((msgType & 0x0F) << 4) | (ProtocolConst.PROTOCOL_VERSION & 0x0F);
|
||||
|
||||
// 字节2：序列化方式(4位) + 压缩方式(4位)
|
||||
// 序列化方式左移4位（占高4位），压缩方式占低4位（&0x0F 确保仅4位）
|
||||
header[1] = (serialization << 4) | (compression & 0x0F);
|
||||
// 字节1：序列化方式(高3位) + 压缩方式(中3位) + 保留位(低2位，填0)
|
||||
header[1] = ((serialization & 0x07) << 5) | ((compression & 0x07) << 2) | 0x00;
|
||||
|
||||
// 字节3~4：协议版本（16位大端序）
|
||||
// 大端序：高位字节在前，低位字节在后（网络传输标准字节序）
|
||||
header[2] = (ProtocolConst.PROTOCOL_VERSION >> 8) & 0xFF; // 版本高8位（当前版本为1，高8位为0）
|
||||
header[3] = ProtocolConst.PROTOCOL_VERSION & 0xFF; // 版本低8位（当前版本为1）
|
||||
// 字节2~3：消息顺序号（16位大端序，0~65535）
|
||||
header[2] = (sequence >> 8) & 0xFF; // 顺序号高8位
|
||||
header[3] = sequence & 0xFF; // 顺序号低8位
|
||||
|
||||
// 字节5~8：包体长度（32位大端序）
|
||||
// 32位整数：最高位字节（第5字节）→ 最低位字节（第8字节）
|
||||
header[4] = (bodyLen >> 24) & 0xFF; // 包体长度第24~31位
|
||||
header[5] = (bodyLen >> 16) & 0xFF; // 包体长度第16~23位
|
||||
header[6] = (bodyLen >> 8) & 0xFF; // 包体长度第8~15位
|
||||
header[7] = bodyLen & 0xFF; // 包体长度第0~7位
|
||||
// 字节4~6：消息体长度（24位大端序，0~0xFFFFFF）
|
||||
header[4] = (bodyLen >> 16) & 0xFF; // 长度高8位
|
||||
header[5] = (bodyLen >> 8) & 0xFF; // 长度中8位
|
||||
header[6] = bodyLen & 0xFF; // 长度低8位
|
||||
|
||||
// 6. 拼接头部和包体：生成完整协议包
|
||||
const totalLen = ProtocolConst.HEADER_SIZE + bodyLen; // 总长度 = 头部8字节 + 包体长度
|
||||
const packet = new Uint8Array(totalLen); // 完整包缓冲区
|
||||
// 字节7：保留位（固定填0x00）
|
||||
header[7] = 0x00;
|
||||
|
||||
packet.set(header, 0); // 从索引0开始写入头部（占前8字节）
|
||||
packet.set(compressedBody, ProtocolConst.HEADER_SIZE); // 从索引8开始写入包体
|
||||
// 7. 拼接头部和包体
|
||||
const totalLen = ProtocolConst.HEADER_SIZE + bodyLen;
|
||||
const packet = new Uint8Array(totalLen);
|
||||
packet.set(header, 0);
|
||||
packet.set(compressedBody, ProtocolConst.HEADER_SIZE);
|
||||
|
||||
return packet; // 返回完整协议包（Uint8Array，网络传输高效）
|
||||
return packet;
|
||||
}
|
||||
|
||||
/**
|
||||
* 解包协议包：将二进制协议包解析为业务数据
|
||||
* @param packet 完整协议包（网络接收的二进制数据，支持 Uint8Array 或 ArrayBuffer）
|
||||
* @returns 结构化解包结果（UnpackedResult 接口，包含消息类型、包体等信息）
|
||||
* @throws 包长度过短、版本不匹配、解压缩失败、反序列化失败等异常
|
||||
* 解包协议包
|
||||
* @param packet 完整协议包
|
||||
* @returns 结构化解包结果（含顺序号）
|
||||
* @throws 各种解析异常
|
||||
*/
|
||||
static unpack(packet: Uint8Array | ArrayBuffer): UnpackedResult {
|
||||
// 统一数据类型：将 ArrayBuffer 转为 Uint8Array（便于按字节操作）
|
||||
const uint8Packet = packet instanceof ArrayBuffer
|
||||
? new Uint8Array(packet)
|
||||
: packet;
|
||||
|
||||
// 1. 校验包长度：至少包含8字节头部
|
||||
// 1. 校验包长度（至少8字节头部）
|
||||
if (uint8Packet.length < ProtocolConst.HEADER_SIZE) {
|
||||
throw new Error(
|
||||
`包长度过短（${uint8Packet.length}字节），至少需要${ProtocolConst.HEADER_SIZE}字节头部`
|
||||
);
|
||||
}
|
||||
|
||||
// 2. 拆分头部和包体：前8字节为头部，剩余为包体
|
||||
const header = uint8Packet.subarray(0, ProtocolConst.HEADER_SIZE); // 头部（0~7索引）
|
||||
const bodyBuffer = uint8Packet.subarray(ProtocolConst.HEADER_SIZE); // 包体（8索引开始）
|
||||
// 2. 拆分头部和包体
|
||||
const header = uint8Packet.subarray(0, ProtocolConst.HEADER_SIZE);
|
||||
const bodyBuffer = uint8Packet.subarray(ProtocolConst.HEADER_SIZE);
|
||||
|
||||
// 3. 解析头部字段（按协议结构逐字节解析，大端序）
|
||||
// 字节1：消息类型(4位) + 保留位(4位)
|
||||
const byte1 = header[0];
|
||||
const msgType = (byte1 >> 4) & 0x0F; // 右移4位取高4位（消息类型），&0x0F 确保仅4位
|
||||
// 校验消息类型合法性（防止非法包注入）
|
||||
// 3. 解析头部字段
|
||||
// 字节0：消息类型(高4位) + 协议版本(低4位)
|
||||
const byte0 = header[0];
|
||||
const msgType = (byte0 >> 4) & 0x0F; // 消息类型（0~15）
|
||||
const version = byte0 & 0x0F; // 协议版本（0~15）
|
||||
|
||||
// 校验消息类型
|
||||
if (!Object.values(MessageType).includes(msgType as MessageType)) {
|
||||
throw new Error(`非法消息类型：${msgType}（无对应枚举值）`);
|
||||
throw new Error(`非法消息类型：${msgType}（0b${msgType.toString(2).padStart(4, '0')}）`);
|
||||
}
|
||||
|
||||
// 字节2：序列化方式(4位) + 压缩方式(4位)
|
||||
const byte2 = header[1];
|
||||
const serialization = (byte2 >> 4) & 0x0F; // 右移4位取高4位（序列化方式）
|
||||
const compression = byte2 & 0x0F; // 取低4位（压缩方式）
|
||||
// 校验序列化方式合法性
|
||||
if (!Object.values(SerializationType).includes(serialization as SerializationType)) {
|
||||
throw new Error(`非法序列化方式：${serialization}（无对应枚举值）`);
|
||||
}
|
||||
// 校验压缩方式合法性
|
||||
if (!Object.values(CompressionType).includes(compression as CompressionType)) {
|
||||
throw new Error(`非法压缩方式：${compression}（无对应枚举值）`);
|
||||
}
|
||||
|
||||
// 字节3~4：协议版本（16位大端序）
|
||||
const version = (header[2] << 8) | header[3]; // 大端序解析：高位字节<<8 + 低位字节
|
||||
// 校验版本兼容性（仅支持当前协议版本）
|
||||
// 校验版本
|
||||
if (version !== ProtocolConst.PROTOCOL_VERSION) {
|
||||
throw new Error(
|
||||
`协议版本不匹配：收到v${version}，当前支持v${ProtocolConst.PROTOCOL_VERSION}`
|
||||
`协议版本不匹配：收到v${version}（0b${version.toString(2).padStart(4, '0')}），当前支持v${ProtocolConst.PROTOCOL_VERSION}（0b${ProtocolConst.PROTOCOL_VERSION.toString(2).padStart(4, '0')}）`
|
||||
);
|
||||
}
|
||||
|
||||
// 字节5~8：包体长度（32位大端序）
|
||||
const bodyLen = (header[4] << 24) | (header[5] << 16) | (header[6] << 8) | header[7];
|
||||
// 校验包体长度一致性（头部声明长度 vs 实际包体长度）
|
||||
// 字节1：序列化方式(高3位) + 压缩方式(中3位) + 保留位(低2位)
|
||||
const byte1 = header[1];
|
||||
const serialization = (byte1 >> 5) & 0x07; // 高3位（1~8）
|
||||
const compression = (byte1 >> 2) & 0x07; // 中3位（1~8）
|
||||
// 保留位：(byte1 & 0x03)，暂不处理
|
||||
|
||||
// 校验序列化方式
|
||||
if (!Object.values(SerializationType).includes(serialization as SerializationType)) {
|
||||
throw new Error(`非法序列化方式：${serialization}（0b${serialization.toString(2).padStart(3, '0')}）`);
|
||||
}
|
||||
|
||||
// 校验压缩方式
|
||||
if (!Object.values(CompressionType).includes(compression as CompressionType)) {
|
||||
throw new Error(`非法压缩方式：${compression}（0b${compression.toString(2).padStart(3, '0')}）`);
|
||||
}
|
||||
|
||||
// 字节2~3：消息顺序号（16位大端序）
|
||||
const sequence = (header[2] << 8) | header[3]; // 0~65535
|
||||
|
||||
// 字节4~6：消息体长度（24位大端序），字节7：保留位（忽略）
|
||||
const bodyLen = (header[4] << 16) | (header[5] << 8) | header[6];
|
||||
|
||||
// 校验包体长度（空包体时 bodyBuffer.length 应为0）
|
||||
if (bodyBuffer.length !== bodyLen) {
|
||||
throw new Error(
|
||||
`包体长度不匹配：头部声明${bodyLen}字节，实际接收${bodyBuffer.length}字节（可能包丢失或非法包）`
|
||||
`包体长度不匹配：头部声明${bodyLen}字节，实际接收${bodyBuffer.length}字节`
|
||||
);
|
||||
}
|
||||
|
||||
// 4. 解压包体：按头部指定的压缩方式解压
|
||||
let decompressedBody: Uint8Array; // 解压后的二进制数据
|
||||
// 4. 解压包体
|
||||
let decompressedBody: Uint8Array;
|
||||
if (compression === CompressionType.NONE) {
|
||||
// 无压缩：直接透传包体数据
|
||||
decompressedBody = bodyBuffer;
|
||||
} else if (compression === CompressionType.GZIP) {
|
||||
// 若需启用GZIP，取消注释下方代码
|
||||
// try {
|
||||
// decompressedBody = pako.ungzip(bodyBuffer);
|
||||
// } catch (e) {
|
||||
// throw new Error(`GZIP 解压失败：${(e as Error).message}`);
|
||||
// }
|
||||
throw new Error("GZIP 解压暂未启用，请导入pako库并取消对应代码注释");
|
||||
} else {
|
||||
// 此处理论上不会触发（已提前校验压缩方式合法性）
|
||||
throw new Error(`不支持的压缩方式：${CompressionType[compression]}（值：${compression}）`);
|
||||
throw new Error(`不支持的压缩方式：${CompressionType[compression]}（值：${compression}，0b${compression.toString(2).padStart(3, '0')}）`);
|
||||
}
|
||||
|
||||
// 5. 反序列化包体：将二进制数据转为业务数据（按序列化方式处理）
|
||||
let body: UnpackedResult["body"]; // 反序列化后的原始业务数据
|
||||
const textDecoder = new TextDecoder(ProtocolConst.STRING_ENCODING); // UTF-8 解码器
|
||||
// 5. 反序列化包体（PING 消息空包体返回 null）
|
||||
let body: UnpackedResult["body"];
|
||||
const textDecoder = new TextDecoder();
|
||||
|
||||
switch (serialization) {
|
||||
case SerializationType.RAW:
|
||||
// RAW 反序列化：直接返回 Uint8Array（二进制数据，如音频 PCM）
|
||||
body = decompressedBody;
|
||||
break;
|
||||
// 特殊处理：空包体（PING 消息常见）返回 null
|
||||
if (decompressedBody.length === 0) {
|
||||
body = null;
|
||||
} else {
|
||||
switch (serialization) {
|
||||
case SerializationType.RAW:
|
||||
body = decompressedBody;
|
||||
break;
|
||||
|
||||
case SerializationType.STRING:
|
||||
// STRING 反序列化：UTF-8 解码为字符串（无 JSON 解析步骤）
|
||||
try {
|
||||
body = textDecoder.decode(decompressedBody);
|
||||
} catch (e) {
|
||||
throw new Error(`STRING 反序列化失败：${(e as Error).message}（UTF-8 解码错误，可能是非法字符串数据）`);
|
||||
}
|
||||
break;
|
||||
|
||||
case SerializationType.JSON:
|
||||
// JSON 反序列化：先 UTF-8 解码为字符串，再 JSON.parse 转为对象/数组
|
||||
try {
|
||||
const jsonStr = textDecoder.decode(decompressedBody); // 二进制→JSON 字符串
|
||||
body = JSON.parse(jsonStr); // JSON 字符串→对象/数组
|
||||
} catch (e) {
|
||||
if (e instanceof TypeError) {
|
||||
throw new Error(`JSON 反序列化失败：${ProtocolConst.STRING_ENCODING} 解码错误（非法 UTF-8 数据）`);
|
||||
} else if (e instanceof SyntaxError) {
|
||||
throw new Error(`JSON 反序列化失败：格式错误（${(e as Error).message}），请检查 JSON 语法`);
|
||||
} else {
|
||||
throw new Error(`JSON 反序列化失败：${(e as Error).message}`);
|
||||
case SerializationType.STRING:
|
||||
try {
|
||||
body = textDecoder.decode(decompressedBody);
|
||||
} catch (e) {
|
||||
throw new Error(`STRING 反序列化失败：UTF-8 解码错误`);
|
||||
}
|
||||
}
|
||||
break;
|
||||
break;
|
||||
|
||||
default:
|
||||
// 此处理论上不会触发（已提前校验序列化方式合法性）
|
||||
throw new Error(`不支持的序列化方式：${SerializationType[serialization]}（值：${serialization}）`);
|
||||
case SerializationType.JSON:
|
||||
try {
|
||||
const jsonStr = textDecoder.decode(decompressedBody);
|
||||
body = JSON.parse(jsonStr);
|
||||
} catch (e) {
|
||||
if (e instanceof SyntaxError) {
|
||||
throw new Error(`JSON 反序列化失败：格式错误（${(e as Error).message}）`);
|
||||
} else {
|
||||
throw new Error(`JSON 反序列化失败：${(e as Error).message}`);
|
||||
}
|
||||
}
|
||||
break;
|
||||
|
||||
default:
|
||||
throw new Error(`不支持的序列化方式：${SerializationType[serialization]}（值：${serialization}，0b${serialization.toString(2).padStart(3, '0')}）`);
|
||||
}
|
||||
}
|
||||
|
||||
// 6. 构造并返回解包结果（利用枚举反向映射获取名称，便于日志和展示）
|
||||
// 6. 返回解包结果
|
||||
return {
|
||||
msgType: msgType as MessageType, // 消息类型枚举值
|
||||
msgTypeName: MessageType[msgType] as keyof typeof MessageType, // 消息类型名称（如 "TEXT_MESSAGE"）
|
||||
serialization: serialization as SerializationType, // 序列化方式枚举值
|
||||
serializationName: SerializationType[serialization] as keyof typeof SerializationType, // 序列化方式名称
|
||||
compression: compression as CompressionType, // 压缩方式枚举值
|
||||
compressionName: CompressionType[compression] as keyof typeof CompressionType, // 压缩方式名称
|
||||
body: body, // 反序列化后的原始业务数据
|
||||
msgType: msgType as MessageType,
|
||||
msgTypeName: MessageType[msgType] as keyof typeof MessageType,
|
||||
serialization: serialization as SerializationType,
|
||||
serializationName: SerializationType[serialization] as keyof typeof SerializationType,
|
||||
compression: compression as CompressionType,
|
||||
compressionName: CompressionType[compression] as keyof typeof CompressionType,
|
||||
sequence: sequence,
|
||||
body: body,
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -8,10 +8,19 @@
|
||||
@onStop="stopIt">
|
||||
</yao-RecordFrame>
|
||||
<sdx-StreamPlayer ref="aaa">xx</sdx-StreamPlayer>
|
||||
<button @click="test">测试</button>
|
||||
</view>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
import {
|
||||
ProtocolCodec,
|
||||
MessageType,
|
||||
SerializationType,
|
||||
CompressionType,
|
||||
ControlCommand,
|
||||
ProtocolConst,
|
||||
} from './ProtocolCodec'; // 确保协议文件也是 ESModule 格式（export 导出）
|
||||
export default {
|
||||
data() {
|
||||
return {
|
||||
@@ -32,7 +41,10 @@
|
||||
},
|
||||
methods: {
|
||||
|
||||
test() {
|
||||
|
||||
|
||||
},
|
||||
// 申请录音权限
|
||||
async applyRecordPermission() {
|
||||
try {
|
||||
@@ -55,16 +67,16 @@
|
||||
// ArrayBuffer 转字符串
|
||||
// 兼容的 ArrayBuffer 转字符串方法
|
||||
arrayBufferToStringCompat(buffer) {
|
||||
// 方法1: 使用 String.fromCharCode 和 Uint8Array
|
||||
const uint8Array = new Uint8Array(buffer);
|
||||
let str = '';
|
||||
for (let i = 0; i < uint8Array.length; i++) {
|
||||
str += String.fromCharCode(uint8Array[i]);
|
||||
}
|
||||
return str;
|
||||
// 方法1: 使用 String.fromCharCode 和 Uint8Array
|
||||
const uint8Array = new Uint8Array(buffer);
|
||||
let str = '';
|
||||
for (let i = 0; i < uint8Array.length; i++) {
|
||||
str += String.fromCharCode(uint8Array[i]);
|
||||
}
|
||||
return str;
|
||||
|
||||
// 方法2: 或者使用更简洁的方式
|
||||
// return String.fromCharCode.apply(null, new Uint8Array(buffer));
|
||||
// 方法2: 或者使用更简洁的方式
|
||||
// return String.fromCharCode.apply(null, new Uint8Array(buffer));
|
||||
},
|
||||
// 开始录音
|
||||
async onStartRecord() {
|
||||
@@ -127,7 +139,7 @@
|
||||
// 处理帧数据（如实时上传/渲染）
|
||||
// console.log('帧数据:', frameData);
|
||||
this.ws.send({
|
||||
data: frameBuffer
|
||||
data: ProtocolCodec.pack(MessageType.AUDIO_DATA, frameBuffer);
|
||||
});
|
||||
},
|
||||
onDecibels: (decibels) => {
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
{
|
||||
"hash": "66599b56",
|
||||
"hash": "030e727a",
|
||||
"configHash": "c22f3258",
|
||||
"lockfileHash": "e3b0c442",
|
||||
"browserHash": "13ac6a72",
|
||||
"lockfileHash": "c10b225f",
|
||||
"browserHash": "77dd6173",
|
||||
"optimized": {},
|
||||
"chunks": {}
|
||||
}
|
||||
Reference in New Issue
Block a user