Rocket 框架提供了维持状态(State)的机制,将状态分为「应用程序状态」和「请求状态」两种。前者可以将任何类型当作状态来使用,而且可以自由、便利地使这些状态「加载」到任意路由处理程序中;而后者则是因一个 HTTP 请求可能会由多个路由处理程序尝试匹配而诞生出来的缓存机制。
应用程序状态
应用程序状态的有效范围是整个 Rocket 应用程序。使用方式很简单,只需将想要作为状态使用的实体(可以是任意类型),全都透过 Rocket 结构实体的 manage 方法来注册给 Rocket 使用就好了。
例如:
use std::sync::Mutex;
struct Config {
domain: String,
}
struct HitCount {
count: usize,
}
let config = Config { domain: "magiclen.org".to_string() };
let hit_count = Mutex::new(HitCount { count: 0 });
rocket::build().manage(config).manage(hit_count)
对于会在 Rocket 应用程序运行时被改变的状态,我们可以用 Mutex 结构体来包裹它,使其可以在多个线程下被安全访问。
当我们需要在路由处理程序中读取这些状态时,可以在路由处理程序的函数中,加上类型为 &State<T> 的参数,T 即为我们注册给 Rocket 当状态使用的实体的类型。
例如:
#[macro_use]
extern crate rocket;
use std::sync::Mutex;
use rocket::State;
#[derive(Debug)]
struct Config {
domain: String,
}
struct HitCount {
count: usize,
}
#[get("/hit")]
fn hit(config: &State<Config>, hit_count: &State<Mutex<HitCount>>) -> String {
let s = format!("{:?}", config);
let mut hit_count = hit_count.lock().unwrap();
hit_count.count += 1;
s
}
#[get("/hit-count")]
fn hit_count(hit_count: &State<Mutex<HitCount>>) -> String {
format!("{}", hit_count.lock().unwrap().count)
}
#[launch]
fn rocket() -> _ {
let config = Config {
domain: "magiclen.org".to_string()
};
let hit_count = Mutex::new(HitCount {
count: 0
});
rocket::build().manage(config).manage(hit_count).mount("/", routes![hit, hit_count])
}
原子(Atomic)状态
对于基本数据类型(如 i8、u32、i64、bool 等),我们可以利用 Rust 标准函数库内置的 std::sync::atomic 模块所提供的原子结构体。这些结构体包含整数和布尔等基本数据类型的原子(Atomic)版本,例如 AtomicI8、AtomicU32、AtomicI64、AtomicBool 等。
不过由于 Rocket 框架是以数据类型来区分应用程序状态,因此若要使用原子结构体,最好另外自订一个类型将其包裹起来,以免后续无法再使用相同的原子结构体。
承前一个小节的程序范例,可以用原子结构体改写如下:
#[macro_use]
extern crate rocket;
use std::sync::atomic::{AtomicU64, Ordering};
use rocket::State;
#[derive(Debug)]
struct Config {
domain: String,
}
struct HitCount {
count: AtomicU64,
}
#[get("/hit")]
fn hit(config: &State<Config>, hit_count: &State<HitCount>) -> String {
let s = format!("{:?}", config);
hit_count.count.fetch_add(1, Ordering::Relaxed);
s
}
#[get("/hit-count")]
fn hit_count(hit_count: &State<HitCount>) -> String {
format!("{}", hit_count.count.load(Ordering::Relaxed))
}
#[launch]
fn rocket() -> _ {
let config = Config {
domain: "magiclen.org".to_string()
};
let hit_count = HitCount {
count: AtomicU64::new(0)
};
rocket::build().manage(config).manage(hit_count).mount("/", routes![hit, hit_count])
}
在临界区段(Critical Section)的资源数量未满 4 个的情况下,使用原子结构体来代替 Mutex 结构体可以使程序性能更好!
请求状态
请求状态的有效范围是一个 HTTP 请求。由于 Rocket 框架使用请求守卫来进行路由处理程序的匹配,因此为了避免同一个请求守卫在同一个 HTTP 请求中被匹配多次,我们可以使用请求的缓存机制来暂存请求状态。
例如:
#[macro_use]
extern crate rocket;
use rocket::request::{FromRequest, Outcome, Request};
struct MyGuard<'a> {
authorization: Option<&'a str>,
}
#[rocket::async_trait]
impl<'r> FromRequest<'r> for MyGuard<'r> {
type Error = ();
async fn from_request(request: &'r Request<'_>) -> Outcome<Self, Self::Error> {
let authorization = request.headers().get("authorization").next();
info!("Create a new MyGuard instance.");
Outcome::Success(MyGuard {
authorization,
})
}
}
#[get("/auth?<id>", rank = 1)]
fn handler_1(guard: MyGuard, id: i32) -> String {
format!("ID: {}, Auth: {}", id, guard.authorization.unwrap_or(""))
}
#[get("/auth?<token>", rank = 2)]
fn handler_2(guard: MyGuard, token: String) -> String {
format!("Token: {}, Auth: {}", token, guard.authorization.unwrap_or(""))
}
#[launch]
fn rocket() -> _ {
rocket::build().mount("/", routes![handler_1, handler_2])
}
有关于 info! 宏的用法可以参考这篇文章:
以上程序在对一个 HTTP 请求寻找可匹配的路由处理程序时,MyGuard 这个请求守卫的 from_request 关联函数可能会被运行多次,而创建出好几个 MyGuard 结构实体。若要解决这个问题,可以用请求状态将以上程序改写成:
#[macro_use]
extern crate rocket;
use rocket::request::{FromRequest, Outcome, Request};
struct MyGuard {
authorization: Option<String>,
}
#[rocket::async_trait]
impl<'r> FromRequest<'r> for &'r MyGuard {
type Error = ();
async fn from_request(request: &'r Request<'_>) -> Outcome<Self, Self::Error> {
Outcome::Success(request.local_cache(|| {
let authorization = request.headers().get("authorization").next();
info!("Create a new MyGuard instance.");
MyGuard {
authorization: authorization.map(|s| s.to_string())
}
}))
}
}
#[get("/auth?<id>", rank = 1)]
fn handler_1(guard: &MyGuard, id: i32) -> String {
format!("ID: {}, Auth: {}", id, guard.authorization.as_deref().unwrap_or(""))
}
#[get("/auth?<token>", rank = 2)]
fn handler_2(guard: &MyGuard, token: String) -> String {
format!("Token: {}, Auth: {}", token, guard.authorization.as_deref().unwrap_or(""))
}
#[launch]
fn rocket() -> _ {
rocket::build().mount("/", routes![handler_1, handler_2])
}
虽然这个作法可以使传入 Request 结构实体的 local_cache 方法的闭包不被多次运行,但这也会使得 from_request 函数回传的数据类型不能使用 Rocket 的生命周期参数(因为传入 local_cache 方法的闭包必须回传实体,或是生命周期为 'static 的参考),各有利弊。
总结
「应用程序状态」和「请求状态」分别针对全 Rocket 应用程序以及单一的 HTTP 请求提供额外的数据暂存功能。而「应用程序状态」其实还有更为强大的应用方式,那就是可以用来保存 Rocket 应用程序所用到的数据库的实体!有关于 Rocket 框架与数据库的搭配用法,将会在之后的章节做介绍。
