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 框架与数据库的搭配用法,将会在之后的章节做介绍。

下一章:中间件(Middleware)与整流片(Fairing)。