C / C++ / 系统课时

统一错误处理与日志约定

统一错误处理与日志约定

网络库最难排查的不是“调用失败”,而是失败后该重试、断开连接还是立即暴露程序缺陷。本节建立最小错误分类、统一错误对象与诊断日志约定,让上层不必在各处重复判断零散的 errno。

学习目标

  • 区分可重试错误、连接级错误与程序错误,并选择对应处理动作
  • 用统一错误对象保存系统错误码、操作名与连接上下文
  • 通过稳定的结构化日志字段快速定位网络 I/O 失败

先把错误分成三类

非阻塞 I/O 中,系统调用失败不等于连接失败。EAGAIN 或 EWOULDBLOCK 表示当前暂时不能继续,应等待下一次就绪事件;EINTR 表示调用被信号打断,通常可以重新执行。这些属于可重试错误。

ECONNRESET、EPIPE、ETIMEDOUT、ENOTCONN 等说明当前连接已经无法正常继续通信,属于连接级错误。处理重点不是重复当前调用,而是停止该连接上的 I/O,进入关闭流程并通知上层。

程序错误来自库自身违反前置条件,例如已经关闭连接后仍提交写操作、把非法状态交给事件循环,或者破坏内部不变量。这类问题不能伪装成网络抖动;调试环境可以断言,生产环境至少要记录高严重度日志并停止错误继续扩散。

统一错误描述

错误对象至少应回答四个问题:执行了什么操作、系统错误码是什么、错误属于哪一类、发生在哪个连接。下面的完整示例把常见 errno 转成统一的 NetError,再输出固定格式的诊断日志。

cpp
#include <cerrno>
#include <cstring>
#include <iostream>
#include <string>
#include <string_view>

enum class ErrorKind {
    Retryable,
    Connection,
    Program
};

struct NetError {
    ErrorKind kind;
    int sys_errno;
    std::string operation;
    std::string message;
};

NetError from_errno(std::string_view operation, int err) {
    ErrorKind kind = ErrorKind::Program;

    // 非阻塞暂不可用或被信号打断时,连接本身仍可能完全正常。
    if (err == EAGAIN || err == EWOULDBLOCK || err == EINTR) {
        kind = ErrorKind::Retryable;
    } else if (err == ECONNRESET || err == EPIPE ||
               err == ETIMEDOUT || err == ENOTCONN) {
        kind = ErrorKind::Connection;
    }

    return {kind, err, std::string(operation), std::strerror(err)};
}

const char* kind_name(ErrorKind kind) {
    switch (kind) {
        case ErrorKind::Retryable: return "retryable";
        case ErrorKind::Connection: return "connection";
        case ErrorKind::Program: return "program";
    }
    return "program";
}

void log_error(const NetError& error, int connection_id) {
    std::cerr << "level=error"
              << " kind=" << kind_name(error.kind)
              << " op=" << error.operation
              << " errno=" << error.sys_errno
              << " connection_id=" << connection_id
              << " message=\"" << error.message << "\"\n";
}

int main() {
    log_error(from_errno("recv", EAGAIN), 42);
    log_error(from_errno("send", EPIPE), 42);
    log_error({ErrorKind::Program, 0, "write",
               "write requested after connection closed"}, 42);
}

预期输出如下。不同 Linux 环境的错误码数值和 strerror 文案可能不同,因此用占位符表示动态内容。

text
level=error kind=retryable op=recv errno=<ID> connection_id=42 message="<SYSTEM_MESSAGE>"
level=error kind=connection op=send errno=<ID> connection_id=42 message="<SYSTEM_MESSAGE>"
level=error kind=program op=write errno=0 connection_id=42 message="write requested after connection closed"

实际 <ID> 与 <SYSTEM_MESSAGE> 由操作系统决定。生产实现还可以增加 fd、对端地址和事件循环线程编号,但同一字段应始终保持相同语义,避免不同模块各写一套日志句式。

让处理动作跟着错误类型走

统一分类的价值在于把“识别错误”和“执行恢复动作”分开。I/O 层负责生成错误描述,连接层再根据分类决定等待、关闭还是暴露程序缺陷。下面的示例只演示策略分派,因此没有把网络系统调用再次复制一遍。

cpp
#include <iostream>

enum class ErrorKind {
    Retryable,
    Connection,
    Program
};

void handle_error(ErrorKind kind) {
    switch (kind) {
        case ErrorKind::Retryable:
            std::cout << "keep connection and wait for next event\n";
            break;
        case ErrorKind::Connection:
            std::cout << "close connection and notify owner\n";
            break;
        case ErrorKind::Program:
            std::cout << "report invariant violation\n";
            break;
    }
}

int main() {
    handle_error(ErrorKind::Retryable);
    handle_error(ErrorKind::Connection);
    handle_error(ErrorKind::Program);
}

预期输出:

text
keep connection and wait for next event
close connection and notify owner
report invariant violation

这样设计后,read、write、accept 等回调不需要各自维护一份错误处理分支。以后替换 Poller、增加 TLS 或把错误继续传到 RPC 层时,也可以沿用同一套语义。

约定日志级别与字段

网络库日志应优先输出结构化字段,而不是依赖一整句自然语言。建议固定 level、kind、op、errno、connection_id 等核心字段,需要时再添加 fd、peer、event。稳定字段便于检索、聚合和告警,也方便把同一连接的多条日志关联起来。

可重试错误出现频率通常很高,EAGAIN 不应每次都记录为 error,否则正常负载也会淹没真正故障。连接级错误可根据业务场景使用 info、warn 或 error;程序错误应保持较高严重度,并携带足以复现问题的状态信息。

当错误分类、恢复策略和日志字段形成统一约定后,事件循环只需要传递明确的错误语义,而不必让每一层重新解析系统错误码。这套边界也是后续实现连接关闭、超时管理和 RPC 错误传播的基础。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

统一错误处理与日志约定

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通