1 unstable release
0.1.1 | Dec 2, 2024 |
---|
#709 in Procedural macros
16KB
192 lines
register_actix_routes
- A Proc Macro for Dynamic Route Registration in Actix Web
register_routes
is a Rust proc macro library designed to simplify the registration of routes in an Actix Web application. It enables automatic grouping and configuration of routes, reducing boilerplate code while maintaining scalability and clarity in route management.
Features
-
Automatic Route Registration:
- Use
#[auto_register("/prefix")]
to annotate your handler functions and group them by scope.
- Use
-
Dynamic Service Configuration:
- Generate
register_service
functions that automatically configure routes under their respective scopes.
- Generate
-
Route Listing:
- Dynamically list all registered routes at runtime with
list_routes
.
- Dynamically list all registered routes at runtime with
-
Support for All HTTP Verbs:
- Works seamlessly with
#[get]
,#[post]
,#[put]
,#[delete]
, and#[patch]
.
- Works seamlessly with
-
Error Handling and Debugging:
- Provides detailed error messages if routes are misconfigured or missing attributes.
-
Customizable Tabled Output:
- Display all routes in a clean, tabular format using the
tabled
crate.
- Display all routes in a clean, tabular format using the
Installation
Add the register_routes
crate to your project:
[dependencies]
register_routes = "0.1.1"
tabled = "0.17.0" # Required for route listing
Usage
1. Annotate Handlers with #[auto_register]
Add #[auto_register("/scope")]
to your handler functions to group them by a shared prefix.
use actix_web::{get, web, Responder};
use register_routes::auto_register;
#[auto_register("/events")]
#[get("/search")]
pub async fn search() -> impl Responder {
"Search handler"
}
#[auto_register("/events")]
#[post("/create")]
pub async fn create() -> impl Responder {
"Create handler"
}
2. Generate register_service
Use the generate_register_service
macro to create a function that registers all handlers for a specific scope.
You'll need it at the end of your handlers file.
When integrating the configuration with an existing scope
use register_routes::generate_register_service;
generate_register_service!(["/events"]);
This will generate a register_service
function like:
pub fn register_service(cfg: &mut actix_web::web::ServiceConfig) {
cfg.service(
actix_web::web::scope("")
.service(search)
.service(create)
);
}
If you need the scope created with the path:
use register_routes::generate_register_service;
generate_register_service!(["/events", use_scope = true ]);
This will generate a register_service
function like:
pub fn register_service(cfg: &mut actix_web::web::ServiceConfig) {
cfg.service(
actix_web::web::scope("/events")
.service(search)
.service(create)
);
}
3. Configure Actix Web Application
Use the generated register_service
functions to configure your Actix Web app:
Here an example if you used use_scope = true to generate a scoped list of services
use actix_web::{App, HttpServer};
use crate::handlers::event_handler::register_service as register_event_handlers;
#[actix_web::main]
async fn main() -> std::io::Result<()> {
HttpServer::new(|| {
App::new()
.configure(register_event_handlers) // Register event handlers
})
.bind("127.0.0.1:8080")?
.run()
.await
}
4. List All Registered Routes
Use the generate_list_routes
macro to display all automatically registered routes in a tabular format.
use register_routes::generate_list_routes;
generate_list_routes!();
Call the list_routes
function at application startup:
fn main() {
list_routes();
}
This will print:
List of the automatically registered routes:
+--------------------+----------------+----------------+-------+
| Scope | Path | Handler | Verb |
+--------------------+----------------+----------------+-------+
| /events | /search | search | GET |
| /events | /create | create | POST |
+--------------------+----------------+----------------+-------+
Error Handling
The macros provide clear error messages for common mistakes:
- Missing HTTP Verb or Path: Ensure each handler has a valid Actix Web route macro (e.g.,
#[get("/path")]
). - Invalid Scope: The
auto_register
attribute requires a valid scope prefix (e.g.,#[auto_register("/events")]
).
Advanced Usage
Custom Middleware
You can wrap entire scopes with middleware while still using register_service
:
use actix_web::middleware::Logger;
HttpServer::new(|| {
App::new()
.wrap(Logger::default())
.configure(register_event_handlers)
})
Combine Scopes
You can use multiple register_service
functions to organize routes by feature:
use crate::handlers::{
event_handler::register_service as register_event_handlers,
booking_handler::register_service as register_booking_handlers,
};
HttpServer::new(|| {
App::new()
.configure(register_event_handlers)
.configure(register_booking_handlers)
})
Limitations
-
Actix-Specific:
- The macros rely on Actix Web’s routing macros and are not compatible with other frameworks.
-
Requires
tabled
:- The route listing feature depends on the
tabled
crate for pretty output.
- The route listing feature depends on the
Contributing
Contributions, issues, and feature requests are welcome! To contribute:
- Fork the repository.
- Create a new branch for your feature/bug fix.
- Submit a pull request with detailed information.
License
This project is licensed under the MIT License.
Enjoy clean and scalable route management in your Actix Web projects! 🚀 """
Dependencies
~3.5MB
~62K SLoC