Rocket 的 rocket_contrib 套件虽然有提供 StaticFiles 结构体,可以直接将它的实体注册给 Rocket,使 Rocket 能够提供静态文件(如 JS、CSS、图片文件等),但是这些文件必须要和程序可执行文件分开来保存才行,所以如果想要实现单档运行的 Web 应用程序,就需要靠其它的方式来实作程序。
先前虽然介绍过把外部文件和 Rust 程序编译在一起的方式,但如果要直接用这样的方式搭配 Rocket 框架,让它能够提供存在于程序可执行文件内部的静态文件的话,会遇到一些问题。如果是使用 include_bytes 宏的话,首当其冲会遇到编译速度的问题,这个问题虽然也可以利用该篇文章介绍的「Lazy Static Include」套件获得缓解,但还有个大问题是依然存在的。
Rocket 应用程序提供的静态文件,在开发阶段时也会跟着 Rust 程序不断进行修改。如果将这些文件编译进程式可执行文件中,那么每当这些文件被修改后,总是要重新编译并重新运行 Rocket 应用程序才能看到修改后的结果,进而严重拖慢开发速度。
Include Static Resources for Rocket Framework
「Include Static Resources for Rocket Framework」是笔者开发的套件,是针对上述问题提出的解决方案。在非使用 release 模式来编译程序项目时,这个套件不会将静态文件与 Rust 程序编译在一起,取而代之的是,将其读取到内存中,并且在每次取用时,依照文件的修改日期来检查文件是否有被修改过,如果有的话就会读取新文件的内容。这个套件会自动依照文件路径中的文件扩展名来设置要回应的内容类型(Content-Type),除此之外还提供了 HTTP 的 ETag 机制。
Crates.io
Cargo.toml
使用方法
rocket_include_static_resources 这个 crate 提供了 StaticResponse 结构体,可以直接作为路由处理程序的函数回传值的类型。在使用这个套件时,首先要用 StaticResponse 结构体提供的 fairing 关联函数来产生整流片,并注册给 Rocket 来使用。fairing 关联函数必须传入一个闭包,在这个闭包中,必须使用 rocket_include_static_resources 这个 crate 提供的 static_resources_initialize 宏,来设置要一同编译进 Rust 程序的静态文件,而其设置的方式为:先指定静态文件的键值,再指定静态文件的路径。范例程序使用的 static_resources_initializer 宏,可以一次完成产生整流片和设置静态文件这两个动作。在路由处理程序中,可以用 &State<StaticContextManager> 和 EtagIfNoneMatch 作为请求守卫,再调用 StaticContextManager 结构实体的 build 方法,传入 EtagIfNoneMatch 结构实体的参考和要回应的静态文件的键值,就可以产生出对应的 StaticResponse 结构实体。如果只是要替某个路径回应某个静态文件,也可以直接用 static_response_handler 宏来产生路由处理程序。
举例来说,在 Cargo 程序项目的根目录底下的 examples/front-end/images 目录中,有 favicon.ico 和 favicon-16.png 这两个图档,若要使 Rocket 应用程序能够提供这两个静态文件,并且使这两个文件能跟可执行文件编译在一起的话,程序可以写成以下这样:
#[macro_use]
extern crate rocket;
#[macro_use]
extern crate rocket_include_static_resources;
use rocket::State;
use rocket_include_static_resources::{EtagIfNoneMatch, StaticContextManager, StaticResponse};
static_response_handler! {
"/favicon.ico" => favicon => "favicon",
"/favicon-16.png" => favicon_png => "favicon-png",
}
#[get("/")]
fn index(
static_resources: &State<StaticContextManager>,
etag_if_none_match: EtagIfNoneMatch,
) -> StaticResponse {
static_resources.build(&etag_if_none_match, "html-readme")
}
#[launch]
fn rocket() -> _ {
rocket::build()
.attach(static_resources_initializer!(
"favicon" => "examples/front-end/images/favicon.ico",
"favicon-png" => "examples/front-end/images/favicon-16.png",
"html-readme" => ("examples", "front-end", "html", "README.html"),
))
.mount("/", routes![favicon, favicon_png])
.mount("/", routes![index])
}
