Python socket 处理 TCP 粘包与半包:用长度前缀还原消息边界

举报
yd_226410095 发表于 2026/11/18 07:23:23 2026/11/18
【摘要】 用 Python 标准库实现并实测长度前缀帧解析,处理半包、粘包、空消息、超长声明和截断帧,并说明真实 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 或跨语言兼容性。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。