HwhKit 🚀

一个用于快速构建 Web 服务的 Rust 工具库，支持前后端分离和不分离两种架构。

✨ 特性

• 🚀 一键构建 - 通过简单的构建器模式快速创建 Web 服务
• 🏗️ 双架构支持 - 支持前后端分离(API)和不分离(全栈)两种架构
• ⚙️ 配置驱动 - 基于 TOML 配置文件的中间件装载机制
• 🔧 丰富中间件 - 内置 CORS、JWT、静态文件、模板渲染等中间件
• 💾 数据库支持 - 支持 PostgreSQL、MySQL、SQLite 和 Qdrant 向量数据库（可选）
• ⚡ 高性能 - 基于 Axum 和 Tokio 构建，性能卓越
• 🎨 模板支持 - 内置 Tera 模板引擎支持（可选）
• 📝 类型安全 - 完全的 Rust 类型安全保障

🛠️ 安装

将以下内容添加到你的 Cargo.toml：

[dependencies]
hwhkit = "0.1"
tokio = { version = "1.0", features = ["full"] }

# 可选特性
hwhkit = { version = "0.1", features = ["templates", "jwt", "database", "vector"] }

可用特性

• templates - 启用 Tera 模板引擎支持
• jwt - 启用 JWT 认证支持
• database - 启用关系数据库支持（PostgreSQL、MySQL、SQLite）
• vector - 启用 Qdrant 向量数据库支持
• full - 启用所有特性

📚 快速开始

前后端分离架构（API 模式）

use hwhkit::{WebServerBuilder, get, Json, Serialize};

#[derive(Serialize)]
struct ApiResponse {
    message: String,
    status: String,
}

async fn hello_world() -> Json<ApiResponse> {
    Json(ApiResponse {
        message: "Hello, World!".to_string(),
        status: "success".to_string(),
    })
}

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

    let server = WebServerBuilder::new()
        .listen("0.0.0.0", 3000)
        .cors(vec!["http://localhost:3000".to_string()])
        .routes(app)
        .build()
        .await?;

    server.serve().await?;
    Ok(())
}

前后端不分离架构（全栈模式）

use hwhkit::{WebServerBuilder, get, Html, ArchitectureType};

async fn index() -> Html<&'static str> {
    Html("<h1>欢迎使用 HwhKit!</h1>")
}

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

    let server = WebServerBuilder::new()
        .listen("0.0.0.0", 8080)
        .architecture(ArchitectureType::Full)
        .static_files("static", "/static")
        .templates("templates", "html")
        .routes(app)
        .build()
        .await?;

    server.serve().await?;
    Ok(())
}

使用配置文件

创建 config.toml：

[server]
host = "0.0.0.0"
port = 3000
architecture = "api"

[middleware.cors]
enabled = true
origins = ["*"]
methods = ["GET", "POST", "PUT", "DELETE"]
headers = ["Content-Type", "Authorization"]

[middleware.jwt]
enabled = true
secret = "your-secret-key"
expires_in = 3600

[middleware.static_files]
enabled = true
dir = "public"
prefix = "/static"

[middleware.logging]
level = "info"
requests = true

然后在代码中使用：

use hwhkit::WebServerBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = WebServerBuilder::new()
        .config_from_file("config.toml")
        .build()
        .await?;

    server.serve().await?;
    Ok(())
}

🎯 架构类型

API 架构（前后端分离）

适用于构建 RESTful API 服务：

• ✅ CORS 支持
• ✅ JSON 响应
• ✅ JWT 认证
• ✅ 静态文件服务
• ❌ 模板渲染

Full 架构（前后端不分离）

适用于构建传统的全栈 Web 应用：

• ✅ 模板渲染
• ✅ 静态文件服务
• ✅ 表单处理
• ✅ 会话管理
• ⚠️ CORS（通常不需要）

🔧 中间件配置

CORS

[middleware.cors]
enabled = true
origins = ["http://localhost:3000", "https://yourdomain.com"]
methods = ["GET", "POST", "PUT", "DELETE"]
headers = ["Content-Type", "Authorization"]

JWT 认证

[middleware.jwt]
enabled = true
secret = "your-super-secure-secret-key"
expires_in = 3600  # 1小时

静态文件

[middleware.static_files]
enabled = true
dir = "public"  # 静态文件目录
prefix = "/static"  # URL 前缀

模板引擎

[middleware.templates]
enabled = true
dir = "templates"  # 模板文件目录
extension = "html"  # 模板文件扩展名

日志

[middleware.logging]
level = "info"  # trace, debug, info, warn, error
requests = true  # 启用请求日志

💾 数据库支持

HwhKit 支持关系数据库和向量数据库：

关系数据库

[dependencies]
hwhkit = { version = "0.1", features = ["database"] }

配置文件：

[database]
enabled = true
db_type = "postgres"  # postgres, mysql, sqlite
url = "postgresql://user:password@localhost/myapp"
max_connections = 10

使用示例：

let server = WebServerBuilder::new()
    .config_from_file("config.toml")
    .build()
    .await?;

if let Some(db) = server.database() {
    let pool = db.pool();
    // 使用 SQLx 执行查询
}

向量数据库（Qdrant）

[dependencies]
hwhkit = { version = "0.1", features = ["vector"] }

配置文件：

[qdrant]
enabled = true
url = "http://localhost:6334"
default_collection = "my_collection"

更多详情请查看 DATABASE.md。

📖 示例

查看 examples/ 目录获取完整示例：

• api-server.rs - 前后端分离架构示例
• full-server.rs - 前后端不分离架构示例
• database-example.rs - 数据库集成示例

运行示例：

# API 服务器示例
cargo run --example api-server

# 全栈服务器示例
cargo run --example full-server

# 数据库示例
cargo run --example database-example --features database

🧪 测试

运行所有测试：

cargo test

运行特定特性的测试：

cargo test --features "templates,jwt"

📋 路线图

• 基本 Web 服务器构建
• 配置文件支持
• CORS 中间件
• 静态文件服务
• 基础模板支持
• JWT 认证框架
• 关系数据库集成（PostgreSQL、MySQL、SQLite）
• 向量数据库集成（Qdrant）
• WebSocket 支持
• 请求限流
• 缓存中间件
• 监控和指标
• 热重载开发模式

🤝 贡献

欢迎贡献代码！请查看 CONTRIBUTING.md 了解详细信息。

开发环境设置

# 克隆仓库
git clone https://github.com/yourusername/hwhkit.git
cd hwhkit

# 安装依赖
cargo build

# 运行测试
cargo test

# 运行示例
cargo run --example api-server

📄 许可证

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

🙋 支持

• 📖 文档
• 🐛 问题反馈
• 💬 讨论

🌟 致谢

感谢以下项目为 HwhKit 提供了灵感和基础：

• Axum - 现代异步 Web 框架
• Tower - 模块化网络服务
• Tera - 模板引擎
• Serde - 序列化框架