在开发 Web 应用程序的时候,我们常会需要透过 POST 请求来取得客户端上传的文件数据,这时候的 HTTP 主体通常就会使用 multipart/form-data 格式。然而,Rocket 框架虽有支持 multipart/form-data 的数据,但使用起来限制重重,不太方便。所以这篇文章会介绍一个替代方案来处理 multipart/form-data 的数据。

Multipart Form Data for Rocket Framework

「Multipart Form Data for Rocket Framework」是笔者开发的套件,能解析 Rocket 框架所接收到的 HTTP 请求(request)的主体(body)中,类型为 multipart/form-data 的数据,并将主体中指定字段的值分别保存到内存或是文件系统中。为了避免用户在 HTTP 主体中夹带过大或是错误的数据,这个套件还可以事先限制要解析的数据量以及类型(Content-Type)。

Crates.io

Cargo.toml

rocket-multipart-form-data = "*"

使用方法

rocket_multipart_form_data 这个 crate 提供了 MultipartFormDataOptions 和 MultipartFormDataField 这两个结构体,可以用来设置要读取 multipart/form-data 的数据中的哪些字段,并且可以针对该字段的数据大小和类型进行限制。

创建 MultipartFormDataOptions 和 MultipartFormDataField 的结构实体的方式很简单,程序如下:

use rocket_multipart_form_data::{mime, MultipartFormDataOptions, MultipartFormDataField, Repetition};

let mut options = MultipartFormDataOptions::with_multipart_form_data_fields(
    vec![
        MultipartFormDataField::file("photo").content_type_by_string(Some(mime::IMAGE_STAR)).unwrap(),
        MultipartFormDataField::raw("fingerprint").size_limit(4096),
        MultipartFormDataField::text("name"),
        MultipartFormDataField::text("email").repetition(Repetition::fixed(3)),
        MultipartFormDataField::text("email")
    ]
);

以上的 MultipartFormDataOptions 结构实体,可以用来将 multipart/form-data 的数据中的 photo 字段的数据读取到文件系统中,且限制其大小最多为 8MiB(此为保存到文件系统的数据大小上限的默认值),类型必须只能是图片。文件的保存的目录预设为操作系统的暂存目录,如果想要更改,可以设置 MultipartFormDataOptions 结构实体的 temporary_dir 字段。另外,以上的 MultipartFormDataOptions 结构实体也可以将 fingerprint 字段的数据读取到内存中,且限制其大小最多为 4KiB。也可以将 name 字段的数据读取到内存中,其必须可以被正常编码成 UTF-8,且限制其大小最多为 1MiB(此为保存到内存的数据大小上限的默认值)。同时,它也可以将一个 email 字段设置为重复读取多次同名字段(此处设为 3+1 次),形成数组结构,这四个同名字段的值必须可以被正常编码成 UTF-8,且个别的大小最多为 1MiB。

将 MultipartFormDataOptions 结构实体创建并设置完成之后,就可以用来创建同样由 rocket_multipart_form_data 这个 crate 提供的 MultipartFormData 结构体的实体。程序如下:

#[macro_use] extern crate rocket;

use rocket::Data;
use rocket::http::ContentType;

use rocket_multipart_form_data::{mime, MultipartFormDataOptions, MultipartFormData, MultipartFormDataField, Repetition};

#[post("/", data = "<data>")]
async fn index(content_type: &ContentType, data: Data<'_>) {
    let mut options = MultipartFormDataOptions::with_multipart_form_data_fields(
        vec! [
            MultipartFormDataField::file("photo").content_type_by_string(Some(mime::IMAGE_STAR)).unwrap(),
            MultipartFormDataField::raw("fingerprint").size_limit(4096),
            MultipartFormDataField::text("name"),
            MultipartFormDataField::text("email").repetition(Repetition::fixed(3)),
            MultipartFormDataField::text("email"),
        ]
    );

    let multipart_form_data = MultipartFormData::parse(content_type, data, options).await.unwrap();
}

在使用 MultipartFormData 结构体的 parse 关联函数来创建出 MultipartFormData 结构实体的同时,就会将 HTTP 主体中的数据解析完,此时被成功创建出来的 MultipartFormData 结构实体就是 multipart/form-data 数据的解析结果啦!

之后就是去读取 MultipartFormData 结构实体中的数据,来进行处理啦!程序如下:

...

let mut multipart_form_data = MultipartFormData::parse(content_type, data, options).await.unwrap();

let photo = multipart_form_data.files.get("photo"); // Use the get method to preserve file fields from moving out of the MultipartFormData instance in order to delete them automatically when the MultipartFormData instance is being dropped
let fingerprint = multipart_form_data.raw.remove("fingerprint"); // Use the remove method to move raw fields out of the MultipartFormData instance (recommended)
let name = multipart_form_data.texts.remove("name"); // Use the remove method to move text fields out of the MultipartFormData instance (recommended)
let email = multipart_form_data.texts.remove("email");

if let Some(file_fields) = photo {
    let file_field = &file_fields[0]; // Because we only put one "photo" field to the allowed_fields, the max length of this file_fields is 1.

    let _content_type = &file_field.content_type;
    let _file_name = &file_field.file_name;
    let _path = &file_field.path;

    // You can now deal with the uploaded file.
}

if let Some(mut raw_fields) = fingerprint {
    let raw_field = raw_fields.remove(0); // Because we only put one "fingerprint" field to the allowed_fields, the max length of this raw_fields is 1.

    let _content_type = raw_field.content_type;
    let _file_name = raw_field.file_name;
    let _raw = raw_field.raw;

    // You can now deal with the raw data.
}

if let Some(mut text_fields) = name {
    let text_field = text_fields.remove(0); // Because we only put one "text" field to the allowed_fields, the max length of this text_fields is 1.

    let _content_type = text_field.content_type;
    let _file_name = text_field.file_name;
    let _text = text_field.text;

    // You can now deal with the text data.
}

if let Some(text_fields) = email {
    for text_field in text_fields { // We put "email" field to the allowed_fields for two times and let the first time repeat for 3 times, so the max length of this text_fields is 4.
        let _content_type = text_field.content_type;
        let _file_name = text_field.file_name;
        let _text = text_field.text;

        // You can now deal with the text data.
    }
}