mirror of
https://github.com/actix/actix-website
synced 2024-11-24 08:43:01 +01:00
140 lines
5.8 KiB
Markdown
140 lines
5.8 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*
|
|
(ie, `impl FromRequest`). By default, actix-web provides several extractor implementations.
|
|
|
|
## Extractors Within Handler Functions
|
|
|
|
An extractor can be accessed in a few different ways.
|
|
|
|
Option 1 - passed as a parameter to a handler function:
|
|
|
|
{{< include-example example="extractors" file="main.rs" section="option-one" >}}
|
|
|
|
Option 2 - accessed by calling `extract()` on the Extractor
|
|
|
|
{{< include-example example="extractors" file="main.rs" section="option-two" >}}
|
|
|
|
# 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/{userid}/{friend}` path
|
|
two segments could be deserialized, `userid` 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 to deserialize 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. Json extractor
|
|
[*JsonConfig*][jsonconfig] type for configuration. To configure an extractor, pass it's
|
|
configuration object to the resource's `.data()` method. In case of a *Json* extractor
|
|
it returns a *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" >}}
|
|
|
|
# Multiple extractors
|
|
|
|
Actix-web provides extractor implementations for tuples (up to 10 elements) whose
|
|
elements implement `FromRequest`.
|
|
|
|
For example we can use a path extractor and a query extractor at the same time.
|
|
|
|
{{< include-example example="extractors" file="multiple.rs" section="multi" >}}
|
|
|
|
# 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.
|
|
* *bytes::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]
|
|
|
|
# Async Data Access
|
|
|
|
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,
|
|
> unique for each thread. If you run your application in several threads, actix will
|
|
> create the same amount as number of threads of application state objects and handler
|
|
> objects.
|
|
|
|
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, `self.0` will be different depending on the number of threads and
|
|
number of requests processed per thread. A proper implementation would use `Arc` and `AtomicUsize`.
|
|
|
|
{{< include-example example="request-handlers" file="handlers_arc.rs" section="arc" >}}
|
|
|
|
> 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 [actix][actix] actor system.
|
|
|
|
[pathstruct]: https://docs.rs/actix-web/2/actix_web/dev/struct.Path.html
|
|
[querystruct]: https://docs.rs/actix-web/2/actix_web/web/struct.Query.html
|
|
[jsonstruct]: https://docs.rs/actix-web/2/actix_web/web/struct.Json.html
|
|
[jsonconfig]: https://docs.rs/actix-web/2/actix_web/web/struct.JsonConfig.html
|
|
[formconfig]: https://docs.rs/actix-web/2/actix_web/web/struct.FormConfig.html
|
|
[datastruct]: https://docs.rs/actix-web/2/actix_web/web/struct.Data.html
|
|
[stringexample]: https://docs.rs/actix-web/2/actix_web/trait.FromRequest.html#example-2
|
|
[bytesexample]: https://docs.rs/actix-web/2/actix_web/trait.FromRequest.html#example-4
|
|
[payloadexample]: https://docs.rs/actix-web/2/actix_web/web/struct.Payload.html
|
|
[actix]: https://actix.github.io/actix/actix/
|