我先说结论Logger.h和Logger.cc这组文件几乎是一切 C 后端服务和客户端工具的地基。无论你是刚接触 C 不久还是已经写了两三年业务代码只要项目里出现过“日志打不出来”“多线程日志串了”“日志文件越来越大”这类问题那你迟早得打开这两个文件看一遍。这个标题看起来朴素实际拆开之后能讲的东西非常多接口怎么设计、宏怎么埋、级别怎么定、线程安全怎么做、文件滚动怎么写、性能瓶颈在哪。这篇文章就围绕一份典型的Logger.hLogger.cc实现把里面值得关注的细节一个个讲透。我会按照“先看整体设计 → 再拆头文件 → 再拆实现文件 → 最后给集成和踩坑经验”的顺序展开。不想听原理、只想知道怎么改的读者可以直接跳到第 4 节和第 5 节想把这组文件吃透、以后自己也能维护的建议从头顺序看。1. 拿到 Logger.h先看整体设计很多人在项目里看到Logger.h和Logger.cc第一反应是“这不就是个打日志的工具吗”然后扫一眼就过了。但真正经历过线上问题排查的人都知道日志系统往往决定了一个问题的定位速度。所以拿到这组文件我一般不是先看某个函数怎么实现而是先回答三个问题为什么自研、为什么拆文件、接口长什么样。1.1 为什么选择自研而不是直接上开源库现在 C 生态里有不少成熟日志库性能好、功能全按理说不该重复造轮子。但实际项目里我见过太多团队最后又回到手写Logger.hLogger.cc的路线。原因不外乎几个编译期依赖和版本兼容问题。引入一个大型日志库意味着构建系统要处理新的依赖树某些基础组件库甚至要求日志库必须跟随主工程一起发布这种绑定关系在多个团队协作时特别痛苦。需要深度定制。比如日志格式必须符合公司内部规范输出位置要写到某个指定的共享内存或者 syslog 通道这些需求在开源库里往往要靠改源码才能满足那还不如一开始就自己维护一个精简版本。教学和内部工具场景下一个只有几百行的Logger.hLogger.cc足够覆盖 80% 的项目需求而维护成本几乎为零。所以我在看代码时并不会只盯着“实现的完整度”看而是会判断这套实现到底是为哪种场景服务的。如果是用于一个核心服务那它的性能设计就要比较严格如果只是给工具类程序做辅助输出那简单可靠就是第一位。1.2 头文件和源文件分离的工程意义Logger.h和Logger.cc的拆分本身就是信息。头文件里放的是接口和类型定义源文件里放的是实现和内部状态。这种拆分至少带来三个好处编译依赖隔离。业务代码只需要包含Logger.h不关心Logger.cc里用了什么内部容器、什么锁类型。一旦实现细节发生变化只要接口不变业务代码的编译就不受影响。ABI 稳定。如果只有头文件所有实现都被内联改一个私有函数可能就要重新编译所有引用的对象文件拆开之后只有Logger.cc单独重编。可测试性。实现集中在源文件里接口清晰了针对不同需求替换实现比如从同步日志换成异步日志时只需要改.cc文件或者换一个编译单元非常灵活。1.3 Logger.h 在实际项目中扮演的角色往大了说日志系统是程序运行状态的“黑匣子”往小了说Logger.h是一套规约规定了全项目所有代码写日志的方式。比如日志级别的定义放这里、输出宏放这里、常见的格式化重载放这里。这也是为什么很多人拿到一个项目的第一件事就是先翻它的Logger.h因为看完这个头文件你基本就知道了这个项目的调试习惯、上线规范、性能要求。2. Logger.h接口层到底藏着哪些设计细节一份典型的Logger.h通常会有三块内容日志级别枚举、输出接口、辅助宏定义。这三块看似简单实际上每个细节都决定了后面实现的写法。2.1 日志级别枚举别小看一个枚举常见定义是这样enum LogLevel { TRACE 0, DEBUG, INFO, WARN, ERROR, FATAL };这个顺序是有讲究的数字从小到大正好对应严重程度从低到高。后面判断“某个级别是否应该输出”时只需要比较数字大小就行例如if (level currentLevel_) { // 输出 }我见过一些项目把枚举值搞成 1、10、20、30目的是为了以后在中间插入新级别不改动已有值。这种做法有一定道理但对于内部使用的日志来说纯粹增加了心智负担。个人经验是如果暂时只有 6 个级别直接用 0~5 就够了真到要插新级别的时候枚举本身换个值不是什么大工程。需要添加到Logger.h里的往往还有对应的字符串转换函数比如const char* logLevelToString(LogLevel level);这个函数可以声明在头文件里实现放在.cc。千万要注意不要在头文件里用switch直接返回字符串的inline函数除非你确定不会有人用不同编译选项来编译它否则很容易遇到 ODR 问题。更常见的做法是头文件里只声明.cc里用数组或者switch实现。2.2 日志输出的核心接口流式还是格式化Logger.h里核心输出接口总逃不过两种风格。一种是类printf风格void log(LogLevel level, const char* fmt, ...);另一种是流式风格class Logger { public: void log(LogLevel level, const std::string msg); };搭配宏之后流式风格通常会被做成这样#define LOG_INFO(msg) Logger::instance().log(LogLevel::INFO, msg)两种风格各有市场。printf风格的好处是格式控制直接、性能开销小、类型信息也够用缺点是类型不安全传错参数类型可能直接崩。流式风格的好处是operator天然支持自定义类型写起来更符合 C 习惯缺点是引入临时对象如果实现不考究会多出不少构造析构开销。从实际经历看团队里如果 C 风格比较重用printf风格接受度高如果都是现代 C 习惯流式风格更受欢迎。我在Logger.h里最喜欢看到的是两者结合对外暴露流式接口底层用snprintf做格式化缓冲。这种设计既有流式的写码体验又有printf的性能。2.3 宏定义源码位置的自动采集看Logger.h时如果没有宏只有成员函数那日志输出通常拿不到__FILE__、__LINE__这种信息。拿到了这些信息你才好在每行日志里自动带上源码位置。所以典型宏是这样#define LOG_INFO(...) \ Logger::instance().log(LogLevel::INFO, __FILE__, __LINE__, __VA_ARGS__)这里有几个容易踩的细节宏内部不能直接写入std::ostream因为输出可能跨线程流对象的状态管理会很麻烦。宏里带着__FILE__和__LINE__展开之后日志实现里就能自动记录位置。使用__VA_ARGS__的可变参数宏时要留意不同编译器的兼容性。在 C20 之前标准是...和__VA_ARGS__某些老编译器对空参数列表支持不一致所以很多项目会再包装一层。还有一种做法是用函数重载替代宏来拿source_location比如 C20 的std::source_location::current()。如果项目允许使用 C20那完全可以把__FILE__的宏依赖去掉接口会更干净。但现实中很多老项目还停留在 C14/17宏依然是普遍的写法。2.4 线程安全与线程ID的设计暗示在Logger.h的接口里如果看到类似setLevel、setOutputFile这种接口却看不到任何锁相关的内容不要慌。线程安全不一定非得暴露在头文件里但接口设计能暗示实现取舍Logger::instance()本身要注意跨线程的安全初始化。日志写入接口如果设计成const成员函数说明内部状态会被mutable或全局状态管理这些东西都留在.cc里。如果头文件里有#include mutex说明实现的锁粒度比较重可能在每次log调用时都加锁。如果头文件里出现std::atomicLogLevel说明日志级别的读写走的是无锁路径性能会好一些。另外有些Logger.h会提供setThreadName或自动打印线程ID的接口。这个功能在排查多线程问题时特别重要因为只看日志输出分不清哪条是哪个线程打的。头文件里有没有这个接口直接决定后续排查逻辑的便捷程度。提示拿到的Logger.h如果同时具备“级别可动态调整”和“线程ID自动打印”两个能力这个项目大概率是经历过真实线上排查的不是随手写的玩具。3. Logger.cc实现层的关键细节与性能取舍头文件再多设计最终还是要落到.cc的实现里。这一节我会按实现顺序拆单例怎么建、时间戳怎么格式化、文件输出怎么管理、性能问题怎么处理。3.1 单例模式静态局部变量的线程安全Logger.cc里最常见的单例实现长这样Logger Logger::instance() { static Logger instance; return instance; }这是 C11 之后的标准做法利用静态局部变量的初始化保证唯一性。重点在于C11 标准明确要求静态局部变量初始化是线程安全的编译器会往这里插入一个 guard flag 和对应的加锁逻辑。所以这段代码即使多个线程第一次同时调用instance()也只有一个线程执行构造函数其他线程会等第一个初始化完成。但这里有个容易被忽略的坑如果 Logger 的构造函数里调用了instance()本身或者构造期间触发了其他需要 Logger 的代码就会形成递归构造这会导致未定义行为。设计上要注意构造函数里只做简单的初始化不要产生日志输出。如果你看到的是另一种老式写法static Logger* instance nullptr; if (instance nullptr) { instance new Logger(); } return instance;那是 C11 之前的老代码存在数据竞争多线程下可能创建出多个实例。遇到这种实现我建议尽快改成静态局部变量版改动成本极低收益非常确定。3.2 时间戳格式化性能和可读性的平衡日志里最重要也最容易出错的是时间戳。一份好的Logger.cc通常会在时间戳处理上做不少细节打磨。常见实现是time_t now time(nullptr); struct tm tm_now; localtime_r(now, tm_now); char buffer[64]; strftime(buffer, sizeof(buffer), %Y-%m-%d %H:%M:%S, tm_now);这段代码功能没问题但要注意几点localtime不是线程安全的必须要用localtime_r。strftime的格式字符串每次调用都解析一次在最新实现中可以考虑缓存。如果日志打印非常频繁一次timelocaltime_rstrftime的消耗也不低大多数日志系统会做毫秒级时间戳但毫秒值需要单独取不能只靠time_t。更高性能的做法是缓存格式化的时间字符串每秒只重新计算一次其余日志直接复用。很多日志实现会有如下结构uint64_t lastTime 0; char timeBuffer[32]; if (currentTime ! lastTime) { // 格式化 timeBuffer lastTime currentTime; }这种优化在日志量大时非常明显。另外如果希望日志里带毫秒需要用gettimeofday或std::chrono获取更精确的时间然后再拼到缓冲区里。这一步虽然简单但如果不注意位数对齐打出来的日志时间就会出现2025-05-20 10:11:12.3这种不整齐的格式给后续解析程序带来麻烦。正确做法是固定毫秒宽度不足补零。3.3 文件输出的滚动与句柄管理Logger.cc里面一个常见的功能是支持写日志文件。最朴素的实现是std::ofstream file_; file_.open(path, std::ios::app | std::ios::out);简单可用但一个非常大的问题是没有滚动。日志文件会无限增长直到磁盘满。能支撑生产环境的实现基本上要按大小或按天数滚动。一个常见的按大小滚动实现思路如下每次写日志前检查文件大小。如果当前文件大小超过阈值比如 100MB就关闭当前文件把文件名加上.1、.2这样的后缀滚动。滚动后重新打开新文件。具体代码一般会封装openLogFile()函数在文件需要切换时调用。这里需要注意检查文件大小本身也有开销不建议每次写日志都stat一次。常见做法是维护一个writtenBytes_计数每次写入后累加超过阈值时再滚动。滚动超期文件删除策略要提前设计。如果日志只保留最近 10 个文件在滚动时要清理最旧的。文件句柄泄漏是重灾区。如果openLogFile失败旧的句柄必须关闭否则会占住文件导致后续无法滚动。3.4 性能瓶颈与优化策略看完上述实现再来谈性能。同步日志的模型是每次LOG_INFO→ 加锁 → 格式化 → 写入文件/控制台 → 释放锁。这个模型在小流量下非常稳但日志并发高时锁竞争会成为瓶颈。Logger.cc里常见的优化思路有几种减少格式化开销。日志级别不满足时宏内部可以提前判断避免传入字符串构造std::string。比如宏写成#define LOG_DEBUG(...) \ do { if (Logger::instance().isEnabled(LogLevel::DEBUG)) \ Logger::instance().log(LogLevel::DEBUG, __FILE__, __LINE__, __VA_ARGS__); } while(0)这样在 release 版本里DEBUG 日志几乎零开销。减少锁复杂度。把锁从std::mutex换成std::recursive_mutex是下策虽然解决了递归日志问题但会放大锁竞争。更好的是用std::lock_guard配合细粒度锁或者干脆做成无锁队列。使用异步日志。把格式化后的日志消息丢到一个 ring buffer 里由独立的日志线程负责写文件。这个方案能极大降低业务线程阻塞但Logger.h的接口变化不大主要是.cc里多了一个后台线程和队列。作为起步项目我不会建议一开始就上异步。先实现一个正确的同步版本等确实压测出瓶颈再改成异步。很多项目其实到不了异步这个阶段因为日志引入的延迟是微秒级的真正让业务卡顿的往往是文件写太频繁而不是打印本身。提示看到.cc里如果有一个std::thread成员变量或者std::queuestd::string大概率是异步日志实现。这时要留意析构函数有没有做“把队列清空再退出”的处理否则程序退出时容易丢日志。4. 集成与编译的实操指南只看代码不编译其实很难彻底理解Logger.h和Logger.cc。这一节我直接给出一个最小可用的集成方案并说明编译链接时容易出的问题。4.1 CMake 接入完整示例假设目录结构是这样的src/ Logger.h Logger.cc main.cc在CMakeLists.txt里按如下方式配置cmake_minimum_required(VERSION 3.16) project(DemoLogger) add_executable(demo_logger src/Logger.cc src/main.cc ) target_compile_features(demo_logger PRIVATE cxx_std_17)这里要注意Logger.cc不能漏掉如果只写src/main.cc编译的时候会报Logger::instance()未定义引用。这是因为头文件里的成员函数只有声明没有实现没有把Logger.cc加进编译就会链接失败。这是一个特别常见的错误我第一次集成时也栽在过这里。main.cc里这样写#include Logger.h int main() { LOG_INFO(hello logger); LOG_ERROR(some error happened %d, 42); return 0; }假设Logger.h的宏定义是#define LOG_INFO(...) Logger::instance().log(LogLevel::INFO, __FILE__, __LINE__, __VA_ARGS__)那么编译运行之后输出应该类似于2025-05-20 10:11:12.123 [INFO] main.cc:4 hello logger 2025-05-20 10:11:12.124 [ERROR] main.cc:5 some error happened 42一看到[INFO]后面自动带了文件行号就知道宏层面的设计是成功的。4.2 从一行日志到一套监控系统的演进我见过很多项目最开始就是用这样的Logger.hLogger.cc打点。后来做着做着有些人会选择在Logger.cc里增加一个logSink抽象把输出目标变成“控制台 文件 UDP 上报”这样就能把日志直接送进日志分析系统形成一个简易监控链路。具体演进顺序通常是这样第一版只有控制台输出用来调试。第二版增加文件输出和大小滚动用于上线运行。第三版增加日志级别热切换支持通过配置文件修改运行时的日志级别方便线上临时排查。第四版增加异步队列和指标上报把日志发送到统一采集端。Logger.h的接口从第一版到第四版可能没有太大变化变的都是.cc的内部实现。这其实正是接口设计得好的表现调用方不需要感知内部实现维护者可以放心改进。5. 常见问题与排查技巧实录这一节整理的是我实际使用和帮别人排查时经常遇到的问题。每一条都是真实踩过坑之后总结出来的建议收藏备用。5.1 多线程下日志丢失或重复症状多个线程同时打印日志时偶尔会出现后半条被截断或者两条日志混在一起。原因几乎都是写入过程没有加锁或者锁的范围不够。比如Logger.cc里如果只对std::cout的写入加了锁但格式化字符串是在锁外完成的多个线程可能同时把各自格式化好的字符串写入同一个输出流。更常见的是直接用了fprintfFILE*内部虽然有缓冲但多线程写入时的原子性和顺序性并不能保证。遇到这种问题排查思路很简单打开Logger.cc找log函数的实现确认整个“取当前状态 → 格式化 → 写入”的过程是否被同一把锁覆盖。如果是异步日志就要看队列的入队操作是否线程安全。5.2 时间戳不正确或者只有秒级精度我见过有人发现日志时间比实际时间早了 8 小时多半是因为用gmtime而不是localtime_r或者容器环境时区变量没设置。排查方法一般是直接执行date命令看系统时区再确认Logger.cc里的取时间函数。另一个问题是毫秒级精度缺失。如果Logger.cc里只用time(nullptr)日志只能精确到秒。对于高并发场景秒级精度会让人很难定位先后的顺序尤其是同一秒内的大量日志。改进方法是在Logger.cc里改用std::chrono::system_clock::now()再手动拼接毫秒。5.3 文件大小一直不滚动日志打了一晚上还是老文件这个问题我在一个经历过的项目上排查了很久最后发现原因是滚动条件用stat去拿文件大小而实际写入的句柄还没有flush导致stat拿到的旧文件大小一直不变。文件内容虽然通过缓冲写入了文件系统但stat只反映最后一次 flush 的尺寸所以一直触发不了滚动条件。根治办法是不要依赖外部文件系统状态而是在每次写入时累加writtenBytes_。这种做法更直接也能避免重复调用stat。5.4 宏定义在 if/else 中产生的隐藏 bug这是一个非常经典的 C/C 宏问题。如果你的宏定义长这样#define LOG_INFO(...) Logger::instance().log(LogLevel::INFO, __FILE__, __LINE__, __VA_ARGS__)那么下面这段代码在外观上是正常的if (isReady()) LOG_INFO(ready); else doSomething();宏展开后变成if (isReady()) Logger::instance().log(...); else doSomething();这看起来没问题。但如果宏内部有多个语句比如#define LOG_INFO(...) \ Logger::instance().setLevel(LogLevel::INFO); \ Logger::instance().log(LogLevel::INFO, __FILE__, __LINE__, __VA_ARGS__)展开后if (isReady()) Logger::instance().setLevel(LogLevel::INFO); Logger::instance().log(...); // 这行一定会执行 else doSomething(); // 这里语法就崩了正确的宏包装方式是do { ... } while(0)#define LOG_INFO(...) \ do { \ Logger::instance().log(LogLevel::INFO, __FILE__, __LINE__, __VA_ARGS__); \ } while(0)这就是为什么很多成熟的Logger.h里宏都会带一层无用的do-while外壳。不是写代码的人闲得慌而是这样能保证宏在if、for、函数调用等任何场景下都表现得像一个普通语句。判断一个日志宏写得好不好看它有没有用do { } while(0)基本就能看出作者的功底。5.5 日志全部正常但程序崩溃时最后几条丢失这个问题在异步日志里最常见。业务线程把日志丢到队列后台日志线程还没来得及写文件程序就abort了。排查方法看Logger.cc析构函数有没有主动“flush 队列并等待线程退出”。给日志增加周期刷新比如每 1 秒强制flush一次保证崩溃前最多丢 1 秒。更彻底的方案是加信号钩子在崩溃处理函数里调用Logger::instance().flush()把缓冲区的数据落盘。对同步日志来说日志是边写边刷的一般不会丢。但同步日志也有损性能的风险很多项目最终还是会选择异步。两头权衡我建议先确认自己的场景是否真的需要低延迟日志如果只是排查问题同步日志已经够用了。写代码之外的几个实际体会最后再分享一个我自己的实践经验。Logger.h和Logger.cc这类文件看着简单其实是最能反映一个 C 工程维护水平的窗口。一个精心维护的日志模块往往具备以下特征宏定义都有do { } while(0)包裹。时间戳格式化有缓存有毫秒精度。日志级别开关能做到编译期裁剪release 版本里低级别日志完全不产生开销。文件滚动逻辑不依赖外部stat而是内部计数。只有一个线程安全清晰的instance()入口。如果你手里的项目Logger.h已经具备其中三四条那说明这个项目的维护者是真的在拿日志当基础设施做。如果一条都不具备也别急着重写先用上第 5 节里最关键的do { } while(0)修复宏隐患再把文件滚动改成分级计数几行代码就能让稳定性提高一大截。我自己的经验是不要一上来就追求特别复杂的设计。先从Logger.hLogger.cc的同步版本开始让每一条日志都带时间、级别、文件行号运行稳定后再加异步和滚动。这样每一步的收益都能即时看到出问题也容易回退。日志模块跟业务代码不一样它不产生直接收益但一旦出问题影响的却是整个系统的可维护性。能在这一组文件里看到“克制”和“严谨”比看到花哨的技巧更有价值。
