rwf2
/
Rocket
mirror of https://github.com/rwf2/Rocket.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Clarify route ranking in requests guide. 

Closes #2687.
This commit is contained in:
Sergio Benitez 2024-01-17 10:52:00 -08:00
parent b3abc760ae
commit de6a4c50ec
1 changed files with 11 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
site/guide/4-requests.md
View File

@ -211,10 +211,11 @@ other matching routes to try. When there are no remaining routes, the [error
catcher](#error-catchers) associated with the status set by the last forwarding catcher](#error-catchers) associated with the status set by the last forwarding
guard is called. guard is called.
Routes are attempted in increasing _rank_ order. Rocket chooses a default Routes are attempted in increasing _rank_ order. Every route has an associated
ranking from -12 to -1, detailed in the next section, but a route's rank can also rank. If one is not specified, Rocket chooses a default rank designed to avoid
be manually set with the `rank` attribute. To illustrate, consider the following collisions based on a route's _color_, detailed in the [next
routes: section](#default-ranking), but a route's rank can also be manually set with the
`rank` attribute. To illustrate, consider the following routes:
```rust ```rust
# #[macro_use] extern crate rocket; # #[macro_use] extern crate rocket;
@ -272,17 +273,21 @@ parameter resolves this collision.
### Default Ranking ### Default Ranking
If a rank is not explicitly specified, Rocket assigns a default rank. The If a rank is not explicitly specified, Rocket assigns a default rank to a route.
Default ranks range from `-12` to `-1`. This differs from ranks that can be
assigned manually in a route attribute, which must be positive numbers. The
default rank prefers static segments over dynamic segments in both paths and default rank prefers static segments over dynamic segments in both paths and
queries: the _more_ static a route's path and query are, the higher its queries: the _more_ static a route's path and query are, the higher its
precedence. precedence.
There are three "colors" to paths and queries: There are three "colors" assignable to each path and query:
1. `static`, meaning all components are static 1. `static`, meaning all components are static
2. `partial`, meaning at least one component is dynamic 2. `partial`, meaning at least one component is dynamic
3. `wild`, meaning all components are dynamic 3. `wild`, meaning all components are dynamic
Additionally, a query may have _no_ color (`none`) if there is no query.
Static paths carry more weight than static queries. The same is true for partial Static paths carry more weight than static queries. The same is true for partial
and wild paths. This results in the following default ranking table: and wild paths. This results in the following default ranking table: