Rocket Derive

courier 是一个用于 Rocket 框架的工具库，它允许您为您自定义类型派生 FromData 和 Responder。以下是一个使用 courier 来处理客户端发送和接收自定义数据的示例

#![feature(plugin)]
#![plugin(rocket_codegen)]

extern crate rocket;
#[macro_use]
extern crate courier;
extern crate serde;
#[macro_use]
extern crate serde_derive;
extern crate serde_json;

#[derive(Deserialize, FromData)]
pub struct CustomRequest {
    pub foo: String,
    pub bar: usize,
}

#[derive(Serialize, Responder)]
pub struct CustomResponse {
    pub baz: usize,
}

#[post("/endpoint", data = "<request>")]
pub fn handle_request(request: CustomRequest) -> CustomResponse {
    if request.foo == "foo" {
        CustomResponse { baz: 0 }
    } else {
        CustomResponse { baz: request.bar }
    }
}

在这个示例中，响应的编码方式与请求相同，例如，如果客户端将请求体作为JSON发送，则响应将以JSON发送。

用法

将 courier 以及相关的Serde库添加到您的 Cargo.toml 文件中

[dependencies]
courier = "0.3.1"
serde = "1.0"
serde_derive = "1.0"
serde_json = "1.0"

将库导入到您的项目中

#[macro_use]
extern crate courier;

extern crate serde;
#[macro_use]
extern crate serde_derive;
extern crate serde_json;

请注意，您必须在 extern crate 语句上添加 #[macro_use] 属性才能使用此库的功能。

现在，您可以为您的自定义类型使用 #[derive(FromData)] 和 #[derive(Responder)]。

支持的格式

courier 支持以多种格式接收请求体和发送响应体。对于您想要启用的每一种格式，您都需要在您的 Cargo.toml 中启用一个功能，并将相关的 Serde 包添加到您的项目中。以下表格显示了当前支持哪些格式、该格式的功能名称以及您需要包含哪些 Serde 包。

默认情况下，仅启用 JSON 支持。例如，如果您想添加 MessagePack 支持，则需要编辑您的 Cargo.toml 以启用 msgpack 功能，并将 rmp-serde 作为依赖项添加

[dependencies]
rmp-serde = "0.13.6"
serde = "1.0"
serde_derive = "1.0"
serde_json = "1.0"

[dependencies.courier]
version = "0.3.1"
features = ["msgpack"]

然后将 rmp-serde 添加到项目根目录

#[macro_use]
extern crate courier;

extern crate rmp_serde;
extern crate serde;
#[macro_use]
extern crate serde_derive;
extern crate serde_json;

注意，为了也支持 JSON，您仍然需要将 serde_json 作为依赖项包含在内。如果您不想支持 JSON，您可以在您的 Cargo.toml 中指定 default-features = false

[dependencies.courier]
version = "0.3.1"
default-features = false
features = ["msgpack"]

使用多种格式

当同时启用多种格式时，请求中的 Content-Type 标头用于确定请求数据所在的格式，而 Accept 标头用于确定响应应使用哪种格式。

虽然这主要消除了对 rocket_contrib::Json（和类似类型）的需求，但仍然可以使用它来覆盖由 courier 定义的默认行为。例如，假设您为您的 Rocket 路由指定了格式

#[post("/endpoint", format = "application/json", data = "<request>")]
pub fn handle_request(request: CustomRequest) -> CustomResponse {
    if request.foo == "foo" {
        CustomResponse { baz: 0 }
    } else {
        CustomResponse { baz: request.bar }
    }
}

在这种情况下，Rocket 将在将请求路由到 handle_request 之前检查内容类型，然后 CustomRequest 的 FromData 实现将再次检查它。如果不希望这样，您可以使用 rocket_contrib::Json 来跳过第二次检查

use rocket_contrib::Json;

#[post("/endpoint", format = "application/json", data = "<request>")]
pub fn handle_request(request: Json<CustomRequest>) -> Json<CustomResponse> {
    if request.foo == "foo" {
        Json(CustomResponse { baz: 0 })
    } else {
        Json(CustomResponse { baz: request.bar })
    }
}

但是，建议如果使用 courier，不要显式指定路由的 format 参数。由 courier 生成的代码允许您编写与内容类型无关的路由处理器，因此手动指定期望的格式是不必要的。