|
| 1 | +--- |
| 2 | +date: "2025-01-01" |
| 3 | +title: "Announcing axum 0.8.0" |
| 4 | +description: "January 01, 2025" |
| 5 | +--- |
| 6 | + |
| 7 | +Happy new year! 🎉 |
| 8 | + |
| 9 | +Today, we're happy to announce [`axum`] version 0.8. `axum` is an ergonomic |
| 10 | +and modular web framework built with [`tokio`], [`tower`], and [`hyper`]. |
| 11 | + |
| 12 | +This also includes new major versions of [`axum-core`], [`axum-extra`], and |
| 13 | +[`axum-macros`]. |
| 14 | + |
| 15 | +Here is a small selection of the most notable changes in this release: |
| 16 | + |
| 17 | +## Path parameter syntax changes |
| 18 | + |
| 19 | +The path parameter syntax has changed from `/:single` and `/*many` to |
| 20 | +`/{single}` and `/{*many}`. |
| 21 | + |
| 22 | +There are many reasons for this change, but the most important one is that the |
| 23 | +old syntax was not allowing route definitions with leading `:` or `*` |
| 24 | +characters. |
| 25 | + |
| 26 | +This new syntax was introduced with our upgrade to [`matchit`] 0.8. It should |
| 27 | +feel somewhat familiar from the `format!()` macro, and it's also the syntax |
| 28 | +that is being used in [OpenAPI] descriptions. Escaping is done with double |
| 29 | +braces, so if you want to match a literal `{` or `}` character, you can do so |
| 30 | +by writing `{{` or `}}`. |
| 31 | + |
| 32 | +We understand that this is a breaking change for basically all axum users, but |
| 33 | +we believe that it's better to make this change now than to have to do it later |
| 34 | +when even more users depend on the old syntax. The migration path should also |
| 35 | +be relatively straightforward, so we hope that this change won't cause too much |
| 36 | +trouble for you. |
| 37 | + |
| 38 | +You can find more information and migration examples in the corresponding |
| 39 | +[pull request](https://github.com/tokio-rs/axum/pull/2645). Thank you to |
| 40 | +[David Mládek](https://github.com/mladedav) for the implementation in `axum` |
| 41 | +and to [Ibraheem Ahmed](https://github.com/ibraheemdev/matchit) for your |
| 42 | +continued work on `matchit`. |
| 43 | + |
| 44 | +## `Option<T>` as an extractor |
| 45 | + |
| 46 | +The way `Option<T>` is used as an extractor has changed. Previously, any |
| 47 | +rejections from the `T` extractor were simply ignored and turned into `None`. |
| 48 | + |
| 49 | +Now, `Option<T>` as an extractor requires `T` to implement the new trait |
| 50 | +`OptionalFromRequestParts` (or `OptionalFromRequest`). |
| 51 | + |
| 52 | +This makes it possible to handle rejections from the `T` extractor and turn them |
| 53 | +into error responses, while still allowing extractors to be optional. |
| 54 | + |
| 55 | +Imagine you have an `AuthenticatedUser` extractor that requires a valid token |
| 56 | +to be present in the request, but in some cases authentication is optional. |
| 57 | +You can now use `Option<AuthenticatedUser>` as an extractor without losing the |
| 58 | +ability to return an error response if the token is invalid or the database |
| 59 | +connection failed. |
| 60 | + |
| 61 | +Thank you to [Jonas Platte](https://github.com/jplatte) for the |
| 62 | +[pull request](https://github.com/tokio-rs/axum/pull/2475) that introduced this |
| 63 | +new capability. |
| 64 | + |
| 65 | +## `#[async_trait]` removal |
| 66 | + |
| 67 | +In late 2023, the Rust team made it possible to use `impl Future<Output = _>` |
| 68 | +in traits. This feature is called [return-position `impl Trait` in traits](https://blog.rust-lang.org/2023/12/21/async-fn-rpit-in-traits.html). |
| 69 | +and means that we no longer need the `#[async_trait]` macro to define async |
| 70 | +methods in traits. |
| 71 | + |
| 72 | +This change primarily affects our `FromRequestParts` and `FromRequest` traits, |
| 73 | +since they use async methods. If you have custom extractors that implement these |
| 74 | +traits, you will need to remove the `#[async_trait]` annotation from them. |
| 75 | + |
| 76 | +This [change](https://github.com/tokio-rs/axum/pull/2308) was implemented by |
| 77 | +[Zheng Li](https://github.com/lz1998). Thank you for your contribution! |
| 78 | + |
| 79 | +## See the changelog for more |
| 80 | + |
| 81 | +There are many more changes in this release, including new features, bug fixes, |
| 82 | +and less visible breaking changes. We encourage you to read the [changelog] to |
| 83 | +see all the changes! |
| 84 | + |
| 85 | +Also, please [open a GitHub discussion] if you have trouble updating. You're |
| 86 | +also welcome to ask questions in [Discord]. |
| 87 | + |
| 88 | +<div style="text-align:right">— <a href="https://github.com/tokio-rs/axum/discussions/3099">the axum maintainers</a></div> |
| 89 | + |
| 90 | +[`axum`]: https://crates.io/crates/axum |
| 91 | +[`axum-core`]: https://crates.io/crates/axum-core |
| 92 | +[`axum-extra`]: https://crates.io/crates/axum-extra |
| 93 | +[`axum-macros`]: https://crates.io/crates/axum-macros |
| 94 | +[`tokio`]: https://crates.io/crates/tokio |
| 95 | +[`tower`]: https://crates.io/crates/tower |
| 96 | +[`hyper`]: https://crates.io/crates/hyper |
| 97 | +[`matchit`]: https://crates.io/crates/matchit |
| 98 | +[changelog]: https://github.com/tokio-rs/axum/blob/main/axum/CHANGELOG.md |
| 99 | +[Discord]: https://discord.gg/tokio |
| 100 | +[open a GitHub discussion]: https://github.com/tokio-rs/axum/discussions |
| 101 | +[OpenAPI]: https://www.openapis.org/ |
0 commit comments