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

规范资源路径

规范资源路径

本课解决资源文件位置散落在业务代码中的问题。我们将建立“逻辑路径到磁盘路径”的统一映射,让渲染、音频和场景代码只依赖稳定标识,并补上路径规范化与越界检查。

学习目标

  • 理解逻辑路径与磁盘路径分离的价值
  • 实现 res:// 逻辑路径到资源根目录的安全映射
  • 验证路径规范化、非法协议和目录越界行为

为什么不能直接写磁盘路径

把 assets/textures/player.png、D:\game\assets\... 等位置直接写进业务代码,会让目录调整、打包方式和运行平台影响上层逻辑。更稳妥的做法是让业务代码只保存逻辑路径,例如 res://textures/player.png,再由资源系统决定它实际位于开发目录、安装目录还是资源包中。

逻辑路径应满足三个条件:格式稳定、与平台无关、不能逃出资源根目录。磁盘路径则属于运行环境配置,不应成为场景或组件数据的一部分。

逻辑路径到磁盘路径的映射关系

设计路径规则

本课采用以下约定:

  • 所有引擎资源使用 res:// 前缀
  • 前缀后的部分是相对资源根目录的路径
  • 路径解析前执行词法规范化,消除 . 与可消解的 ..
  • 解析结果必须仍位于资源根目录内部
  • 逻辑路径统一使用正斜杠,磁盘分隔符交给 std::filesystem

这些规则让资源引用可以写入场景文件、组件数据和缓存键,而不会绑定某台机器的绝对路径。

实现安全的路径解析器

下面的 C++17 示例建立资源根目录,并将逻辑路径解析为磁盘路径。程序还演示正常路径、错误协议和目录越界三种情况。

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

class ResourcePathResolver {
public:
    explicit ResourcePathResolver(std::filesystem::path root)
        : root_(std::filesystem::absolute(std::move(root)).lexically_normal()) {}

    std::filesystem::path resolve(const std::string& logicalPath) const {
        constexpr const char* prefix = "res://";
        if (logicalPath.rfind(prefix, 0) != 0) {
            throw std::invalid_argument("resource path must start with res://");
        }

        std::filesystem::path relative = logicalPath.substr(6);
        if (relative.empty() || relative.is_absolute()) {
            throw std::invalid_argument("resource path must be relative");
        }

        const auto result = (root_ / relative).lexically_normal();
        if (!isInsideRoot(result)) {
            throw std::invalid_argument("resource path escapes asset root");
        }
        return result;
    }

private:
    bool isInsideRoot(const std::filesystem::path& path) const {
        auto rootIt = root_.begin();
        auto pathIt = path.begin();
        for (; rootIt != root_.end(); ++rootIt, ++pathIt) {
            if (pathIt == path.end() || *rootIt != *pathIt) {
                return false;
            }
        }
        return true;
    }

    std::filesystem::path root_;
};

int main() {
    ResourcePathResolver resolver("assets");

    for (const std::string path : {
             "res://textures/../textures/player.png",
             "file://player.png",
             "res://../secret.txt"}) {
        try {
            const auto resolved = resolver.resolve(path);
            std::cout << path << " -> " << resolved.generic_string() << '\n';
        } catch (const std::exception& error) {
            std::cout << path << " -> ERROR: " << error.what() << '\n';
        }
    }
}

编译并运行:

bash
g++ -std=c++17 -O2 main.cpp -o resource_path_demo
./resource_path_demo

预期输出如下。绝对路径前缀会随实际工作目录变化,因此使用 <PATH> 表示。

text
res://textures/../textures/player.png -> <PATH>/assets/textures/player.png
file://player.png -> ERROR: resource path must start with res://
res://../secret.txt -> ERROR: resource path escapes asset root

关键边界

lexically_normal() 只做路径文本规范化,不会检查文件是否真实存在。存在性、文件类型和读取权限应由加载器处理,这样“路径解析”和“文件读取”保持单一职责。

资源根目录在生产环境中应由启动配置或平台层提供,而不是由业务模块自行拼接。Windows 路径比较还可能涉及大小写和盘符规则;跨平台项目可在平台适配层补充更严格的规范化策略。

Tips:逻辑路径适合作为缓存键。先统一前缀、分隔符和冗余路径段,再进入缓存,可避免同一文件因不同写法被加载多次。

本课总结

  • 业务代码应引用稳定的逻辑路径,而不是直接依赖磁盘位置
  • 路径解析器负责前缀校验、规范化和资源根目录越界检查
  • 文件是否存在与能否解析,应交给后续资源加载器判断

下一课预告

下一课将基于统一逻辑路径实现资源加载器,为文本、二进制等不同资源类型建立一致的读取与解析入口。

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

目录与阅读设置

阅读设置

17

记录一个想法

规范资源路径

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

登录哪都通