cache_bust

这是一个用于编译时“缓存破坏”的库，包括在文件名中包含哈希值以优化缓存。

为什么需要缓存破坏？

缓存破坏主要用于Web应用程序，优化浏览器缓存的利用。通过在文件名中包含文件内容的哈希值，可以在HTTP头部中将文件声明为不可变（在Cache-Control中声明文件为不可变），同时不丢失向浏览器推送文件更新的能力。只要文件未更改，它就可以继续缓存。一旦文件更改，浏览器将简单地以新的名称查找它。

如何使用cache_bust

asset! 宏

要将资产包含在源代码中，请使用 asset! 宏

use cache_bust::asset;

let img_src = asset!("images/circle.png");
assert_eq!(img_src, "images/circle.f04a632bf7de8a58d730988671a9139d6f7b3b197bbc78b6c74a4542eaa4878d.png");

默认情况下，这将查找您crate内部的 assets 目录中的资产。要使用不同的目录，请设置 CACHE_BUST_ASSETS_DIR 环境变量。如果文件不存在，宏将产生错误。

也可以禁用文件名的哈希，例如在未使用缓存破坏的调试构建中，可以通过设置 CACHE_BUST_SKIP_HASHING 环境变量为 1 来实现。在这种情况下，宏将作为恒等函数，同时如果文件不存在，仍将产生错误。

构建时间

下一步是将磁盘上的文件重命名为包含它们的哈希值。这可以就地发生，或者可以将重命名的文件复制到新位置，具体取决于您的运行时期望资产的位置。

有两种方法可以实现这一点：使用Rust API或使用CLI工具。

Rust API

可以从 build.rs 构建脚本中调用Rust API

use cache_bust::CacheBust;

let cache_bust = CacheBust::builder()
	.out_dir("hashed_assets".to_owned())
	.build();

cache_bust.hash_dir()?;
assert_eq!(
	std::fs::read("assets/images/circle.png")?,
	std::fs::read("hashed_assets/images/circle.f04a632bf7de8a58d730988671a9139d6f7b3b197bbc78b6c74a4542eaa4878d.png")?
);

CLI工具

或者可以使用 cache_bust_cli 从其他构建工具中进行哈希和重命名文件

cachebust assets --out hashed_assets

动态文件

有些文件可能在构建时动态生成，因此无法使用 asset! 宏包含。可以在构建时单独对它们进行哈希，并获取它们的哈希名称。如何将这些名称传递给运行时由您决定。

Rust API

use cache_bust::CacheBust;

let cache_bust = CacheBust::builder()
	.out_dir("hashed_assets".to_owned())
	.build();

let path = cache_bust.hash_file("generated/script.js")?;
assert_eq!(
	std::fs::read_to_string(path)?,
	"alert('Hello world');\n"
);

CLI工具

cachebust assets --file generated/script.js --out hashed_assets --print-file-name
cachebust assets --file generated/script.js --out hashed_assets --print-file-path

特性

默认

启用所有特性。

宏

启用 asset! 程序化宏。

构建

启用在构建时哈希文件的 CacheBust 和 CacheBustBuilder 结构体。