Visindigo::Network::HttpRequest Class

Visindigo::Network::HttpRequest request;
request.setUrl("https://example.com/api/v1/items")
       .setBearerToken(token)
       .setTag("items")
       .setRetryPolicy(policy);

成员函数文档

[since Visindigo 0.17.0] HttpRequest::HttpRequest(Visindigo::Network::HttpRequest::Method method, const QUrl &url)

以方法与目标地址直接构造请求。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::addMultipartField(const QString &name, const QString &value)

向多部分表单追加一个普通字段。一旦追加过字段或文件，请求体就会在发送时 按 multipart/form-data 组装，Content-Type 中会带上自动生成的 boundary。

name 字段名。 value 字段值。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::addMultipartFile(const QString &name, const QString &filePath)

向多部分表单追加一个文件字段。文件在发送时读取，因此若文件在提交请求与 真正发送之间被删除，请求会以错误结束。

name 字段名。 filePath 待上传文件的路径。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest::BodySink HttpRequest::getBodySink() const

返回当前的响应体消费方式。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] QByteArray HttpRequest::getCustomMethod() const

返回设置的自定义方法名，未设置时为空。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest::Method HttpRequest::getMethod() const

返回当前设置的请求方法。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] QString HttpRequest::getTag() const

返回请求标签，未设置时为空字符串。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] QUrl HttpRequest::getUrl() const

返回当前设置的目标地址。若使用的是 setPath()，这里得到的是尚未与 BaseUrl 合并的相对地址。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setAccept(const QMimeType &mime)

QMimeType 重载，直接采用该 MIME 类型的名称。

mime MIME 类型。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setAccept(const QString &mime)

设置 Accept 请求头，声明期望的响应类型。

mime MIME 类型名。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setBasicAuth(const QString &user, const QString &password)

设置 Basic 认证的 Authorization 头。

user 用户名。 password 密码。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setBearerToken(const QString &token)

设置 Bearer 形式的 Authorization 头。

若本函数未被调用，且中心通过 setAuthProvider() 配置了凭据提供者， 则由该提供者按目标地址生成凭据。这样可以让令牌刷新逻辑集中在一处， 而不必在每个发起请求的地方重复实现。

token 访问令牌。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setBodySink(Visindigo::Network::HttpRequest::BodySink sink)

设置响应体的消费方式。详见 BodySink 的说明。

sink 响应体消费方式。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setContentType(const QMimeType &mime)

QMimeType 重载，直接采用该 MIME 类型的名称。

mime MIME 类型。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setContentType(const QString &mime)

设置 Content-Type 请求头。

mime MIME 类型名，例如 "application/json"。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setCustomMethod(const QByteArray &verb)

设置自定义方法名，配合 Method::Custom 使用。典型场景是 WebDAV 的 PROPFIND / MKCOL 这类不在标准枚举内的动词。

方法名必须是合法的 HTTP token（RFC 7230），即只允许字母、数字与 ! # $ % & ' * + - . ^ _ ` | ~ 这些字符。

verb 自定义方法名。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setDownloadFilePath(const QString &filePath)

指定下载文件的落盘路径，并隐含地把消费方式设为 BodySink::ToFile。

落盘采用原子替换语义：数据先写入同目录下的临时文件，全部成功后才覆盖目标， 因此不会出现"看起来完整但实际残缺"的文件。失败或中止时目标路径保持原样。

落盘只针对最终响应的消息体。重定向途中的 3xx 响应体不会写入文件， 非 2xx 响应也不会写入——避免把错误页当成下载结果保存下来。

filePath 落盘目标路径。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setFollowRedirectsMax(qint32 count)

设置最大跟随跳数，默认 5。超出后请求以 HttpError::ErrorType::TooManyRedirects 失败。

这个上限同时也是一个安全边界：没有它，两个互相指向对方的地址可以构成 无限跳转，从而把请求永久卡死。

count 最大跟随跳数。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setFormBody(const QMap<QString, QString> &fields)

以 application/x-www-form-urlencoded 形式提交表单字段。

fields 表单字段表。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setHeader(const QMap<QString, QString> &headers)

批量设置请求头。

headers 请求头表。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setHeader(const QString &key, const QString &value)

设置单个请求头。同名键会被覆盖。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setIdleTimeoutMs(qint32 ms)

设置空闲超时毫秒数，即两次数据到达之间的最大间隔。大于 0 时为显式值， 等于 0 时采用中心默认值，小于 0 时关闭空闲超时。

这个超时比总超时更能表达"连接还活着吗"：只要服务端持续推送数据， 连接就不会被判定为超时，而一旦长时间没有任何字节到达，就说明链路已经出问题。

ms 空闲超时毫秒数；0 采用中心默认值，小于 0 关闭空闲超时。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setJsonBody(const QByteArray &rawJson)

以已序列化好的 JSON 字节作为请求体。不做合法性校验，原样发出。

本函数也自动设置 Content-Type 为 application/json（若调用方此前已显式设置过 Content-Type，则保留先前的设置）。 rawJson 已序列化的 JSON 字节。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setJsonBody(const Visindigo::Utility::JsonConfig &json)

以 JsonConfig 作为请求体，并自动设置 Content-Type 为 application/json （若调用方此前已显式设置过 Content-Type，则保留先前的设置）。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setMaxBufferBytes(qint64 bytes)

设置内存缓存上限，默认 64 MiB。超出上限时请求以 HttpError::ErrorType::ResponseTooLarge 失败。

这个上限存在的意义是防御：若不加限制，一个恶意的或错误的超长响应 可以直接把进程的内存吃光。

bytes 内存缓存上限，单位为字节。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setMaxFrameBytes(qint64 bytes)

设置单帧上限，默认 16 MiB。解码器缓冲超过该长度仍未见分帧符时， 视图以 HttpError::ErrorType::ParseError 失败。

它防的是"服务端迟迟不发换行"这一种情况：此时解码器的内部缓冲会无限增长。

bytes 单帧上限，单位为字节。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setMaxResponseBytes(qint64 bytes)

设置落盘总字节上限，0 表示不限，默认不限。

它作用于 BodySink::ToFile，用于避免下载任务被一个无限增长的服务端响应 拖垮磁盘。

bytes 落盘总字节上限；0 表示不限。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setMethod(Visindigo::Network::HttpRequest::Method method)

设置请求方法。默认是 Method::Get。

需要注意的是：把方法改为非幂等方法（如 POST）后，RetryPolicy 中 默认开启的 RetryPolicy::RetryIdempotentOnly 会导致该请求不再被重试。 这是刻意设计，避免重复提交造成服务端重复处理。

method 请求方法。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setPath(const QString &relativePath)

以相对路径指定目标，实际发送时会与中心配置的 BaseUrl 合并。

之所以提供这个入口，是为了让调用方不必到处拼接基础地址，从而避免升级域名或 切换测试环境时遗漏某个硬编码的完整 URL。

relativePath 相对于中心 BaseUrl 的路径。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setPriority(Visindigo::Network::HttpRequest::Priority priority)

设置调度优先级，默认 Priority::Normal。

priority 调度优先级。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setProxyOverride(const QUrl &proxy)

为本次请求单独指定代理，覆盖中心配置的全局代理。传入空的 QUrl 表示 "本请求直连"，即便全局配置了代理。

proxy 代理地址；传空的 QUrl 表示本请求直连。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setQuery(const QMap<QString, QString> &params)

批量追加查询参数，同样是追加而非覆盖。

params 查询参数表。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setQuery(const QString &key, const QString &value)

追加一个查询参数。同一个键多次调用会得到多个同名参数（形如 "?tag=a&tag=b"），而不会相互覆盖，这一点与 setHeader() 不同。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setRawBody(const QByteArray &body)

直接设置原始请求体，不自动附加任何 Content-Type。

body 原始请求体字节。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setRedirectPolicy(Visindigo::Network::HttpRequest::RedirectPolicy policy)

设置重定向跟随策略，默认 RedirectPolicy::Safe。

policy 重定向跟随策略。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setRetryPolicy(const Visindigo::Network::RetryPolicy &policy)

设置重试策略。默认策略对幂等方法重试 3 次（含首次），采用带抖动的指数退避。

policy 重试策略。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setStreamDecoder(std::shared_ptr<Visindigo::Network::IStreamDecoder> decoder)

挂载流帧解码器。挂载之后，响应的字节流会按该解码器切分成 Visindigo::Network::StreamFrame，并经 HttpReply::frameReceived 交付。

对于 NDJSON 可以直接使用 Visindigo::Network::JsonLinesDecoder； 对于 SSE 通常不必手动设置，SSERequest 会自动挂载 SseDecoder。

请注意，被挂载的decoder其所有权由调用方负责，HttpRequest不会对其进行管理。 decoder 解码器实例，所有权由调用方持有。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setTag(const QString &tag)

给请求打上标签，用于按组批量取消，以及把统计结果归到不同业务名下。

典型用法是给同一个界面发起的全部请求打同一个标签，界面关闭时调用 Visindigo::Network::HttpCenter::abortByTag() 一次性取消，避免界面销毁后 仍在接收回调。

tag 标签文本。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setTimeoutMs(qint32 ms)

设置总超时毫秒数，0 表示采用中心配置的默认值。

ms 总超时毫秒数；0 表示采用中心配置的默认值。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setUrl(const QString &url)

设置目标地址的字符串重载，内部转为 QUrl。

url 目标地址字符串。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setUrl(const QUrl &url)

设置目标地址。若传入的是绝对地址，则中心配置的 BaseUrl 不参与拼接。

url 目标地址。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setUserAgent(const QString &userAgent)

设置 User-Agent。未设置时使用中心配置的默认值。

userAgent User-Agent 取值。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpRequest &HttpRequest::setVerifyTls(bool verify)

设置是否校验证书，默认 true。

verify 是否校验证书。

这个function 从 Visindigo 0.17.0 开始支持。