WAE - Wae Algebraic Effects

微服务优先的 Rust 异步框架，深度融合 tokio 运行时，提供从 HTTP 服务到云服务的一站式解决方案。

---

✨ 核心特性

特性	说明
🚀 微服务优先	服务发现、配置中心、链路追踪、健康检查、优雅关闭，开箱即用
⚡ 深度融合 tokio	基于 tokio-net 零抽象，原生 async/await，极致性能
🤖 AI 友好	清晰的 Trait 抽象，统一的错误处理，最小化样板代码
🦀 纯血 Rust	零 FFI 绑定，跨平台支持，内存安全，可审计

---

📦 模块概览

WAE 采用模块化的 Crate 设计，每个模块可独立使用：

模块	功能
wae-https	HTTP/HTTPS 服务，构建器模式，统一响应结构
wae-effect	代数效应依赖注入，声明式依赖获取
wae-ai	AI 服务抽象，支持腾讯混元、火山引擎等
wae-storage	存储服务抽象，支持腾讯云 COS、阿里云 OSS、本地存储
wae-database	数据库服务，基于 Turso (SQLite 兼容)
wae-cache	缓存服务抽象，支持内存缓存
wae-service	服务发现与注册，负载均衡策略
wae-config	多层级配置管理，支持 TOML/YAML/环境变量
wae-email	邮件服务抽象，支持 SMTP/Sendmail
wae-types	统一错误类型与结果类型

---

🚀 快速开始

安装

[dependencies]
wae = { git = "https://github.com/oovm/wae" }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }

基础 HTTP 服务

use wae::prelude::*;
use wae::effect::{Effectful, AlgebraicEffect, Dependencies};

#[derive(Debug, Clone, Deserialize)]
struct AppConfig {
    ai_api_key: String,
}

async fn generate_image(
    e: Effectful,
    Json(params): Json<TextToImageParams>,
) -> Result<Json<Vec<String>>, EffectError> {
    let config = e.use_config::<AppConfig>().await?;
    let ai = HunyuanProvider::new(&config.ai_api_key);
    ai.text_to_image(&params).await.map(Json)
}

fn routes(deps: Arc<Dependencies>) -> Router {
    Router::new()
        .route("/api/generate", post(generate_image))
        .route("/health", get(|| async { "OK" }))
        .with_state(deps)
}

#[wae::main]
async fn main() -> Result<()> {
    let config = AppConfig::from_env();
    let deps = AlgebraicEffect::new()
        .with_config(config)
        .build();
    
    Server::bind("0.0.0.0:3000")
        .routes(routes(deps))
        .with_graceful_shutdown()
        .serve()
        .await
}

---

🎯 代数效应模式

WAE 采用代数效应风格的依赖注入，通过单一的 Effectful 参数统一管理所有依赖：

async fn handler(e: Effectful) -> Result<Json<Response>, EffectError> {
    let db = e.use_database().await?;
    let config = e.use_config::<AppConfig>().await?;
    let user = e.use_auth::<User>().await?;
    let cache = e.use_arc::<Cache>().await?;
}

优势：声明式依赖获取 · 编译时类型检查 · 易于测试和 mock

---

🏗️ 架构设计

分层架构

┌─────────────────────────────────────────────────────────┐
│                    Application Layer                     │
│  Router │ Middleware │ Handlers │ State                 │
├─────────────────────────────────────────────────────────┤
│                    Abstraction Layer                     │
│  Request │ Response │ Extractors │ Responders           │
├─────────────────────────────────────────────────────────┤
│                    Protocol Layer                        │
│  HTTP/1.1 (httparse) │ HTTP/2 (h2) │ WebSocket          │
├─────────────────────────────────────────────────────────┤
│                      Core Layer                          │
│              tokio::net::TcpListener/Stream              │
└─────────────────────────────────────────────────────────┘

相比传统框架的优势

特性	传统方案	WAE 方案
HTTP 服务	hyper + tower 多层抽象	tokio-net 零抽象
依赖注入	手动解构 tuple state	代数效应统一管理
错误处理	IntoResponse 转换	CloudError 统一处理
配置管理	多库组合	ConfigLoader 一站式

---

🔧 Capability 模式

每个能力定义为独立的 trait，服务商通过实现多个 Capability 来声明支持的能力：

pub struct HunyuanProvider;

impl ChatCapability for HunyuanProvider { /* ... */ }
impl TextToImageCapability for HunyuanProvider { /* ... */ }
impl AiImageCapability for HunyuanProvider { /* ... */ }

---

📖 文档

• 简介 - 了解 WAE 的设计理念
• 快速开始 - 5 分钟上手 WAE
• 核心优势 - 深入了解各模块特性
• 架构设计 - 模块化设计原则

---

📝 开发规范

Emoji 提交规范

Emoji	含义
🎂	项目初始化
🎉	发布新版本
🧪🔮	实验性代码
🔧🐛🐞	Bug 修复
🔒	安全修复
🐣🐤🐥	新增功能
📝🎀	文档更新
🚀	性能优化
🚧	开发中
🚨	测试覆盖
🚥	CI 改进
🔥🧨	删除代码或文件
🧹	代码重构
📈	添加分析或分支
🤖	自动化修复
📦	更新依赖

---

📄 License

MIT License