111 lines
2.8 KiB
Markdown
111 lines
2.8 KiB
Markdown
# Axum Web Service Template
|
|
|
|
A production-ready template for building web services with Rust and Axum.
|
|
|
|
## Features
|
|
|
|
- 🚀 **Axum** - Fast and ergonomic web framework
|
|
- ⚙️ **Configuration Management** - Environment-based config with `figment`
|
|
- 📝 **Structured Logging** - JSON logging in production with `tracing`
|
|
- 🔄 **Graceful Shutdown** - Handles SIGTERM and SIGINT signals
|
|
- 🏗️ **Plugin Architecture** - Modular app initialization with `axum-app-wrapper`
|
|
- 🔌 **Optional OpenAPI** - API documentation with `aide` (optional)
|
|
|
|
## Usage
|
|
|
|
### Using cargo-generate
|
|
|
|
Install cargo-generate if you haven't already:
|
|
|
|
```bash
|
|
cargo install cargo-generate
|
|
```
|
|
|
|
Generate a new project from this template:
|
|
|
|
```bash
|
|
cargo generate --git <your-template-repo-url>
|
|
```
|
|
|
|
You'll be prompted for:
|
|
- **Project name**: The name of your new project
|
|
- **Project description**: A brief description
|
|
- **Environment variable prefix**: Prefix for env vars (e.g., `APP` for `APP_HOST`, `APP_PORT`)
|
|
- **Default port**: The server's default port
|
|
- **Default log level**: trace, debug, info, warn, or error
|
|
- **Include aide**: Whether to include OpenAPI documentation support
|
|
|
|
### Manual Setup
|
|
|
|
1. Clone or download this repository
|
|
2. Update `Cargo.toml` with your project name and details
|
|
3. Copy `.env.example` to `.env` and configure your environment variables
|
|
4. Run `cargo build`
|
|
|
|
## Configuration
|
|
|
|
Configuration is loaded from environment variables. The prefix is configurable during template generation.
|
|
|
|
Example with `APP` prefix:
|
|
|
|
```bash
|
|
# Required
|
|
APP_API_KEY=your-secret-key
|
|
|
|
# Optional (defaults shown)
|
|
APP_HOST=127.0.0.1
|
|
APP_PORT=8080
|
|
APP_LOG_LEVEL=info
|
|
```
|
|
|
|
In development, you can use a `.env` file (copy from `.env.example`).
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── src/
|
|
│ ├── main.rs # Entry point, server setup
|
|
│ ├── lib.rs # App initialization
|
|
│ ├── config.rs # Configuration management
|
|
│ └── state.rs # Application state
|
|
├── Cargo.toml # Dependencies
|
|
└── .env.example # Example environment variables
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Run in development mode (loads .env file)
|
|
cargo run
|
|
|
|
# Run with custom log level
|
|
RUST_LOG=debug cargo run
|
|
|
|
# Build for production
|
|
cargo build --release
|
|
```
|
|
|
|
## Adding Routes
|
|
|
|
This template uses `axum-app-wrapper` for modular initialization. To add routes:
|
|
|
|
1. Create a new plugin in a separate module
|
|
2. Register it in `lib.rs`:
|
|
|
|
```rust
|
|
pub async fn create_app() -> anyhow::Result<(axum::Router, AppConfig, impl Future + Send)> {
|
|
let (router, state, on_shutdown) = App::new()
|
|
.register(config::plugin())
|
|
.register(your_routes::plugin()) // Add your plugin here
|
|
.init()
|
|
.await?;
|
|
|
|
let app_config = state.config.to_owned();
|
|
Ok((router.with_state(state), app_config, on_shutdown))
|
|
}
|
|
```
|
|
|
|
## License
|
|
|
|
Configure your license as needed. |