fbc-starter

一个基于 Rust 和 Axum 的生产级 Web 服务器启动器，提供了开箱即用的基础功能和最佳实践。

✨ 功能特性

• ✅ Web 框架: 基于 Axum 的高性能异步 Web 框架
• ✅ 配置管理: 使用 .env 文件和环境变量进行配置（支持 dotenvy）
• ✅ 日志系统: 集成 tracing 和 tracing-subscriber，支持结构化日志，默认 UTC+8 时区
• ✅ CORS 支持: 可配置的跨域资源共享
• ✅ 请求压缩: 自动 Gzip 压缩响应
• ✅ 健康检查: 提供符合 Prometheus 标准的 /health 端点
• ✅ 优雅关闭: 支持 Ctrl+C 和 SIGTERM 信号
• ✅ 错误处理: 统一的错误处理机制
• ✅ 中间件: 请求追踪、日志记录等
• ✅ 路由扩展: 支持 Controller 风格和函数式路由组织
• ✅ 可选特性: 数据库（PostgreSQL/MySQL/SQLite）和 Redis 缓存支持
• ✅ 上下文路径: 支持可配置的服务上下文路径

🚀 快速开始

安装

在 Cargo.toml 中添加：

[dependencies]
fbc-starter = "0.1.0"

基础使用

use fbc_starter::start;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    start().await
}

添加自定义路由

use fbc_starter::start_with_routes;
use axum::{routing::get, Router};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_routes = Router::new()
        .route("/api/users", get(get_users));

    start_with_routes(Some(api_routes)).await?;
    Ok(())
}

async fn get_users() -> &'static str {
    "users"
}

Controller 风格路由

use fbc_starter::{start_with_routes, routing::{registry, RouteGroup}};
use axum::{routing::get, Router};

struct UserController;

impl RouteGroup for UserController {
    fn routes(&self) -> Router {
        Router::new()
            .route("/", get(list_users))
            .route("/:id", get(get_user))
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_routes = registry()
        .nest_group("/api/users", UserController)
        .build();

    start_with_routes(Some(api_routes)).await?;
    Ok(())
}

📖 配置

环境变量

创建 .env 文件：

# 服务器配置
APP__SERVER__ADDR=0.0.0.0
APP__SERVER__PORT=3000
APP__SERVER__CONTEXT_PATH=/api  # 可选，服务上下文路径

# 日志配置
APP__LOG__LEVEL=info
APP__LOG__JSON=false

# CORS 配置
APP__CORS__ALLOWED_ORIGINS=*
APP__CORS__ALLOWED_METHODS=GET,POST,PUT,DELETE,PATCH,OPTIONS
APP__CORS__ALLOWED_HEADERS=*
APP__CORS__ALLOW_CREDENTIALS=false

# 数据库配置（可选，需要启用 database 特性）
APP__DATABASE__URL=postgres://user:password@localhost/dbname
APP__DATABASE__MAX_CONNECTIONS=100
APP__DATABASE__MIN_CONNECTIONS=10

# Redis 配置（可选，需要启用 redis 特性）
APP__REDIS__URL=redis://127.0.0.1:6379
APP__REDIS__PASSWORD=your_password  # 可选
APP__REDIS__POOL_SIZE=10

配置项说明

服务器配置

• APP__SERVER__ADDR: 监听地址（默认: 0.0.0.0）
• APP__SERVER__PORT: 监听端口（默认: 3000）
• APP__SERVER__CONTEXT_PATH: 上下文路径，如 /api（可选）

日志配置

• APP__LOG__LEVEL: 日志级别（trace, debug, info, warn, error，默认: info）
• APP__LOG__JSON: 是否使用 JSON 格式（默认: false）

CORS 配置

• APP__CORS__ALLOWED_ORIGINS: 允许的源（默认: *）
• APP__CORS__ALLOWED_METHODS: 允许的 HTTP 方法（默认: GET,POST,PUT,DELETE,PATCH,OPTIONS）
• APP__CORS__ALLOWED_HEADERS: 允许的请求头（默认: *）
• APP__CORS__ALLOW_CREDENTIALS: 是否允许凭证（默认: false）

🔧 特性

启用数据库支持

[dependencies]
fbc-starter = { version = "0.1.0", features = ["database"] }

使用：

use fbc_starter::get_postgres_pool;

let pool = get_postgres_pool()?;
let users = sqlx::query!("SELECT * FROM users")
    .fetch_all(&pool)
    .await?;

启用 Redis 支持

[dependencies]
fbc-starter = { version = "0.1.0", features = ["redis"] }

使用：

use fbc_starter::get_redis_connection;

let mut conn = get_redis_connection().await?;
redis::cmd("SET").arg("key").arg("value")
    .query_async(&mut conn).await?;

📚 文档

• 路由扩展指南 - 详细的 Controller 风格路由使用指南
• API 文档 - 完整的 API 文档

🎯 API 端点

系统端点

• GET / - 欢迎信息和版本信息
• GET /health - 健康检查（符合 Prometheus 标准）

🏗️ 项目结构示例

src/
├── main.rs
├── controllers/
│   ├── mod.rs
│   ├── users.rs
│   └── posts.rs
└── handlers/
    └── mod.rs

📝 示例

完整示例

use fbc_starter::{start_with_routes, routing::{registry, RouteGroup}};
use axum::{routing::get, Router, extract::Path, response::Json};
use serde_json::json;

struct UserController;

impl RouteGroup for UserController {
    fn routes(&self) -> Router {
        Router::new()
            .route("/", get(list_users))
            .route("/:id", get(get_user))
    }
}

async fn list_users() -> Json<serde_json::Value> {
    Json(json!({ "users": [] }))
}

async fn get_user(Path(id): Path<u64>) -> Json<serde_json::Value> {
    Json(json!({ "id": id }))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api_routes = registry()
        .nest_group("/api/users", UserController)
        .build();

    start_with_routes(Some(api_routes)).await?;
    Ok(())
}

🔍 特性说明

默认特性

默认情况下，fbc-starter 只包含核心功能，不包含数据库和 Redis 支持。

可选特性

• database: 启用数据库支持（PostgreSQL/MySQL/SQLite）
• redis: 启用 Redis 缓存支持

可以同时启用多个特性：

[dependencies]
fbc-starter = { version = "0.1.0", features = ["database", "redis"] }

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目采用 MIT 或 Apache-2.0 双许可证。

🙏 致谢

• Axum - 高性能 Web 框架
• Tokio - 异步运行时
• Tracing - 结构化日志