JavaLYG

Python TCP接收JSON偶发缺半截:用长度前缀与循环读取保留消息边界

一、JSON偶发缺半截,先别急着补重试

Python阻塞TCP连接里,发送方明明传了一份完整JSON,接收方却偶发报解码错误;把recv缓冲调大,问题又暂时消失。先检查是否把一次recv当成一条消息。下面用四字节长度头和循环读取恢复应用层消息边界,并用本机回环与人工分片分别验证。

这是一类长期存在的协议设计问题,不是某个新版本突然引入的故障。完整实验只用标准库,实际运行环境是Python 3.14.3。

二、TCP保留字节顺序,不替你保留消息

TCP提供字节流,没有一次send对应一次recv的承诺。一次发送的内容可能需要多次接收;连续发送的两条消息也可能已经一起到达接收缓冲区。recv(4096)的参数是本次最多返回的字节数,不是必须凑够4096才返回。

因此,直接对每次recv的结果执行json.loads,既可能遇到半份JSON,也可能遇到两份JSON连在一起。中文还可能在UTF-8字符的中间断开。把缓冲调大或者加sleep,只是改变时机,不会生成消息边界;按大括号切割,也处理不了字符串内容和嵌套结构。

官方Socket HOWTO列出固定长度、分隔符、长度信息和关闭连接几种结束方式。本文选择长度前缀,允许同一连接连续传多帧。HTTP等成熟协议已有自己的消息规则时,应使用对应协议库,不要再套一层自创规则。

Python TCP字节流与长度前缀循环读取对照
图为本例应用层4字节长度前缀方案:左侧是单次读取的局限,右侧是处理路径,两者不是等价方案。先循环读满头、解析并校验正文长度,再循环读正文;长度不含头部。完整帧仍可能解码失败,业务结果另验。

三、协议先写清:长度数的是字节

每帧由四字节头加正文组成。头使用struct的!I格式:网络字节序、四字节无符号整数;正文是UTF-8编码的JSON对象。必须先编码再取len,不能把中文字符串的字符数填入头中。收发双方也不能一边用二进制头,另一边按十进制文本解析。

演示把正文限制为1至4096字节,收到头后立即检查,再读取正文;拒绝零长度是本文的业务策略,不是TCP的限制。空对象{}编码后并非零字节,仍能正常传输。为避免JSON的null与帧前EOF都返回None产生歧义,示例只接受JSON对象,数组、数字和null均拒绝;对象内字段还需业务另行校验。

改旧程序时,必须让收发两端约定一致,不能只升级接收端。若旧端原来直接发送JSON,新端却把最前四个字符当长度,就会读出完全错误的数值。先用隔离连接核对原始字节,再确定切换方式;需要兼容时另行约定版本字段与握手,不靠猜测首字符决定格式。收到合法对象之后,也要逐项检查业务字段、类型和允许范围,不能因为大括号配对成功就直接执行操作。

四、完整代码:头和正文都循环读取

保存为sample.py,运行python3 sample.py。读取定长函数每次只请求尚缺的字节:先凑齐四字节头,再凑齐正文。这样不会顺手拿走下一帧;如果改成大块预读,就必须自行保存未消费的尾部,不能直接丢掉。

代码里的分片接收是人工recv适配器,专门确定性制造小片返回与同一缓冲中连续两帧,不是对真实网络分包的观察。真实TCP部分只监听127.0.0.1的随机端口,使用很小的两帧数据,无线程、无sleep;它不假定操作系统如何拆分每次recv。

import json
import socket
import struct

上限 = 4096


def 读取定长(连接, 长度, 允许帧前结束=False):
    数据 = bytearray()
    while len(数据) < 长度:
        分片 = 连接.recv(长度 - len(数据))
        if not 分片:
            if 允许帧前结束 and not 数据:
                return None
            raise EOFError("头或正文尚未读完,连接已结束")
        数据.extend(分片)
    return bytes(数据)


def 编帧(对象):
    if not isinstance(对象, dict):
        raise ValueError("演示协议只接收JSON对象")
    正文 = json.dumps(对象, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
    if not 1 <= len(正文) <= 上限:
        raise ValueError("正文长度超出1..4096字节")
    return struct.pack("!I", len(正文)) + 正文


def 接收对象(连接):
    try:
        头 = 读取定长(连接, 4, True)
        if 头 is None:
            return None
        长度 = struct.unpack("!I", 头)[0]
        if not 1 <= 长度 <= 上限:
            raise ValueError("拒绝零长度或超大帧")
        对象 = json.loads(读取定长(连接, 长度).decode("utf-8"))
        if not isinstance(对象, dict):
            raise ValueError("演示协议只接收JSON对象")
        return 对象
    except (OSError, EOFError, ValueError):
        连接.close()  # 超时或坏帧后不从流中间恢复
        raise


class 分片接收:
    # 人工recv适配器,不是对真实TCP分片的观察
    def __init__(self, 数据, 片长=1, 超时=False):
        self.数据, self.片长, self.超时 = 数据, 片长, 超时
        self.已关闭, self.调用数 = False, 0

    def recv(self, 长度):
        self.调用数 += 1
        if self.超时:
            raise TimeoutError("人工单操作超时")
        分片 = self.数据[:min(长度, self.片长)]
        self.数据 = self.数据[len(分片):]
        return 分片

    def close(self):
        self.已关闭 = True


def 自检():
    通过数 = 0

    def 检查(条件, 名称):
        nonlocal 通过数
        if not 条件:
            raise RuntimeError("检查失败:" + 名称)
        通过数 += 1
        print("通过:" + 名称)

    def 拒绝(数据, 异常, 名称, 超时=False):
        连接 = 分片接收(数据, 4096, 超时)
        try:
            接收对象(连接)
        except 异常:
            检查(连接.已关闭, 名称)
        else:
            raise RuntimeError("未拒绝:" + 名称)
        return 连接

    中文 = {"消息": "中文你好"}
    检查(接收对象(分片接收(编帧(中文))) == 中文, "人工头体逐字节读取")
    缓冲 = 分片接收(编帧(中文) + 编帧({}), 4096)
    检查(接收对象(缓冲) == 中文 and 接收对象(缓冲) == {}
         and 接收对象(缓冲) is None, "人工同一缓冲两帧及EOF")
    检查(接收对象(分片接收(b"")) is None, "人工帧前EOF")
    拒绝(b"\x00", EOFError, "人工短头")
    拒绝(struct.pack("!I", 3) + b"{}", EOFError, "人工短体")
    超大 = 拒绝(struct.pack("!I", 上限 + 1) + b"unread", ValueError, "人工超大头")
    检查(超大.调用数 == 1, "超大头未读取正文")
    拒绝(struct.pack("!I", 0), ValueError, "人工零长度头")
    拒绝(struct.pack("!I", 1) + b"\xff", UnicodeDecodeError, "人工非法UTF8")
    拒绝(struct.pack("!I", 1) + b"{", json.JSONDecodeError, "人工非法JSON")
    拒绝(struct.pack("!I", 4) + b"null", ValueError, "人工非对象JSON")
    拒绝(b"", TimeoutError, "人工超时关闭", True)
    临界 = {"x": "a" * (上限 - 8)}
    检查(len(编帧(临界)) == 上限 + 4
         and 接收对象(分片接收(编帧(临界), 31)) == 临界, "人工4096字节边界")
    try:
        编帧({"x": "a" * 上限})
    except ValueError:
        检查(True, "发送前拒绝超大正文")
    else:
        raise RuntimeError("发送前未拒绝超大正文")
    # 小数据、阻塞连接;无需线程、sleep或假设recv分片大小
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as 监听:
        监听.settimeout(2)
        监听.bind(("127.0.0.1", 0))
        监听.listen(1)
        with socket.create_connection(监听.getsockname(), timeout=2) as 发送端:
            接收端, _ = 监听.accept()
            with 接收端:
                接收端.settimeout(2)
                发送端.sendall(编帧(中文) + 编帧({}))
                发送端.shutdown(socket.SHUT_WR)
                检查(接收对象(接收端) == 中文 and 接收对象(接收端) == {}
                     and 接收对象(接收端) is None, "真实AF_INET回环两帧中文空对象及EOF")
    print(f"完成:{通过数}项检查;人工适配器与真实回环分开记录")


if __name__ == "__main__":
    自检()

五、EOF、超时和坏帧不能混着处理

请求正数长度时,recv返回空字节表示接收方向已到EOF,不表示“现在没消息,等会儿再试”。如果新帧一个头字节都没读到,函数返回None;已经读到部分头,或者头声明的正文尚未读完,则抛EOFError。对端关闭写方向后仍可能继续读,因此EOF也不等于双方所有方向都已关闭。

超时、非法UTF-8或非法JSON都会使接收函数关闭连接并重新抛出异常,不尝试从流中间重新找下一帧。调用层仍应通过with或finally收尾。这里的两秒是单次socket操作的超时,不是整帧的总时间预算;循环多次recv可能累计更久。sendall自身的超时覆盖该次完整发送操作,也不能据此推出整项业务的截止时间。

现象常见原因或边界处理方向
JSON缺尾或中文解码失败把一次recv当作完整正文先读取长度,再按剩余量循环
JSON报Extra data两份文档落在同一段字节中按帧解析,保留后续字节
头也不足四字节头同样可能分多次返回读头不能只调用一次recv
零长度或超大长度不符合演示协议读取正文前拒绝并关闭
头中、体中EOF或超时本帧结果不完整或未知停止使用连接,不盲目重发业务

六、发送完成,不等于业务成功

sendall会持续发送给定字节,直到全部发送或发生错误;成功返回None,并不证明对端已经解析JSON,更不证明数据库写入等业务已完成。发送报错时,也不能据此确定到底有多少字节已经成功发送。

因此,网络超时不能直接转换成“安全重试一次”。有副作用的业务还需要请求标识、幂等约定和应用层响应。本例只讨论阻塞连接上的分帧;同一连接的并发读必须串行,同方向多写者也须串行,不能让两帧字节交叉。双向交互的读写协作、认证、TLS、总预算、限流和背压都未实现,不是生产就绪框架。

七、验收要区分真实连接与人工输入

随文代码共完成15项显式检查,不依赖assert;默认、-O和-OO模式的数量一致。人工输入覆盖逐字节读头读体、同缓冲两帧、帧前EOF、短头短体、超大头及不读正文、零头、非法编码、非法JSON、非对象JSON、超时关闭、4096字节边界和发送前超限拒绝。最后一项是实际AF_INET回环上的中文对象、空对象、连续两帧与EOF。

  • 检查长度采用UTF-8字节数,发送和接收的字节序一致。
  • 检查头与正文均按剩余量循环,坏帧不继续复用连接。
  • 检查帧前EOF与截断帧分开处理,异常向调用层传播。
  • 检查监听与连接均由上下文退出关闭,没有后台线程遗留。
  • 检查输出成功不越界解释为公网、TLS或真实业务验收。

八、对照官方资料再决定扩展方式

需要扩展协议时,先约定消息类型、最大长度、错误响应与业务确认,再考虑压缩或并发。长度前缀解决的是“这一帧到哪里结束”,不是消息内容可信、业务恰好执行一次或者连接永不失败。

  1. Python 3.14 socket文档:核对recv返回值、缓冲上限,以及同页sendall的完成与错误语义。
  2. Python Socket Programming HOWTO:核对消息结束方式、连续消息尾部保留,以及读头读体需要两层循环的说明。

🔕 评论已关闭