AFaster：一个开箱即用的 Rust 高性能后端框架模板

基于 afast 构建，内置 25+ 业务模块，从微信支付到链路追踪，一行配置即可启用。

前言

在日常后端开发中，我们反复做的事情往往不是写核心业务逻辑，而是搭架子------接数据库、配 JWT、对接微信支付、接入 OSS 存储、写日志、搞限流......这些"胶水代码"每个项目都要来一遍，耗时且容易出错。

AFaster 就是为了解决这个问题而生的：它是一个基于 Rust 的后端框架模板，把常见的业务模块全部预置好，通过 Cargo feature 按需启用，通过 config.toml 统一配置，让你在 main() 里写几行代码就能跑起一个功能完备的后端服务。

rust 复制代码

use afaster::AFaster;

#[tokio::main]
async fn main() {
    AFaster::new("config.toml".to_string()).await
        .unwrap()
        .run()
        .await;
}

是的，就这么点代码。下面聊聊它背后的设计和能力。

设计理念

1. Feature-driven，按需组合

AFaster 的所有功能模块都通过 Cargo feature 控制。不需要微信支付？不启用 wx-pay-* 就行，编译产物不会包含任何相关代码。需要 Redis + PostgreSQL + 邮件发送？组合启用即可：

toml 复制代码

[dependencies]
afaster = { version = "0.0.3", features = ["redis", "db-postgres", "email"] }

这种设计带来了两个直接好处：

编译产物精简------未启用的模块不会被编译进来
依赖冲突可控------每个 feature 只拉取自己需要的依赖

2. 统一配置，链式构建

所有模块的配置统一放在 config.toml 中，结构清晰：

toml 复制代码

[backend]
host = "0.0.0.0"
port = 5000

[redis]
host = "127.0.0.1"
port = 6379

[wx_pay]
mch_id = "your_mch_id"
app_id = "your_app_id"
# ...

而在代码侧，AFaster 提供链式 Builder API 来注册回调、配置行为：

rust 复制代码

AFaster::new("config.toml".to_string()).await
    .unwrap()
    .with_github_oauth2(|g| g.with_github_callback(|(state, result, oauth_state)| {
        async move {
            // 处理 GitHub OAuth2 登录回调
            Ok(result)
        }
    }))
    .with_wx_virtual_pay(|w| w
        .with_goods_deliver_callback(|(state, notify)| {
            async move {
                // 处理虚拟支付道具发货
                Ok(afaster::wx_virtual_pay::WxPayNotifyResult::success())
            }
        })
    )
    .run()
    .await;

3. 静态文件服务内置

前后端分离项目中，SPA 部署是刚需。AFaster 内置了静态文件服务模块，支持两种模式：

运行时目录模式------从磁盘读取：

rust 复制代码

AFaster::new("config.toml".to_string()).await
    .unwrap()
    .with_serve(Serve::from_dir("./dist").with_spa(true))
    .run()
    .await;

编译期嵌入模式------整个目录打包进二进制，部署时只需一个文件：

rust 复制代码

AFaster::new("config.toml".to_string()).await
    .unwrap()
    .with_serve(Serve::from_embedded(include_dir!("$CARGO_MANIFEST_DIR/dist")).with_spa(true))
    .run()
    .await;

SPA 模式下，未匹配的路径会自动回退到 index.html，前端路由不再 404。

功能模块全景

AFaster 目前内置 25+ 个功能模块，覆盖了后端开发的方方面面。按类别梳理如下：

认证与安全

模块	说明
`jwt`	JWT 令牌认证，可配置过期时间和密钥
`nonce`	随机字符串生成，适用于 OAuth2 state、CSRF 防护
`github-oauth2`	GitHub OAuth2 登录，带回调机制
`argon2-hash`	Argon2 密码哈希，业界推荐的密码存储方案
`rbac`	基于角色的权限管理，支持自定义存储实现
`rate-limit`	令牌桶 / 滑动窗口限流
`afast-tls`	HTTPS / WSS 支持，基于 rustls

微信生态

这是 AFaster 最用心的部分之一，覆盖了微信体系下的主流场景：

登录：小程序登录、APP 登录、网页扫码登录
公众号：模板消息、菜单管理、素材管理、网页授权
支付：H5 / Native / APP / 小程序 / JSAPI 五种支付方式
虚拟支付：代币支付、道具发货、退款、投诉处理
内容安全：微信内容安全检测

每种支付方式都有独立的 feature 和回调机制，互不干扰。

云服务集成

阿里云：OSS 对象存储、支付宝电脑网站支付、短信服务
腾讯云：COS 对象存储、短信服务、腾讯地图

数据层

多数据库支持：PostgreSQL / SQLite / MySQL，可同时启用
Redis / Valkey：共享实现，灵活切换
Ahrisql：自研数据库引擎
内存 KV：无需外部依赖的内存缓存
布隆过滤器：支持自动 Hook，按 IP / 路径 / Header 过滤

文件处理

本地文件服务：文件上传下载
Excel / CSV ：导入导出，支持 calamine 和 rust_xlsxwriter
PDF 生成 ：基于 printpdf
图片生成 ：基于 image + imageproc

消息通知

邮件：SMTP 发送（基于 lettre）
推送：个推 / 极光 / 小米推送
SSE：Server-Sent Events 实时推送

工具集

Snowflake ID：分布式 ID 生成器，已修复高并发竞态问题
定时任务：基于 Cron 表达式的调度器
链路追踪：支持 SQLite / HTTP / TCP 三种后端，内置可视化 UI
正则工具：常用正则表达式封装
时钟工具：时间处理辅助

实战：用 AFaster 搭一个博客系统

AFaster 的 example/ 目录下就有一个完整的多人博客系统示例，展示了如何用框架快速搭建业务。它包含三个 Service：

user：公开接口（注册、登录、浏览文章）
user_backend：用户后台（管理自己的文章、评论）
admin：管理员接口（审核、用户管理、分类标签管理）

通过 RBAC 实现权限控制，每个接口都有明确的权限码，框架自动完成鉴权：

rust 复制代码

// RBAC 存储实现（SQLite）
impl RbacStore for SqliteRbacStore {
    fn check_permission(&self, user_id: i64, permission_code: &str)
        -> Pin<Box<dyn Future<Output = Result<bool>> + Send + '_>>
    {
        // 查询用户角色关联的权限表
    }
}

这个示例涵盖了数据库操作、JWT 认证、RBAC 权限、分页查询等典型后端场景，是很好的学习参考。

错误码设计

AFaster 采用 5 位数字错误码，设计巧妙：

第 1 位：4 = 用户错误，5 = 内部错误
第 2-3 位：模块编号（如 28 = 某个具体模块）
第 4-5 位：模块内序号

例如 42801 表示"模块 28 的第 1 个用户错误"，52803 表示"模块 28 的第 3 个内部错误"。这种设计让错误码既有序又可读，排查问题时一眼就能定位到模块。

链路追踪

AFaster 的链路追踪模块（trace）值得一提。它支持三种后端：

trace-sqlite：存储到 SQLite，适合单机部署
trace-http：通过 HTTP 上报，适合集中式收集
trace-tcp：通过 TCP 上报，性能更好

更贴心的是，它还内置了一个 Web UI，可以直接在浏览器中查看链路瀑布图、Span 树、耗时分布等。对于排查性能问题非常有帮助。

代码生成

启用 afast-ts / afast-js / afast-kt / afast-rs 等 feature 后，AFaster 可以自动生成客户端代码（TypeScript / JavaScript / Kotlin / Rust），让前后端对接更加顺畅。这意味着你定义好 Service 接口后，前端可以直接拿到类型安全的 SDK。

总结

AFaster 不是要替代 Actix-web 或 Axum 这样的通用框架，而是在它们之上提供一层业务模板。它的定位很明确：

✅ 快速搭建功能完备的后端服务
✅ 内置微信生态、云服务、支付等中国特色业务模块
✅ Feature-driven 按需组合，不引入多余依赖
✅ 统一配置 + 链式 API，降低心智负担
✅ 内置链路追踪、限流、RBAC 等生产级能力

如果你正在用 Rust 做后端开发，且项目涉及微信生态或常见的业务模块集成，AFaster 值得一试。它能帮你跳过大量的"轮子搭建"阶段，直接进入核心业务开发。

项目地址：github.com/ahriknow/af...

文档：afaster.ahriknow.help

AFaster 基于 MIT 协议开源，欢迎 Star 和 PR。