干网络协议的人大概都遇到过这种尴尬抓包工具里清清楚楚显示 TCP 数据但里面全是24 00 00 04 00 00 00 00 00之类的二进制字节根本看不出这是请求还是响应、是头还是体。HTTP/2 跟 HTTP/1.1 最大的区别就是“半二进制化”——你没法再用肉眼在一堆 ASCII 里找到 URL 了。我当时为了搞懂这些字节把 python-hyper 生态里的 hyperframe 库翻了个底朝天。这个库很小核心代码也就几百行但它做了一件非常纯粹的事把 HTTP/2 的每一帧从字节变成对象再把对象变回字节。hyperframes 这个话题表面看是讲一个库实际是把 HTTP/2 分帧层的协议细节全部摊开。适合想深入理解 HTTP/2 的 Python 后端工程师、爬虫开发者以及所有写过代理或抓包工具、但对帧层还停留在“大概知道”阶段的人。1. 为什么协议栈里最不起眼的“分帧层”反而最值得单独研究1.1 一个 HTTP/2 帧的 9 字节头信息密度远超你想象HTTP/2 和 HTTP/1.1 的一个本质区别是它的请求和响应被拆成了“帧”在 TCP 连接上传输。每个帧由两部分组成固定 9 字节的帧头 不定长的帧体payload。帧头是整个协议的命门因为它决定了这一帧是什么、属于哪个流、后面跟着多长的数据。偏移长度字段说明03payload 长度24 位无符号整数网络字节序最大 1677721531帧类型0~9 为 RFC 9113 定义类型10 以上供扩展41标志位按帧类型含义不同同一字节在不同帧里代表完全不同的东西54流标识符最高位必须为 0实际有效位数 31 位取值 0~2^31-1很多初学者会把第一个字段理解成“整个帧的长度”这是错的。这 3 字节只表示帧体长度不包含 9 字节帧头。也就是说一个帧在网络上的总字节数等于9 payload_length。解析多帧连续数据时offset 的推进必须按9 帧头里读到的长度来走差的这 9 个字节会让整个解析器错位而且是那种最难查的错位。1.2 先搞清楚 hyperframe 在整个 HTTP/2 生态里的位置python-hyper 项目其实是一个家族我经常看到有人把它们混为一谈hyperframe只做帧层的编码和解析不关心业务不关心连接状态不关心头部压缩。hpack专门处理 HTTP/2 的头部压缩HPACK作用是让:method、:path这些键值对变成紧凑的二进制。h2高层协议实现负责连接状态机、流管理、流量控制内部同时依赖 hyperframe 和 hpack。hyper早期基于上述库做的完整 HTTP/2 客户端。写这篇文章只围绕 hyperframe 展开不是因为它比 h2 好用而是因为它是整个链路里最接近“协议事实”的一层。h2 会自动帮你判断帧合不合法、该不该发送、如何回复 ACK而 hyperframe 不做这些判断它只负责忠实还原这一帧是什么类型、带什么标志、属于哪个流、承载什么字节。调试的时候把 h2 的“礼貌”全部剥掉直接面对帧本身反而能最快定位问题。2. hyperframe 的编码模型用对象替代字节流再用字节流触发对象2.1 从 Frame 基类到十几个帧子类的映射hyperframe 的核心设计非常直观一个Frame基类 十几个子类每个子类对应一种帧类型。Frame.parse_frame_header()读取 9 字节头里的类型字段自动实例化对应的子类然后把帧体交给子类的parse_body()去解析序列化方向则是子类的serialize()把对象重新拼回字节。type 值hyperframe 中的类帧名通常作用0DataFrameDATA传输请求/响应体1HeadersFrameHEADERS传输头部块打开新流2PriorityFramePRIORITY设置流优先级依赖3RstStreamFrameRST_STREAM终止某个流4SettingsFrameSETTINGS连接级参数协商5PushPromiseFramePUSH_PROMISE服务端推送承诺6PingFramePING探活与 RTT 测量7GoAwayFrameGOAWAY连接级优雅关闭8WindowUpdateFrameWINDOW_UPDATE流量控制窗口更新9ContinuationFrameCONTINUATION头部块的后续分段10AltSvcFrameALTSVC广播替代服务如果你愿意还能调用register_frame注册自定义帧类型。这一点让 hyperframe 并不局限于标准协议遇到私有扩展帧也能解析成对象而不是直接报“未知类型”。2.2 解析流程9 字节头如何决定后面 body 的命运parse_frame_header是进入 hyperframe 世界的唯一入口。它只要求至少 9 字节返回两个值已经实例化但还没完整填充 body 的 Frame 对象以及帧头里声明的 payload 长度。注意它不会等 body 全部到齐再返回它只是把当前 buffer 里能拿到的9 length字节截出来交给对应的parse_body处理。所以官方推荐的用法是先确保 buffer 里至少有 9 字节解析头部拿到 length再判断 buffer 是否已经攒够了9 length字节。够了解析不够就继续等。这个“解析器必须自带缓冲等待机制”的思路直接决定了后面第 3 节里那个通用解析器的写法。2.3 标志位是位掩码不是布尔值帧头的第 5 个字节是标志位但千万别把它当成一个表示“是否结束”的布尔值。它是一整字节的位掩码不同帧类型对每个 bit 的定义完全不同。hyperframe 把所有标志定义放进了Flags类里。比如一个 HeaderFrame 的 flags 字节是0x25二进制是00100101拆开看等于0x1 | 0x4 | 0x200x01END_STREAM本帧是流的最后一帧0x04END_HEADERS头部块到此结束后面没有 CONTINUATION 了0x20PRIORITY本帧带优先级信息判断一个标志是否置位正确做法是用位与from hyperframe.frame import Flags if frame.flags Flags.END_STREAM: print(这个流到这里结束了)不要写成frame.flags Flags.END_STREAM因为一个帧可以同时带多个标志位直接判等会把0x25这种合法组合误判成“不是 END_STREAM”。这是我第一次写 HTTP/2 解析器时踩过的坑看起来基础但代价是大量请求被当成“未结束”处理白白等半天超时才报错。3. 实测连上一个真实 HTTPS 站点把每一帧都剥开看3.1 最小环境与连接代码先装依赖pip install hyperframe h2这里用h2不是为了避开 hyperframe而是为了让它帮我们完成 HTTP/2 握手发送 client preface、发送 HEADERS 帧、处理服务端的 SETTINGS 帧。真正“看帧”的工作全部交给 hyperframe。import socket import ssl import h2.connection from hyperframe.frame import Frame sock socket.create_connection((nghttp2.org, 443), timeout10) ctx ssl.create_default_context() ctx.set_alpn_protocols([h2, http/1.1]) sock ctx.wrap_socket(sock, server_hostnamenghttp2.org) print(ALPN 协商结果:, sock.selected_alpn_protocol()) conn h2.connection.H2Connection() conn.initiate_connection() sock.sendall(conn.data_to_send()) conn.send_headers( stream_id1, headers[ (:method, GET), (:path, /), (:scheme, https), (:authority, nghttp2.org), (:user-agent, hyperframe-demo/1.0), ], end_streamTrue, ) sock.sendall(conn.data_to_send())3.2 逐帧程序与输出解读接下来把 socket 收到的数据按帧切开def parse_frame_stream(byte_stream): offset 0 while offset len(byte_stream): if offset 9 len(byte_stream): break header_view byte_stream[offset:offset 9] frame, payload_length Frame.parse_frame_header(header_view) print( ftype{frame.type} flags{frame.flags:#04x} fstream{frame.stream_id} body_len{payload_length} ) offset 9 payload_length for _ in range(5): data sock.recv(65535) if not data: break parse_frame_stream(data)跑起来后你会看到一类典型输出ALPN 协商结果: h2 type4 flags0x0 stream0 body_len18 type4 flags0x1 stream0 body_len0 type1 flags0x5 stream1 body_len... type0 flags0x1 stream1 body_len...第一行type4是服务端发来的 SETTINGS 帧stream_id 是 0说明这是连接级帧body 里带了 3 组参数每组 6 字节正好 18 字节。第二行flags0x1对 SETTINGS 来说是 ACK表示它确认收到了我们发出的 SETTINGS。这两行都没有 stream_id它们属于整个连接而不是某个请求。第三行type1 flags0x5 stream1才是真正的响应头部0x5 0x1 | 0x4表示这个流同时带 END_STREAM 和 END_HEADERS。也就是说响应的头部块在这里结束而且因为 GET 请求没有 body流也在这里结束。如果你请求一个较大页面还会看到 DATA 帧接在后面最后一个 DATA 帧会带上0x1这个 END_STREAM 标志。这个细节很典型同一个0x1在 SETTINGS 帧里叫 ACK在 DATA 帧里叫 END_STREAM完全两码事。3.3 半包/粘包把 recv 缓冲区安全切成帧的通用解析器上面这个例子有个偷懒前提每次recv回来的数据恰好是完整的一帧或多帧。真实环境几乎不可能这么干净尤其是高并发长连接TCP 是字节流不是消息流一次recv可能只拿到半个帧也可能一口气吞下几十个帧。这就是半包和粘包问题。一个能进生产环境的解析器必须自带累积缓冲class FrameBufferParser: def __init__(self): self.buffer b def feed(self, data): self.buffer data while True: if len(self.buffer) 9: break frame, payload_length Frame.parse_frame_header(self.buffer[:9]) total_frame_len 9 payload_length if len(self.buffer) total_frame_len: break # 帧还没攒齐等下一次 feed full_frame_bytes self.buffer[:total_frame_len] self.buffer self.buffer[total_frame_len:] yield frame, full_frame_bytes这段逻辑看起来简单却是所有 HTTP/2 抓包工具的基础。核心要点是两个判断先判len(buffer) 9表示连帧头都没攒够再判len(buffer) total_frame_len表示帧体没到齐。两次判断的顺序不能反。我在实际项目里遇到过把这两行写反的情况结果在遇到超大帧时索引越界排查了整整一个下午。4. 反向构造流量控制与探活的三种手写帧4.1 SETTINGS 帧给对端立规矩前先看 6 字节参数槽光会解析还不够用 hyperframe 最爽的是可以徒手造帧。比如你想主动告诉对端“最多同时开 100 条流”可以这样from hyperframe.frame import SettingsFrame settings SettingsFrame(settings{0x3: 100}) # SETTINGS_MAX_CONCURRENT_STREAMS 0x3 wire settings.serialize() print(wire.hex())SETTINGS 帧体是一组 6 字节的参数前 2 字节是参数 ID后 4 字节是参数值全部网络字节序。常用的参数 ID 包括ID参数默认值含义0x1HEADER_TABLE_SIZE4096HPACK 动态表大小上限0x2ENABLE_PUSH1是否允许服务端推送0x3MAX_CONCURRENT_STREAMS无限制单连接最大并发流数0x4INITIAL_WINDOW_SIZE65535流级流量控制窗口初始值0x5MAX_FRAME_SIZE16384单帧最大 payload 长度0x6MAX_HEADER_LIST_SIZE无限制头部块解压后最大字节数注意一个坑仅当 SETTINGS 帧不带 ACK 标志时body 里才能放这些参数带 ACK 标志的 SETTINGS 帧body 必须是 0 字节。如果违反对端会直接判定FRAME_SIZE_ERROR。hyperframe 不拦你它会忠实地把你构造出来的非法 SETTINGS ACK 帧也序列化出去然后由对端给你一记重拳。4.2 WINDOW_UPDATE 帧31 位窗口增量背后的协议防御流量控制是 HTTP/2 里最容易出问题的部分。连接级和流级各有一个“窗口”对端没有收到足够的 WINDOW_UPDATE就不会继续发 DATA。手写一个补窗口的帧非常容易from hyperframe.frame import WindowUpdateFrame wu WindowUpdateFrame(stream_id0, window_increment65535) sock.sendall(wu.serialize())但很多人在window_increment上吃过亏。这里有个隐藏规则WINDOW_UPDATE 帧体是一个 4 字节整数但最高位必须为 0也就是实际有效窗口增量只有 31 位最大值是2^31 - 1 2147483647。如果你不小心填了2147483648前面的比特位会置 1协议栈会认为你在协商一个非法值并直接断开连接。为什么协议要留这一个保留位因为它要防止窗口增量出现负整数或者回绕导致的不可控状态。理解了这一点你就知道为什么所有实现都会严格检查这个最高位而不是像处理普通整数那样放过去。另外WINDOW_UPDATE 按作用范围分两种stream_id0是补连接总窗口stream_idN是补第 N 条流的窗口。很多人只补流级窗口、忘了补连接级窗口导致连接明明建着对端的 DATA 却永远发不过来。抓包看到的现象就是连接活得好好的PING 也正常就是业务数据一动不动。4.3 PING 帧8 字节荷载的 RTT 探针连接假死的另一个排查手段是 PING。PING 帧类型为 6stream_id 必须为 0body 固定 8 字节可以随便填通常放时间戳或随机数。收到 PING 的一方必须原样返回一个带 ACK 标志的 PING。import struct import time from hyperframe.frame import PingFrame payload struct.pack(!Q, int(time.time() * 1_000_000) % 2**64) ping PingFrame(opaque_datapayload) sock.sendall(ping.serialize())对端回 ACK 时你拿当前时间减去发送时记录的时间就是一次很准的 RTT 测量。这个技巧在排查“连接看起来还活着但数据不动”时特别好用如果 RTT 正常说明网络通问题大概率在流控或协议状态如果 RTT 超时说明 TCP 链路本身已经挂了。5. 最容易出事的三个细节帧长、CONTINUATION 和同名标志位5.1 帧长上限为什么 16384 是默认值为什么 3 字节还会溢出帧头第一个字段只有 3 字节所以协议设计上允许的最大帧体是2^24 - 1 16777215字节。但 RFC 规定在没有协商的情况下对端的帧体长度不能超过 16384 字节2^14只有通过 SETTINGS 帧里的MAX_FRAME_SIZE调大才能突破这个限制。这个默认值其实是个折中TCP 是流协议一个过大的 HTTP/2 帧如果只发了一半发送端要等接收端 ACK 才能继续发同帧的后续字节吗不HTTP/2 帧本身没有“分段”的概念一个帧必须完整的、一次性由 TCP 递交到应用层。帧体越大接收端就要在缓冲区里等越久占内存越高。所以默认 16384 是为了在“单帧能装下的数据量”和“缓冲区等待成本”之间取一个平衡值。用 hyperframe 解析时它不会替你校验这个长度限制。你完全可以构造一个 2MB prelude 的 DATA 帧发出去至于对端是否接受那是另一个问题。如果你做的是抓包工具最好自己在解析层加一条检查如果收到的 payload_length 大于对端声明过的MAX_FRAME_SIZE至少打个警告不要老实等着攒完 16MB 才发现这是个畸形帧。5.2 CONTINUATION 与 HEADERS 共用一个 HPACK 比特流HTTP/2 头部并不是完整放在一个 HEADERS 帧里的。当头部块经过 HPACK 压缩后仍然太长时协议会把它拆成 1 个 HEADERS 帧 N 个 CONTINUATION 帧。判断方式看 HEADERS 帧是否带END_HEADERS标志带了说明头部块到此结束没带后面必须紧跟 CONTINUATION而且中间不允许插入任何其他类型的帧。我第一次抓大请求头时看到连续五六个 type9 的帧还以为自己解析器坏了其实它们合起来才是完整的头部。如果你用 hyperframe 手动拼头部需要这样聚合header_block b while True: if frame.type 1 and not (frame.flags 0x04): header_block frame.body break # 等后面的 CONTINUATION elif frame.type 9: header_block frame.body if frame.flags 0x04: break # 头部块凑齐注意在 HEADERS 没有结束标志的情况下如果中间出现 DATA 帧、SETTINGS 帧甚至 PING 帧对端会报COMPRESSION_ERROR并直接 GOAWAY。这不是“语法有点问题”而是 HPACK 动态表状态被打破后续所有头部解析都不可能正确了所以必须断掉整个连接。这也就是为什么很多代理工具在处理大头部时特别小心宁可等齐一整个头部块也不允许其他帧插队。5.3 同一个 0x01 标志在不同帧里意思完全不同这是本文最想强调的一点。0x01 这个比特位在不同帧类型里的含义完全不同帧类型0x01 标志含义DATAEND_STREAM数据结束HEADERSEND_STREAM头部和流一起结束SETTINGSACK确认参数PINGACK确认收到了 pingPUSH_PROMISEEND_HEADERS头块结束所以写解析器时第一步必须先用frame.type分流再根据帧类型解释标志位。如果只写一个全局的if frame.flags Flags.END_STREAM你会把 SETTINGS ACK 和 PING ACK 全部误判成流结束。hyperframe 把所有 flag 定义集中在Flags类里按位定义但跨帧类型复用所以做判断时务必先确认当前帧的类型。这个习惯养成之后再回去看自己以前写的“通用 HTTP/2 解析器”基本都会冷汗直流。6. 连接异常排错让帧自己开口说话6.1 GOAWAY 帧的 error_code 是连接级事故的唯一裁判HTTP/2 连接级错误通常以 GOAWAY 帧收场。GOAWAY 的 body 分为三段最后处理的流 ID、错误码、附加调试信息。用 hyperframe 解析时GoAwayFrame 会把这些字段暴露成对象属性。实战中看到 GOAWAY先看错误码错误码名称触发场景0x0NO_ERROR正常关闭0x1PROTOCOL_ERROR帧顺序/结构违反协议0x2INTERNAL_ERROR对端内部错误0x3FLOW_CONTROL_ERROR窗口量非法0x4SETTINGS_TIMEOUT没等到 SETTINGS ACK0x5STREAM_CLOSED在已关闭流上发帧0x6FRAME_SIZE_ERROR帧体长度非法0x7REFUSED_STREAM流被拒绝可安全重试0x8CANCEL流被取消0x9COMPRESSION_ERRORHPACK 解压失败0xbENHANCE_YOUR_CALM带宽滥用0xdHTTP_1_1_REQUIRED需要退回 HTTP/1.1比如你收到error_code0x9问题基本锁定在 HPACK 动态表状态不一致上典型原因是自己把 h2 的收发顺序打乱导致某个头部块的解压上下文错位。别再傻傻去查 DNS、查防火墙。6.2 案例一RST_STREAM 只杀单流别动整个连接有一次线上服务突发大量连接重建当时的直觉是 HTTP/2 连接出问题了于是把客户端 HTTP/2 连接池的错误日志翻出来。结果发现真正的问题是一连串RstStreamFrame错误码是0x8 (CANCEL)但连接本身并没有 GOAWAY后续请求依然在这条连接上正常完成。用 hyperframe 写个过滤逻辑把所有 RST_STREAM 按 stream_id 和 error_code 聚合一下from collections import Counter from hyperframe.frame import RstStreamFrame rst_counter Counter() if isinstance(frame, RstStreamFrame): rst_counter[(frame.stream_id, frame.error_code)] 1聚合出来的结果非常明确某个服务端在大量取消特定路径的流但连接从未被关闭。这说明问题在下游服务处理策略而不是 HTTP/2 握手失败。如果当时把整条连接关掉重建不仅解决不了问题还会白白增加 TCPTLS 握手开销。记住一个原则RST_STREAM 只针对某个流GOAWAY 才针对整个连接。6.3 案例二WINDOW_UPDATE 记错对象造成的假死连接另一个真实场景是“连接活得好好的业务就是不推进”。这时我的排查顺序是先看有没有 PING ACK确认链路通不通再统计所有 WINDOW_UPDATE 帧是按哪个 stream_id 发的。有一次发现自己实现的客户端把所有 WINDOW_UPDATE 都累加到了连接级窗口上而实际服务端发来的 DATA 是挂在某个 stream_id 上的。服务端所见的连接级窗口早已枯竭客户端却以为自己在不停补窗口。两边状态不一致结果就是服务端一直不推数据客户端一直傻等。用 hyperframe 把流级和连接级的 window_increment 分开统计问题一目了然conn_window 0 stream_windows Counter() if isinstance(frame, WindowUpdateFrame): if frame.stream_id 0: conn_window frame.window_increment else: stream_windows[frame.stream_id] frame.window_increment修复方式是把窗口记账逻辑改成“流级窗口和连接级窗口分开维护”补连接级窗口用stream_id0的 WINDOW_UPDATE补流级窗口用对应的stream_id。这个坑在新手实现协议栈时尤其常见因为很多教程为了简化示例只演示了连接级窗口结果读者照抄之后稍微一发大 body 就卡死。回到 hyperframe 这个库本身它教会我的最重要一件事是不要怕二进制协议。帧头就 9 个字节类型、标志、流 ID 三个字段掰开揉碎之后所有抓包工具里那些“看起来很神秘”的输出都有了确定的含义。我后来给自己写了个 30 行的frame_dump日志函数每次接入新的 HTTP/2 场景第一件事就是跑一遍逐帧 dump把 type、flags、stream_id 全打出来比自己对着 RFC 猜半天高效得多。如果你也在排查 HTTP/2 相关问题建议先把 bin 层的帧整理清楚再谈业务层的优化。