patch_jack

一句话：你在本机开个端口等人连；外面的交换程序按自己的配置主动连上来。连上之后怎么转发、走哪条线，都由交换程序决定，本库帮你处理「监听、收发、编解码」这些脏活。

适合你吗

1. 你的进程只想在本机被动监听，不想写「主动去连中央」的客户端。
2. 可能有多路交换程序（或多实例）要同时连到同一个业务进程。
3. 你想直接发 Python 对象（字典、数据类、带校验的模型），不想手搓二进制协议。

三条里命中任意一条，就值得往下看。

常用词对照

设计特性

你只管开端口，谁来连由交换程序决定

1. 你在代码里指定本机要绑的 主机 和 端口（端口也可以写 0，让系统随便挑一个空的）。
2. 交换程序读自己的表，主动连你这个地址。
3. 你不用在业务里记「中央在哪」——对方会来找你。

好几台交换程序可以同时连你

• 不会因为「已经有一台连上了」就把后来的拒掉。
• 每台连接单独维护；发数据时可以一起通知当前所有连接。

发一次，所有连着的人都收到同一份

你发一条业务消息时：

1. 内容会原样发给当前所有连接。
2. 大家拿到的是同一份字节和同一个序号，方便各台交换程序各自做路由、对账。

你平时还是写 Python 对象，不用自己拼二进制

回调可以写类型，对不上就不瞎调

• 处理函数第一个参数可以写类型注解。
• 对得上的才调用；对不上会打日志，不会悄悄把错数据塞进你的函数。

想打日志可以挂几个小钩子

适合记日志、做调试的同步回调包括（名字不必背，知道「有这回事」即可）：

1. 监听起来了 / 有人连上或断开
2. 收到对端转过来的数据 / 发不出去
3. 对面报错 / 收到「已收到」的确认

钩子别太耗时；重活请自己 create_task 或丢线程池。

想看得顺眼可以装彩色日志（不装也行）

• 装了常见彩色终端库：事件可以打成一行、带颜色。
• 没装：退回标准 logging，不会因为少依赖就崩。

端口写 0 也行，起来后再问「我实际监听的是哪」

端口写 0  →  启动完成  →  取 listen_address 字符串
         →  复制到交换程序配置里的 address

本机「全零监听」时，也会给你一个适合写进本机配置的地址形式（含 IPv6 时的括号习惯）。

命令行跑着时，Ctrl+C 能正常收尾

库带一个「等到用户想退出再继续」的辅助协程，适合示例和小脚本：收到中断或退出意图后，可以统一关掉监听和连接，不至于一团糟。