Rust HTTP请求处理库http-serde-ext的使用：增强serde的HTTP序列化与反序列化功能

简介

http-serde-ext提供了对http crate中类型的serde序列化和反序列化支持，包括：

• Response
• Request
• HeaderMap
• StatusCode
• Uri
• Method
• HeaderName
• HeaderValue
• uri::Authority
• uri::Scheme
• uri::PathAndQuery
• Version
• 通用的HeaderMap<T>(其中T不是HeaderValue)

还支持上述类型包装在以下std容器类型中：

• Option
• Result(Ok位置)
• Vec
• VecDeque
• LinkedList
• HashMap(作为Key，除了HeaderMap、Request和Response；作为Value支持所有类型)
• BTreeMap(作为Key仅支持HeaderValue、StatusCode和Version；作为Value支持所有类型)
• HashSet(除了HeaderMap、Request和Response)
• BTreeSet(仅支持HeaderValue、StatusCode和Version)

安装

在项目目录中运行以下Cargo命令：

cargo add http-serde-ext

或者在Cargo.toml中添加以下行：

http-serde-ext = "1.0.2"

使用示例

这个库旨在与serde的derive功能一起使用。字段应使用适当的#[serde(with = "...")]注解。以下是完整示例：

use std::collections::*;

use http::*;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(with = "http_serde_ext::response")]
    base: Response<Vec<u8>>,

    #[serde(with = "http_serde_ext::request::option", default)]
    option: Option<Request<String>>,

    #[serde(with = "http_serde_ext::method::vec")]
    vec: Vec<Method>,

    #[serde(with = "http_serde_ext::uri::vec_deque")]
    vec_deque: VecDeque<Uri>,

    #[serde(with = "http_serde_ext::header_map::linked_list")]
    linked_list: LinkedList<HeaderMap>,

    #[serde(with = "http_serde_ext::header_map_generic::hash_map")]
    hash_map: HashMap<String, HeaderMap<String>>,

    #[serde(with = "http_serde_ext::status_code::btree_map_key")]
    btree_map: BTreeMap<StatusCode, i32>,

    #[serde(with = "http_serde_ext::authority::hash_set")]
    hash_set: HashSet<uri::Authority>,
}

这个库也可以用于手动序列化/反序列化类型，例如使用serde_json时：

let uri = http::Uri::default();
let serialized = http_serde_ext::uri::serialize(&uri, serde_json::value::Serializer).unwrap();
let deserialized = http_serde_ext::uri::deserialize(serialized).unwrap();
assert_eq!(uri, deserialized);

let mut responses: Vec<http::Response<()>> = vec![http::Response::default()];
let serialized =
    http_serde_ext::response::vec::serialize(&responses, serde_json::value::Serializer)
        .unwrap();
let mut deserialized: Vec<http::Response<()>> =
    http_serde_ext::response::vec::deserialize(serialized).unwrap();

let original = responses.remove(0).into_parts();
let deserialized = deserialized.remove(0).into_parts();

assert_eq!(original.0.status, deserialized.0.status);
assert_eq!(original.0.version, deserialized.0.version);
assert_eq(original.0.headers, deserialized.0.headers);
assert_eq!(original.1, deserialized.1);

完整示例代码

use std::collections::{BTreeMap, HashMap, HashSet, LinkedList, VecDeque};
use http::{HeaderMap, Method, Request, Response, StatusCode, Uri};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct ApiResponse {
    #[serde(with = "http_serde_ext::response")]
    response: Response<String>,
    
    #[serde(with = "http_serde_ext::status_code::btree_map_key")]
    status_codes: BTreeMap<StatusCode, &'static str>,
    
    #[serde(with = "http_serde_ext::uri::vec_deque")]
    endpoints: VecDeque<Uri>,
}

fn main() {
    // 创建一个响应示例
    let response = Response::builder()
        .status(StatusCode::OK)
        .header("Content-Type", "application/json")
        .body("{\"message\":\"Hello, World!\"}".to_string())
        .unwrap();

    // 创建状态码映射
    let mut status_codes = BTreeMap::new();
    status_codes.insert(StatusCode::OK, "OK");
    status_codes.insert(StatusCode::NOT_FOUND, "Not Found");
    
    // 创建端点列表
    let mut endpoints = VecDeque::new();
    endpoints.push_back("/api/v1/users".parse().unwrap());
    endpoints.push_back("/api/v1/products".parse().unwrap());

    // 构建我们的结构体
    let api_response = ApiResponse {
        response,
        status_codes,
        endpoints,
    };

    // 序列化为JSON
    let json = serde_json::to_string(&api_response).unwrap();
    println!("Serialized JSON:\n{}", json);

    // 反序列化
    let deserialized: ApiResponse = serde_json::from_str(&json).unwrap();
    println!("Deserialized response status: {}", deserialized.response.status());
}

完整示例demo

下面是一个更完整的示例，展示如何使用http-serde-ext处理HTTP请求和响应：

use std::collections::{BTreeMap, HashMap};
use http::{header, HeaderMap, Method, Request, Response, StatusCode, Uri};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct ApiRequest {
    #[serde(with = "http_serde_ext::request")]
    request: Request<String>,
    
    #[serde(with = "http_serde_ext::header_map::hash_map")]
    custom_headers: HashMap<String, HeaderMap<String>>,
}

#[derive(Debug, Serialize, Deserialize)]
struct ApiResponse {
    #[serde(with = "http_serde_ext::response")]
    response: Response<String>,
    
    #[serde(with = "http_serde_ext::status_code::btree_map_key")]
    status_mapping: BTreeMap<StatusCode, String>,
}

fn main() {
    // 创建请求示例
    let request = Request::builder()
        .method(Method::POST)
        .uri("/api/v1/data")
        .header("Authorization", "Bearer token")
        .body("{\"data\":\"test\"}".to_string())
        .unwrap();

    // 创建自定义头映射
    let mut custom_headers = HashMap::new();
    let mut headers1 = HeaderMap::new();
    headers1.insert("X-Custom-1", "Value1".parse().unwrap());
    custom_headers.insert("req1".to_string(), headers1);

    // 构建请求结构体
    let api_request = ApiRequest {
        request,
        custom_headers,
    };

    // 序列化请求
    let request_json = serde_json::to_string(&api_request).unwrap();
    println!("Serialized Request:\n{}", request_json);

    // 创建响应示例
    let response = Response::builder()
        .status(StatusCode::CREATED)
        .header("Content-Type", "application/json")
        .header("X-Rate-Limit", "100")
        .body("{\"id\":123}".to_string())
        .unwrap();

    // 创建状态码映射
    let mut status_mapping = BTreeMap::new();
    status_mapping.insert(StatusCode::OK, "Success".to_string());
    status_mapping.insert(StatusCode::CREATED, "Created".to_string());

    // 构建响应结构体
    let api_response = ApiResponse {
        response,
        status_mapping,
    };

    // 序列化响应
    let response_json = serde_json::to_string(&api_response).unwrap();
    println!("Serialized Response:\n{}", response_json);

    // 反序列化请求
    let deserialized_request: ApiRequest = serde_json::from_str(&request_json).unwrap();
    println!(
        "Deserialized Request Method: {}",
        deserialized_request.request.method()
    );

    // 反序列化响应
    let deserialized_response: ApiResponse = serde_json::from_str(&response_json).unwrap();
    println!(
        "Deserialized Response Status: {}",
        deserialized_response.response.status()
    );
}

致谢

这个crate很大程度上受到Kornel的http-serde的启发。