axum-bootstrap

基于 Axum 框架的 Rust Web 服务器脚手架，提供了开箱即用的 TLS、日志、监控等功能，帮助开发者快速搭建生产级别的 Web 服务。

✨ 特性

• 🚀 基于 Axum + Hyper：使用 Rust 最流行的异步 Web 框架
• 🔒 TLS/HTTPS 支持：内置 TLS 支持，基于 tokio-rustls
• 📝 多种日志方案：支持 tracing-subscriber、env_logger、flexi_logger
• 🎯 优雅关闭：支持 graceful shutdown，确保请求正常处理
• 🔑 JWT 认证：可选的 JWT 认证中间件
• 🌐 双栈监听：同时支持 IPv4 和 IPv6
• 🛡️ 错误处理：统一的错误处理机制
• 🔧 请求拦截器：可自定义请求拦截逻辑
• ⏱️ 超时控制：可配置的连接空闲超时

📦 安装

在 Cargo.toml 中添加依赖：

[dependencies]
axum-bootstrap = "0.1"

📚 示例程序

项目提供了两个完整的示例程序，展示了不同的使用场景：

1. 基础示例 (basic.rs)

基础的 HTTP/HTTPS 服务器示例，包含完整的中间件栈和常用功能：

主要功能：

• ✅ HTTP/HTTPS 支持
• ✅ MySQL 数据库集成（可选）
• ✅ Prometheus 指标收集
• ✅ CORS、压缩、超时控制
• ✅ 请求追踪和日志
• ✅ JSON 数据处理

运行方式：

# HTTP 模式
cargo run --example basic

# HTTPS 模式
cargo run --example basic -- --tls --cert cert.pem --key privkey.pem

# 启用 MySQL 支持
cargo run --example basic --features mysql

2. JWT 认证示例 (jwt.rs)

完整的 JWT 用户认证实现，包含登录、登出和受保护的 API：

主要功能：

• 🔐 JWT token 生成和验证
• 🍪 Cookie-based 会话管理
• 🔒 密码 bcrypt 哈希
• 🛡️ 受保护的 API 端点
• 📁 静态文件服务

API 端点：

• POST /api/login - 用户登录
• POST /api/logout - 用户登出
• GET /api/me - 获取当前用户信息（需认证）
• GET /health - 健康检查

运行方式：

# HTTP 模式
cargo run --example jwt --features jwt -- \
  --username admin \
  --password secret123

# HTTPS 模式
cargo run --example jwt --features jwt -- \
  --username admin \
  --password secret123 \
  --cert cert.pem \
  --key privkey.pem

💡 提示： 所有示例程序都包含详细的代码注释，可以直接查看源码了解实现细节。

功能特性（Features）

# 默认启用 tracing-subscriber 日志
axum-bootstrap = { version = "0.1", features = ["use_tracing_subscriber"] }

# 启用 JWT 认证功能
axum-bootstrap = { version = "0.1", features = ["jwt"] }

# 使用 env_logger
axum-bootstrap = { version = "0.1", features = ["use_env_logger"] }

# 使用 flexi_logger
axum-bootstrap = { version = "0.1", features = ["use_flexi_logger"] }

可用的 features：

• use_tracing_subscriber（默认）：使用 tracing-subscriber 进行日志记录
• use_env_logger：使用 env_logger 进行日志记录
• use_flexi_logger：使用 flexi_logger 进行日志记录
• jwt：启用 JWT 认证功能

工具函数

• util::format：地址格式化工具
• util::io：IO 相关工具，包括双栈监听器创建
• util::json：JSON 处理工具
• util::tls：TLS 配置工具

📖 API 文档

完整的 API 文档请访问 docs.rs

🛣️ 路线图

当前限制

• ⏳ HTTP/3 支持：等待 hyper 和 axum 上游支持
  • hyper HTTP/3 PR
  • axum HTTP/3 Issue

未来计划

• 更多中间件示例
• 性能监控和追踪
• 更完善的错误处理
• 数据库连接池管理
• WebSocket 支持示例

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📝 许可证

本项目采用 MIT OR Apache-2.0 双重许可。详见 LICENSE 文件。

🙏 致谢

本项目参考和学习了以下项目：

1. axum serve-with-hyper
2. axum hyper graceful shutdown
3. axum anyhow-error-response
4. axum error-handling

👤 作者

arloor - admin@arloor.com

项目主页：https://github.com/arloor/axum-bootstrap

⭐ Star History

如果这个项目对你有帮助，请给它一个 Star！