Visindigo::Network::HttpError Struct
struct Visindigo::Network::HttpError网络层统一错误信息. 详情...
| 头文件： | #include <Network/HttpTypes.h> |
| 自以下版本： | Visindigo 0.17.0 |
公开类型
(自 Visindigo 0.17.0 引入) enum class | ErrorType { NoError, Aborted, Timeout, IdleTimeout, ConnectionRefused, …, Unknown } |
公开成员函数
静态公开成员
(自 Visindigo 0.17.0 引入) QString | errorTypeName(Visindigo::Network::HttpError::ErrorType type) |
详细说明
网络失败属于可预期结果，而非异常情况，因此 Visindigo 的网络模块不使用 异常表达错误，而是在结果类型（std::expected）或信号中传递本结构。
这样做的另一个好处是：错误信息可以跨线程、跨信号槽安全传递，且不会被 栈展开意外绕过——异常在 Qt 的信号槽中传播本身就是不推荐的用法。
- Type 错误分类，取值见 HttpError::ErrorType。
- HttpStatus 有 HTTP 响应时为状态码，否则为 0。
- Message 面向用户的简短错误描述。
- Detail 服务端返回的原始错误体（已按上限截断），常用于展示 4xx/5xx 的具体原因。
- Retryable 该错误是否可按重试策略重试。
- SuggestedRetryDelayMs 服务端建议的等待毫秒数，来自 Retry-After；无建议时为 -1。
成员类型文档
[since Visindigo 0.17.0] enum class HttpError::ErrorType
错误分类。命名参照 Visindigo::General::CommandErrorData::ErrorType， 以避免与下方同名的成员变量 Type 发生名称冲突。
| Constant | Value | Description |
|---|---|---|
Visindigo::Network::HttpError::ErrorType::NoError | 0 | 无错误。 |
Visindigo::Network::HttpError::ErrorType::Aborted | 1 | 调用方主动中止。 |
Visindigo::Network::HttpError::ErrorType::Timeout | 2 | 连接或总时长超时。 |
Visindigo::Network::HttpError::ErrorType::IdleTimeout | 3 | 流式请求中两次数据到达的间隔超过空闲超时。 |
Visindigo::Network::HttpError::ErrorType::ConnectionRefused | 4 | 连接被拒绝。 |
Visindigo::Network::HttpError::ErrorType::HostNotFound | 5 | 域名解析失败。 |
Visindigo::Network::HttpError::ErrorType::NetworkUnreachable | 6 | 网络不可达（常见于断网或路由问题）。 |
Visindigo::Network::HttpError::ErrorType::ProxyError | 7 | 代理相关错误。 |
Visindigo::Network::HttpError::ErrorType::TlsError | 8 | TLS 握手失败。 |
Visindigo::Network::HttpError::ErrorType::CertificateError | 9 | 证书校验失败。此类错误不应被静默忽略，否则等同于放弃中间人防护。 |
Visindigo::Network::HttpError::ErrorType::TooManyRedirects | 10 | 重定向次数超过 setFollowRedirectsMax() 设定的上限。 |
Visindigo::Network::HttpError::ErrorType::ProtocolError | 11 | HTTP 协议层面的错误（响应格式非法等）。 |
Visindigo::Network::HttpError::ErrorType::HttpStatusError | 12 | 服务端返回 4xx 或 5xx。 |
Visindigo::Network::HttpError::ErrorType::ResponseTooLarge | 13 | 响应体超过 setMaxResponseBytes() 或 setMaxBufferBytes() 设定的上限。 |
Visindigo::Network::HttpError::ErrorType::LocalIoError | 14 | 本地 I/O 失败，例如落盘目录无法创建、目标文件无法写入。 |
Visindigo::Network::HttpError::ErrorType::ParseError | 15 | 流式分帧或 JSON 解析失败。 |
Visindigo::Network::HttpError::ErrorType::QueueRejected | 16 | 请求被队列拒绝，通常是命中了并发上限或队列长度上限。 |
Visindigo::Network::HttpError::ErrorType::UrlSchemeRejected | 17 | URL 协议不在中心允许的白名单内。 |
Visindigo::Network::HttpError::ErrorType::Unknown | 18 | 未归类的错误。 |
这个enum 从 Visindigo 0.17.0 开始支持。
成员函数文档
[static, since Visindigo 0.17.0] QString HttpError::errorTypeName(Visindigo::Network::HttpError::ErrorType type)
返回枚举值对应的名字字符串；传入未收录的取值时返回 "Unknown"。
实现走 QMetaEnum 反射而不是手写 switch，这是本结构声明为 Q_GADGET 的直接 收益：枚举名只有一个来源（即声明本身），将来往 ErrorType 里增加取值时 不必记得同步修改映射表，也就不存在"新增了错误类型但日志里显示 Unknown" 这类遗漏。同时它对调用方是公开的，日志与界面可以直接拿它做展示。
type 错误类型取值。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] bool HttpError::isError() const
判断本结构是否真的表示一个错误，即 Type 不等于 ErrorType::NoError。
return 不是 NoError 时返回 true。
这个function 从 Visindigo 0.17.0 开始支持。
[since Visindigo 0.17.0] QString HttpError::toString() const
生成适合写入日志的单行描述，形如：
[Timeout] Connection timed out (HTTP 504)
仅在 HttpStatus 不为 0 时附加状态码部分。若 Detail 非空， 调用方可自行决定是否展示，本函数不将其包含在内，以免日志被超长文本淹没。
这个function 从 Visindigo 0.17.0 开始支持。