Skip to main content

yang_base/table/
entity.rs

1//! TableEntity 类型化基础设施
2//!
3//! 提供 `TableEntity` trait 以及 `WhereOp<V>`、`SqlCondition` 等类型,
4//! 用于 Action 系统的端到端类型安全(H-1)。
5
6#[cfg(feature = "mysql")]
7use crate::table::TableConfig;
8use serde::{Deserialize, Serialize};
9#[cfg(feature = "mysql")]
10use std::hash::Hash;
11
12/// 表实体契约:用户定义的行类型(一般通过 `#[derive(TableEntity)]` 派生)。
13///
14/// 把"行 struct"、"字段名枚举"、"where 条件枚举"、"主键类型"统一在一个 trait 下,
15/// 让整个 Action 系统能从一个 `T` 推导出全部类型化契约。
16#[cfg(feature = "mysql")]
17pub trait TableEntity:
18    serde::de::DeserializeOwned
19    + serde::Serialize
20    + schemars::JsonSchema
21    + for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow>
22    + Send
23    + Sync
24    + Unpin
25    + 'static
26{
27    /// 主键类型(i64 / String / Uuid 等)。
28    type Pk: serde::de::DeserializeOwned
29        + serde::Serialize
30        + schemars::JsonSchema
31        + Send
32        + Sync
33        + 'static;
34
35    /// 字段名枚举(派生生成)。所有合法列名的封闭集合。
36    /// `Eq + Hash` bound 让 `T::Field` 可用作 `HashSet`/`HashMap` 的 key。
37    type Field: AsColumnName
38        + serde::de::DeserializeOwned
39        + serde::Serialize
40        + schemars::JsonSchema
41        + Copy
42        + Eq
43        + Hash
44        + Send
45        + Sync
46        + 'static;
47
48    /// where 条件枚举(派生生成)。每个变体绑定字段类型。
49    type WhereCond: IntoSqlCondition
50        + serde::de::DeserializeOwned
51        + schemars::JsonSchema
52        + Send
53        + Sync
54        + 'static;
55
56    /// 数据库表名,对应 SQL `FROM` 子句。
57    const TABLE_NAME: &'static str;
58    /// 主键列名,对应 SQL `WHERE <PK> = ?`。
59    const PK_FIELD: &'static str;
60
61    /// 运行时表配置。OnceLock 缓存,全程序生成一次。
62    fn table_config() -> &'static TableConfig;
63}
64
65/// 字段名 → 静态列名字符串。所有判别式都映射到 `&'static str`,
66/// 杜绝列名拼接 SQL 注入。
67pub trait AsColumnName {
68    /// 返回对应数据库列名的静态字符串引用。
69    fn column_name(&self) -> &'static str;
70}
71
72/// where 条件 → SqlCondition(运行期 SQL 片段描述)。
73pub trait IntoSqlCondition {
74    /// 将类型化 where 条件转换为运行时 SQL 描述。
75    fn into_sql_condition(self) -> SqlCondition;
76}
77
78/// 通用 where 操作符。
79///
80/// JSON 形态由 `#[serde(tag = "op", content = "value")]` 决定:
81/// `{ "op": "eq", "value": 42 }` / `{ "op": "in", "value": [1,2,3] }` /
82/// `{ "op": "between", "value": [10, 20] }` / `{ "op": "is_null" }`
83#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
84#[serde(tag = "op", content = "value", rename_all = "snake_case")]
85pub enum WhereOp<V> {
86    /// 等于(`= v`)。
87    Eq(V),
88    /// 不等于(`<> v`)。
89    Ne(V),
90    /// 小于(`< v`)。
91    Lt(V),
92    /// 小于等于(`<= v`)。
93    Lte(V),
94    /// 大于(`> v`)。
95    Gt(V),
96    /// 大于等于(`>= v`)。
97    Gte(V),
98    /// 在集合中(`IN (v1, v2, ...)`)。
99    In(Vec<V>),
100    /// 不在集合中(`NOT IN (v1, v2, ...)`)。
101    NotIn(Vec<V>),
102    /// 区间(`BETWEEN a AND b`)。
103    Between(V, V),
104    /// 为 NULL(`IS NULL`)。
105    IsNull,
106    /// 不为 NULL(`IS NOT NULL`)。
107    IsNotNull,
108}
109
110/// 字符串字段专用 where 操作符(额外含 Like)。
111#[derive(Debug, Clone, Deserialize, Serialize, schemars::JsonSchema)]
112#[serde(tag = "op", content = "value", rename_all = "snake_case")]
113pub enum StringWhereOp {
114    /// 等于(`= v`)。
115    Eq(String),
116    /// 不等于(`<> v`)。
117    Ne(String),
118    /// 小于(`< v`)。
119    Lt(String),
120    /// 小于等于(`<= v`)。
121    Lte(String),
122    /// 大于(`> v`)。
123    Gt(String),
124    /// 大于等于(`>= v`)。
125    Gte(String),
126    /// 在集合中(`IN (v1, v2, ...)`)。
127    In(Vec<String>),
128    /// 不在集合中(`NOT IN (v1, v2, ...)`)。
129    NotIn(Vec<String>),
130    /// 区间(`BETWEEN a AND b`)。
131    Between(String, String),
132    /// 模糊匹配(`LIKE pattern`)。
133    Like(String),
134    /// 为 NULL(`IS NULL`)。
135    IsNull,
136    /// 不为 NULL(`IS NOT NULL`)。
137    IsNotNull,
138}
139
140/// 运行时 SQL 条件描述。column 是 `'static str`,绝对安全。
141#[derive(Debug, Clone)]
142pub struct SqlCondition {
143    /// 列名(`'static str`,来自 `AsColumnName::column_name`)。
144    pub column: &'static str,
145    /// SQL 操作符。
146    pub op: SqlOp,
147    /// 绑定参数(JSON 编码,供查询构建器消费)。
148    pub params: Vec<serde_json::Value>,
149}
150
151/// SQL 操作符枚举,对应 WHERE 子句中的各类比较/范围/空值条件。
152#[derive(Debug, Clone, Copy)]
153pub enum SqlOp {
154    /// 等于(`=`)。
155    Eq,
156    /// 不等于(`<>`)。
157    Ne,
158    /// 小于(`<`)。
159    Lt,
160    /// 小于等于(`<=`)。
161    Lte,
162    /// 大于(`>`)。
163    Gt,
164    /// 大于等于(`>=`)。
165    Gte,
166    /// 在集合中(`IN`)。
167    In,
168    /// 不在集合中(`NOT IN`)。
169    NotIn,
170    /// 区间(`BETWEEN`)。
171    Between,
172    /// 模糊匹配(`LIKE`)。
173    Like,
174    /// 为 NULL(`IS NULL`)。
175    IsNull,
176    /// 不为 NULL(`IS NOT NULL`)。
177    IsNotNull,
178}
179
180impl SqlCondition {
181    /// 把运行期 `SqlCondition` 转换为受保护层的 [`WhereCondition`](crate::table::WhereCondition)。
182    ///
183    /// 这是类型化布尔树([`Filter`])桥接到 `TableQuery` 的关键一跳:派生宏产出的
184    /// 类型化叶子先 `into_sql_condition()` 成 `SqlCondition`,再经此转为受保护层
185    /// 能递归校验/渲染的 `WhereCondition` 叶子。
186    ///
187    /// 参数个数不足时(理论上不会发生,派生宏保证)退化为恒真 `1=1`(`NotIn` 空集),
188    /// 不 panic。
189    pub fn into_where_condition(self) -> crate::table::WhereCondition {
190        use crate::table::WhereCondition as WC;
191        let SqlCondition {
192            column,
193            op,
194            mut params,
195        } = self;
196        let field = column.to_string();
197        // 取第 n 个参数,缺失则用 Null 兜底(保持总量不 panic)
198        let take = |params: &mut Vec<serde_json::Value>, i: usize| -> serde_json::Value {
199            params.get(i).cloned().unwrap_or(serde_json::Value::Null)
200        };
201        match op {
202            SqlOp::Eq => WC::Eq {
203                field,
204                value: take(&mut params, 0),
205            },
206            SqlOp::Ne => WC::Ne {
207                field,
208                value: take(&mut params, 0),
209            },
210            SqlOp::Lt => WC::Lt {
211                field,
212                value: take(&mut params, 0),
213            },
214            SqlOp::Lte => WC::Lte {
215                field,
216                value: take(&mut params, 0),
217            },
218            SqlOp::Gt => WC::Gt {
219                field,
220                value: take(&mut params, 0),
221            },
222            SqlOp::Gte => WC::Gte {
223                field,
224                value: take(&mut params, 0),
225            },
226            SqlOp::In => WC::In {
227                field,
228                values: params,
229            },
230            SqlOp::NotIn => WC::NotIn {
231                field,
232                values: params,
233            },
234            SqlOp::Between => {
235                let lo = take(&mut params, 0);
236                let hi = take(&mut params, 1);
237                WC::Between { field, lo, hi }
238            }
239            SqlOp::Like => {
240                let pattern = params
241                    .first()
242                    .and_then(|v| v.as_str())
243                    .unwrap_or("")
244                    .to_string();
245                WC::Like { field, pattern }
246            }
247            SqlOp::IsNull => WC::IsNull { field },
248            SqlOp::IsNotNull => WC::IsNotNull { field },
249        }
250    }
251}
252
253impl<V: serde::Serialize> WhereOp<V> {
254    /// 把通用 WhereOp 转为 SqlCondition(给定列名)。供派生宏生成的 IntoSqlCondition 调用。
255    pub fn to_sql_condition(self, column: &'static str) -> SqlCondition {
256        match self {
257            WhereOp::Eq(v) => SqlCondition {
258                column,
259                op: SqlOp::Eq,
260                params: vec![to_v(v)],
261            },
262            WhereOp::Ne(v) => SqlCondition {
263                column,
264                op: SqlOp::Ne,
265                params: vec![to_v(v)],
266            },
267            WhereOp::Lt(v) => SqlCondition {
268                column,
269                op: SqlOp::Lt,
270                params: vec![to_v(v)],
271            },
272            WhereOp::Lte(v) => SqlCondition {
273                column,
274                op: SqlOp::Lte,
275                params: vec![to_v(v)],
276            },
277            WhereOp::Gt(v) => SqlCondition {
278                column,
279                op: SqlOp::Gt,
280                params: vec![to_v(v)],
281            },
282            WhereOp::Gte(v) => SqlCondition {
283                column,
284                op: SqlOp::Gte,
285                params: vec![to_v(v)],
286            },
287            WhereOp::In(vs) => SqlCondition {
288                column,
289                op: SqlOp::In,
290                params: vs.into_iter().map(to_v).collect(),
291            },
292            WhereOp::NotIn(vs) => SqlCondition {
293                column,
294                op: SqlOp::NotIn,
295                params: vs.into_iter().map(to_v).collect(),
296            },
297            WhereOp::Between(a, b) => SqlCondition {
298                column,
299                op: SqlOp::Between,
300                params: vec![to_v(a), to_v(b)],
301            },
302            WhereOp::IsNull => SqlCondition {
303                column,
304                op: SqlOp::IsNull,
305                params: vec![],
306            },
307            WhereOp::IsNotNull => SqlCondition {
308                column,
309                op: SqlOp::IsNotNull,
310                params: vec![],
311            },
312        }
313    }
314}
315
316impl StringWhereOp {
317    /// 把字符串专用操作符转为 SqlCondition(给定列名)。
318    pub fn to_sql_condition(self, column: &'static str) -> SqlCondition {
319        match self {
320            StringWhereOp::Like(p) => SqlCondition {
321                column,
322                op: SqlOp::Like,
323                params: vec![serde_json::Value::String(p)],
324            },
325            // 其余复用 WhereOp 的语义
326            StringWhereOp::Eq(v) => WhereOp::Eq(v).to_sql_condition(column),
327            StringWhereOp::Ne(v) => WhereOp::Ne(v).to_sql_condition(column),
328            StringWhereOp::Lt(v) => WhereOp::Lt(v).to_sql_condition(column),
329            StringWhereOp::Lte(v) => WhereOp::Lte(v).to_sql_condition(column),
330            StringWhereOp::Gt(v) => WhereOp::Gt(v).to_sql_condition(column),
331            StringWhereOp::Gte(v) => WhereOp::Gte(v).to_sql_condition(column),
332            StringWhereOp::In(vs) => WhereOp::In(vs).to_sql_condition(column),
333            StringWhereOp::NotIn(vs) => WhereOp::NotIn(vs).to_sql_condition(column),
334            StringWhereOp::Between(a, b) => WhereOp::Between(a, b).to_sql_condition(column),
335            StringWhereOp::IsNull => WhereOp::<String>::IsNull.to_sql_condition(column),
336            StringWhereOp::IsNotNull => WhereOp::<String>::IsNotNull.to_sql_condition(column),
337        }
338    }
339}
340
341fn to_v<V: serde::Serialize>(v: V) -> serde_json::Value {
342    serde_json::to_value(v).unwrap_or_else(|e| {
343        // Serialize 实现缺陷理论上不会发生;降级为 Null 而非 panic,避免
344        // 任意 Serialize 异常导致整个 dispatch 崩溃。
345        log::error!("WhereOp 参数序列化失败,降级为 Null: {}", e);
346        serde_json::Value::Null
347    })
348}
349
350/// 类型化布尔过滤树(C2a 类型化层)。
351///
352/// 在类型化叶子 `W`(一般是 `T::WhereCond`,JSON 形态 `{"field":..,"cond":..}`)之上
353/// 叠加 `And`/`Or` 嵌套结构,端到端保持字段名/操作符的编译期类型安全,同时支持任意
354/// 深度的布尔组合。
355///
356/// # JSON 线格式(`#[serde(untagged)]`)
357///
358/// 一个节点是以下三者之一:
359/// - AND 组:`{"and": [<子节点>, ...]}`
360/// - OR 组:`{"or": [<子节点>, ...]}`
361/// - 叶子:直接是 `W` 的形态,如 `{"field":"age","cond":{"op":"gte","value":18}}`
362///
363/// ```json
364/// {
365///   "or": [
366///     {"field": "status", "cond": {"op": "eq", "value": "active"}},
367///     {"and": [
368///       {"field": "age", "cond": {"op": "gte", "value": 18}},
369///       {"field": "vip", "cond": {"op": "eq", "value": true}}
370///     ]}
371///   ]
372/// }
373/// ```
374///
375/// # 与受保护层桥接
376///
377/// [`Filter::into_where_condition`] 把整棵树降解为受保护层的
378/// [`WhereCondition`](crate::table::WhereCondition),叶子经 `IntoSqlCondition` →
379/// `SqlCondition` → `WhereCondition`,由 `TableQuery` 统一做递归权限校验与渲染。
380#[derive(Debug, Clone, Deserialize, schemars::JsonSchema)]
381#[serde(untagged)]
382pub enum Filter<W> {
383    /// AND 组:`{"and": [...]}`,子节点全部成立。
384    And {
385        /// AND 子节点列表
386        and: Vec<Filter<W>>,
387    },
388    /// OR 组:`{"or": [...]}`,子节点任一成立。
389    Or {
390        /// OR 子节点列表
391        or: Vec<Filter<W>>,
392    },
393    /// 叶子节点:直接是类型化 where 条件 `W`。
394    Leaf(W),
395}
396
397impl<W: IntoSqlCondition> Filter<W> {
398    /// 把类型化布尔树降解为受保护层的 [`WhereCondition`](crate::table::WhereCondition)。
399    ///
400    /// 叶子经 `into_sql_condition()` → `into_where_condition()` 转换;组节点递归降解。
401    /// 不做深度限制(受保护层 `TableQuery` 在校验/渲染期统一施加
402    /// `MAX_WHERE_DEPTH` 上限并返回错误)。
403    pub fn into_where_condition(self) -> crate::table::WhereCondition {
404        match self {
405            Filter::Leaf(w) => w.into_sql_condition().into_where_condition(),
406            Filter::And { and } => crate::table::WhereCondition::And {
407                conditions: and.into_iter().map(Filter::into_where_condition).collect(),
408            },
409            Filter::Or { or } => crate::table::WhereCondition::Or {
410                conditions: or.into_iter().map(Filter::into_where_condition).collect(),
411            },
412        }
413    }
414}