Interface IHttpRequest

一次 HTTP 请求的配置。交给 SendAsync(IHttpRequest, CancellationToken) 后由 client 解读成对应的 libcurl easy handle 选项。典型实现是 HttpRequest,按 POCO 字段赋值即可;认证等扩展方法见 HttpRequestExtensions。

public interface IHttpRequest

Extension Methods: HttpRequestExtensions.WithBasicAuth(IHttpRequest, string, string)

HttpRequestExtensions.WithBearerToken(IHttpRequest, string)

Properties

是否让 libcurl 自动处理响应压缩。默认 true。

为 true:发送 Accept-Encoding: gzip, deflate(按编译时链接的压缩库), libcurl 自动解压响应, HttpResponse.Body 拿到的是解压后的原文。对 JSON/HTML/text 可降低 3-5 倍下行流量。

为 false:不发 Accept-Encoding, 响应按 server 原样交付; 如果 server 仍回 Content-Encoding: gzip, Body 是压缩字节, 需调用方自理。

Body: 请求体 raw bytes。与 BodyStream 互斥,同时设置会在 Send 时 throw。 JSON / form-urlencoded / multipart 等常见 body 可用 HttpClientExtensions 的便利方法构造。

BodyStream 的总长度。

对 MemoryStream / FileStream 这类可 seek 的 Stream,传 stream.Length - stream.Position 是常见做法。

BodyStream: 流式请求体。非 null 时以流式上传,request 期间 libcurl 按需从该 Stream 读数据; 与 Body 互斥(同时设置会 throw);仅支持 POST/PUT/PATCH 等带 body 的方法。

是否接入所属 IHttpClient 的共享 cookie jar。默认 false。

为 true 时：服务端 Set-Cookie 写入 jar、后续请求自动回发匹配 cookie，在 同一个 IHttpClient 实例 内跨请求持久化。不同 client 实例的 jar 互相独立。

为 false 时：cookie engine 完全不启用 —— 本次请求既不读 jar 也不写 jar （即便 client 的 jar 已有条目也不会带出），且同一请求 redirect 链内的 Set-Cookie 也不会被解析回发。需要这两种行为之一时请置 true。

jar 为纯内存存储，client Dispose 后清空；暂不支持文件持久化。

Headers: 自定义请求头。允许重复 key,libcurl 会把同名 header 按集合顺序合并送出。设置 User-Agent 会覆盖 UserAgent。

OnDataReceived: 流式数据回调（文件下载等场景）。设置后响应体不缓冲，数据逐块交付，Response.Body 为 null。在后台线程调用。参数: (buffer, offset, length)