Python socket 处理 TCP 粘包与半包:用长度前缀还原消息边界
TCP 提供可靠的字节流,但不保留应用层消息边界。连续发送的两条消息可能被一次 recv() 读到,也可能被拆成多次读取。若把一次 recv() 当成完整消息,就可能出现截断或拼接。
本文用 Python 标准库实现长度前缀协议:每条消息前放 4 字节网络字节序无符号整数,表示后续 payload 字节数。接收端累积数据,只在完整帧到齐后交付;不完整尾部留给下一次读取。示例限制单帧为 1024 字节,并拒绝超长声明和连接结束时的截断帧。
代码使用 socket、struct、sys 和内置类型,在 Python 3.12.3 的本机 socket.socketpair() 上测试,不访问网络服务或依赖第三方库。它是协议边界示例,不是生产级 TCP 服务端。
消息格式
一帧为:4 字节长度(网络字节序)加 payload 字节。长度指字节数而不是字符数;中文和 emoji 需要先用 UTF-8 编码再计算长度。struct.Struct(“!I”) 的 ! 表示网络字节序,I 表示 4 字节无符号整数。编码端和解码端都检查最大长度。
完整可运行代码
保存为 length_prefix_protocol.py:
from __future__ import annotations
import socket
import struct
import sys
HEADER = struct.Struct("!I")
MAX_PAYLOAD = 1024
class FrameError(ValueError):
"""Raised when a length-prefixed frame is invalid."""
def encode_frame(payload: bytes) -> bytes:
if len(payload) > MAX_PAYLOAD:
raise FrameError(f"payload too large: {len(payload)} > {MAX_PAYLOAD}")
return HEADER.pack(len(payload)) + payload
def feed_frames(buffer: bytearray, incoming: bytes) -> list[bytes]:
"""Append bytes and return every complete frame, retaining an incomplete tail."""
buffer.extend(incoming)
frames: list[bytes] = []
while len(buffer) >= HEADER.size:
(length,) = HEADER.unpack_from(buffer)
if length > MAX_PAYLOAD:
raise FrameError(f"declared payload too large: {length} > {MAX_PAYLOAD}")
total = HEADER.size + length
if len(buffer) < total:
break
start = HEADER.size
frames.append(bytes(buffer[start:total]))
del buffer[:total]
return frames
def recv_frames(sock: socket.socket) -> list[bytes]:
"""Read until EOF and decode all frames received from a stream socket."""
buffer = bytearray()
frames: list[bytes] = []
while True:
chunk = sock.recv(7)
if not chunk:
break
frames.extend(feed_frames(buffer, chunk))
if buffer:
raise FrameError(f"truncated frame: {len(buffer)} trailing bytes")
return frames
def assert_rejected(action, label: str) -> None:
try:
action()
except FrameError as exc:
print(f"rejected {label}: {exc}")
else:
raise AssertionError(f"{label} was accepted")
def main() -> None:
print("python:", sys.version.split()[0])
messages = ["", "hello", "中文🙂".encode("utf-8").decode(), "last"]
wire = b"".join(encode_frame(message.encode("utf-8")) for message in messages)
buffer = bytearray()
decoded: list[bytes] = []
chunk_sizes = [1, 2, 5, 3, 8, 13]
offset = 0
index = 0
while offset < len(wire):
size = chunk_sizes[index % len(chunk_sizes)]
decoded.extend(feed_frames(buffer, wire[offset:offset + size]))
offset += size
index += 1
assert decoded == [message.encode("utf-8") for message in messages]
assert not buffer
print("partial chunks decoded:", [item.decode("utf-8") for item in decoded])
left, right = socket.socketpair()
try:
left.sendall(encode_frame(b"socketpair") + encode_frame(b"two"))
left.shutdown(socket.SHUT_WR)
received = recv_frames(right)
assert received == [b"socketpair", b"two"]
print("socketpair decoded:", [item.decode("ascii") for item in received])
finally:
left.close()
right.close()
assert_rejected(lambda: encode_frame(b"x" * (MAX_PAYLOAD + 1)), "oversized payload")
oversized_header = HEADER.pack(MAX_PAYLOAD + 1)
assert_rejected(lambda: feed_frames(bytearray(), oversized_header), "oversized declaration")
truncated = encode_frame(b"complete")[:-1]
assert_rejected(lambda: recv_from_bytes(truncated), "truncated frame")
print("assertions: PASS")
def recv_from_bytes(data: bytes) -> list[bytes]:
left, right = socket.socketpair()
try:
left.sendall(data)
left.shutdown(socket.SHUT_WR)
return recv_frames(right)
finally:
left.close()
right.close()
if __name__ == "__main__":
try:
main()
except (AssertionError, OSError) as exc:
raise SystemExit(f"FAIL: {exc}")
运行:
python3 length_prefix_protocol.py
python3 -m py_compile length_prefix_protocol.py && echo "py_compile: PASS"
为什么不能只调用一次 recv()
recv(7) 的 7 只是本例故意设置的读取上限,不代表消息长度。feed_frames() 先追加数据,再循环读取 4 字节长度、判断缓冲区是否包含完整 payload,完整时取出帧并删除已消费的字节。只有半个头部或 payload 未到齐时保留缓冲区;一次读入两帧时循环连续取出。交付条件是完整帧已经到齐,而非 recv() 返回一次。
示例将空消息、ASCII、中文和 emoji 编成连续字节,再按 1、2、5、3、8、13 字节变化的大小喂给解析器。零长度帧仍有完整的 4 字节头部,因此也可还原。
安全和生产边界
长度前缀只解决消息边界,不提供身份认证、加密或防重放。双方必须遵守相同字节序和编码约定;扩展协议时要同步更新解析规则和最大长度。超长声明在解析长度后立即拒绝,生产代码还需要累计缓冲区上限、单连接和空闲超时、并发连接限制等,避免不完整消息长期占用资源。连接关闭时缓冲区仍有字节,本例会抛出 FrameError 而不是静默丢弃。
示例的 recv_frames() 使用阻塞 socket,在 EOF 后返回所有帧。真实服务端通常为每个连接保留缓冲区,在 selectors 或 asyncio 可读事件中调用 recv();一次事件可能产生零帧、一帧或多帧。发送端也不能假设一次 send() 写完全部数据,应该维护待发送缓冲区。asyncio 可用 StreamReader.readexactly() 读取固定头部和 payload,但仍需限制长度并处理 IncompleteReadError;TLS 依然需要应用层消息边界。
本例没有实现认证、加密、心跳、重连、背压、消息优先级、请求超时或版本协商,这些需要结合实际业务设计。
本地测试输出
python: 3.12.3
partial chunks decoded: ['', 'hello', '中文🙂', 'last']
socketpair decoded: ['socketpair', 'two']
rejected oversized payload: payload too large: 1025 > 1024
rejected oversized declaration: declared payload too large: 1025 > 1024
rejected truncated frame: truncated frame: 11 trailing bytes
assertions: PASS
py_compile: PASS
测试覆盖正常消息、分片输入、连续两帧、空消息、多字节 UTF-8、编码端超长数据、解码端超长声明和截断帧。测试使用本机 socket.socketpair(),没有创建 TCP 监听连接或访问外部网络,不能据此宣称验证了真实 TCP 链路、公网延迟、丢包、代理、TLS 或跨语言兼容性。
- 点赞
- 收藏
- 关注作者
评论(0)