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 消息体”。

4 字节长度的理论上限很大,但服务端仍应设置业务上限,例如 1 MiB。否则攻击者可以先发送一个极大的长度值,诱导服务端长期等待或分配过多内存。
下面的示例把同一帧故意拆成三段喂给 StreamReader,验证解析逻辑不依赖网络分段方式。
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())预期输出
requestId=req-001
action=echo
text=hello实际网络中的分段位置每次都可能不同,但输出应保持一致。生产代码还要处理 IncompleteReadError,它表示连接在一帧收完整之前已经关闭。
让错误码对客户端可编程
错误码应表示稳定的失败类别,而不是直接等于异常类名。客户端通常需要据此决定是修正请求、重试,还是记录服务端故障。
| 错误码 | 适用情况 | 客户端建议 |
|---|---|---|
INVALID_REQUEST |
JSON 合法,但字段缺失或类型错误 | 修正请求,不重试 |
UNSUPPORTED_VERSION |
version 不受支持 |
升级或降级协议 |
UNKNOWN_ACTION |
action 未注册 |
修正动作名 |
FRAME_TOO_LARGE |
消息体超过上限 | 缩小请求 |
INTERNAL_ERROR |
服务端未预期异常 | 可按策略有限重试 |
把协议约束写成双方都能检查的契约
实现客户端和服务端前,应明确版本策略、最大帧大小、字段必填规则、字符编码以及连接关闭语义。例如收到未知版本时立即返回错误并关闭连接;收到业务错误时可以保持连接继续处理后续请求。
一套可压测的协议不需要一开始就很复杂,但必须让“如何分帧、如何关联请求与响应、失败如何表达”没有歧义。只要这三点稳定,后续再增加认证、压缩或更多业务动作,也不会破坏最基本的读写边界。