游戏客户端架构 / 系统课时

建立日志与断言

建立日志与断言

本课将搭建一个可直接复用的 C++ 日志与调试断言模块:日志负责记录运行轨迹,断言在状态违背约束时立即停止当前流程,并给出表达式、文件和行号,方便后续定位引擎问题。

学习目标

  • 设计包含级别、消息和来源位置的最小日志接口。
  • 实现只在调试构建中生效的断言机制。
  • 编译运行示例,并根据输出验证模块行为。

设计最小接口

日志首先要解决“发生了什么”,断言则要回答“哪个约束被破坏”。最小版本保留 DEBUG、INFO、WARN、ERROR 四个级别,并让断言自动记录失败表达式、说明、源文件和行号。

日志接口不应依赖渲染器或游戏循环,否则引擎启动早期发生错误时反而无法输出。当前实现直接写入标准输出,后续再替换为文件、控制台面板或异步队列。

实现日志与调试断言

将下面代码保存为 main.cpp。ENGINE_ASSERT 通过宏捕获表达式文本、__FILE__ 和 __LINE__;定义 NDEBUG 的发布构建会直接移除断言调用,条件表达式也不会执行。

cpp
#include <iostream>
#include <sstream>
#include <stdexcept>
#include <string>

enum class LogLevel {
    Debug,
    Info,
    Warn,
    Error
};

const char* toText(LogLevel level) {
    switch (level) {
        case LogLevel::Debug: return "DEBUG";
        case LogLevel::Info: return "INFO";
        case LogLevel::Warn: return "WARN";
        case LogLevel::Error: return "ERROR";
    }
    return "UNKNOWN";
}

class Logger {
public:
    static void write(LogLevel level, const std::string& message) {
        // 基础日志不依赖渲染器,确保引擎启动阶段也能输出。
        std::cout << '[' << toText(level) << "] " << message << '\n';
    }
};

void assertOrThrow(
    bool condition,
    const char* expression,
    const std::string& message,
    const char* file,
    int line
) {
    if (condition) {
        return;
    }

    // 先组合完整诊断信息,再交给统一日志接口。
    std::ostringstream detail;
    detail << "Assertion failed: " << expression
           << " | " << message
           << " | " << file << ':' << line;
    Logger::write(LogLevel::Error, detail.str());

    // 抛出异常便于演示;真实引擎也可在此触发调试器中断。
    throw std::runtime_error(message);
}

#define ENGINE_LOG_DEBUG(message) Logger::write(LogLevel::Debug, (message))
#define ENGINE_LOG_INFO(message) Logger::write(LogLevel::Info, (message))
#define ENGINE_LOG_WARN(message) Logger::write(LogLevel::Warn, (message))

#ifndef NDEBUG
#define ENGINE_ASSERT(condition, message) assertOrThrow((condition), #condition, (message), __FILE__, __LINE__)
#else
#define ENGINE_ASSERT(condition, message) ((void)0)
#endif

int main() {
    try {
        ENGINE_LOG_INFO("Engine startup");
        ENGINE_LOG_DEBUG("Loading texture metadata");

        const int textureWidth = 0;
        ENGINE_ASSERT(textureWidth > 0, "Texture width must be positive");
    } catch (const std::exception&) {
        ENGINE_LOG_WARN("Startup stopped by debug assertion");
    }

    return 0;
}

运行与验证

使用支持 C++17 的编译器构建调试版本。这里没有定义 NDEBUG,所以断言会执行。

bash
g++ -std=c++17 -O0 -g main.cpp -o logger_demo
./logger_demo

预期输出如下。<PATH> 和 <LINE> 会随文件位置及代码行号变化。

text
[INFO] Engine startup
[DEBUG] Loading texture metadata
[ERROR] Assertion failed: textureWidth > 0 | Texture width must be positive | <PATH>:<LINE>
[WARN] Startup stopped by debug assertion

当日志顺序、失败表达式和说明都出现时,说明基础模块已生效。

使用边界

断言用于检查程序员能够保证的内部条件,例如纹理尺寸必须大于零、组件指针不能为空、状态枚举必须有效。网络超时、文件不存在或玩家输入错误属于可恢复问题,应记录错误并返回结果,而不是依赖断言处理。

发布构建可通过 -DNDEBUG 关闭断言,但关键输入校验不能因此消失。日志也应避免在每帧循环中无条件输出大量信息,否则磁盘与格式化开销可能掩盖真正的性能问题。

本课总结

  • 日志记录运行轨迹,断言在内部约束失效时提供精确定位信息。
  • 基础实现应尽量独立,保证引擎启动早期也能工作。
  • 断言只处理不可接受的程序状态,可恢复错误仍需正常返回和记录。

下一课预告

下一课将建立引擎数学基础,从坐标系与统一单位开始,为变换、摄像机和碰撞计算准备共同约定。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

建立日志与断言

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通