到目前为止,我们已经知道一个路由处理程序的函数可以选择不回传任何值,或是选择回传一个字符串或一个字符串切片。在这篇文章中,将会介绍 Rocket 框架所提供的多种不同的类型,来让我们的路由处理程序能够回应(respond)更多类型的数据。

response::Responder

先来复习一下上一章所提到的 Rocket 的路由处理程序的基本架构,如下:

#[HTTP请求方法("路径")]
fn handler() -> 要回应的数据类型 { 处理请求的程序区块 }

在这个架构中,要回应的数据类型 可以使用任何实作了 rocket 这个 crate 提供的 response::Responder 特性的类型。Rocket 框架预设已经替 &str、String、&[u8]、Vec<u8> 和 File 等 Rust 与标准函数库内置的类型实作了 response::Responder 特性。另外,Rocket 还在 response 模块中另外内置了 content、status、stream 模块以及 Redirect 类型,来处理常用的回应数据类型。

由于 HTTP 回应并不只是把数据放进 HTTP 主体中,我们总是还需要针对数据类型、数据大小以及数据的缓存来撰写 HTTP 回应的标头。而 Rocket 框架显然是把 HTTP 标头的写入动作都交由 response::Responder 特性来解决了,我们无法直接从路由处理程序的架构得知它回应的 HTTP 标头到底会有哪些。所以说,在使用一个陌生的 response::Responder 前,最好先熟悉一下该类型会如何处理 HTTP 回应中的标头。

不回传或是回传 ()

在 Rust 编程语言中,不回传数据的函数其实就是回传 () 这个类型的值。如果我们的路由处理程序不想要在 HTTP 回应中回传任何多余的数据,可以替路由处理程序定义不需回传数据或是回传值类型为 () 的函数。

例如:

#[delete("/resources")]
fn handler() {
    println!("Resources are deleted!");
}

或:

#[delete("/resources")]
fn handler() -> () {
    println!("Resources are deleted!");
}

如此一来,HTTP 回应中的标头字段只会有基本的六项:

  • Server:Rocket 框架预设会自动在每个 HTTP 回应中添加这个字段,并且将值设置为 Rocket。如果想要改写这个字段,可以借由设置 Rocket 框架来达成,这部份会在之后的章节说明。
  • Content-Length:一个 HTTP 回应中基本上都应该要有这个字段。这个字段的值为 HTTP 主体的数据大小,单位为字节(bytes)。如果 HTTP 主体没有数据,这个字段的值应被设为 0。
  • Date:这个字段的值为此 HTTP 回应在服务器上的创建时间,值的格式可参考 RFC 7231。
  • X-Content-Type-Options:Rocket 框架预设激活的 Shield 整流片(fairing)会自动在每个 HTTP 回应中添加这个字段,并且将值设置为 nosniff,让浏览器不要自行猜测回应数据的 MIME 类型。
  • X-Frame-Options:同样由 Shield 整流片添加,值为 SAMEORIGIN,只允许相同来源的网页用框架嵌入这个网页。
  • Permissions-Policy:同样由 Shield 整流片添加,值为 interest-cohort=(),用来禁用 FLoC 这个广告追踪功能。

回传 &'static str 或 &str

当一个函数回传值的类型为参考时,还记得《Rust 学习之路》系列文章中的泛型、特性和生命周期中介绍的编译器推论函数的参数和回传值的生命周期的规则吗?若要回传生命周期为 'static 的字符串切片,记得要在回传值类型中明确地把 'static 写出来。

例如:

#[get("/hello")]
fn handler() -> &'static str {
    "Hello!"
}

而如果是要回传可以被编译器直接推论出生命周期的参考,则函数的回传值类型可以省略不写生命周期。

例如:

use rocket::{
    http::Status,
    request::{FromRequest, Outcome, Request},
};

struct MyGuard<'a> {
    authorization: &'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();

        match authorization {
            Some(authorization) => Outcome::Success(MyGuard {
                authorization,
            }),
            None => Outcome::Forward(Status::Unauthorized),
        }
    }
}

#[get("/auth")]
fn handler(guard: MyGuard) -> &str {
    guard.authorization
}

当路由处理程序的函数是回传字符串切片时,HTTP 回应中的标头字段除了上面提到的六个基本字段外,还会多出 Content-Type 字段,且该字段的值会被设置为 text/plain; charset=utf-8,也就是以 UTF-8 编码的纯文字数据。所以,使用字符串切片是无法正常回传 HTML 网页的哦!

回传 String

例如:

#[get("/<name>")]
fn handler(name: String) -> String {
    name
}

当路由处理程序的函数是回传字符串时,HTTP 回应中的标头字段除了上面提到的六个基本字段外,还会多出 Content-Type 字段,且该字段的值会被设置为 text/plain; charset=utf-8,也就是以 UTF-8 编码的纯文字数据。所以,使用字符串也是无法正常回传 HTML 网页的哦!

回传 &'static [u8] 或 &[u8]

因为生命周期限制的缘故,路由处理程序的函数几乎不会回传 &[u8],所以这边就不示例了。不过如果是 &'static [u8],还是会有机会用到的。可以搭配 Rust 编程语言内置的 include_bytes 宏,使路由处理程序直接在 HTTP 回应的主体中提供某个文件的数据内容,且这个文件会在程序编译阶段时,也跟着被编进程式可执行文件中。

例如:

#[get("/file")]
fn handler() -> &'static [u8] {
    include_bytes!("/path/to/file")
}

如果您对单档运行有兴趣,可以延伸阅读这篇文章。

当路由处理程序的函数是回传 u8 数组切片时,HTTP 回应中的标头字段除了上面提到的六个基本字段外,还会多出 Content-Type 字段,且该字段的值会被设置为 application/octet-stream,也就是不知道是什么格式的数据串流啦!通常我们会对 u8 数组切片再包一层实作了 response::Responder 的类型,用来覆写 Content-Type 字段,甚至还会顺便添加更多标头字段(如缓存相关的字段)。

回传 Vec<u8>

例如:

use rand::RngCore;

#[get("/salt")]
fn handler() -> Vec<u8> {
    let mut result = vec![0u8; 16];

    rand::thread_rng().fill_bytes(&mut result);

    result
}

当路由处理程序的函数是回传 Vec<u8> 时,HTTP 回应中的标头字段除了上面提到的六个基本字段外,还会多出 Content-Type 字段,且该字段的值会被设置为 application/octet-stream,也就是不知道是什么格式的数据串流啦!通常我们会对 Vec<u8> 再包一层实作了 response::Responder 的类型,用来覆写 Content-Type 字段,甚至还会顺便添加更多标头字段(如缓存相关的字段)。

回传 File

例如:

use std::fs::File;
    
#[get("/file")]
fn handler() -> File {
    File::open("/path/to/file").unwrap()
}

当路由处理程序的函数是回传 File 时,HTTP 回应中的标头字段只会有上面提到的六个基本字段。

虽然 Rust 标准函数库的 File 结构体也可以直接被 Rocket 回应,但我们最好还是使用 Rocket 提供的异步 I/O 模块(rocket::tokio)来操作 I/O,避免阻塞(blocking)。例如以上程序改写成以下这样会更好:

use rocket::tokio::fs::File;

#[get("/file")]
async fn handler() -> File {
    File::open("/path/to/file").await.unwrap()
}

回传 response::content::*

当我们想要控制回传的 HTTP 回应的 Content-Type 标头字段时,可以使用 response::content 模块下的结构体来包裹要回传的数据。

结构体与 Content-Type 字段值的对应关系如下表:

结构体名称 Content-Type 字段值
RawCss text/css
RawHtml text/html
RawJavaScript text/javascript
RawJson application/json
RawMsgPack application/msgpack
RawText text/plain
RawXml text/xml

例如:

#[get("/")]
fn handler() -> RawHtml<&'static str> {
    RawHtml(
        r#"<html>
    <head>
        <meta charset=UTF-8>
        <title>My Website</title>
    </head>
    <body>
        Welcome!
    </body>
</html>"#,
    )
}

如果要使用上表没有的 Content-Type 字段值,或者想要回应浮动的 Content-Type 标头字段时,可以使用 http::ContentType 结构体再搭配我们原本要使用的 response::Responder 类型,用 (ContentType, Responder) 这样的方式将它们组合成元组,Rocket 框架会自动将其变成新的 response::Responder 类型。这样说可能还是很模糊,直接看以下例子比较快:

use rocket::http::ContentType;

#[get("/")]
fn handler() -> (ContentType, &'static [u8]) {
    (ContentType::PDF, include_bytes!("/path/to/file"))
}

http::ContentType 已经内置了许多常用扩展名的 MIME 类型。如果想要自行填入 MIME 类型的话,程序可以这样写:

use rocket::http::ContentType;

#[get("/")]
fn handler() -> (ContentType, &'static [u8]) {
    (ContentType::new("application", "x-person"), include_bytes!("../Cargo.toml"))
}

另外,http::ContentType 的参考类型,也就是 &http::ContentType,也可以当作请求守卫来用哦!用来取得 HTTP 请求的 Content-Type 标头字段。

回传 fs::NamedFile

如果我们想要让 Rocket 提供静态文件(如图片档、CSS、JS 等等的静态资源档),可以让路由处理程序的函数回传 fs::NamedFile。

例如:

use rocket::fs::NamedFile;
    
#[get("/file")]
async fn handler() -> NamedFile {
    NamedFile::open("/path/to/file").await.unwrap()
}

当路由处理程序的函数是回传 fs::NamedFile 时,HTTP 回应中的标头字段除了上面提到的六个基本字段外,还会自动加入 Content-Type 字段。这个 Content-Type 字段的值会根据 fs::NamedFile 打开的文件类型(依照文件扩展名)而自动作适当的变化。

如果想要提供文件系统中某个目录下的所有文件,可以让 fs::NamedFile 与区段守卫搭配使用。

例如:

use std::path::{Path, PathBuf};

use rocket::fs::NamedFile;

#[get("/file/<path..>")]
async fn handler(path: PathBuf) -> NamedFile {
    NamedFile::open(Path::new("static/").join(path)).await.unwrap()
}

不过,对于这方面的功能,Rocket 框架还有提供一种更好用的作法,会在以后的章节来介绍。

回传 response::stream::*

下面是一个说明在 Rocket 框架中,产生串流(stream)和读取串流的基本程序写法:

use rocket::{futures::stream::Stream, response::stream::stream};

fn f(stream: impl Stream<Item = u8>) -> impl Stream<Item = String> {
    stream! {
        for s in ["hi", "there"]{
            yield s.to_string();
        }

        for await n in stream {
            yield format!("n: {n}");
        }
    }
}

use rocket::futures::stream::{self, StreamExt};

let stream = f(stream::iter([3, 7, 11]));
let strings = stream.collect::<Vec<String>>().await;

assert_eq!(strings, ["hi", "there", "n: 3", "n: 7", "n: 11"]);

response::stream 有针对不同类型的数据提供不同的 response::Responder 类型,这边只介绍比较会用到的 response::stream::ReaderStream 结构体,它可以把某个甚至是多个有实作 AsyncRead 特性的类型的实体,直接当作 HTTP 回应主体的数据源。程序撰写方式如下:

use rocket::{response::stream::ReaderStream, tokio::fs::File};

#[get("/reader/stream")]
fn stream() -> ReaderStream![File] {
    ReaderStream! {
        for path in ["safe/path", "another/safe/path"] {
            if let Ok(file) = File::open(path).await {
                yield file;
            }
        }
    }
}

当路由处理程序的函数是回传 response::stream::ReaderStream 时,HTTP 回应中的标头字段中的六个基本字段,会缺少 Content-Length 这一项,因为 AsyncRead 特性只能让我们从头到尾读取某段数据,无法让我们在读取前事先得知接下来要读取的数据总大小。此外,标头字段中还会多出一个 Transfer-Encoding 字段,且字段的值会是 chunked。

回传 response::Redirect

response::Redirect 结构体可以实现客户端的转址(redirection)功能。它提供了以下几个关联函数:

  • moved:HTTP 回应的状态码为 301,属于永久性的转址。有些网页浏览器或是 HTTP 客户端对于 POST、PUT 或是 DELETE 等带有 HTTP 主体的请求方法,可能会无法自动再使用相同请求方法来重新发送 HTTP 主体,所以 Rocket 框架比较建议使用 permanent 关联函数。
  • found:HTTP 回应的状态码为 302,属于暂时性的转址。有些网页浏览器或是 HTTP 客户端对于 POST、PUT 或是 DELETE 等带有 HTTP 主体的请求方法,可能会无法自动再使用相同请求方法来重新发送 HTTP 主体,所以 Rocket 框架比较建议使用 temporary 或是 to 关联函数。
  • to:HTTP 回应的状态码为 303,属于暂时性的转址。永远使用 GET 请求方法来进行转址。
  • temporary:HTTP 回应的状态码为 307,属于暂时性的转址。永远使用与前次相同的 HTTP 请求方法来进行转址,可以正常重新发送 HTTP 主体。
  • permanent:HTTP 回应的状态码为 308,属于永久性的转址。永远使用与前次相同的 HTTP 请求方法来进行转址,可以正常重新发送 HTTP 主体。

这些关联方法可以传入一个可作为 Uri 使用的类型的值。虽然直接使用字符串或是字符串切片也是可以的,例如:

use rocket::response::Redirect;

#[get("/old?<id>")]
fn handler(id: i32) -> Redirect {
    Redirect::temporary(format!("/new?id={id}&from_old=true"))
}

#[get("/new?<id>&<from_old>")]
fn handler_new(id: i32, from_old: Option<bool>) -> String {
    let mut s =
        if from_old.unwrap_or(false) { String::from("Hi, old friend. ") } else { String::new() };

    use std::fmt::Write;

    s.write_fmt(format_args!("Your id is {id}.")).unwrap();

    s
}

但是 Rocket 既然号称要做到「类型安全」,网址的组成当然也要是安全的才行。所以 Rocket 框架还提供了一个有用的宏──uri!。

我们可以将以上程序用 uri! 宏改写如下:

use rocket::response::Redirect;

#[get("/old?<id>")]
fn handler(id: i32) -> Redirect {
    Redirect::temporary(uri!(handler_new(id = id, from_old = Some(true))))
}

#[get("/new?<id>&<from_old>")]
fn handler_new(id: i32, from_old: Option<bool>) -> String {
    let mut s =
        if from_old.unwrap_or(false) { String::from("Hi, old friend. ") } else { String::new() };

    use std::fmt::Write;

    s.write_fmt(format_args!("Your id is {id}.")).unwrap();

    s
}

uri! 宏可以在程序编译阶段,去检查要串接的 Uri 是否符合指定的路由处理程序所定义的匹配方式。如此一来就不用担心日后修改路由处理程序的 API 时,会忘记把原本连到旧 API 的网址也一并改过来而造成程序在运行阶段出错了!另外,网址查找字符串中,有些字段是可以省略的,如果要在 uri! 宏中省略某个可省略的网址查找字符串的字段,那就把该字段的值设置为 _ 吧!如下:

uri!(handler_new(id = id, from_old = _))

uri! 宏固然好用,只是比较可惜的是,uri! 宏只适用于串接出来的 Uri 是连到目前这个 Rocket 应用程序本身所能提供路由服务的某个路径(换句话说就是目前使用 Rocket 框架的程序项目中,已存在的路由处理程序)。如果是要连到其它的 Web 应用程序,或是外部网站的话,就不能使用 uri! 宏了。

可以在替我们的类型加上 FromForm 这一个 derive 属性的参数时,也顺便加上 UriDisplayQuery 参数。如此一来这个类型也能够直接使用在 uri! 宏中。

例如:

use rocket::response::Redirect;

#[derive(FromForm, UriDisplayQuery)]
struct User {
    id:    i32,
    name:  Option<String>,
    email: Option<String>,
}

#[get("/old?<user..>")]
fn handler(user: User) -> Redirect {
    Redirect::temporary(uri!(handler_new(from_old = Some(true), user = user)))
}

#[get("/new?<from_old>&<user..>")]
fn handler_new(from_old: Option<bool>, user: User) -> String {
    let mut s =
        if from_old.unwrap_or(false) { String::from("Hi, old friend. ") } else { String::new() };

    use std::fmt::Write;

    s.write_fmt(format_args!("Your id is {}.", user.id)).unwrap();

    s
}

此外,如果路由处理程序的注册路径不是 / 的话,可以在 uri! 宏的第一个参数中,插入指定的注册路径,例如:

uri!("/path", handler_new(id = id, from_old = _))

回传 response::status::* 或 http::Status

通常如果路由处理程序的函数不回传数据或是有正常回传数据的话,HTTP 回应的状态码会使用 200。如果要进行更改,可以利用 response::status 这个模块底下的结构体来包裹原本要回传的数据。

而 response::status 模块所提供的结构体有以下这些:

  • Created:HTTP 回应的状态码为 201。
  • Accepted:HTTP 回应的状态码为 202。
  • NoContent:HTTP 回应的状态码为 204。
  • BadRequest:HTTP 回应的状态码为 400。
  • Unauthorized:HTTP 回应的状态码为 401。
  • Forbidden:HTTP 回应的状态码为 403。
  • NotFound:HTTP 回应的状态码为 404。
  • Conflict:HTTP 回应的状态码为 409。
  • Custom:HTTP 回应的状态码根据传入的 http::Status 结构实体来决定。

例如:

use rocket::response::status;
    
#[get("/404")]
fn handler() -> status::NotFound<&'static str> {
    status::NotFound("Sorry, I couldn't find it!")
}

或是:

use rocket::{http::Status, response::status};

#[get("/404")]
fn handler() -> status::Custom<&'static str> {
    status::Custom(Status::NotFound, "Sorry, I couldn't find it!")
}

如果我们只想利用 HTTP 回应的状态码来提示 API 的调用结果,可以直接让路由处理程序的函数回传 http::Status 结构实体。

例如:

use rocket::http::Status;
    
#[get("/404")]
fn handler() -> Status {
    Status::NotFound
}

这边要注意的是,并不是每个 http::Status 结构实体都可以直接被路由处理程序的函数回传,有些有着必须与其它数据搭配才有特殊功用的实体(如 PartialContent、SeeOther 等),若直接拿来回传,就会使 Rocket 框架自动将这些变体改为 InternalServerError。

让路由处理程序的函数回传 http::Status 的作法,如果使用的变体是用来表示客户端或是服务器端的「错误」的话(例如 NotFound 或是 InternalServerError),就会触发 Rocket 框架的错误捕获者(Error Catcher)机制,而去使用 Rocket 在启动前就先设置好的错误捕获者,或是使用 Rocket 预设的错误处理方式,来协助处理 HTTP 回应。这部份会在之后的章节做详细介绍。

实作我们自己的 response::Responder 结构体

如果我们想要自由地修改回应的 HTTP 标头,就得创建一个专门的结构体为其实作 response::Responder 特性。

一个最基本的 response::Responder 特性的实作方式如下:

use rocket::{
    request::Request,
    response::{self, Responder, Response},
};

struct MyStruct;

impl<'r, 'o: 'r> Responder<'r, 'o> for MyStruct {
    fn respond_to(self, request: &'r Request<'_>) -> response::Result<'o> {
        let mut response = Response::build();

        // do something

        response.ok()
    }
}

response::Response 结构体所提供的 build 关联函数,可以在 respond_to 方法产生 response::Builder 结构实体,来手动设置要回传的 HTTP 回应中该放的标头字段和主体。最后再使用 response::Builder 结构实体提供的 ok 方法,来尝试创建出要回传的 response::Response 结构实体。

例如:

use rocket::{
    http::{ContentType, Status},
    request::Request,
    response::{self, Responder, Response},
    tokio::{fs::File, io::AsyncRead},
};

struct MyStruct<R> {
    reader: R,
}

impl<'r, 'o: 'r, R: AsyncRead + Send + 'o> Responder<'r, 'o> for MyStruct<R> {
    fn respond_to(self, _: &'r Request<'_>) -> response::Result<'o> {
        let mut response = Response::build();

        response
            .status(Status::Ok)
            .header(ContentType::Binary)
            .raw_header("Content-Disposition", "attachment")
            .streamed_body(self.reader);

        response.ok()
    }
}

#[get("/download/<id>")]
async fn handler(id: i32) -> MyStruct<File> {
    todo!("do something")
}

response::Builder 结构实体所提供的 sized_body 方法和 streamed_body 方法,都可以用来设置 HTTP 回应中的主体内的数据,传入的数据都必须要实作 AsyncRead 特性。我们也可以利用 Cursor 结构体来尝试将内存中的 u8 数组赋予 AsyncRead(和 AsyncSeek)特性,程序如下:

use std::io::Cursor;

use rocket::{
    http::{ContentType, Status},
    request::Request,
    response::{self, Responder, Response},
};

struct MyStruct {
    data: Vec<u8>,
}

impl<'r, 'o: 'r> Responder<'r, 'o> for MyStruct {
    fn respond_to(self, _: &'r Request<'_>) -> response::Result<'o> {
        let mut response = Response::build();

        response
            .status(Status::Ok)
            .header(ContentType::Binary)
            .raw_header("Content-Disposition", "attachment")
            .sized_body(self.data.len(), Cursor::new(self.data));

        response.ok()
    }
}

#[get("/download/<id>")]
async fn handler(id: i32) -> MyStruct {
    todo!("do something")
}

使用 Option 或是 Result 来包裹要回传的类型

路由处理程序的函数所回传的数据类型,可以使用 Option 或是 Result 来进行包裹。

若是使用 Option 来包裹,当回传的 Option 变体为 None 时,等同于回传了上面提过的 http::Status 的 NotFound 结构实体。

例如:

use std::path::{Path, PathBuf};

use rocket::fs::NamedFile;

#[get("/file/<path..>")]
async fn handler(path: PathBuf) -> Option<NamedFile> {
    NamedFile::open(Path::new("static/").join(path)).await.ok()
}

若是使用 Result 来包裹,Ok 或是 Err 变体所包裹的数据类型都必须是有实作 response::Responder 特性的类型。把 Result 当作路由处理程序的函数回传类型的功用,就像是将原先只有一种回传类型的函数变成两种(换句话说,原本这支 API 可以回传一种 HTTP 回应,加上 Result 来包裹后就可以将其扩充为两种)。

例如:

use std::path::{Path, PathBuf};

use rocket::{fs::NamedFile, response::status};

#[get("/file/<path..>")]
async fn handler(path: PathBuf) -> Result<NamedFile, status::NotFound<&'static str>> {
    NamedFile::open(Path::new("static/").join(path))
        .await
        .map_err(|_| status::NotFound("Cannot find this file."))
}

当然,我们也可以利用多层(嵌套)Result 来包裹要拿来回传的不同类型的数据,实现出能够回传多种 HTTP 回应的路由处理程序。

使用 #[derive(Responder)] 属性来快速实作我们的 response::Responder 结构

使用 #[derive(Responder)] 属性来实作 response::Responder 特性时,结构必须要有特定的字段顺序和类型。

直接看以下的代码:

use rocket::http::{Header, ContentType};

#[derive(Responder)]
#[response(status = 500, content_type = "json")]
struct MyResponder {
    inner: OtherResponder,
    // Override the Content-Type declared above.
    header: ContentType,
    more: Header<'static>,
    #[response(ignore)]
    unrelated: MyType,
}

以上程序,将回应的 HTTP 状态码设置为 500,且 Content-Type 设置为 application/json。在我们自订的结构中,第一个字段的类型必须要实作 response::Responder 特性,且必须要存在。而接下来的字段类型则必须要实作 Into<http::Header> 特性,其则不一定要存在,但可以有很多个。

利用枚举可以更灵活地做出不同的 HTTP 回应。如下:

use rocket::http::{ContentType, Header, Status};
use rocket::fs::NamedFile;

#[derive(Responder)]
enum Error {
    #[response(status = 500, content_type = "json")]
    A(String),
    #[response(status = 404)]
    B(NamedFile, ContentType),
    C {
        inner: (Status, Option<String>),
        header: ContentType,
    }
}

总结

在这个章节中,我们学会了路由处理程序的函数的回传值类型的用法。至目前为止,我们已经将一个 Web 框架所具备的基本功能(路由和回应 HTTP 请求)都学全了,但是我们还不知道如何配置 Rocket 应用程序,使其能够运作在正式的服务器环境中。所以下一章将会介绍 Rocket 的组态配置方式。

下一章:设置 Rocket 框架。