From 4978248cc1faf8543f6ee558eb3e5c2f3b726260 Mon Sep 17 00:00:00 2001 From: zavakid Date: Fri, 13 Dec 2024 10:50:19 +0800 Subject: [PATCH] feat(web): add comprehensive documentation for extraction --- crates/web/src/extract/extract_body.rs | 38 +++++++++++++++++++ crates/web/src/extract/extract_header.rs | 47 ++++++++++++++++++++++++ crates/web/src/extract/extract_url.rs | 26 +++++++++++++ 3 files changed, 111 insertions(+) diff --git a/crates/web/src/extract/extract_body.rs b/crates/web/src/extract/extract_body.rs index e88c38f..cd489b5 100644 --- a/crates/web/src/extract/extract_body.rs +++ b/crates/web/src/extract/extract_body.rs @@ -1,3 +1,31 @@ +//! Body data extraction implementations +//! +//! This module provides implementations for extracting typed data from request bodies. +//! It supports extracting raw bytes, strings, JSON data and form data. +//! +//! # Examples +//! +//! ```no_run +//! # use micro_web::extract::{Json, Form}; +//! # use serde::Deserialize; +//! +//! #[derive(Deserialize)] +//! struct User { +//! name: String, +//! age: u32 +//! } +//! +//! // Extract JSON data +//! async fn handle_json(Json(user): Json) { +//! println!("Got user: {}", user.name); +//! } +//! +//! // Extract form data +//! async fn handle_form(Form(user): Form) { +//! println!("Got user: {}", user.name); +//! } +//! ``` + use crate::body::OptionReqBody; use crate::extract::{Form, FromRequest, Json}; use crate::RequestContext; @@ -7,6 +35,7 @@ use http_body_util::BodyExt; use micro_http::protocol::ParseError; use serde::Deserialize; +/// Extracts raw bytes from request body #[async_trait] impl FromRequest for Bytes { type Output<'any> = Bytes; @@ -17,6 +46,7 @@ impl FromRequest for Bytes { } } +/// Extracts UTF-8 string from request body #[async_trait] impl FromRequest for String { type Output<'any> = String; @@ -32,6 +62,10 @@ impl FromRequest for String { } } +/// Extracts form data from request body +/// +/// This implementation expects the request body to be URL-encoded form data +/// and deserializes it into the target type using `serde_urlencoded`. #[async_trait] impl FromRequest for Form where @@ -48,6 +82,10 @@ where } } +/// Extracts JSON data from request body +/// +/// This implementation expects the request body to be valid JSON +/// and deserializes it into the target type using `serde_json`. #[async_trait] impl FromRequest for Json where diff --git a/crates/web/src/extract/extract_header.rs b/crates/web/src/extract/extract_header.rs index d5c62f1..d312a88 100644 --- a/crates/web/src/extract/extract_header.rs +++ b/crates/web/src/extract/extract_header.rs @@ -1,3 +1,35 @@ +//! HTTP header extraction implementations +//! +//! This module provides extractors for HTTP header-related information from requests, +//! including HTTP methods, header maps and raw request headers. These extractors allow +//! handlers to directly access header information in a type-safe way. +//! +//! The extractors support both owned and borrowed access to the header data: +//! - Owned extractors like `Method` and `HeaderMap` take ownership of the data +//! - Borrowed extractors like `&Method` and `&HeaderMap` provide reference access +//! +//! # Examples +//! +//! ```no_run +//! use http::{HeaderMap, Method}; +//! +//! // Access HTTP method +//! async fn handle_method(method: Method) { +//! match method { +//! Method::GET => println!("Handling GET request"), +//! Method::POST => println!("Handling POST request"), +//! _ => println!("Handling other request method") +//! } +//! } +//! +//! // Access headers +//! async fn handle_headers(headers: &HeaderMap) { +//! if let Some(content_type) = headers.get("content-type") { +//! println!("Content-Type: {:?}", content_type); +//! } +//! } +//! ``` + use crate::body::OptionReqBody; use crate::extract::from_request::FromRequest; use crate::RequestContext; @@ -5,6 +37,9 @@ use async_trait::async_trait; use http::{HeaderMap, Method}; use micro_http::protocol::{ParseError, RequestHeader}; +/// Extracts the HTTP method by value +/// +/// This extractor takes ownership of the request method. #[async_trait] impl FromRequest for Method { type Output<'any> = Method; @@ -15,6 +50,9 @@ impl FromRequest for Method { } } +/// Extracts a reference to the HTTP method +/// +/// This extractor borrows the request method, avoiding cloning. #[async_trait] impl FromRequest for &Method { type Output<'r> = &'r Method; @@ -25,6 +63,9 @@ impl FromRequest for &Method { } } +/// Extracts a reference to the raw request header +/// +/// Provides access to the underlying HTTP request header structure. #[async_trait] impl FromRequest for &RequestHeader { type Output<'r> = &'r RequestHeader; @@ -35,6 +76,9 @@ impl FromRequest for &RequestHeader { } } +/// Extracts a reference to the header map +/// +/// This extractor provides borrowed access to all HTTP headers. #[async_trait] impl FromRequest for &HeaderMap { type Output<'r> = &'r HeaderMap; @@ -45,6 +89,9 @@ impl FromRequest for &HeaderMap { } } +/// Extracts the header map by value +/// +/// This extractor clones and takes ownership of all HTTP headers. #[async_trait] impl FromRequest for HeaderMap { type Output<'any> = HeaderMap; diff --git a/crates/web/src/extract/extract_url.rs b/crates/web/src/extract/extract_url.rs index ffe5cab..4b83f35 100644 --- a/crates/web/src/extract/extract_url.rs +++ b/crates/web/src/extract/extract_url.rs @@ -1,9 +1,35 @@ +//! URL query string extraction functionality +//! +//! This module provides implementation for extracting typed data from URL query strings. +//! It allows handlers to receive strongly-typed query parameters by implementing the +//! `FromRequest` trait for the `Query` type. +//! +//! # Example +//! ```no_run +//! # use serde::Deserialize; +//! # use micro_web::extract::Query; +//! +//! #[derive(Deserialize)] +//! struct Params { +//! name: String, +//! age: u32, +//! } +//! +//! async fn handler(Query(params): Query) { +//! println!("Name: {}, Age: {}", params.name, params.age); +//! } +//! ``` + use crate::extract::{FromRequest, Query}; use crate::{OptionReqBody, RequestContext}; use async_trait::async_trait; use micro_http::protocol::ParseError; use serde::Deserialize; +/// Implements query string extraction for any type that implements Deserialize +/// +/// This implementation allows automatic deserialization of query string parameters +/// into a strongly-typed struct using serde_qs. #[async_trait] impl FromRequest for Query where