fbc-starter 0.1.2

# fbc-starter

[![Crates.io](https://img.shields.io/crates/v/fbc-starter.svg)](https://crates.io/crates/fbc-starter)
[![Documentation](https://docs.rs/fbc-starter/badge.svg)](https://docs.rs/fbc-starter)
[![License](https://img.shields.io/crates/l/fbc-starter.svg)](LICENSE)

一个基于 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` 中添加：

```toml
[dependencies]
fbc-starter = "0.1.0"
```

### 基础使用

```rust
use fbc_starter::start;

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

### 添加自定义路由

```rust
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 风格路由

```rust
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` 文件：

```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`）

## 🔧 特性

### 启用数据库支持

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

使用：

```rust
use fbc_starter::get_postgres_pool;

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

### 启用 Redis 支持

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

使用：

```rust
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_GUIDE.md) - 详细的 Controller 风格路由使用指南
- [API 文档](https://docs.rs/fbc-starter) - 完整的 API 文档

## 🎯 API 端点

### 系统端点

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

## 🏗️ 项目结构示例

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

## 📝 示例

### 完整示例

```rust
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 缓存支持

可以同时启用多个特性：

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

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

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

## 🙏 致谢

- [Axum](https://github.com/tokio-rs/axum) - 高性能 Web 框架
- [Tokio](https://tokio.rs/) - 异步运行时
- [Tracing](https://github.com/tokio-rs/tracing) - 结构化日志