第28章库的错误处理

课程目录第28章库的错误处理

库的错误处理：错误码设计、异常安全、错误恢复、断言与日志

说到库的错误处理，我其实挺有感触的。早年写库的时候，总觉得功能实现就完事了，错误处理嘛，随便返回个 -1 就得了。结果呢？调用方根本不知道哪里出了问题，调试起来像大海捞针。后来我才明白——一个库好不好用，很大程度上取决于它的错误处理做得怎么样。

今天咱们就来聊聊，怎么给静态库和共享库设计一套靠谱的错误处理机制。说白了，就是让库的使用者能快速定位问题，也让库本身足够健壮。

一、错误码设计：别让调用方猜谜

错误码是最基础、最常用的错误报告方式。我见过不少库，错误码就定义个 SUCCESS 和 FAILURE，然后没了。你想想看，调用方拿到一个 FAILURE，能干嘛？只能干瞪眼。

好的错误码设计，应该做到这几点：

语义清晰：每个错误码代表一种具体的错误场景
可扩展：后续增加新错误码时，不影响已有代码
便于排查：最好能通过错误码直接定位到问题

我个人习惯用枚举来定义错误码，这样既清晰又安全。举个例子：

// error_codes.h
typedef enum {
    ERR_SUCCESS          = 0,
    ERR_INVALID_PARAM    = -1,
    ERR_OUT_OF_MEMORY    = -2,
    ERR_FILE_NOT_FOUND   = -3,
    ERR_PERMISSION_DENIED = -4,
    ERR_TIMEOUT          = -5,
    ERR_NETWORK_FAILURE  = -6,
    ERR_UNKNOWN          = -99
} ErrorCode;

这里有个小技巧：把成功码设为 0，错误码设为负数。这样调用方可以用 if (ret != 0) 快速判断是否出错，非常直观。

我的经验：曾经有个项目，错误码定义得乱七八糟，有的正数表示错误，有的负数表示错误，还有用指针的。后来重构时，我统一改成枚举 + 负数，代码可读性直接提升了一个档次。

二、异常安全：C++ 库的必修课

如果你在写 C++ 库，那异常安全就是个绕不开的话题。C 的库可以用错误码，但 C++ 有异常机制，用好了能让代码更简洁。

不过要注意——异常不是万能的。我在项目中遇到过几次因为异常没处理好，导致资源泄漏的惨案。比如：

// 不安全的写法
void process() {
    Resource* res = new Resource();
    // 如果这里抛出异常，res 就泄漏了
    doSomething();  // 可能抛异常
    delete res;
}

正确的做法是使用 RAII（资源获取即初始化）技术：

// 安全的写法
void process() {
    std::unique_ptr<Resource> res(new Resource());
    doSomething();  // 即使抛异常，res 也会自动释放
}

C++ 的异常安全分为三个级别：

级别	说明	适用场景
基本保证	抛出异常后，资源不泄漏，对象处于有效状态	大多数库函数
强保证	操作要么完全成功，要么回滚到操作前的状态	事务性操作
不抛异常	保证函数不会抛出任何异常	析构函数、移动操作

注意：析构函数里千万别抛异常！否则程序会直接 terminate。我曾经见过一个同事在析构里写日志，日志模块抛异常了，结果整个进程挂掉。嗯，那场面相当尴尬。

三、错误恢复：给调用方一条活路

错误恢复，说白了就是库在遇到错误时，能不能自己缓一缓，或者给调用方一个补救的机会。我见过一些库，一遇到错误就直接 abort，调用方连个反应的时间都没有。

好的做法是：

区分致命错误和可恢复错误：内存不足可能是致命的，但文件不存在也许可以换个路径重试
提供重试机制：比如网络库可以自动重连，或者暴露重试接口
保留上下文：错误发生时，尽量保留当前状态，方便调用方做后续处理

举个例子，一个简单的重试机制：

// 库内部实现
int connect_with_retry(const char* host, int port, int max_retries) {
    for (int i = 0; i < max_retries; i++) {
        int ret = try_connect(host, port);
        if (ret == ERR_SUCCESS) {
            return ERR_SUCCESS;
        }
        // 等待一段时间再重试
        sleep(1 << i);  // 指数退避
    }
    return ERR_TIMEOUT;
}

调用方拿到错误码后，可以决定是重试、回退还是直接报错。这样灵活性就大多了。

四、断言：调试时的好帮手

断言（assert）是个好东西，但很多人用错了地方。断言应该用来检查不应该发生的情况，而不是用来处理可能发生的错误。

比如：

// 正确的用法：检查内部逻辑错误
void sort_array(int* arr, int n) {
    assert(arr != nullptr);  // 如果传了空指针，说明调用方代码有 bug
    assert(n > 0);           // 长度应该为正
    // ... 排序逻辑
}

// 错误的用法：用断言处理用户输入
void read_file(const char* path) {
    assert(path != nullptr);  // 不应该！用户输入错误应该返回错误码
    // ...
}

  关键区别：断言在 Release 模式下会被移除，所以不能依赖它做错误处理。它只是调试阶段的辅助工具。

我曾经在一个项目里看到有人用断言检查文件是否存在，结果 Release 版本上线后，文件没找到，程序直接崩溃了。嗯，这就是典型的滥用断言。

五、日志：库的「黑匣子」

日志就像是飞机的黑匣子，平时用不上，但出问题的时候，它就是救命稻草。一个好的库，应该提供完善的日志机制。

我建议库的日志设计遵循这几个原则：

分级输出：DEBUG、INFO、WARN、ERROR、FATAL，调用方可以控制日志级别
可配置：允许调用方设置日志输出目标（文件、控制台、网络等）
性能友好：日志不能拖慢主流程，尤其是高频调用的函数

一个简单的日志接口示例：

// 库提供的日志接口
typedef void (*LogCallback)(int level, const char* msg, void* user_data);

void lib_set_log_callback(LogCallback cb, void* user_data);
void lib_set_log_level(int level);

// 库内部使用
#define LIB_LOG(level, fmt, ...) \
    do { \
        if (level >= g_log_level) { \
            char buf[256]; \
            snprintf(buf, sizeof(buf), fmt, ##__VA_ARGS__); \
            g_log_callback(level, buf, g_log_user_data); \
        } \
    } while(0)

这里用宏而不是函数，是为了在日志级别不满足时，连参数求值的开销都省掉。性能敏感的场景下，这点差别挺大的。

六、知识体系总览

说了这么多，咱们用一张图来梳理一下库的错误处理到底包含哪些内容：

这张图把错误处理的几个核心模块串起来了。你会发现，它们不是孤立的——错误码和异常是报告错误的手段，断言和日志是辅助排查的工具，错误恢复则是最后的兜底策略。实际项目中，往往是多种方式组合使用。

好了，关于库的错误处理，咱们就聊到这儿。记住一句话：好的错误处理，不是让程序不出错，而是让出错时能快速定位、优雅恢复。下次写库的时候，不妨多花点心思在这上面，调用方会感激你的。

公众号:蓝海资料掘金营，微信deep3321

📚 课程目录

库的错误处理：错误码设计、异常安全、错误恢复、断言与日志

一、错误码设计：别让调用方猜谜

二、异常安全：C++ 库的必修课

三、错误恢复：给调用方一条活路

四、断言：调试时的好帮手

五、日志：库的「黑匣子」

六、知识体系总览