C / C++ / 系统课时
统一传播远端调用错误
统一传播远端调用错误
RPC 调用失败时,调用方真正需要的不是一句“调用失败”,而是知道失败发生在哪一层、是否值得重试、能否展示给用户。本节把网络失败、超时、协议错误和服务端业务错误收敛为统一错误模型,并让错误沿 RPC 响应稳定传回调用方。
学习目标
- 能区分传输、超时、协议与业务四类失败,并避免互相覆盖
- 能设计统一的 RPC 结果类型,让成功值和远端错误使用同一返回通道
- 能根据错误类别决定重试、告警和业务提示策略
先固定错误边界
一个 RPC 调用至少跨过客户端、网络、服务端框架和业务处理四层。错误模型最容易失控的原因,是这些层都用字符串返回错误,最终调用方只能看到 failed、timeout 之类无法稳定判断的文本。
建议把错误分成四类:网络失败表示连接建立、断开或读写失败;超时表示在规定时间内没有得到完整响应;协议错误表示帧、消息类型、序列号或反序列化不合法;业务错误则由服务端业务逻辑主动返回,例如“余额不足”或“订单不存在”。

错误类别稳定后,调用方才可以写可靠策略。例如网络错误和超时可能允许重试,协议错误通常意味着版本不兼容或程序缺陷,业务错误则通常不应该由 RPC 框架自动重试。
统一结果类型
核心做法是让 RPC 接口始终返回一个“成功值或错误”的结果对象,而不是一部分错误抛异常、一部分错误写日志、另一部分塞进业务响应。下面示例使用 std::variant 构造最小可运行模型。
#include <iostream>
#include <string>
#include <variant>
enum class RpcErrorCategory {
Network,
Timeout,
Protocol,
Business
};
struct RpcError {
RpcErrorCategory category;
int code;
std::string message;
bool retryable;
};
template <typename T>
using RpcResult = std::variant<T, RpcError>;
std::string categoryName(RpcErrorCategory category) {
switch (category) {
case RpcErrorCategory::Network: return "NETWORK";
case RpcErrorCategory::Timeout: return "TIMEOUT";
case RpcErrorCategory::Protocol: return "PROTOCOL";
case RpcErrorCategory::Business: return "BUSINESS";
}
return "UNKNOWN";
}
RpcResult<std::string> callRemote(int scenario) {
// 示例中用 scenario 模拟不同失败层,真实项目应在对应层创建 RpcError。
if (scenario == 1) {
return RpcError{RpcErrorCategory::Network, 1001, "connection reset", true};
}
if (scenario == 2) {
return RpcError{RpcErrorCategory::Timeout, 1002, "request timeout", true};
}
if (scenario == 3) {
return RpcError{RpcErrorCategory::Protocol, 2001, "invalid response frame", false};
}
if (scenario == 4) {
return RpcError{RpcErrorCategory::Business, 4004, "order not found", false};
}
return std::string("order-42");
}
int main() {
for (int scenario = 0; scenario <= 4; ++scenario) {
auto result = callRemote(scenario);
if (std::holds_alternative<std::string>(result)) {
std::cout << "OK " << std::get<std::string>(result) << '\n';
continue;
}
const auto& error = std::get<RpcError>(result);
std::cout << categoryName(error.category)
<< " code=" << error.code
<< " retryable=" << std::boolalpha << error.retryable
<< " message=" << error.message << '\n';
}
}预期输出
OK order-42
NETWORK code=1001 retryable=true message=connection reset
TIMEOUT code=1002 retryable=true message=request timeout
PROTOCOL code=2001 retryable=false message=invalid response frame
BUSINESS code=4004 retryable=false message=order not found这里最重要的是 category、code 和 retryable 不依赖自然语言文本。日志可以记录 message,但程序分支应基于稳定字段判断。
把服务端错误装进协议
业务错误只有经过响应协议才能跨进程返回。可以在响应头中固定 status、error_code、error_message 等字段,成功时携带业务载荷,失败时携带统一错误信息。协议层解析失败时则不能信任这份远端错误,应在本地生成 Protocol 错误。
片段示例,假设响应消息已经由项目现有编解码器完成解码:
RpcResult<std::string> handleResponse(
bool frameValid,
int status,
int errorCode,
const std::string& errorMessage,
const std::string& payload) {
if (!frameValid) {
return RpcError{RpcErrorCategory::Protocol, 2001,
"invalid response frame", false};
}
if (status != 0) {
return RpcError{RpcErrorCategory::Business, errorCode,
errorMessage, false};
}
return payload;
}这段代码依赖项目现有的响应帧解码上下文。生效行为是:只有结构合法的远端响应才有资格产生 Business 错误;坏帧始终被框架归类为 Protocol。
调用方只按语义处理
统一模型的价值最终体现在调用方。自动重试模块只看 retryable;监控系统按 category 聚合;业务层根据 Business 的稳定错误码决定提示文案。这样即使服务端调整错误文本,也不会破坏客户端逻辑。
当所有失败都进入同一个 RpcResult 通道后,RPC 框架就能把“发生了什么、能否重试、谁负责处理”明确分开。错误传播因此从字符串约定升级为稳定接口契约。