如何安全取消 wreq 请求？深入 HTTP/1、HTTP/2、HTTP/3 的 Cancel Safety 完整指南-育师

【免费下载链接】wreq

An ergonomic, privacy-aware Rust HTTP Client

项目地址：https://gitcode.com/gh_mirrors/rq/wreq

wreq 是一个注重易用性与隐私的 Rust 异步 HTTP 客户端。在 wreq 中取消请求的方式非常统一：丢弃（drop）try_send_request返回的请求 future 即可。但不同协议下，这次取消真正"做到"的事情完全不同——这就是cancel safety（取消安全性）的核心差异。

本文带你 3 分钟搞懂：wreq 中取消请求的底层机制、HTTP/1、HTTP/2、HTTP/3 三种协议的取消行为差异，以及让取消真正生效的实操要点。🎯

先搞懂统一模型：丢弃 future = 取消请求

wreq 对三个协议采用同一个取消入口，官方文档把它称为 "Cancel safety"：

请求 future 支持取消：在 future 完成前 drop 它，就是取消该操作的标准方式。协议决定这次取消在网络上实际做什么。

请求被取消后，仍在排队的请求会得到TrySendError（定义见 dispatch.rs）；
连接上后续发出的请求会返回canceled 错误，可以用Error::is_canceled判断，错误信息显示为"operation was canceled"。

完整说明见模块级文档：lib.rs。

一张表看懂三大协议的取消差异

协议	取消时在网络上做什么	连接能否复用	影响范围
HTTP/1	关闭底层 I/O（协议无单请求中止机制）	❌ 不能	整条连接
HTTP/2	发送`RST_STREAM`（`CANCEL`错误码）	✅ 可以	仅单条流
HTTP/3	用`H3_REQUEST_CANCELLED`取消未完成的发送/接收方向	✅ 可以	仅单个请求

HTTP/1 取消：整条连接"陪葬" ⚠️

HTTP/1 的响应是按顺序串行写在同一条连接上的，协议本身没有"只中止第 N 个请求"的手段。所以 wreq 的处理是：

你 drop 掉 in-flight 的请求 future；
连接驱动器观察到取消后关闭底层 I/O；
同一个SendRequest上后续所有调用都会返回canceled错误——连接不可复用，需要重建连接。

HTTP/2 取消：RST_STREAM 精准重置单条流 ✅

HTTP/2 是多路复用的：一条连接上有许多独立的"流"（stream），取消可以精准到流。

wreq 的做法是：若请求流已打开，取消时会发送RST_STREAM帧并携带CANCEL错误码（对应 RFC 9113 §7），通知对端停止处理这条流——而不是继续传输一个反正会被丢弃的响应体。重置帧由后台任务在驱动时发出，共享连接对其它在途及后续请求完全不受影响。

核心实现：检测到客户端取消后发送重置，见 proto/http2/client.rs；行为文档见 conn/http2.rs。

HTTP/3 取消：双向取消，连接继续可用 🚀

HTTP/3 建立在 QUIC 之上，同样多路复用。wreq 的取消分两种情况：

响应头交付前取消：请求 future 未完成就被 drop，会取消该请求未完成的发送方向和接收方向，QUIC 层使用H3_REQUEST_CANCELLED错误码（对应 RFC 9114 §4.1.1），共享连接保持可用；
响应头交付后取消：此时丢弃响应体只会取消"接收"方向；若请求体还没发完，发送工作会继续独立进行，不受影响。

关键实现：发送/接收守护对象的Drop分别调用stop_stream/stop_sending发出H3_REQUEST_CANCELLED，见 proto/http3/client.rs；行为文档见 conn/http3.rs。

实操要点：让取消真正生效的 3 步 📌

第 1 步：用"丢弃"表达取消。典型做法是配合tokio::time::timeout——超时时超时逻辑会 drop 内部 future，取消自动生效：

// 5 秒超时，超时后 future 被 drop，请求即被取消 let res = tokio::time::timeout(Duration::from_secs(5), tx.try_send_request(req)).await;

第 2 步：保持驱动连接和后台任务。无论哪种协议，取消信号（如RST_STREAM）都需要连接驱动继续运行才能送达对端。drop 请求 future 后，请继续spawn并 poll 那个Connectionfuture，直到它完成——三个协议的文档都特别强调了这一点（"Keep driving the connection and its background tasks"）。

第 3 步：按协议预期处理错误。