feat(axum-extra): support deserializing Vec<Enum> from repeated query parameters

[Zelys-DFKH]

Fixes #3696

Summary

This PR adds two new extractors to handle a real pain point: query strings with mixed enum variants. You can now write handlers that accept ?id=123&username=alice&id=456 and get back a properly-typed Vec<SearchFilter> with all the variants in order.

Problem

Axum's query parameter handling works great for flat structs. But if you need to accept different parameter names as different enum variants — like filtering by ID or username in the same request — you're stuck. serde_html_form doesn't support this pattern because it doesn't know that the parameter name should pick the enum variant.

Your options were: hand-parse the query string, build a custom extractor, or restructure the API. None of them are fun.

Solution

Two new extractors:

• QueryList<T> - Deserializes all query parameters into Vec<T>, where T is an enum. The parameter name becomes the variant discriminator.
• OptionalQueryList<T> - Same as QueryList, but returns an empty vec if there are no parameters (no error on missing data).

How it works

The trick is simple: for each query parameter pair, create a JSON object { variant_name: value } and let serde's enum deserializer do the work. Serde already knows how to pick the right enum variant from the object key. We just had to bridge the gap between query strings and JSON objects.

The implementation also handles value types correctly: id=123 deserializes as the number 123 (not the string "123"), and active=true becomes a boolean, just like you'd expect from JSON semantics.

Example

#[derive(Deserialize)]
#[serde(rename_all = "lowercase")]
enum SearchFilter {
    Id(u32),
    Username(String),
}

async fn search(QueryList(filters): QueryList<SearchFilter>) {
    for filter in filters {
        match filter {
            SearchFilter::Id(id) => println!("Filter by ID: {}", id),
            SearchFilter::Username(name) => println!("Filter by user: {}", name),
        }
    }
}

// GET /search?id=123&username=alice&id=456
// Receives: [Id(123), Username("alice"), Id(456)]

Testing

Nine tests cover the realistic cases:

• Alternating enum variants in any order
• The same variant repeated (e.g., ?id=1&id=2&id=3)
• Empty query strings
• Unknown variant names (400 Bad Request)
• Invalid values (type errors)
• Both sync and async extraction paths
• OptionalQueryList behavior with and without parameters

All existing tests pass. No breakage.

Changes

• axum-extra/src/extract/query.rs — Added QueryList<T>, OptionalQueryList<T>, the deserialize_pair helper, and rejection types
• axum-extra/src/extract/mod.rs — Exported the new types
• axum-extra/Cargo.toml — Added serde_json dependency for the "query" feature

Notes

• Reuses the existing FailedToDeserializeQueryString rejection type for consistency
• Follows the same patterns as Query/OptionalQuery so the API surface is familiar
• Works with any DeserializeOwned enum — full type safety
• Values parse as JSON types: id=123 is a number, active=true is a boolean, name=alice is a string

Natural fit for axum-extra's extraction toolkit. The approach is simple and delegates the hard work to serde, which already knows how to deserialize enums correctly.

[yanns]

Could you add some tests where the parameter values have special characters (like & or whitespace) that needs to be encoded / decoded.

[yanns]

In case we keep pairs, can we use Vec with capacity of the pairs to avoid allocations?

[yanns]

Do we need to create this temporary Vec or could we use iterator all way long?

[yanns]

Nitpick: this change is not necessary.

[Zelys-DFKH]

Thanks for catching that special character requirement! Added tests with URL-encoded whitespace and ampersand. Also fixed a couple of clippy warnings that showed up in the new run.