Document that Router::new().fallback(...) isn't optimal (#1940)

axum/CHANGELOG.md

@@ -9,8 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **fixed:** Don't allow extracting `MatchedPath` in fallbacks ([#1934])
 - **fixed:** Fix panic if `Router` with something nested at `/` was used as a fallback ([#1934])
+- **added:** Document that `Router::new().fallback(...)` isn't optimal ([#1940])
 
 [#1934]: https://github.com/tokio-rs/axum/pull/1934
+[#1940]: https://github.com/tokio-rs/axum/pull/1940
 
 # 0.6.15 (12. April, 2023)
 

axum/src/docs/routing/fallback.md

@@ -26,3 +26,38 @@ async fn fallback(uri: Uri) -> (StatusCode, String) {
 Fallbacks only apply to routes that aren't matched by anything in the
 router. If a handler is matched by a request but returns 404 the
 fallback is not called.
+
+# Handling all requests without other routes
+
+Using `Router::new().fallback(...)` to accept all request regardless of path or
+method, if you don't have other routes, isn't optimal:
+
+```rust
+use axum::Router;
+
+async fn handler() {}
+
+let app = Router::new().fallback(handler);
+
+# async {
+axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
+    .serve(app.into_make_service())
+    .await
+    .unwrap();
+# };
+```
+
+Running the handler directly is faster since it avoids the overhead of routing:
+
+```rust
+use axum::handler::HandlerWithoutStateExt;
+
+async fn handler() {}
+
+# async {
+axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
+    .serve(handler.into_make_service())
+    .await
+    .unwrap();
+# };
+```