Visindigo::Network::HttpCenter Class

成员函数文档

[since Visindigo 0.17.0] void HttpCenter::abort(quint64 id)

按下发时取得的编号中止请求，无论它正在排队还是已经发出。

id 请求编号。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::abortAll()

中止全部排队中与进行中的请求。进程退出前调用它可以避免回调在对象已经 析构之后才到达。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::abortByTag(const QString &tag)

中止所有带指定标签的请求。典型场景是某个界面关闭时，把该界面发起的全部 请求一并撤销，避免回调打到已经销毁的对象上。

tag 请求标签。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::addRequestInterceptor(Visindigo::Network::HttpCenter::RequestInterceptor interceptor)

追加一个请求拦截器，在请求提交时被调用，可以修改请求的头、体与地址。 多个拦截器按添加顺序执行。

interceptor 请求拦截器。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::addResponseInterceptor(Visindigo::Network::HttpCenter::ResponseInterceptor interceptor)

追加一个响应拦截器。它会在两个时机被调用一次：响应头到达时，以及请求 结束时（包括失败与中止）。因此实现必须自己处理“响应尚未收齐”的情形， 不能假设消息体已可用。

典型用途是埋点与统一日志：把状态码、耗时、错误分类记录到一处， 而不必在每个调用点重复写。

interceptor 响应拦截器。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::clearInterceptors()

清空全部请求与响应拦截器。

主要用途是测试：在用例之间恢复干净状态，避免上一个用例注册的拦截器 干扰下一个。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpReply *HttpCenter::get(const QUrl &url)

以 GET 方法提交请求的便利入口。

url 目标地址。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] qint32 HttpCenter::getActiveRequestCount() const

返回正在进行中的请求数量。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] qint64 HttpCenter::getAverageElapsedMs() const

返回已完成请求的平均耗时毫秒数。没有可用样本时返回 0。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] QUrl HttpCenter::getDefaultBaseUrl() const

返回当前设置的默认基础地址，未设置时为空。

这个function 从 Visindigo 0.17.0 开始支持。

[static, since Visindigo 0.17.0] Visindigo::Network::HttpCenter *HttpCenter::getInstance()

取得中心实例，首次调用时创建。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] qint32 HttpCenter::getQueuedRequestCount() const

返回等待出队的请求数量。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] quint64 HttpCenter::getTotalBytesReceived() const

返回累计接收的消息体字节数。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] quint64 HttpCenter::getTotalBytesSent() const

返回累计发送的字节数。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] quint64 HttpCenter::getTotalFailureCount() const

返回累计失败的请求数。失败包含超时、连接错误、非 2xx 状态码与队列拒绝， 但不包含调用方主动中止——主动放弃不算故障，否则统计会因正常的 界面关闭而变得很难解读。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] quint64 HttpCenter::getTotalRequestCount() const

返回自启动（或上次清零）以来提交过的请求总数，包含成功与失败。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] quint64 HttpCenter::getTotalRetryCount() const

返回累计发生的重试次数（不含首次发送）。

它是判断服务稳定性的重要指标：失败数与请求数之比可能很低，但重试数很高， 说明服务正在频繁抖动，只是恰好被重试策略掩盖了。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] bool HttpCenter::isOnline() const

判断当前是否具备网络可达性。该判断来自系统的网络状态通告， 它只说明"链路可达"，不保证目标服务一定可用。

return 系统通告网络可达时返回 true。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] bool HttpCenter::isPaused() const

返回队列是否处于暂停状态。

return 暂停时返回 true。

这个function 从 Visindigo 0.17.0 开始支持。

[signal, since Visindigo 0.17.0] void HttpCenter::onlineStateChanged(bool online)

网络可达性发生变化。界面上的离线提示可以挂在这里，不必自己轮询。

online 网络是否可达。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::WebSocketSession *HttpCenter::openWebSocket(const Visindigo::Network::WebSocketRequest &request)

建立一个 WebSocket 会话。会话与 HTTP 句柄不同，默认不会自动销毁， 请在不再需要时明确关闭。

request WebSocket 连接描述。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpReply *HttpCenter::postJson(const QUrl &url, const Visindigo::Utility::JsonConfig &body)

以 POST 方法提交 JSON 请求体的便利入口。

url 目标地址。 body 请求体 JSON。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::HttpReply *HttpCenter::request(const Visindigo::Network::HttpRequest &request)

提交一个普通 HTTP 请求，立即返回句柄。请求可能仍在排队，因此不要假设 返回时它已经发出。

返回的句柄默认在结束后自动销毁；若希望持有它以便稍后查询结果， 请先调用 Visindigo::Network::HttpReply::setAutoDelete()。

request 要提交的请求描述。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Network::SSEReply *HttpCenter::request(const Visindigo::Network::SSERequest &request)

提交一个 SSE 请求。中心会自动完成三件调用方不必操心的事：挂载 Visindigo::Network::SseDecoder、把接受类型设为 text/event-stream、 以及在设置了续传起点时补上 Last-Event-ID 请求头。

request 要提交的 SSE 请求描述。

这个function 从 Visindigo 0.17.0 开始支持。

[signal, since Visindigo 0.17.0] void HttpCenter::requestFailed(quint64 id, const Visindigo::Network::HttpError &error)

请求失败。被中止的请求不计入其中，它们只走 HttpReply::aborted。

id 请求编号。 error 失败原因。

这个function 从 Visindigo 0.17.0 开始支持。

[signal, since Visindigo 0.17.0] void HttpCenter::requestFinished(quint64 id, const Visindigo::Network::HttpResponse &response)

请求成功结束。

id 请求编号。 response 最终响应。

这个function 从 Visindigo 0.17.0 开始支持。

[signal, since Visindigo 0.17.0] void HttpCenter::requestStarted(quint64 id, const Visindigo::Network::HttpRequest &request)

请求已提交。request 是中心补齐解码器、凭据与超时之后的最终形态， 而不是调用方传进来的那一份；排查问题时应当以它为准。

id 请求编号。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::resetStatistics()

清零累计统计。它不会影响进行中的请求，也不会改变实时状态计数。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setAllowedUrlSchemes(const QStringList &schemes)

设置允许请求的 URL 协议白名单，默认只允许 https 与 http。

不在白名单内的地址会在发出前就被拒绝，以 Visindigo::Network::HttpError::ErrorType::UrlSchemeRejected 失败，而不是 交给传输层去尝试。这可以防止调用方把用户可控的字符串直接当地址使用， 例如 file: 或 ftp: 这类会绕过 HTTP 栈语义的协议。

schemes 允许的协议白名单。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setAuthProvider(Visindigo::Network::HttpCenter::AuthProvider provider)

设置凭据提供者。仅当请求自身没有设置 Authorization 头时，中心才调用它。

它的价值在于把令牌刷新逻辑集中到一处：令牌快过期时只需要在一个地方续期， 而不必在每个发起请求的地方重复实现，也不会出现“某个调用点忘了带令牌”。

传入的地址是请求的目标地址，使提供者可以按域名返回不同服务商的凭据。

provider 凭据提供者。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setCertificateVerificationEnabled(bool enabled)

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

全局开关与请求级 Visindigo::Network::HttpRequest::setVerifyTls() 是“与” 关系：只有两者都为真才会校验证书。这样全局关闭可以一次性放开所有请求， 而单个请求的关闭不会反过来影响其它请求。

enabled 全局是否校验证书。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setCookieJarEnabled(bool enabled)

设置是否启用全局 Cookie 存储，默认关闭。

默认关闭是刻意的：Cookie 是全局共享状态，一旦自动携带，不同业务之间的 登录态会互相污染，而且很难在事后定位“为什么这个请求带上了别人的身份”。 需要维持会话的调用方应当显式开启，或自行管理 Cookie 头。

enabled 是否启用全局 Cookie 存储。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setDefaultBaseUrl(const QUrl &baseUrl)

设置默认基础地址。使用 Visindigo::Network::HttpRequest::setPath() 指定相对 路径的请求会基于它解析。

baseUrl 默认基础地址。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setDefaultIdleTimeoutMs(qint32 ms)

设置默认空闲超时毫秒数，即两次数据到达之间的最大间隔，默认 60000。 请求可用 Visindigo::Network::HttpRequest::setIdleTimeoutMs() 单独覆盖。

这是长连接唯一合适的超时形式：只要服务端持续推送数据，连接就不会被判 超时，而长时间没有字节到达则说明链路确实出了问题。

ms 默认空闲超时毫秒数。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setDefaultRetryPolicy(const Visindigo::Network::RetryPolicy &policy)

设置默认重试策略，作为模板应用于未自行设置过策略的请求。 请求一旦调用过 Visindigo::Network::HttpRequest::setRetryPolicy()， 就完全以它自己的设置为准，本项不再参与。

policy 默认重试策略。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setDefaultTimeoutMs(qint32 ms)

设置默认总超时毫秒数，默认 30000。请求可用 Visindigo::Network::HttpRequest::setTimeoutMs() 单独覆盖。

ms 默认总超时毫秒数。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setDefaultUserAgent(const QString &userAgent)

设置默认 User-Agent，请求未单独指定时使用。

userAgent 默认 User-Agent 取值。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setLogSensitiveHeaders(bool enabled)

设置请求日志是否包含敏感头部，默认关闭。

关闭时（默认）日志只记录方法与地址；打开后会额外输出完整请求头， 其中可能包含 Authorization 与 Cookie。因此本项只应在排查问题等临时场景下 打开，且不应随正式构建默认启用。

enabled 是否在日志中输出敏感头部。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setMaxConcurrentRequests(qint32 count)

设置同时进行的请求数上限，默认 6。超出的请求会排队等待。

count 并发请求数上限，最小为 1。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setMaxQueuedRequests(qint32 count)

设置等待队列长度上限，默认 128。队满时新请求会立即以 Visindigo::Network::HttpError::ErrorType::QueueRejected 失败， 而不是无限堆积。

count 等待队列长度上限。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] void HttpCenter::setPaused(bool paused)

暂停或恢复队列出队。暂停只影响尚未发出的请求，已经在传输中的请求会 继续完成——中途掐断它们既没有必要，也会让状态更难推理。

paused 是否暂停出队。

这个function 从 Visindigo 0.17.0 开始支持。

另请参阅 isPaused().

[since Visindigo 0.17.0] void HttpCenter::setProxy(const QUrl &proxy)

设置全局代理，传入空 URL 表示不使用代理。单个请求可通过 Visindigo::Network::HttpRequest::setProxyOverride() 覆盖本设置。

proxy 代理地址；传空的 QUrl 表示不使用代理。

这个function 从 Visindigo 0.17.0 开始支持。