From b11a2f6e99482f072465e04fe8f9e84c85009a76 Mon Sep 17 00:00:00 2001 From: Rob Ede Date: Thu, 7 Apr 2022 15:54:55 +0100 Subject: [PATCH] improve path docs --- .vscode/settings.json | 3 ++- content/docs/extractors.md | 10 +++++----- examples/extractors/src/path_one.rs | 4 +--- examples/extractors/src/path_three.rs | 6 +++--- 4 files changed, 11 insertions(+), 12 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 2cae3c9..ad4a01b 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,6 +1,7 @@ { "cSpell.words": [ "actix", - "rustls" + "rustls", + "serde" ] } diff --git a/content/docs/extractors.md b/content/docs/extractors.md index a8b7fcc..10a9e58 100644 --- a/content/docs/extractors.md +++ b/content/docs/extractors.md @@ -6,7 +6,7 @@ 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. +Actix Web provides a facility for type-safe request information access called _extractors_ (i.e., `impl FromRequest`). There are lots of built-in extractor implementations (see [implementors](https://actix.rs/actix-web/actix_web/trait.FromRequest.html#implementors)). 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. @@ -14,17 +14,17 @@ An extractor can be accessed as an argument to a handler function. Actix Web sup # Path -[_Path_][pathstruct] provides information that can be extracted from the Request's path. You can deserialize any variable segment from the path. +[_Path_][pathstruct] provides information that is extracted from the request's path. Parts of the path that are extractable are called "dynamic segments" and are marked with curly braces. 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. +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 as a tuple in the order they are declared (e.g., `Path<(u32, String)>`). {{< 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. +It is also possible to extract path information to a type that implements the `Deserialize` trait from `serde` by matching dynamic segment names with field names. 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: +As a non-type-safe alternative, it's also possible to `query` the request for path parameters by name within a handler: {{< include-example example="extractors" file="path_three.rs" section="path-three" >}} diff --git a/examples/extractors/src/path_one.rs b/examples/extractors/src/path_one.rs index c45acae..e415628 100644 --- a/examples/extractors/src/path_one.rs +++ b/examples/extractors/src/path_one.rs @@ -1,5 +1,5 @@ // -use actix_web::{get, web, Result}; +use actix_web::{get, web, App, HttpServer, Result}; /// extract path info from "/users/{user_id}/{friend}" url /// {user_id} - deserializes to a u32 @@ -12,8 +12,6 @@ async fn index(path: web::Path<(u32, String)>) -> Result { #[actix_web::main] async fn main() -> std::io::Result<()> { - use actix_web::{App, HttpServer}; - HttpServer::new(|| App::new().service(index)) .bind(("127.0.0.1", 8080))? .run() diff --git a/examples/extractors/src/path_three.rs b/examples/extractors/src/path_three.rs index 7f12824..b2ba374 100644 --- a/examples/extractors/src/path_three.rs +++ b/examples/extractors/src/path_three.rs @@ -1,12 +1,12 @@ use actix_web::{get, HttpRequest, Result}; // -#[get("/users/{userid}/{friend}")] // <- define path parameters +#[get("/users/{user_id}/{friend}")] // <- define path parameters async fn index(req: HttpRequest) -> Result { let name: String = req.match_info().get("friend").unwrap().parse().unwrap(); - let userid: i32 = req.match_info().query("userid").parse().unwrap(); + let userid: i32 = req.match_info().query("user_id").parse().unwrap(); - Ok(format!("Welcome {}, userid {}!", name, userid)) + Ok(format!("Welcome {}, user_id {}!", name, userid)) } #[actix_web::main]