Python asyncio 传输层与协议层完全指南:从 asyncio-transports 到低层事件循环 API

原创2026-09-06 18:50:141,896 阅读
文章标签:编程语言语言运行时解释器标准库并发编程

Python asyncio 传输层与协议层完全指南:从 asyncio-transports 到低层事件循环 API

本文深度讲解 CPython 官方文档 asyncio-protocol.rst 的核心主题——asyncio 的 Transports(传输层) 与 Protocols(协议层)。这是 loop.create_connection、loop.create_server、loop.create_datagram_endpoint、loop.subprocess_exec 等低层事件循环 API 的回调式编程模型,也是自研 HTTP、RPC 等高性能网络框架时的标准基础设施。读完本文,你将掌握 Transport/Protocol 类体系的每一类接口方法、回调状态机、写缓冲流控语义,并能徒手写出基于协议类的 TCP/UDP/子进程通信程序,同时理解它们在 Lib/asyncio/transports.py、Lib/asyncio/protocols.py、Lib/asyncio/selector_events.py 中真实的底层实现。

1. 为什么需要 Transports 与 Protocols

官方文档开篇便划清了边界:Transports 与 Protocols 只服务低层事件循环 API(low-level event loop APIs),例如 loop.create_connection()。它们采用回调式编程风格(callback-based programming style),可以支撑高性能网络/IPC 协议(如 HTTP)的实现。本质上,这两层抽象应该被库和框架使用,而绝不应出现在高层 asyncio 应用里——普通应用请优先使用基于流的 asyncio.open_connection / asyncio.start_server,或更上层的 asyncio.StreamReader/StreamWriter。

这一页文档同时覆盖 Transports 与 Protocols 两个主题,二者通过以下三种视角被区分:

  • 职责视角:transport 关心字节如何(how)被传输;protocol 决定传输哪些字节(which)、以及在何种时机传输。
  • 抽象视角:transport 是对 socket(或同类 I/O 端点)的抽象;protocol 则是站在 transport 视角对一个"应用程序"的抽象。
  • 接口视角:二者接口合在一起,定义了一套用于网络 I/O 与进程间 I/O 的抽象接口。

关键在于 transport 与 protocol 对象始终是 1:1 对应:protocol 调用 transport 的方法来发送数据,transport 调用 protocol 的方法来把收到的数据交给它。大多数面向连接的 event loop 方法(如 loop.create_connection())接受一个 protocol_factory 参数,用它为一个连接创建 Protocol 对象(该连接由 Transport 对象表示),并通常返回 (transport, protocol) 元组。

transport, protocol = await loop.create_connection(protocol_factory, host, port)

2. Transports 传输层:通信通道的抽象

实现源码:Lib/asyncio/transports.py

Transport 是 asyncio 为抽象各种通信通道而提供的类。transport 对象永远由 asyncio 事件循环实例化,用户不直接 new。asyncio 为 TCP、UDP、SSL、子进程管道(subprocess pipes) 提供了现成实现;transport 上可用的方法取决于其种类。所有 transport 类均非线程安全(详见文档中多线程约束章节)。

2.1 传输层类层次(Transports Hierarchy)

BaseTransport 是一切传输的基类,包含所有传输共有的方法:

  • BaseTransport:所有 asyncio transport 共有的方法基类。
  • WriteTransport(BaseTransport):只写连接的基础传输。实例由 loop.connect_write_pipe() 返回,也被 loop.subprocess_exec() 等子进程方法使用。
  • ReadTransport(BaseTransport):只读连接的基础传输。实例由 loop.connect_read_pipe() 返回,也被子进程相关方法(如 loop.subprocess_exec())使用。
  • Transport(WriteTransport, ReadTransport):双向传输接口,如一条 TCP 连接。用户不直接实例化,而是调用某个工具函数,把 protocol factory 及其它必要信息传给它;由事件循环方法返回/使用,例如 loop.create_connection()、loop.create_unix_connection()、loop.create_server()、loop.sendfile() 等。
  • DatagramTransport(BaseTransport):数据报(UDP)连接的传输,由 loop.create_datagram_endpoint() 返回。
  • SubprocessTransport(BaseTransport):父进程与其子 OS 进程之间连接的抽象,由 loop.subprocess_shell() 与 loop.subprocess_exec() 返回。

在源码中,这些类只是抽象接口,几乎所有方法在基类里都 raise NotImplementedError,唯一例外是 WriteTransport.writelines()(其默认实现将迭代对象拼接后调用 write()):

def writelines(self, list_of_data):
    data = b''.join(list_of_data)
    self.write(data)

(见 transports.py)

2.2 BaseTransport:通用方法与 get_extra_info 元信息查询

  • BaseTransport.close():关闭 transport。若存在出站数据缓冲,缓冲数据会异步冲刷;此后不再接收数据;待缓冲排空后,protocol 的 connection_lost() 会以 None 为参数被调用。transport 一旦关闭便不应再使用。
  • BaseTransport.is_closing():transport 正在关闭或已关闭时返回 True。
  • BaseTransport.get_extra_info(name, default=None):查询 transport 自身或其底层资源的信息。name 是待查信息的字符串;default 是在信息不可用、或当前第三方事件循环实现/当前平台不支持查询时返回的值。例如要取到底层 socket 对象:
sock = transport.get_extra_info('socket')
if sock is not None:
    print(sock.getsockopt(...))

文档列出了各类型传输上可查询的信息类别,实践中这是拿对端地址、套接字、TLS 参数的首选途径:

类别 键 name 含义
socket 'peername' 远端地址,socket.getpeername() 的结果(出错时为 None)
'socket' socket.socket 实例
'sockname' 本端地址,socket.getsockname() 的结果
SSL socket 'compression' 使用的压缩算法字符串;未压缩连接为 None(ssl.SSLSocket.compression())
'cipher' 三元组:所用 cipher 名称、定义其使用的 SSL 协议版本、使用的密钥位数(ssl.SSLSocket.cipher())
'peercert' 对端证书(ssl.SSLSocket.getpeercert())
'sslcontext' ssl.SSLContext 实例
'ssl_object' ssl.SSLObject 或 ssl.SSLSocket 实例
pipe 'pipe' 管道对象
subprocess 'subprocess' subprocess.Popen 实例

实现上,get_extra_info 只是对内部 _extra 字典的一次查询(transports.py);而 _extra 字典由具体实现填充——例如 selector_events.py 中 _SelectorTransport.__init__ 会写入 'socket'、'sockname'、'peername' 等键。

  • BaseTransport.set_protocol(protocol):设置新 protocol。只有当新旧两个 protocol 都声明支持切换时才应切换(典型的例子是 loop.start_tls() 升级到 SSL 时)。配套的 BaseTransport.get_protocol() 返回当前 protocol。

2.3 ReadTransport:只读传输与读取流控

  • ReadTransport.is_reading()(3.7+):transport 正在接收新数据时返回 True。
  • ReadTransport.pause_reading():暂停接收端。在 resume_reading() 被调用前,不会有数据递交给 protocol 的 data_received()。(3.7 起该方法是幂等的:在已暂停或已关闭的 transport 上也可调用。)
  • ReadTransport.resume_reading():恢复接收端。若有可读数据,data_received() 会再次被调用。(3.7 起同样是幂等的:已在读取状态也可调用。)

以 Linux/BSD 默认的 selector 事件循环实现为例,这三个方法直接操作 selector 的读写注册表(selector_events.py):

def is_reading(self):
    return not self.is_closing() and not self._paused

def pause_reading(self):
    if not self.is_reading():
        return
    self._paused = True
    self._loop._remove_reader(self._sock_fd)   # 从 epoll/kqueue 摘除读关注

def resume_reading(self):
    if self._closing or not self._paused:
        return
    self._paused = False
    self._add_reader(self._sock_fd, self._read_ready)  # 重新注册读回调

也就是说"暂停读取"在底层就是从事件循环的 selector 中摘除该 fd 的读事件,从而让内核不再上报可读事件、避免持续占用 CPU。

2.4 WriteTransport:只写传输与写缓冲流控

  • WriteTransport.abort():立即关闭 transport,不等待未完成操作。缓冲数据会丢失,不再接收数据,connection_lost() 最终以 None 被调用。对应源码中 _force_close(exc) 会先清空 _buffer(selector_events.py)。
  • WriteTransport.can_write_eof():transport 是否支持 write_eof()。
  • WriteTransport.get_write_buffer_size():当前出站缓冲区字节数。
  • WriteTransport.get_write_buffer_limits()(3.4.2+):返回 (low, high) 二元组,即写流控的低/高水位(单位字节),由 set_write_buffer_limits() 设置。
  • WriteTransport.set_write_buffer_limits(high=None, low=None):见下节详解。
  • WriteTransport.write(data):写入若干字节。不阻塞:数据先入缓冲,再由事件循环异步发送。
  • WriteTransport.writelines(list_of_data):写入一组字节(list 或任意 iterable)。功能等价于逐个元素调用 write(),但实现可能更高效——selector 实现会把每个片段打包为 memoryview 统一入队,甚至用 sendmsg() 一次写入多段(selector_events.py)。
  • WriteTransport.write_eof():冲刷所有缓冲后关闭写端;仍可继续接收数据。若 transport(如 SSL)不支持半关闭连接,该方法可抛 NotImplementedError。

写缓冲水位:何时触发 pause_writing/resume_writing

set_write_buffer_limits(high, low) 决定 protocol 的 pause_writing() / resume_writing() 何时被调用:

  • 缓冲大小大于等于 high 时……注意精确边界:官方文档强调,pause_writing() 需要缓冲大小严格超过(strictly over)high 水位才触发;反之 resume_writing() 在缓冲大小等于或低于(equal or lower)low 水位时触发。这些端点条件保证了当任一水位为 0 时行为依然符合预期。
  • 若仅指定 high,low 默认为实现相关的、≤ high 的值;只给 high 不给 low 时,low 不能为负。
  • high 置 0 会强制 low 也为 0,结果是只要缓冲非空就立刻 pause_writing();low 置 0 则要等缓冲完全清空才 resume_writing()。文档明确提示:把任一水位设为 0 通常并非最优,因为它削弱了"I/O 与计算并行"的机会(高频的暂停/恢复回调会打断应用持续写入与事件循环推进的节奏)。

关于"实现相关默认值",可以在 transports.py 的 _FlowControlMixin._set_write_buffer_limits() 找到默认算法:

def _set_write_buffer_limits(self, high=None, low=None):
    if high is None:
        if low is None:
            high = 64 * 1024        # 默认高水位:64 KiB
        else:
            high = 4 * low
    if low is None:
        low = high // 4             # 默认低水位:高水位的 1/4

    if not high >= low >= 0:
        raise ValueError(
            f'high ({high!r}) must be >= low ({low!r}) must be >= 0')

    self._high_water = high
    self._low_water = low

即:未设置任何参数时,high 默认为 64 KiB、low 默认为 16 KiB;只给 high 时 low 取 high // 4;只给 low 时 high 取 4 * low。配合 _maybe_pause_protocol()/_maybe_resume_protocol()(transports.py)可以看出:每次写入入队使缓冲增大后调用前者判断是否需要 pause_writing(),每次数据被内核取走、缓冲缩水后调用后者判断是否 resume_writing()。这两处回调异常会被统一收集进事件循环的 exception handler,而非直接抛出。

另外值得注意:protocols.py 的 docstring 特别注明,pause_writing()/resume_writing() 是唯一不经 EventLoop.call_soon() 间接调用的 protocol 回调——如果它也走 call_soon() 延迟执行,那么当应用在事件循环让步前持续狂写时,暂停指令将永远来不及生效。这正是它必须在发送路径上同步直调的原因。

2.5 DatagramTransport:UDP 数据报传输

  • DatagramTransport.sendto(data, addr=None):向 addr(transport 相关的目标地址)发送 data;addr 为 None 时发给创建 transport 时指定的目标地址。不阻塞,先入缓冲异步发送。
    • 3.13 起:可以用空 bytes 发送零长度数据报;用于流控的缓冲大小计算也改为把数据报头计入(见 selector_events.py,self._buffer_size += len(data) + self._header_size,_header_size = 8)。
  • DatagramTransport.abort():立即关闭,丢弃缓冲数据、不再接收,connection_lost() 最终以 None 回调。

selector 实现里 UDP 还区分了"已连接 UDP"与"未连接 UDP":_SelectorDatagramTransport 会优先尝试立即 send()/sendto(),失败(BlockingIOError)才注册写事件排队重发;每次发送产生 OSError 会转交给 protocol 的 error_received()(selector_events.py)。

2.6 SubprocessTransport:子进程传输

抽象父进程与子 OS 进程之间的连接,实例来自 loop.subprocess_shell() 与 loop.subprocess_exec():

  • SubprocessTransport.get_pid():以整数返回子进程 PID。
  • SubprocessTransport.get_pipe_transport(fd):取与文件描述符 fd 对应的管道 transport:
    • 0:标准输入(stdin)的可写流式 transport;若子进程未以 stdin=PIPE 创建则为 None;
    • 1:标准输出(stdout)的可读流式 transport;未以 stdout=PIPE 创建则为 None;
    • 2:标准错误(stderr)的可读流式 transport;未以 stderr=PIPE 创建则为 None;
    • 其它 fd:一律 None。
  • SubprocessTransport.get_returncode():返回子进程返回码(整数),未返回时为 None,语义同 subprocess.Popen.returncode。
  • SubprocessTransport.kill():杀死子进程。POSIX 上发 SIGKILL;Windows 上等价于 terminate()(参考 subprocess.Popen.kill)。
  • SubprocessTransport.send_signal(signal):向子进程发送信号编号 signal(同 Popen.send_signal)。
  • SubprocessTransport.terminate():终止子进程。POSIX 发 SIGTERM;Windows 调用 Win32 API TerminateProcess()(同 Popen.terminate)。
  • SubprocessTransport.close():若子进程尚未返回则调用 kill(),并关闭 stdin/stdout/stderr 管道的 transports。

3. Protocols 协议层:回调接口与状态机

实现源码:Lib/asyncio/protocols.py

asyncio 提供一组抽象基类用于实现网络协议,它们必须与 transports 搭配使用。抽象基类 protocol 的子类可以实现部分或全部方法;所有方法本质上都是回调(callbacks):由 transport 在特定事件发生时调用(如收到数据时),即"对应的 transport 应该调用基类协议方法"。

3.1 协议基类速览(Base Protocols)

  • BaseProtocol:所有协议共享方法的基类。
  • Protocol(BaseProtocol):实现流式协议(TCP、Unix socket 等)的基类。
  • BufferedProtocol(BaseProtocol):实现"手动控制接收缓冲"流式协议的基类。
  • DatagramProtocol(BaseProtocol):实现数据报(UDP)协议的基类。
  • SubprocessProtocol(BaseProtocol):实现与子进程通信(单向管道)协议的基类。

在 protocols.py 中这些基类的所有回调默认都是空实现(不抛异常),因此你可以只覆写关心的方法。

3.2 BaseProtocol:连接回调与流控回调

所有 asyncio 协议都可以实现 BaseProtocol 回调。

连接回调(Connection Callbacks)

连接回调在所有协议上都会被调用,且每次成功连接恰好各一次;其它一切 protocol 回调只能在这两个方法之间被调用。

  • BaseProtocol.connection_made(transport):连接建立时调用。参数 transport 即代表该连接的 transport;protocol 负责保存这个 transport 引用(例如存为 self.transport),否则后续无法发数据。
  • BaseProtocol.connection_lost(exc):连接丢失或被关闭时调用。参数是异常对象或 None——后者表示收到正常的 EOF,或本端中止/关闭了连接。

流控回调(Flow Control Callbacks)

transport 用它们暂停/恢复 protocol 的写入。细节见 2.4 节 WriteTransport.set_write_buffer_limits()。

  • BaseProtocol.pause_writing():transport 缓冲超过高水位时被调用。
  • BaseProtocol.resume_writing():transport 缓冲排空至低水位以下时被调用。

再次强调文档中的精确边界(结合 protocols.py 的 docstring 更清晰):

若缓冲大小等于高水位,pause_writing() 不被调用——必须严格超过;反之当缓冲大小等于或低于低水位时调用 resume_writing()。这两个端点条件用于保证任一水位为 0 时行为正确。pause_writing() 一旦触发只调用一次(即便后续继续追加数据),直到 resume_writing() 配对恢复。

3.3 Protocol:流式协议

loop.create_server()、loop.create_unix_server()、loop.create_connection()、loop.create_unix_connection()、loop.connect_accepted_socket()、loop.connect_read_pipe()、loop.connect_write_pipe() 等事件方法都接受返回流式协议的 factory。

  • Protocol.data_received(data):收到数据时调用。data 是非空 bytes 对象。数据是否被缓冲、分块或重组取决于 transport——一般来说不要依赖具体的分块语义,应让解析逻辑通用且灵活,但数据总是按正确顺序到达。连接打开期间此方法可被调用任意多次。
  • Protocol.eof_received():对端表示不再发送数据时调用(例如对端同样用 asyncio 时调用了 transport.write_eof())。最多调用一次;一旦 eof_received() 被调用,data_received() 不再被调用。
    • 返回值语义:返回假值(含 None)→ transport 关闭自己;返回真值 → 是否关闭由协议方决定。默认实现返回 None,因此隐式关闭连接。SSL 等不支持半关闭连接的 transport,即便返回真值也会被强制关闭。

Protocol 的完整生命周期状态机(CM=connection_made、DR=data_received、ER=eof_received、CL=connection_lost):

start -> connection_made
    [-> data_received]*
    [-> eof_received]?
-> connection_lost -> end

3.4 BufferedProtocol:手动接收缓冲(3.7+)

BufferedProtocol 适用于所有支持流式协议的 event loop 方法。 它允许协议实现显式地手动分配和控制接收缓冲。事件循环随后可复用协议提供的缓冲,避免不必要的内存拷贝,这对接收大量数据的协议能带来明显的性能提升;精巧的实现甚至可在创建连接时只分配一次缓冲,显著减少分配次数。

它新增两个回调:

  • BufferedProtocol.get_buffer(sizehint):被调用来分配新的接收缓冲。sizehint 是推荐的最小尺寸——返回比它更小或更大的缓冲都可以;sizehint 为 -1 时尺寸任意;返回零尺寸缓冲是错误。get_buffer() 必须返回实现**缓冲协议(buffer protocol)**的对象(如 bytearray、memoryview 等)。
  • BufferedProtocol.buffer_updated(nbytes):缓冲被写入接收数据后调用;nbytes 是写入缓冲的总字节数。
  • BufferedProtocol.eof_received():语义与 Protocol.eof_received() 相同。

get_buffer() 在连接期间可被调用任意多次;但 eof_received() 至多一次,一旦被调用,get_buffer() 与 buffer_updated() 便不再出现。状态机(GB=get_buffer、BU=buffer_updated):

start -> connection_made
    [-> get_buffer
        [-> buffer_updated]?
    ]*
    [-> eof_received]?
-> connection_lost -> end

底层零拷贝路径是怎么实现的

在默认 selector 实现中,transport 的读回调会根据 protocol 类型选择不同派发路径(selector_events.py):set_protocol() 时若 protocol 是 BufferedProtocol 子类,_read_ready_cb 指向 _read_ready__get_buffer,否则指向 _read_ready__data_received。两者的差别恰是文档所述"少一次拷贝"的关键:

# 普通 Protocol:先 recv 到内部缓冲,再传给 data_received(data),存在一次拷贝
data = self._sock.recv(self.max_size)
...
self._protocol.data_received(data)

# BufferedProtocol:直接把内核数据 recv_into 到协议自己分配的缓冲里,零拷贝直达
buf = self._protocol.get_buffer(-1)          # 向协议要缓冲
nbytes = self._sock.recv_into(buf)           # 内核直接写入该缓冲
self._protocol.buffer_updated(nbytes)        # 告知写入字节数

这正是 protocols.py 中 _feed_data_to_buffered_proto() 的配套逻辑:当协议返回的缓冲比待投递数据小(如阻塞式管道写、Proactor 回调场景)时,它会循环 get_buffer() -> 切片拷贝 -> buffer_updated(),直到把数据全部喂完,且若 get_buffer() 返回空缓冲会抛 RuntimeError('get_buffer() returned an empty buffer')。测试可参考 Lib/test/test_asyncio/test_buffered_proto.py 中的 ReceiveStuffProto 与 test_buffered_proto_create_connection。

3.5 DatagramProtocol:数据报(UDP)协议

DatagramProtocol 实例应由传给 loop.create_datagram_endpoint() 的 protocol factory 构造。

  • DatagramProtocol.datagram_received(data, addr):收到一个数据报时调用。data 为包含载荷的 bytes 对象;addr 为对端地址,确切格式取决于 transport。
  • DatagramProtocol.error_received(exc):当某次先前的发送/接收操作抛出 OSError 时调用,exc 为 OSError 实例。这只在罕见条件下触发:transport(如 UDP)检测到某个数据报无法送达收件人;多数情况下不可达的数据报会被静默丢弃。

BSD 系系统流控提示:macOS、FreeBSD 等 BSD 系统上,数据报协议不支持流控——因为没有可靠手段检测"因写入过多数据包导致的发送失败"。socket 看起来永远是"就绪"的,多余的数据包会被直接丢弃;errno 为 errno.ENOBUFS 的 OSError 可能抛出也可能不抛——若抛出会报告给 error_received(),否则被忽略。

3.6 SubprocessProtocol:子进程协议

SubprocessProtocol 实例应由传给 loop.subprocess_exec() 与 loop.subprocess_shell() 的 factory 构造:

  • SubprocessProtocol.pipe_data_received(fd, data):子进程向其 stdout/stderr 管道写入数据时调用。fd 为管道的整数文件描述符,data 为收到的非空 bytes 对象。
  • SubprocessProtocol.pipe_connection_lost(fd, exc):与子进程通信的某根管道关闭时调用。fd 为被关闭的文件描述符。
  • SubprocessProtocol.process_exited():子进程退出时调用。注意:它可能先于 pipe_data_received()/pipe_connection_lost() 被调用(即先知道退出、管道数据后到达),编写清理逻辑时必须容忍这种乱序。

4. 深入底层:事件循环如何"接线" Transport 与 Protocol

回顾 Lib/asyncio/base_events.py,create_connection(L1066)、create_server(L1542)、create_datagram_endpoint(L1388)、connect_read_pipe(L1716)、connect_write_pipe(L1732)、subprocess_shell(L1761)、subprocess_exec(L1797)等都由事件循环实现。典型流程(以 TCP 为例):

  1. 事件循环解析地址、创建并连接 socket;
  2. 调用传入的 protocol_factory() 实例化协议对象;
  3. 事件循环内部实例化对应 transport(如 selector 实现下的 _SelectorSocketTransport),并在构造时保存 protocol 引用、填充 _extra 信息(socket/sockname/peername);
  4. transport 用 loop.call_soon() 调度 protocol.connection_made(self),随后注册读事件——如 selector_events.py 注释所言:"only start reading when connection_made() has been called"(确保连接就绪回调先于任何数据到达);
  5. 此后每当内核报告可读,_read_ready() 分派到 data_received/get_buffer 路径(见 3.4);每当写入缓冲区变空且调用了 close(),则触发 _call_connection_lost(None) 通知协议。

这条"先 connection_made、后注册读写"的顺序保证了协议回调的确定性,也正是文档状态机得以成立的前提。在 Proactor(Windows IOCP)、SSL(见 Lib/asyncio/sslproto.py 中实现 BufferedProtocol 的 SSLProtocol)及 Unix 管道(Lib/asyncio/unix_events.py 的 _UnixReadPipeTransport/_UnixWritePipeTransport)等实现里,同样的接口约定被复用——这就是 Transport/Protocol 抽象真正的价值:业务协议代码与底层 I/O 机制解耦。

5. 完整实战示例:TCP/UDP/子进程协议编程

以下五个示例均直接取自官方文档(asyncio-protocol.rst 的 Examples 章节),运行于 Python 3.7+(asyncio.get_running_loop())。

5.1 TCP Echo Server(loop.create_server)

回显服务端:收到数据原样发回,然后关闭连接。

import asyncio


class EchoServerProtocol(asyncio.Protocol):
    def connection_made(self, transport):
        peername = transport.get_extra_info('peername')
        print('Connection from {}'.format(peername))
        self.transport = transport

    def data_received(self, data):
        message = data.decode()
        print('Data received: {!r}'.format(message))

        print('Send: {!r}'.format(message))
        self.transport.write(data)

        print('Close the client socket')
        self.transport.close()


async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    server = await loop.create_server(
        EchoServerProtocol,
        '127.0.0.1', 8888)

    async with server:
        await server.serve_forever()


asyncio.run(main())

对照:使用高层 asyncio.start_server 的流式 TCP 回显服务见文档 asyncio-streams.rst 的 "TCP echo server using streams" 示例。低层示例更短,但需要自己继承 Protocol 并管理 transport。

5.2 TCP Echo Client(loop.create_connection)

回显客户端:发送数据后等待连接被服务端关闭。

import asyncio


class EchoClientProtocol(asyncio.Protocol):
    def __init__(self, message, on_con_lost):
        self.message = message
        self.on_con_lost = on_con_lost

    def connection_made(self, transport):
        transport.write(self.message.encode())
        print('Data sent: {!r}'.format(self.message))

    def data_received(self, data):
        print('Data received: {!r}'.format(data.decode()))

    def connection_lost(self, exc):
        print('The server closed the connection')
        self.on_con_lost.set_result(True)


async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    on_con_lost = loop.create_future()
    message = 'Hello World!'

    transport, protocol = await loop.create_connection(
        lambda: EchoClientProtocol(message, on_con_lost),
        '127.0.0.1', 8888)

    # Wait until the protocol signals that the connection
    # is lost and close the transport.
    try:
        await on_con_lost
    finally:
        transport.close()


asyncio.run(main())

这里的惯用法值得学习:on_con_lost = loop.create_future() 让回调世界与协程世界对接——connection_lost 回调里 set_result,主协程 await 该 future。跑通 5.1 与 5.2,即可看到典型的一问一答输出。

5.3 UDP Echo Server(loop.create_datagram_endpoint)

UDP 回显服务端:单个协议实例服务所有客户端请求,不区分连接。

import asyncio


class EchoServerProtocol:
    def connection_made(self, transport):
        self.transport = transport

    def datagram_received(self, data, addr):
        message = data.decode()
        print('Received %r from %s' % (message, addr))
        print('Send %r to %s' % (message, addr))
        self.transport.sendto(data, addr)


async def main():
    print("Starting UDP server")

    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    # One protocol instance will be created to serve all
    # client requests.
    transport, protocol = await loop.create_datagram_endpoint(
        EchoServerProtocol,
        local_addr=('127.0.0.1', 9999))

    try:
        await asyncio.sleep(3600)  # Serve for 1 hour.
    finally:
        transport.close()


asyncio.run(main())

注意:这个协议类不继承 asyncio.DatagramProtocol 也可以运行——因为基类回调默认是空实现(见第 3.1 节说明),鸭子类型足够。

5.4 UDP Echo Client(loop.create_datagram_endpoint)

UDP 回显客户端:发一条消息,收到应答后关闭 transport。

import asyncio


class EchoClientProtocol:
    def __init__(self, message, on_con_lost):
        self.message = message
        self.on_con_lost = on_con_lost
        self.transport = None

    def connection_made(self, transport):
        self.transport = transport
        print('Send:', self.message)
        self.transport.sendto(self.message.encode())

    def datagram_received(self, data, addr):
        print("Received:", data.decode())

        print("Close the socket")
        self.transport.close()

    def error_received(self, exc):
        print('Error received:', exc)

    def connection_lost(self, exc):
        print("Connection closed")
        self.on_con_lost.set_result(True)


async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    on_con_lost = loop.create_future()
    message = "Hello World!"

    transport, protocol = await loop.create_datagram_endpoint(
        lambda: EchoClientProtocol(message, on_con_lost),
        remote_addr=('127.0.0.1', 9999))

    try:
        await on_con_lost
    finally:
        transport.close()


asyncio.run(main())

此处 error_received 展示了 3.5 节的错误回调入口,而 UDP "connected socket"(通过 remote_addr 创建)是 3.13 前流控/异常报告能正常工作的前提之一。

5.5 接入已存在的 socket(loop.create_connection(sock=...))

用协议对象等待一个已经创建好的 socket 收到数据(本例用 socket.socketpair() 造一对连通 socket 模拟网络收发):

import asyncio
import socket


class MyProtocol(asyncio.Protocol):

    def __init__(self, on_con_lost):
        self.transport = None
        self.on_con_lost = on_con_lost

    def connection_made(self, transport):
        self.transport = transport

    def data_received(self, data):
        print("Received:", data.decode())

        # We are done: close the transport;
        # connection_lost() will be called automatically.
        self.transport.close()

    def connection_lost(self, exc):
        # The socket has been closed
        self.on_con_lost.set_result(True)


async def main():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()
    on_con_lost = loop.create_future()

    # Create a pair of connected sockets
    rsock, wsock = socket.socketpair()

    # Register the socket to wait for data.
    transport, protocol = await loop.create_connection(
        lambda: MyProtocol(on_con_lost), sock=rsock)

    # Simulate the reception of data from the network.
    loop.call_soon(wsock.send, 'abc'.encode())

    try:
        await protocol.on_con_lost
    finally:
        transport.close()
        wsock.close()


asyncio.run(main())

对照:用低层 loop.add_reader() 直接监听 fd 的示例见官方文档 "watch a file descriptor for read events";用高层 streams open_connection 注册已打开 socket 的版本见 "register an open socket to wait for data using streams" 一节。可以看到,create_connection(sock=...) 是把已有 fd "搬进"事件循环的标准入口。

5.6 loop.subprocess_exec() 与 SubprocessProtocol

用子进程协议获取 date 输出并等待子进程退出:

import asyncio
import sys

class DateProtocol(asyncio.SubprocessProtocol):
    def __init__(self, exit_future):
        self.exit_future = exit_future
        self.output = bytearray()
        self.pipe_closed = False
        self.exited = False

    def pipe_connection_lost(self, fd, exc):
        self.pipe_closed = True
        self.check_for_exit()

    def pipe_data_received(self, fd, data):
        self.output.extend(data)

    def process_exited(self):
        self.exited = True
        # process_exited() method can be called before
        # pipe_connection_lost() method: wait until both methods are
        # called.
        self.check_for_exit()

    def check_for_exit(self):
        if self.pipe_closed and self.exited:
            self.exit_future.set_result(True)

async def get_date():
    # Get a reference to the event loop as we plan to use
    # low-level APIs.
    loop = asyncio.get_running_loop()

    code = 'import datetime as dt; print(dt.datetime.now())'
    exit_future = asyncio.Future(loop=loop)

    # Create the subprocess controlled by DateProtocol;
    # redirect the standard output into a pipe.
    transport, protocol = await loop.subprocess_exec(
        lambda: DateProtocol(exit_future),
        sys.executable, '-c', code,
        stdin=None, stderr=None)

    # Wait for the subprocess exit using the process_exited()
    # method of the protocol.
    await exit_future

    # Close the stdout pipe.
    transport.close()

    # Read the output which was collected by the
    # pipe_data_received() method of the protocol.
    data = bytes(protocol.output)
    return data.decode('ascii').rstrip()

date = asyncio.run(get_date())
print(f"Current date: {date}")

check_for_exit() 中的"双条件汇合"正是 3.6 节强调的回调乱序问题的标准解法:process_exited() 可能先于 pipe_connection_lost(),只有管道已关且进程已退,才认为收尾完成。使用高层 API(asyncio.create_subprocess_exec + StreamReader)的同一示例见官方文档对应章节。

6. 低层协议编程的测试与验证路径

想快速验证上述行为、或自行实现协议类后做回归,可阅读并复用标准库测试套件:

7. 选型总结:何时使用低层 Transports/Protocols

使用场景 推荐 API 层
普通应用中的客户端/服务端通信 高层:asyncio.open_connection / asyncio.start_server(Streams)
框架/库需要精确控制字节流、实现自有协议状态机 低层:Protocol/BufferedProtocol + 上述 event loop 方法
大流量接收、希望消除中间拷贝 BufferedProtocol(3.7+),单连接预分配缓冲
UDP 通信 DatagramProtocol + loop.create_datagram_endpoint()
启动子进程并逐字节消费其 stdout/stderr SubprocessProtocol + loop.subprocess_exec()/subprocess_shell()
把既有 fd/对端已 accept 的 socket 纳入事件循环 loop.create_connection(sock=...) / loop.connect_accepted_socket()
只读/只写管道端点 loop.connect_read_pipe() / loop.connect_write_pipe()

最后回到官方文档最核心的两句忠告,值得反复咀嚼:

  1. transport 决定字节怎么传,protocol 决定传哪些字节——划分好二者职责,是写出可维护网络框架的前提;
  2. transport 与 protocol 永远是 1:1——protocol 通过保存的 transport 发送数据,transport 通过回调驱动 protocol,二者共同构成一套面向网络与进程间 I/O 的抽象接口;面向连接的 event loop 方法(create_connection 一族)接受 protocol_factory 并返回 (transport, protocol) 元组,整篇接口文档都围绕这条 1:1 契约展开。

本文所有接口方法、回调语义与状态机均忠实对应 Doc/library/asyncio-protocol.rst,实现细节则可沿 Lib/asyncio/transports.py、Lib/asyncio/protocols.py、Lib/asyncio/selector_events.py 与 Lib/asyncio/base_events.py 按图索骥、继续深挖。

登录后查看全文
cpython