A powerful parameter handling library for Axum web framework, inspired by Ruby on Rails' parameter system. Seamlessly handles multiple parameter sources and tree-structured data with file uploads.
-
Unified Parameter Handling
- Path parameters
- Query parameters
- Form data
- Multipart form data
- JSON body
- All parameter types can be processed simultaneously
- Every parameter type supports structured data (arrays and objects)
-
Rails-like Tree-Structured Parameters
- Nested parameter handling similar to Rails' strong parameters
- Support for deeply nested structures with arrays and objects
- Files can be placed at any position in the parameter tree, e.g.
post[attachments][][file]
- Seamlessly mix files with other data types in the same request
- Automatic parameter parsing and type conversion
- Handle complex forms with multiple file uploads in nested structures
Example structure:
post: {
title: String,
content: String,
tags: Vec<String>,
cover: UploadFile,
attachments: Vec<{
file: UploadFile,
description: String
}>
}
Add this to your Cargo.toml
:
[dependencies]
axum-params = "0.1"
use axum::{routing::post, Router};
use axum_params::Params;
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize)]
struct Attachment {
file: UploadFile,
description: String,
}
#[derive(Serialize, Deserialize)]
struct CreatePost {
title: String,
content: String,
tags: Vec<String>,
cover: UploadFile,
attachments: Vec<Attachment>,
}
#[debug_handler]
async fn create_post_handler(Params(post, _): Params<CreatePost>) -> impl IntoResponse {
// Handle cover file
let mut cover_file = post.cover.open().await.unwrap();
// process file
// Handle attachments
for attachment in post.attachments {
let mut file = attachment.file.open().await.unwrap();
// process file
}
}
Just like Rails, you can send nested parameters in various formats:
# Combining path parameters, query parameters, and form data
curl -X POST "http://localhost:3000/posts/123?draft=true" \
-F "post[title]=My First Post" \
-F "post[content]=Hello World from Axum" \
-F "post[tags][]=rust" \
-F "post[cover][email protected]"
# Sending JSON data (note: file uploads not possible in pure JSON)
curl -X POST http://localhost:3000/posts \
-H "Content-Type: application/json" \
-d '{
"post": {
"title": "My First Post",
"content": "Hello World from Axum",
"tags": ["rust", "web", "axum"]
}
}'
# Basic form data with nested parameters and file uploads
curl -X POST http://localhost:3000/posts \
-F "post[title]=My First Post" \
-F "post[content]=Hello World from Axum" \
-F "post[tags][]=rust" \
-F "post[tags][]=web" \
-F "post[tags][]=axum" \
-F "post[cover][email protected]" \
-F "post[attachments][][file][email protected]" \
-F "post[attachments][][description]=Project Documentation" \
-F "post[attachments][][file][email protected]" \
-F "post[attachments][][description]=Architecture Diagram"
The library automatically handles multipart form data, allowing you to upload files within nested structures. Files can be placed at any level in the parameter tree, and you can combine them with regular form fields.
# Complex multipart form matching the Post struct example
curl -X POST http://localhost:3000/posts \
-F "post[title]=My First Post" \
-F "post[content]=Hello World from Axum" \
-F "post[tags][]=rust" \
-F "post[tags][]=web" \
-F "post[tags][]=axum" \
-F "post[cover][email protected]" \
-F "post[attachments][][file][email protected]" \
-F "post[attachments][][description]=Project Documentation" \
-F "post[attachments][][file][email protected]" \
-F "post[attachments][][description]=Architecture Diagram" \
-F "post[attachments][][file][email protected]" \
-F "post[attachments][][description]=Application Screenshot"
This example demonstrates how the multipart form maps to the Rust struct:
- Single field (
title
,content
) - Array field (
tags[]
) - Single file field (
cover
) - Nested array with files (
attachments[]
withfile
anddescription
)
- Basic Parameters - Handling path, query, and JSON parameters
- File Upload - Basic file upload with metadata
- Nested Parameters - Complex nested structures with multiple file uploads
# Run basic parameters example
cargo run --example basic_params
# Run file upload example
cargo run --example file_upload
# Run nested parameters example
cargo run --example nested_params
Contributions are welcome! Please feel free to submit a Pull Request.
- The parameter parsing implementation is ported from Rack's QueryParser, which provides robust and battle-tested parameter parsing capabilities.
- This project draws inspiration from Ruby on Rails' parameter handling system, adapting its elegant approach to parameter processing for the Rust and Axum ecosystem.
This project is licensed under the MIT License - see the LICENSE file for details.