rust-http-client

Rust HTTP 客户端

将出站 HTTP 视为一种资源和信任边界。复用已配置的客户端，为每个阶段设置边界，保留协议错误，并明确重试、凭据、代理和目标策略。

范围与路由

此技能适用于 HTTP/1.1、HTTP/2、可选的 HTTP/3 支持、请求构造、连接池、DNS、代理、TLS、重定向、重试、流式传输和客户端测试。

将入站路由器和处理程序转交给 rust-web，将 SSRF 和凭据策略转交给 rust-web-security，将任务生命周期和大规模并发转交给 rust-concurrency，将遥测转交给 rust-observability，将原始 TCP/UDP 或协议实现转交给后续的网络协议技能。

工作流

1. 定义远程契约

记录基础 URL、方法、路径和查询编码、请求头、身份验证、请求和响应架构、状态语义、幂等性、正文大小限制、分页、速率限制、超时预算、重试策略、代理和 TLS 要求，以及支持的平台。检查已锁定的依赖版本和启用的功能。

2. 构建并复用一个已配置的客户端

对于常规应用 HTTP，使用 reqwest::Client。复用该客户端以保留连接池。只有在确实需要更低层级的连接、正文或协议控制时才使用 Hyper，而不是凭猜测进行优化。

use std::time::Duration;

let client = reqwest::Client::builder()
    .connect_timeout(Duration::from_secs(3))
    .timeout(Duration::from_secs(15))
    .redirect(reqwest::redirect::Policy::limited(3))
    .build()?;

不要为每个请求都构造一个客户端。明确决定是否允许系统代理、重定向、Cookie、压缩、系统根证书或自定义根证书。阅读 客户端配置与传输。

3. 限制请求和响应

• 在支持的情况下，设置总期限以及各阶段的专属限制。
• 在分配大型正文之前，限制正在处理的并发请求数。
• 对上传和下载使用流式传输，不要缓冲不可信内容。
• 同时限制声明的正文大小和实际解码后的正文大小；Content-Length 可能缺失或具有误导性。
• 限制分页、重定向、解压缩、重试和错误正文捕获。
• 通过丢弃请求 future 或使用 select 进行选择来保留取消能力；在调用方边界验证清理情况。

4. 仅重试安全操作

仅当操作具有幂等性或受幂等键保护时，才重试传输失败或选定的状态码。设置有限的尝试次数、带抖动的指数退避、总期限，并在有效时遵循 Retry-After 等服务器提示。绝不要重试身份验证失败，也不要不加区分地重试所有 5xx。按文档规定的顺序配置超时、重试、并发限制、速率限制、负载削减和断路器策略。阅读 弹性与背压。

5. 强制执行信任边界

• 使用 url 解析目标；绝不要拼接不可信 URL。
• 对用户可控的目标限制方案、主机、端口、重定向目标、DNS 结果以及私有/链路本地地址范围。
• 将凭据限定于获准的源，并在跨源重定向时删除敏感请求头。
• 保持 TLS 验证启用；检查自定义根证书、客户端证书、SNI、ALPN 和密钥日志记录。
• 判断环境代理是否可信；必要时使用 no_proxy 或显式代理规则。

与 rust-web-security 协调安全策略。

6. 在多个边界进行测试

• 对请求构造、URL 编码、身份验证选择、重试决策和响应映射进行单元测试。
• 使用模拟服务测试状态码、请求头、延迟、重定向、截断的正文和格式错误的负载。
• 使用真实的本地服务测试套接字、流式传输、取消、连接池、代理和 TLS 行为。
• 仅在获得授权且足够稳定、适合用于 CI 时，保留少量外部沙箱或服务提供方契约测试。

阅读 HTTP 客户端测试。

完成标准

• 复用具有明确功能、代理、重定向、DNS 和 TLS 策略的客户端。
• 限制截止时间、并发数、重试次数、重定向次数、分页数和正文大小。
• 保留结构化的传输、协议、解码和应用程序错误。
• 仅重试具有可靠重放契约的操作。
• 防止通过目标地址或重定向泄露凭据，并防范 SSRF。
• 测试成功、超时、过载、重定向、大型正文、格式错误的响应和取消路径。

资源

• 客户端配置和传输
• 韧性和背压
• 测试 HTTP 客户端
• 执行场景
• examples/golden-http-client/：一个针对本地服务编译的、有界阻塞客户端。

上游来源

• reqwest
• Hyper
• Tower
• rustls
• url

数据隐私

此技能不会收集、存储或传输用户数据。未经明确授权，请勿在测试期间发送真实凭据、客户负载或私有端点。