Python / 系统课时

设计一个异步 TCP 业务协议

设计一个异步 TCP 业务协议

异步 TCP 服务要先解决“字节流如何还原成一条业务消息”。本篇设计一套长度前缀协议,统一请求、响应、错误码与大小限制,并用可运行代码验证即使数据被拆成多段到达,也能稳定恢复完整消息。

学习目标

  • 设计包含版本、请求 ID、动作与载荷的请求/响应结构
  • 用长度前缀解决 TCP 无消息边界的问题
  • 为非法消息、未知动作和服务端异常定义稳定错误码

先固定业务消息模型

协议不要直接把某个 Python 类或函数参数暴露给客户端,而应先定义跨语言都容易实现的消息结构。这里使用 UTF-8 JSON 作为消息体,并给每次请求一个 requestId,让客户端可以把响应与原请求对应起来。

请求包含四个字段:

字段 类型 作用
version 整数 协议版本,便于后续兼容升级
requestId 字符串 一次请求的唯一标识
action 字符串 要执行的业务动作
payload 对象 动作需要的业务数据

响应保留相同的 version 与 requestId。成功时使用 ok: true 携带 data;失败时使用 ok: false 携带 error.code 与 error.message。这样客户端不需要从自然语言错误文本中推断失败类型。

用长度前缀定义消息边界

TCP 只提供有序字节流,不保证一次 write() 对应一次 read()。因此不能用“本次读到的字节数”判断一条消息是否结束。这里把每帧定义为“4 字节无符号大端长度 + JSON 消息体”。

长度前缀 TCP 业务帧结构

4 字节长度的理论上限很大,但服务端仍应设置业务上限,例如 1 MiB。否则攻击者可以先发送一个极大的长度值,诱导服务端长期等待或分配过多内存。

下面的示例把同一帧故意拆成三段喂给 StreamReader,验证解析逻辑不依赖网络分段方式。

python
import asyncio
import json
import struct

MAX_FRAME_SIZE = 1024 * 1024

def encode_message(message: dict) -> bytes:
    payload = json.dumps(
        message,
        ensure_ascii=False,
        separators=(",", ":"),
    ).encode("utf-8")
    if len(payload) > MAX_FRAME_SIZE:
        raise ValueError("frame too large")
    return struct.pack("!I", len(payload)) + payload

async def read_message(reader: asyncio.StreamReader) -> dict:
    header = await reader.readexactly(4)
    (length,) = struct.unpack("!I", header)
    if length > MAX_FRAME_SIZE:
        raise ValueError("frame too large")

    payload = await reader.readexactly(length)
    return json.loads(payload.decode("utf-8"))

async def main() -> None:
    request = {
        "version": 1,
        "requestId": "req-001",
        "action": "echo",
        "payload": {"text": "hello"},
    }
    frame = encode_message(request)

    # 模拟 TCP 把同一帧拆成多个到达片段。
    reader = asyncio.StreamReader()
    reader.feed_data(frame[:3])
    reader.feed_data(frame[3:9])
    reader.feed_data(frame[9:])
    reader.feed_eof()

    decoded = await read_message(reader)
    print(f"requestId={decoded['requestId']}")
    print(f"action={decoded['action']}")
    print(f"text={decoded['payload']['text']}")

asyncio.run(main())

预期输出

text
requestId=req-001
action=echo
text=hello

实际网络中的分段位置每次都可能不同,但输出应保持一致。生产代码还要处理 IncompleteReadError,它表示连接在一帧收完整之前已经关闭。

让错误码对客户端可编程

错误码应表示稳定的失败类别,而不是直接等于异常类名。客户端通常需要据此决定是修正请求、重试,还是记录服务端故障。

错误码 适用情况 客户端建议
INVALID_REQUEST JSON 合法,但字段缺失或类型错误 修正请求,不重试
UNSUPPORTED_VERSION version 不受支持 升级或降级协议
UNKNOWN_ACTION action 未注册 修正动作名
FRAME_TOO_LARGE 消息体超过上限 缩小请求
INTERNAL_ERROR 服务端未预期异常 可按策略有限重试

把协议约束写成双方都能检查的契约

实现客户端和服务端前,应明确版本策略、最大帧大小、字段必填规则、字符编码以及连接关闭语义。例如收到未知版本时立即返回错误并关闭连接;收到业务错误时可以保持连接继续处理后续请求。

一套可压测的协议不需要一开始就很复杂,但必须让“如何分帧、如何关联请求与响应、失败如何表达”没有歧义。只要这三点稳定,后续再增加认证、压缩或更多业务动作,也不会破坏最基本的读写边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计一个异步 TCP 业务协议

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通