rust-webx — Rust WebApi Framework

ASP.NET Core 风格的 Rust WebApi 服务框架，基于 rust-dix DI + 中介者模式构建。

特性

• DI + 中介者 双核心 — 以 IRequest<T> + IRequestHandler<T, R> 为载体，框架自动完成路由映射和 DI 解析
• 编译时路由快捷键 — #[get("/path")] #[post("/path")] 等一行标注定义完整端点
• 编译时自动扫描 — 通过 inventory 编译时收集路由元数据，Host::build() 时自动注册
• 零配置 Handler 注册 — #[handler] 属性宏自动向 DI 容器注册 Handler
• 身份认证和授权 — JWT Bearer + 基于资源的路由授权
• ORM 无关 — 框架不依赖 rust-ef；Docbit 在 handlers/src/db.rs 与 host 内联最少胶水

快速开始

use rust_webx::*;

struct HelloRequest;

#[get("/hello")]
impl IRequest<String> for HelloRequest {}

#[derive(Default)]
struct HelloHandler;

#[handler]
#[async_trait]
impl IRequestHandler<HelloRequest, String> for HelloHandler {
    async fn handle(&self, _req: HelloRequest) -> Result<String> {
        Ok("Hello, World! Welcome to Rust WebX.".to_string())
    }
}

#[tokio::main]
async fn main() {
    Host::builder()
        .build()
        .run()
        .await
        .expect("Server failed");
}

架构

┌──────────────────────────────────────────────────────────┐
│                   rust-webx (umbrella)                   │
│  重新导出 core / host / macros / spa / openapi + rust_dix│
├──────────┬──────────┬──────────┬─────────────────────────┤
│rust-webx-│rust-webx-│rust-webx-│ rust-webx-macros        │
│host      │core      │openapi   │ #[get] #[post] #[handler]│
│Host +    │traits +  │OpenAPI   │ #[authorize]             │
│Pipeline  │config    │生成      │                          │
│+ Router  │mediator  │          │                          │
├──────────┴──────────┴──────────┴─────────────────────────┤
│                    rust-webx-core                        │
│  IHost / IHttpContext / IMiddleware / IRequestHandler    │
│  IMediator / AppOptions / Error / AppMode                │
└──────────────────────┬───────────────────────────────────┘
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
   ┌──────────┐ ┌──────────┐ ┌──────────┐
   │ rust-dix │ │  hyper   │ │inventory │
   │ (DI)     │ │(HTTP)    │ │(路由收集) │
   └──────────┘ └──────────┘ └──────────┘

Crate 结构

rust-webx/
├── Cargo.toml              # workspace root (v0.2.0)
├── docbit/                 # 参考应用（作品集 + 博客 + RBAC）
└── crates/
    ├── core/               # rust-webx-core — trait 与配置
    ├── host/               # rust-webx-host — Host、管道、路由
    ├── macros/             # rust-webx-macros — 过程宏
    ├── spa/                # rust-webx-spa — 静态资源 / SPA
    ├── openapi/            # rust-webx-openapi — OpenAPI 生成
    └── webx/               # rust-webx — 伞 crate

核心概念

请求处理流程

HTTP Request
    │
    ▼
HttpContext::new(req).await    ←  读取 body bytes
    │
    ▼
MiddlewarePipeline::execute()
    │  中间件按注册顺序调用
    │  每个可设置 response status 短路
    ▼
Router::match_route(ctx)
    │  Trie 树匹配 method + path
    │  提取 {param} 值到 route_params
    ▼
┌──────────────┐
│ Route matched │──No──▶ 404 "Not Found"
└──────┬───────┘
       │ Yes
       ▼
IEndpoint::handle(ctx)
    │  调用 handler，序列化响应
    ▼
HttpResponse → hyper::Response
    │  若 Err → 内置异常中间件映射状态码
    ▼
JSON 响应: RFC 7807 application/problem+json（404/5xx）

生产就绪能力

环境变量：RUST_WEBX_APP_BASE（应用目录）、JWT_SECRET、APP__Jwt__Secret、APP__* 覆盖 appsettings。详见 docs/rust-webx/。

异常映射

示例应用

参考应用 docbit（docbit/host）演示 rust-ef 集成、JWT、RBAC、SPA 托管：

cargo run -p docbit-host

# http://localhost:5000

生产部署见 docbit/PRODUCTION.md。

依赖

许可证

MIT