CFLogger 使用手册¶
欢迎使用 CFLogger 使用手册！CFLogger 是 CFDesktop 框架的异步日志系统，专为现代桌面应用程序设计。
什么是 CFLogger？¶
CFLogger 是一个高性能、异步、线程安全的 C++ 日志库，具有以下特点：
- 异步处理：日志在后台线程处理，不阻塞主线程
- 零依赖：不依赖 Qt 或其他第三方库
- 灵活扩展：支持自定义格式化器和输出目标
- 优雅降级：队列满时优先保证错误日志不丢失
- 简单易用：提供简单 API 和高级 API 两套接口
为什么使用 CFLogger？¶
| 特性 | CFLogger | 其他日志库 |
|---|---|---|
| 异步处理 | ✅ 内置 | ⚠️ 部分支持 |
| Qt 依赖 | ❌ 无依赖 | ⚠️ 常需 Qt |
| 异常机制 | ❌ 不抛异常 | ⚠️ 可能抛异常 |
| 自定义格式 | ✅ 完全可定制 | ⚠️ 有限支持 |
| 线程安全 | ✅ 全线程安全 | ⚠️ 部分场景需额外处理 |
| 错误保护 | ✅ ERROR 日志永不丢失 | ❌ 可能全部丢失 |
适用场景¶
CFLogger 特别适合以下场景：
✅ 推荐使用¶
- 多线程桌面应用程序
- 需要同时输出到控制台和文件
- 对日志性能有要求的应用
- 需要自定义日志格式
- 嵌入式环境或禁用异常的环境
⚠️ 谨慎使用¶
- 简单单线程脚本（可能过度设计）
- 需要同步日志确认的场景（使用
flush_sync()）
快速预览¶
最简单的使用¶
#include "cflog/cflog.h"
int main() {
using namespace cf::log;
info("Hello, CFLogger!");
return 0;
}
典型配置¶
#include "cflog/cflog.hpp"
void init_logger() {
using namespace cf::log;
FormatterFactory factory;
factory.register_formatter("console", []() {
return std::make_shared<AsciiColorFormatter>();
});
auto console_sink = std::make_shared<ConsoleSink>();
console_sink->setFormat(factory.create("console"));
Logger::instance().add_sink(console_sink);
Logger::instance().setMininumLevel(level::INFO);
}
日志输出示例¶
默认格式输出¶
[14:23:45] [INFO] [CFLog] Application started
[14:23:46] [WARNING] [Config] Config file not found
[14:23:47] [ERROR] [Network] Connection failed
彩色控制台输出¶
[14:23:45] [INFO] [CFLog] Application started
^^^^^^ 绿色
[14:23:46] [WARNING] [Config] Config file not found
^^^^^^^ 黄色
[14:23:47] [ERROR] [Network] Connection failed
^^^^^ 红色
手册结构¶
本手册包含以下章节：
| 章节 | 内容 |
|---|---|
| 快速入门 | 5 分钟上手 CFLogger |
| 基础日志 | 简单 API 详解 |
| 高级用法 | 自定义 Sink 和 Formatter |
| 格式化器 | Formatter 系统详解 |
| 输出目标 | Sink 系统详解 |
| 配置选项 | 完整配置参考 |
| 最佳实践 | 推荐的使用模式 |
| 性能优化 | 性能数据和优化建议 |
| 故障排除 | 常见问题解答 |
学习路径¶
初学者路径：
overview → quick_start → basic_logging → best_practices
进阶路径：
overview → advanced_usage → formatters → sinks → configuration
深入路径：
overview → architecture → performance → troubleshooting
相关资源¶
- API 参考：api_reference.md
- 架构详解：architecture.md
版本要求¶
- C++17 或更高
- 支持的编译器：GCC 9+, Clang 10+, MSVC 2019+
- 支持的平台：Linux, Windows, macOS
获取帮助¶
如果在使用过程中遇到问题：
开始使用 CFLogger，请阅读 快速入门！