第2章：日志系统设计——级别、格式与环形缓冲区

日志系统，说白了就是嵌入式系统的「黑匣子」。我做了十几年嵌入式开发，见过太多产品出问题后只能干瞪眼的场景——没有日志，你连问题出在哪都不知道。这一章，咱们就把日志系统的基础打牢。

2.1 日志级别：DEBUG / INFO / WARN / ERROR

日志级别不是拍脑袋定的。我习惯把级别看作「严重程度」和「输出开关」的组合。你想想看，如果所有日志都打开，系统跑起来会慢得让你怀疑人生。所以，分级是必须的。

2.2 日志格式规范：时间戳 + 模块 + 内容

日志格式不统一，分析起来就是灾难。我见过最离谱的日志，只有一行数字，连是谁打的都不知道。所以，格式必须定死。

我个人习惯的格式模板：

[时间戳] [级别] [模块] [文件名:行号] 内容

举个例子：

[2025-03-21 14:32:18.456] [INFO] [UART_DRV] [uart.c:128] 波特率配置完成: 115200

为什么要有时间戳？因为你要知道事件发生的顺序。为什么要有模块？因为你要快速定位是哪个子系统出了问题。为什么要有文件名和行号？因为代码改了之后，你还能找到原始位置。

2.3 环形缓冲区实现

日志输出不能直接写文件，因为嵌入式系统没有文件系统，或者 Flash 寿命有限。环形缓冲区（Ring Buffer）是标准解法。说白了，就是一个固定大小的数组，写满了从头覆盖。

我画了一张图，帮你理解环形缓冲区的核心逻辑：

代码实现其实不复杂。我给出一个最简版本，你可以在项目里直接套用：

#define LOG_BUF_SIZE 256

typedef struct {
    char buffer[LOG_BUF_SIZE][128];  // 128字节每行
    uint16_t head;                   // 写指针
    uint16_t tail;                   // 读指针
    uint16_t count;                  // 当前条目数
} ring_log_t;

ring_log_t log_ring;

void log_write(const char *msg) {
    strncpy(log_ring.buffer[log_ring.head], msg, 127);
    log_ring.head = (log_ring.head + 1) % LOG_BUF_SIZE;
    if (log_ring.count < LOG_BUF_SIZE) {
        log_ring.count++;
    } else {
        // 缓冲区满了，tail 也要跟着移动
        log_ring.tail = (log_ring.tail + 1) % LOG_BUF_SIZE;
    }
}

int log_read(char *out, uint16_t size) {
    if (log_ring.count == 0) return -1;
    strncpy(out, log_ring.buffer[log_ring.tail], size - 1);
    log_ring.tail = (log_ring.tail + 1) % LOG_BUF_SIZE;
    log_ring.count--;
    return 0;
}

2.4 避坑指南

• 日志字符串太长怎么办？我建议每条日志控制在 128 字节以内。超过的部分截断，或者分多条输出。我曾经见过有人一条日志打了 2KB，直接把环形缓冲区撑爆了。
• 多任务环境怎么保证线程安全？写入操作必须加锁。我习惯用关中断的方式保护临界区，因为日志写入时间很短，关中断不会影响实时性。
• 日志输出到串口还是缓冲区？我的做法是：调试阶段同时输出到串口和缓冲区；发布阶段只写缓冲区，串口关闭。这样既不影响性能，又能在出问题时通过串口导出日志。