mirror of
https://github.com/actix/actix-website
synced 2024-11-28 10:32:38 +01:00
128 lines
5.5 KiB
Markdown
128 lines
5.5 KiB
Markdown
---
|
|
title: Extractors
|
|
menu: docs_basics
|
|
weight: 170
|
|
---
|
|
|
|
# Type-safe information extraction
|
|
|
|
Actix-web provides a facility for type-safe request information access called *extractors*
|
|
(i.e., `impl FromRequest`). By default, actix-web provides several extractor implementations.
|
|
|
|
An extractor can be accessed as an argument to a handler function. Actix-web supports
|
|
up to 12 extractors per handler function. Argument position does not matter.
|
|
|
|
{{< include-example example="extractors" file="main.rs" section="option-one" >}}
|
|
|
|
# Path
|
|
|
|
[*Path*][pathstruct] provides information that can be extracted from the Request's
|
|
path. You can deserialize any variable segment from the path.
|
|
|
|
For instance, for resource that registered for the `/users/{user_id}/{friend}` path,
|
|
two segments could be deserialized, `user_id` and `friend`. These segments could be
|
|
extracted into a `tuple`, i.e. `Path<(u32, String)>` or any structure that implements
|
|
the `Deserialize` trait from the *serde* crate.
|
|
|
|
{{< include-example example="extractors" file="path_one.rs" section="path-one" >}}
|
|
|
|
It is also possible to extract path information to a specific type that implements the
|
|
`Deserialize` trait from *serde*. Here is an equivalent example that uses *serde*
|
|
instead of a *tuple* type.
|
|
|
|
{{< include-example example="extractors" file="path_two.rs" section="path-two" >}}
|
|
|
|
It is also possible to `get` or `query` the request for path parameters by name:
|
|
|
|
{{< include-example example="extractors" file="path_three.rs" section="path-three" >}}
|
|
|
|
# Query
|
|
|
|
The [*Query*][querystruct] type provides extraction functionality for the request's
|
|
query parameters. Underneath it uses *serde_urlencoded* crate.
|
|
|
|
{{< include-example example="extractors" file="query.rs" section="query" >}}
|
|
|
|
# Json
|
|
|
|
[*Json*][jsonstruct] allows deserialization of a request body into a struct. To extract
|
|
typed information from a request's body, the type `T` must implement the `Deserialize`
|
|
trait from *serde*.
|
|
|
|
{{< include-example example="extractors" file="json_one.rs" section="json-one" >}}
|
|
|
|
Some extractors provide a way to configure the extraction process. To configure
|
|
an extractor, pass its configuration object to the resource's `.data()` method.
|
|
In the case of *Json* extractor it returns a [*JsonConfig*][jsonconfig].
|
|
You can configure the maximum size of the JSON payload as
|
|
well as a custom error handler function.
|
|
|
|
The following example limits the size of the payload to 4kb and uses a custom error handler.
|
|
|
|
{{< include-example example="extractors" file="json_two.rs" section="json-two" >}}
|
|
|
|
# Form
|
|
|
|
At the moment, only url-encoded forms are supported. The url-encoded body could be
|
|
extracted to a specific type. This type must implement the `Deserialize` trait from
|
|
the *serde* crate.
|
|
|
|
[*FormConfig*][formconfig] allows configuring the extraction process.
|
|
|
|
{{< include-example example="extractors" file="form.rs" section="form" >}}
|
|
|
|
# Other
|
|
|
|
Actix-web also provides several other extractors:
|
|
|
|
* [*Data*][datastruct] - If you need access to an application state.
|
|
* *HttpRequest* - *HttpRequest* itself is an extractor which returns self, in case you
|
|
need access to the request.
|
|
* *String* - You can convert a request's payload to a *String*. [*Example*][stringexample]
|
|
is available in doc strings.
|
|
* *actix_web::web::Bytes* - You can convert a request's payload into *Bytes*.
|
|
[*Example*][bytesexample]
|
|
is available in doc strings.
|
|
* *Payload* - You can access a request's payload.
|
|
[*Example*][payloadexample]
|
|
|
|
# Application state extractor
|
|
|
|
Application state is accessible from the handler with the `web::Data` extractor;
|
|
however, state is accessible as a read-only reference. If you need mutable access to state,
|
|
it must be implemented.
|
|
|
|
> **Beware**, actix creates multiple copies of the application state and the handlers. It creates
|
|
> one copy for each thread.
|
|
|
|
Here is an example of a handler that stores the number of processed requests:
|
|
|
|
{{< include-example example="request-handlers" file="main.rs" section="data" >}}
|
|
|
|
Although this handler will work, `data.count` will only count the number of requests
|
|
handled *by each thread*. To count the number of total requests across all threads,
|
|
one should use `Arc` and [atomics][atomics].
|
|
|
|
{{< include-example example="request-handlers" file="handlers_arc.rs" section="arc" >}}
|
|
|
|
> **Note**, if you want the *entire* state to be shared across all threads, use
|
|
> `web::Data` and `app_data` as described in [Shared Mutable State][shared_mutable_state].
|
|
|
|
> Be careful with synchronization primitives like `Mutex` or `RwLock`. The `actix-web` framework
|
|
> handles requests asynchronously. By blocking thread execution, all concurrent
|
|
> request handling processes would block. If you need to share or update some state
|
|
> from multiple threads, consider using the tokio synchronization primitives.
|
|
|
|
[pathstruct]: https://docs.rs/actix-web/3/actix_web/dev/struct.Path.html
|
|
[querystruct]: https://docs.rs/actix-web/3/actix_web/web/struct.Query.html
|
|
[jsonstruct]: https://docs.rs/actix-web/3/actix_web/web/struct.Json.html
|
|
[jsonconfig]: https://docs.rs/actix-web/3/actix_web/web/struct.JsonConfig.html
|
|
[formconfig]: https://docs.rs/actix-web/3/actix_web/web/struct.FormConfig.html
|
|
[datastruct]: https://docs.rs/actix-web/3/actix_web/web/struct.Data.html
|
|
[stringexample]: https://docs.rs/actix-web/3/actix_web/trait.FromRequest.html#example-2
|
|
[bytesexample]: https://docs.rs/actix-web/3/actix_web/trait.FromRequest.html#example-4
|
|
[payloadexample]: https://docs.rs/actix-web/3/actix_web/web/struct.Payload.html
|
|
[actix]: https://actix.github.io/actix/actix/
|
|
[atomics]: https://doc.rust-lang.org/std/sync/atomic/
|
|
[shared_mutable_state]: ../application#shared-mutable-state
|