framework-proc-web 26.8.151

lingting framework
Documentation

framework-proc-web

提供 web_api 及 HTTP 方法简化宏，把 async fn 展开为可调用的 WebRoute 构造函数， 并自动叠加 framework-proc-ts 的 ts_api 元数据收集。

宏只生成路由与参数提取代码，运行时的请求上下文、错误处理、响应构造位于 framework-web。

使用

生成的代码引用 framework_web、framework_proc_ts 与 framework_proc_core， 使用方需要自行声明这些依赖（通常通过 framework-web 间接获得）。

feature

feature 作用
collect（默认关闭） 额外生成 push_web_api! 调用，把路由注册进 inventory

framework-web 的 collect 会传递开启本 feature；未开启时路由构造函数依然生成， 但不会自动注册，需要手动挂载。

宏

宏 HTTP 方法
web_api 由 method 参数指定
web_api_get GET
web_api_post POST
web_api_put PUT
web_api_patch PATCH
web_api_delete DELETE

简化宏不接受 method 参数，重复指定会报错。

参数

参数 必填 说明
method 使用 web_api 时必填 HTTP 方法标识符，如 get、post、delete，大小写不敏感
path 是 字符串，两端 / 会被裁掉，裁剪后不能为空
auth 否 授权规则表达式，默认 framework_web::AuthRule::login() 
use framework_proc_web::web_api_post;
use framework_web::{AuthRule, Json};

#[web_api_post(path = "user/create", auth = AuthRule::anonymous())]
pub async fn create_user(params: Json<CreateUserParams>) -> Result<UserVO, anyhow::Error> {
    // ...
}

函数要求

  • 必须是 async fn。
  • 不支持 self 参数。
  • 不支持 WebContext 参数，需在函数内调用 framework_web::use_web()。
  • 每个参数类型必须实现 FromWeb，参数在进入函数体前逐个 await 转换， 转换失败直接返回对应的错误响应。
  • GET 接口最多只能有一个参数（一个从查询参数提取的参数对象）。

返回值处理

按函数返回类型选择响应构造方式：

返回类型 生成的响应
省略或 () 执行后返回 WebResponse::empty()（204）
WebResponse 直接返回
R<T> WebResponse::from_r
T WebResponse::from_t，包装为 R::ok
Result<WebResponse, E> WebResponse::from_result
Result<R<T>, E> WebResponse::from_result_r
Result<T, E> WebResponse::from_result_t

生成内容

对于函数 create_user，宏生成：

  1. 原函数，并叠加 #[framework_proc_ts::ts_api(method = "...", path = "...")]。
  2. pub(crate) fn build_create_user_route() -> framework_web::WebRoute。

路由的 invoke 闭包内依次完成：读取 use_web() 上下文、提取各参数、 在 catch_panic 中执行函数体与响应构造。panic 与参数转换错误都会转为错误响应并记录日志。

开启 collect 时，还会生成 framework_web::push_web_api!(build_create_user_route);， 供 framework-web-axum 的 WebRouter 自动收集。

说明

  • 宏生成的辅助变量使用 __web_argument_<索引> 命名，避免与函数参数冲突。
  • 路径不做前缀拼接与参数占位符解析，WebRouter 按 path 字符串精确匹配。