在这个章节中,将会介绍 Rocket 框架处理 JSON 和 MessagePack 请求的方式,以及 Rocket 框架内置的处理 UUID 的做法,还有提供静态文件(如图片档、CSS、JS 等等的静态资源档)的更好方式。

JSON

Rocket 提供的 serde::json::Json 结构体可以直接当作数据守卫或是路由处理程序的函数的回传值类型,有关于回传 JSON 的用法会在之后的章节再做介绍。

若要使用 serde::json::Json 结构体,必须要在 Cargo 程序项目的设置档中激活 rocket 的 json 特色,同时加入 serde 这个 crate,并激活 derive 特色。如下:

[dependencies]
serde = { version = "1", features = ["derive"] }

rocket = { version = "0.5.0", features = ["json"] }

有关于 serde 的介绍可以参考这篇文章:

简单来说,我们可以替自己实作出来的类型加上 Deserialize 这个 derive 属性的参数,使这个类型的数据可以直接被 Rocket 框架反串行化。使用 serde::json::Json 结构体来包裹可被 serde 反串行化的数据类型,就可以将 JSON 字符串直接反串行化成该类型了!而且我们可以把这个 Json<T> 类型直接当作数据守卫来使用。

例如:

#[macro_use]
extern crate serde;

#[macro_use]
extern crate rocket;

use rocket::serde::json::Json;

#[derive(Deserialize)]
struct User {
    id:   i32,
    name: String,
}

#[post("/", data = "<user>")]
fn handler(user: Json<User>) -> String {
    format!("Hello, world! id = {}, name = {}", user.id, user.name)
}

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/", routes![handler])
}

以上程序,当 HTTP 请求的主体中的数据是 JSON 格式的字符串时,就会被反串行化为 User 结构实体。

为了避免传进来的 JSON 格式的字符串太长,而导致反串行化需要耗费大量时间与内存,我们可以利用先前学过的 Rocket 框架的设置方式,在 limits 设置项目中加入 json 字段来限制数据量。

MessagePack

Rocket 提供的 serde::msgpack::MsgPack 结构体可以直接当作数据守卫或是路由处理程序的函数的回传值类型,有关于回传 MsgPack 的用法会在之后的章节再做介绍。

与 serde::json::Json 结构体一样,若要使用 serde::msgpack::MsgPack 结构体,必须要在 Cargo 程序项目的设置档中激活 rocket 的 msgpack 特色,同时加入 serde 这个 crate,并激活 derive 特色。

使用 serde::msgpack::MsgPack 结构体来包裹可被 serde 反串行化的数据类型,就可以将 MessagePack 格式的数据直接反串行化成该类型了!而且我们可以把这个 MsgPack<T> 类型直接当作数据守卫来使用。

例如:

#[macro_use]
extern crate serde;

#[macro_use]
extern crate rocket;

use rocket::serde::msgpack::MsgPack;

#[derive(Deserialize)]
struct User {
    id:   i32,
    name: String,
}

#[post("/", data = "<user>")]
fn handler(user: MsgPack<User>) -> String {
    format!("Hello, world! id = {}, name = {}", user.id, user.name)
}

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/", routes![handler])
}

以上程序,当 HTTP 请求的主体中的数据是 MessagePack 格式的数据时,就会被反串行化为 User 结构实体。

为了避免传进来的 MessagePack 格式的数据太长,而导致反串行化需要耗费大量时间与内存,我们可以利用先前学过的 Rocket 框架的设置方式,在 limits 设置项目中加入 msgpack 字段来限制数据量。

UUID

Rocket 提供的 serde::uuid::Uuid 结构体可以直接当作参数守卫,也可以用来匹配网址查找字符串的字段。

若要使用 serde::uuid::Uuid 结构体,必须要在 Cargo 程序项目的设置档中激活 rocket 的 uuid 特色。

serde::uuid::Uuid 结构体的使用方式不难,例如以下程序:

#[macro_use]
extern crate rocket;

use rocket::{response::status, serde::uuid::Uuid};

#[get("/device/<uuid>/name")]
fn handler(uuid: Option<Uuid>) -> Result<&'static str, status::NotFound<&'static str>> {
    match uuid {
        Some(uuid) => match uuid.to_fields_le() {
            (1692521986, 53139, 32579, [149, 69, 236, 56, 53, 249, 44, 216]) => {
                // 02d6e164-93cf-437f-9545-ec3835f92cd8
                Ok("Vacuum Cleaner")
            },
            (613895186, 12848, 3396, [160, 28, 6, 3, 61, 174, 199, 229]) => {
                // 124c9724-3032-440d-a01c-06033daec7e5
                Ok("Refrigerator")
            },
            _ => Err(status::NotFound("Unknown device")),
        },
        None => Err(status::NotFound("Incorrect UUID")),
    }
}

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/", routes![handler])
}

静态文件

在先前的章节中我们有提到可以使用区段守卫搭配 Rocket 内置的 fs::NamedFile 结构体,来让 Rocket 实现出提供文件系统的某目录下所有静态文件(如图片档、CSS、JS 等等的静态资源档)的功能。但 Rocket 其实也有提供 fs::FileServer 结构体来帮我们快速实作出这个功能,只要将 fs::FileServer 结构实体透过 Rocket 结构实体的 mount 方法注册给 Rocket 使用即可。

例如:

#[macro_use]
extern crate rocket;

use rocket::fs::FileServer;

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/public", FileServer::from("static"))
}

以上程序,可以使 /public 这个路径底下的相对路径对应到 Rocket 应用程序的工作目录中的 static 目录下的文件。与使用路由处理程序的函数来回传 fs::NamedFile 时一样,使用 fs::FileServer 结构体也会在 HTTP 回应中自动加入 Content-Type 字段。这个 Content-Type 字段的值会根据网址路径指到的文件类型(依照文件扩展名)而自动做适当的变化。

筛选 HTTP 请求的主体类型

Rocket 框架可以依照 HTTP 请求中的 Content-Type 字段,使路由处理程序只允许某种特定类型的 HTTP 请求。要做到这件事,只需要在路由处理程序的 HTTP 请求方法的属性中,加上 format 参数,与 data 参数搭配使用。

例如以下程序,可以使 Rocket 有能力对相同的路径但不同数据类型的 HTTP 请求做不一样的处理。

#[macro_use]
extern crate serde;

#[macro_use]
extern crate rocket;

use rocket::{
    form::Form,
    serde::{json::Json, msgpack::MsgPack},
};

#[derive(FromForm, Deserialize)]
struct User {
    id:   i32,
    name: String,
}

#[post("/", format = "application/json", data = "<user>")]
fn handler_1(user: Json<User>) -> String {
    format!("Hello, world! id = {}, name = {} (from JSON)", user.id, user.name)
}

#[post("/", format = "application/msgpack", data = "<user>")]
fn handler_2(user: MsgPack<User>) -> String {
    format!("Hello, world! id = {}, name = {} (from MessagePack)", user.id, user.name)
}

#[post("/", format = "form", data = "<user>")]
fn handler_3(user: Form<User>) -> String {
    format!("Hello, world! id = {}, name = {} (from Form)", user.id, user.name)
}

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/", routes![handler_1, handler_2, handler_3])
}

format 参数不一定要写出完整的 MIME 类型,以下是它的简写对应表:

MIME 类型 简写
application/octet-stream binary
application/json json
application/msgpack msgpack
application/x-www-form-urlencoded form
text/javascript js
text/html html
text/plain plain
text/css css
text/xml xml
multipart/form-data multipart

总结

这个章节介绍了 Rocket 框架与 serde 框架结合起来处理 HTTP 请求的用法。下一个章节会先暂时抛开 serde,要来介绍 Rocket 框架的状态(state)处理机制。

下一章:状态(State)。