wordval_macros/lib.rs
1//! # wordval-macros
2//!
3//! Wordval 过程宏生态:编译时代码生成,替代 Java 的反射 + 注解扫描。
4//!
5//! ## 提供的宏
6//!
7//! ### 路由宏
8//! - `#[get("/path")]` / `#[post]` / `#[put]` / `#[delete]` — 路由注册;
9//! 同一条注解上用 `audit = "动作名"`、`permission = "权限标识"`、`public`
10//! 声明该路由的审计 / 权限 / 免认证策略(编译成路由守卫元数据,
11//! 启动时由 wordval-web 派生中间件规则,业务侧零额外代码、路径只写一次)。
12//!
13//! ### 模型宏
14//! - `#[derive(Model)]` — 自动实现 `FromRow` + `ToRow` + `ActiveRecord`(`query_as` 要的
15//! `TryFromRow` 由 `wordval-db` 从 `FromRow` blanket 出来);`sqlx::FromRow` **按需**生成,
16//! 要哪个后端写 `#[wordval(sqlx = "sqlite")]`。
17//! 时间(`NaiveDate` / `NaiveDateTime` / `DateTime<Utc>` / `DateTime<Local>`)、
18//! `Uuid`、`Vec<u8>`、`Decimal` 与各 `Option` 字段为类型化绑定(`None` 落 typed null),
19//! 不再经 serde JSON 走文本参数(详见 `model` 模块文档)。
20//!
21//! ### 其他
22//! - `#[idempotent]` — 幂等性保证
23//! - `#[tools]` — MCP 工具注册
24
25mod idempotent;
26mod model;
27mod route;
28mod tools;
29
30use proc_macro::TokenStream;
31
32/// #[derive(Model)] — 自动实现 FromRow + ToRow + ActiveRecord(TryFromRow 由库 blanket 出来)
33/// sqlx::FromRow 默认不生成,按 `#[wordval(sqlx = "postgres,mysql,sqlite")]` 勾选的后端补齐
34#[proc_macro_derive(Model, attributes(wordval))]
35pub fn model_derive(input: TokenStream) -> TokenStream {
36 model::model_derive(input)
37}
38
39/// GET 路由
40///
41/// # 参数
42///
43/// | 参数 | 形式 | 说明 |
44/// |------|------|------|
45/// | 路径 | 位置参数(必填) | 支持 `{id}` 形式的路径参数 |
46/// | `audit` | `audit = "动作名"`(可选) | 本路由命中后落一条审计记录 |
47/// | `permission` | `permission = "权限标识"`(可选) | 访问本路由需要的权限 |
48/// | `public` | 裸标志(可选) | 本路由免认证(与 `permission` 互斥) |
49///
50/// 三个策略参数都编译成路由注册时携带的守卫元数据:路径与方法只在路由注解里
51/// 出现一次,改名或加路由前缀后策略随路由一起走,不存在"权限规则指向不存在的路径"
52/// 而静默失去保护的情况。
53///
54/// `audit` 命中后由审计中间件自动写入审计记录(动作名、方法、路径、状态码、
55/// 结论、耗时、IP、请求 ID 全部自动填);未启用审计写入器时不产生额外开销。
56///
57/// ```ignore
58/// #[wordval::get("/api/orders/{id}", audit = "order.query", permission = "order:query")]
59/// async fn query_order(Path(id): Path<i64>) -> Res<Value> { ... }
60///
61/// #[wordval::post("/api/auth/login", public)]
62/// async fn login(Json(req): Json<LoginReq>) -> ResResult<JsonValue> { ... }
63/// ```
64///
65/// 启动时 `App` 从已注册路由的守卫元数据派生审计 / 权限 / 免认证规则,
66/// 与 `middleware.audit.routes`、`middleware.permission.rules`、`auth.ignore_paths`
67/// 的配置规则合并后挂载对应中间件。
68#[proc_macro_attribute]
69pub fn get(attr: TokenStream, item: TokenStream) -> TokenStream {
70 route::method_route_impl("get", attr, item)
71}
72
73/// POST 路由(参数与 `#[get]` 相同:`audit` / `permission` / `public`)
74#[proc_macro_attribute]
75pub fn post(attr: TokenStream, item: TokenStream) -> TokenStream {
76 route::method_route_impl("post", attr, item)
77}
78
79/// PUT 路由(参数与 `#[get]` 相同:`audit` / `permission` / `public`)
80#[proc_macro_attribute]
81pub fn put(attr: TokenStream, item: TokenStream) -> TokenStream {
82 route::method_route_impl("put", attr, item)
83}
84
85/// DELETE 路由(参数与 `#[get]` 相同:`audit` / `permission` / `public`)
86///
87/// ```ignore
88/// #[wordval::delete("/api/orders/{id}", permission = "order:delete", audit = "order.delete")]
89/// async fn delete_order(Path(id): Path<i64>) -> Res<()> { ... }
90/// ```
91#[proc_macro_attribute]
92pub fn delete(attr: TokenStream, item: TokenStream) -> TokenStream {
93 route::method_route_impl("delete", attr, item)
94}
95
96/// 幂等执行宏:只对需要幂等的写接口标注,业务逻辑对同一 `x-idempotency-key` 只执行一次
97///
98/// # 参数
99///
100/// | 参数 | 类型 | 默认值 | 说明 |
101/// |------|------|--------|------|
102/// | `ttl` | u64 | 86400 | 幂等键有效期(秒),建议 3600~86400 |
103///
104/// # 示例
105///
106/// ```ignore
107/// use wordval::prelude::*;
108///
109/// #[wordval::post("/api/order/create")]
110/// #[wordval::idempotent(ttl = 3600)]
111/// async fn create_order(Json(p): Json<CreateOrderReq>) -> ResResult<Order> {
112/// // ... 同一 x-idempotency-key 只执行一次,重复请求直接返回首次结果
113/// }
114/// ```
115///
116/// 要求:仅支持 async 自由函数(不支持方法/泛型);不携带幂等键的请求直接透传。
117#[proc_macro_attribute]
118pub fn idempotent(attr: TokenStream, item: TokenStream) -> TokenStream {
119 idempotent::idempotent_impl(attr, item)
120}
121
122/// 把普通 API handler 同时声明为大模型业务工具(MCP 工具)
123///
124/// 支持 `Json<T>` / `Query<T>` / `Path<T>` / `ValidatedJson<T>` 提取器参数与
125/// `Res<T>` / `ResResult<T>` 统一响应,可与其他路由宏(`#[post]` 等)叠加:
126/// 同一个函数既提供 HTTP 接口,又注册为 MCP 工具供大模型调用。
127///
128/// # 参数
129///
130/// | 参数 | 类型 | 默认值 | 说明 |
131/// |------|------|--------|------|
132/// | `description` | &str | doc 注释 | 工具描述 |
133/// | `name` | &str | 函数名 | 自定义工具名 |
134/// | `read_only` | flag | false | 标记只读工具 |
135///
136/// # 示例
137///
138/// ```ignore
139/// use wordval::prelude::*;
140///
141/// /// 创建用户(doc 注释作为工具描述)
142/// #[wordval::post("/api/user/create")]
143/// #[wordval::tools]
144/// async fn create_user(Json(req): Json<CreateUserReq>) -> ResResult<JsonValue> {
145/// Ok(Res::ok(json!({"id": 1})))
146/// }
147/// ```
148///
149/// 参数 schema 由 `T::json_schema()`(wordval_agent::tools::schema::JsonSchema)生成,
150/// 业务请求结构体需手动实现该 trait;展开细节见 `wordval-macros` 源码内 `tools` 模块文档。
151#[proc_macro_attribute]
152pub fn tools(attr: TokenStream, item: TokenStream) -> TokenStream {
153 tools::tools_impl(attr, item)
154}