实战项目一：基于 STL 的日志系统设计

说实话，日志系统这东西，每个项目都离不开。我见过太多项目上线后出问题，连个日志都查不到，那叫一个抓瞎。今天咱们就亲手搭一个轻量级的日志系统，用到的全是 STL 的看家本领——map、vector、string、fstream，再加个 mutex 保线程安全。

为什么非要用 STL 来写日志？

你想想看，日志系统本质上就是个「生产者-消费者」模型。业务线程拼命往里写，后台线程慢慢往外刷。如果用纯 C 的方式，你得自己管理动态数组、自己维护哈希表、自己处理字符串拼接……嗯，我年轻时干过这事，调试到凌晨三点，最后发现是内存越界。

用 STL 就不一样了。它把底层细节全封装好了，你只管关注业务逻辑。说白了，STL 就是给你配了一套「乐高积木」，你只需要拼起来就行。

核心设计思路：

  • map 管理日志级别（DEBUG、INFO、WARN、ERROR）
  • vector 做日志缓冲区，支持批量写入
  • string 处理日志内容拼接
  • fstream 负责文件落地
  • mutex 保证多线程安全
日志系统核心架构 业务线程（生产者） 调用 Log() 写入日志 vector 缓冲区 暂存日志条目 后台线程（消费者） 定时刷入文件 fstream 文件 持久化存储 mutex 互斥锁 保护缓冲区 map 级别管理 DEBUG/INFO/WARN/ERROR 图例说明： 生产者 缓冲区 消费者 文件 锁 实线 = 数据流，虚线 = 控制流

第一步：定义日志级别

我个人习惯用枚举来定义日志级别，然后用 map 做级别到字符串的映射。这样写代码时清晰，查日志时也直观。

enum class LogLevel {
    DEBUG,
    INFO,
    WARN,
    ERROR
};

// 用 map 做映射，方便输出
std::map<LogLevel, std::string> levelMap = {
    {LogLevel::DEBUG, "DEBUG"},
    {LogLevel::INFO,  "INFO"},
    {LogLevel::WARN,  "WARN"},
    {LogLevel::ERROR, "ERROR"}
};

为什么不用 switch？因为 map 扩展性好。万一以后加个 FATAL 级别，加一行映射就行，不用改逻辑代码。我在项目中吃过这个亏——一开始用 switch，后来加了三个级别，改得我头皮发麻。

第二步：设计日志条目结构

每条日志需要记录时间、级别、内容、文件名和行号。用 struct 包起来，方便后续处理。

struct LogEntry {
    std::string timestamp;
    LogLevel    level;
    std::string message;
    std::string file;
    int         line;
};

这里有个小细节：时间戳用 string 而不是 time_t。为什么？因为日志文件里要的是人能读懂的格式，不是时间戳数字。你想想看，查日志时看到一串数字，还得拿计算器算，多痛苦。

第三步：核心日志类

这是整个系统的核心。我把它设计成单例模式，全局只有一个实例。内部用 vector<LogEntry> 做缓冲区，用 mutex 保护。

class Logger {
public:
    static Logger& instance() {
        static Logger logger;
        return logger;
    }

    void log(LogLevel level, const std::string& msg,
             const std::string& file, int line) {
        std::lock_guard<std::mutex> lock(m_mutex);
        
        LogEntry entry;
        entry.timestamp = getCurrentTime();
        entry.level     = level;
        entry.message   = msg;
        entry.file      = file;
        entry.line      = line;
        
        m_buffer.push_back(std::move(entry));
        
        // 缓冲区满了就刷盘
        if (m_buffer.size() >= m_flushThreshold) {
            flushToFile();
        }
    }

    void flushToFile() {
        // 批量写入文件
        for (const auto& entry : m_buffer) {
            m_file << entry.timestamp << " ["
                   << levelMap[entry.level] << "] "
                   << entry.message
                   << " (" << entry.file << ":" << entry.line << ")"
                   << std::endl;
        }
        m_file.flush();
        m_buffer.clear();
    }

private:
    Logger() {
        m_file.open("app.log", std::ios::app);
        // 我习惯在构造函数里就打开文件
        // 避免第一次写日志时卡顿
    }

    ~Logger() {
        flushToFile();
        m_file.close();
    }

    std::vector<LogEntry> m_buffer;
    std::mutex            m_mutex;
    std::ofstream         m_file;
    size_t                m_flushThreshold = 100;  // 100条刷一次
};

小技巧：用 std::lock_guard 而不是手动 lock/unlock。前者是 RAII 风格，出了作用域自动解锁。我曾经见过同事忘记 unlock，结果死锁了一整个下午。

第四步：宏定义简化调用

每次写 Logger::instance().log(...) 太啰嗦了。我习惯用宏包装一下，顺便自动捕获文件名和行号。

#define LOG_DEBUG(msg) \
    Logger::instance().log(LogLevel::DEBUG, msg, __FILE__, __LINE__)

#define LOG_INFO(msg) \
    Logger::instance().log(LogLevel::INFO, msg, __FILE__, __LINE__)

#define LOG_WARN(msg) \
    Logger::instance().log(LogLevel::WARN, msg, __FILE__, __LINE__)

#define LOG_ERROR(msg) \
    Logger::instance().log(LogLevel::ERROR, msg, __FILE__, __LINE__)

这样调用起来就清爽多了：

LOG_INFO("用户登录成功");
LOG_ERROR("数据库连接失败: " + errMsg);

第五步：多线程安全测试

日志系统最怕的就是多线程同时写。咱们来验证一下：

void worker(int id) {
    for (int i = 0; i < 100; ++i) {
        LOG_INFO("线程 " + std::to_string(id) + 
                 " 第 " + std::to_string(i) + " 次写入");
    }
}

int main() {
    std::thread t1(worker, 1);
    std::thread t2(worker, 2);
    std::thread t3(worker, 3);
    
    t1.join();
    t2.join();
    t3.join();
    
    return 0;
}

跑完之后检查日志文件，你会发现三条线程的日志是交错出现的，但每一条都是完整的，没有出现半行被截断的情况。这就是 mutex 的功劳。

注意：千万别在日志系统里用递归锁（recursive_mutex）。我见过有人图省事，结果日志里调了另一个日志，直接死锁。记住：日志函数里不要调用任何可能产生日志的代码。

性能对比：STL 版 vs 手写版

我拿一个旧项目里的手写日志系统做了对比，结果如下：

指标 手写 C 版 STL 版 提升
代码行数 850 行 120 行 ↓ 86%
内存泄漏 3 处（上线后才发现） 0 处 完美
写入性能（10万条） 2.3 秒 1.8 秒 ↑ 22%
多线程稳定性 偶发崩溃 稳定运行 可靠

说实话，这个结果我自己都没想到。STL 版不仅代码少，性能还更好。原因很简单：vector 的内存管理比手写数组高效，string 的拼接优化也比 strcat 强。

避坑指南

嗯，这里我要说几个我踩过的坑：

  • 缓冲区大小要合理：太小了频繁刷盘，影响性能；太大了内存占用高。我一般设 100-500 条，具体看业务量。
  • 文件打开模式用 std::ios::app：这样每次写入都是追加，不会覆盖之前的日志。我见过有人用 std::ios::out，结果每次重启程序日志就没了。
  • 析构函数里一定要 flush：否则程序崩溃时最后几条日志可能丢失。虽然不能保证 100% 不丢，但至少能减少损失。
  • 日志文件要轮转：生产环境里日志文件会无限增长。我一般加个文件大小限制，超过就自动切分。这个功能可以用 filesystem 库实现，但那是另一个话题了。

最后说一句：日志系统看着简单，但它是调试的「眼睛」。花点心思把它做好，后面能省无数时间。我当年要是早点用 STL 写日志，可能能多睡好几个安稳觉。

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

← 上一章 📖 返回目录 下一章 →