Skip to main content

yang_base/table/table_query/
write.rs

1//! 写入执行(`mysql` feature):insert/update/delete 及事务内变体,
2//! 含插入数据准备(默认值/时间戳/租户注入)与更新数据校验。
3
4#![cfg(feature = "mysql")]
5
6use super::TableQuery;
7use crate::error::BaseError;
8use serde_json::Value;
9
10impl TableQuery {
11    /// 执行 INSERT 操作
12    ///
13    /// 插入数据到表中,包括以下步骤:
14    /// 1. 按表定义验证所有字段值
15    /// 2. 检查用户是否有字段的写入权限
16    /// 3. 构建 INSERT SQL 语句
17    /// 4. 执行插入操作
18    /// 5. 返回影响行数
19    ///
20    /// # 参数
21    ///
22    /// - `data`:要插入的 [`crate::table::Record`]
23    ///
24    /// # 返回值
25    ///
26    /// - `Ok(u64)`:插入成功,返回影响行数(通常为 1)
27    /// - `Err(BaseError)`:插入失败,返回错误
28    ///
29    /// # 错误
30    ///
31    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
32    /// - `BaseError::FieldRequired`:必填字段缺失
33    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
34    /// - `BaseError::ValidationFailed`:字段值验证失败
35    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
36    ///
37    /// # 示例
38    ///
39    /// ```rust,ignore
40    /// use yang_base::table::Record;
41    ///
42    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
43    /// let data = Record::new()
44    ///     .set("name", "张三")
45    ///     .set("email", "zhangsan@example.com");
46    ///
47    /// // 执行插入
48    /// let affected = query.insert(data).await?;
49    /// println!("插入成功,影响行数: {}", affected);
50    /// # Ok(())
51    /// # }
52    /// ```
53    pub async fn insert(self, data: crate::table::Record) -> Result<u64, BaseError> {
54        // 填充默认值/时间戳并校验(顺序:写权限→填充默认值→必填/类型校验)
55        let data = self.prepare_and_validate_insert(data.into_columns())?;
56        self.compile_db_write_query()?
57            .insert(&data)
58            .await
59            .map_err(BaseError::DatabaseExecuteFailed)?;
60        Ok(1)
61    }
62
63    /// 在事务中执行 INSERT 操作
64    ///
65    /// 与 [`TableQuery::insert`] 完全一致的写权限校验/默认值填充/时间戳/必填校验
66    /// 流程,但在调用方提供的事务内执行,可与其它写操作原子提交。
67    ///
68    /// # 错误
69    ///
70    /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
71    /// - 其余同 [`TableQuery::insert`]
72    pub async fn insert_in_tx(
73        self,
74        tx: &mut yang_db::Transaction,
75        data: crate::table::Record,
76    ) -> Result<u64, BaseError> {
77        let data = self.prepare_and_validate_insert(data.into_columns())?;
78        let query = tx.table(&self.table_config.table_ref);
79        self.apply_write_plan(query)?
80            .insert(&data)
81            .await
82            .map_err(BaseError::DatabaseExecuteFailed)?;
83        Ok(1)
84    }
85
86    /// 执行 INSERT 操作并返回自增主键
87    ///
88    /// 与 [`TableQuery::insert`] 完全一致的校验与拼 SQL 流程,但额外返回本次
89    /// INSERT 产生的自增主键值(`last_insert_id`),便于调用方拿到新建记录 ID。
90    ///
91    /// # 参数
92    ///
93    /// - `data`:要插入的数据
94    ///
95    /// # 返回值
96    ///
97    /// - `Ok((affected, id))`:插入成功,返回 (影响行数, 自增主键值)。
98    ///   表无自增列时 `id` 为 0。
99    /// - `Err(BaseError)`:插入失败
100    ///
101    /// # 错误
102    ///
103    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
104    /// - `BaseError::FieldRequired`:必填字段缺失
105    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
106    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
107    pub async fn insert_returning_id(
108        self,
109        data: crate::table::Record,
110    ) -> Result<(u64, u64), BaseError> {
111        let data = self.prepare_and_validate_insert(data.into_columns())?;
112        let id = self
113            .compile_db_write_query()?
114            .insert(&data)
115            .await
116            .map_err(BaseError::DatabaseExecuteFailed)?;
117        Ok((1, id))
118    }
119
120    /// 在事务中执行 INSERT 并返回自增主键
121    ///
122    /// 与 [`TableQuery::insert_returning_id`] 一致,但在事务内执行。批量写入或
123    /// 「插入父行→用其主键插入子行」等需要拿到新 ID 再继续的原子场景使用。
124    pub async fn insert_returning_id_in_tx(
125        self,
126        tx: &mut yang_db::Transaction,
127        data: crate::table::Record,
128    ) -> Result<(u64, u64), BaseError> {
129        let data = self.prepare_and_validate_insert(data.into_columns())?;
130        let query = tx.table(&self.table_config.table_ref);
131        let id = self
132            .apply_write_plan(query)?
133            .insert(&data)
134            .await
135            .map_err(BaseError::DatabaseExecuteFailed)?;
136        Ok((1, id))
137    }
138
139    /// 填充默认值/时间戳并验证插入数据
140    ///
141    /// 处理顺序(修复 required+default 字段被误报 FieldRequired 的问题):
142    /// 1. 字段与写权限校验:显式提交只读字段时拒绝;null 自增主键视为未提供
143    /// 2. 规范化数据库生成字段:未提供或为 null 的自增字段交给数据库生成
144    /// 3. 填充默认值:data 中缺失且配置了 `default_value` 的字段补默认值
145    /// 4. 填充时间戳:`timestamp_fields` 配置且列存在、调用方未提供时,写入当前时间
146    /// 5. 必填/类型/验证器校验:在补齐后的数据上执行
147    ///
148    /// # 参数
149    ///
150    /// - `data`:调用方提供的原始插入数据
151    ///
152    /// # 返回值
153    ///
154    /// - `Ok(HashMap)`:补齐默认值与时间戳后的最终插入数据
155    /// - `Err(BaseError)`:权限或校验失败
156    pub(crate) fn prepare_and_validate_insert(
157        &self,
158        data: std::collections::HashMap<String, Value>,
159    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
160        let mut prepared = data;
161
162        // tenant key 只能由请求上下文注入,业务输入不得覆盖。
163        if let Some((field, value)) = &self.tenant_scope {
164            if prepared.contains_key(field) {
165                return Err(BaseError::PermissionDenied(format!(
166                    "禁止显式写入租户字段: {field}"
167                )));
168            }
169            prepared.insert(field.clone(), value.clone());
170        }
171
172        // 1. 校验调用方显式提交的字段和写权限。只有 null 自增主键可视为“未提供”,
173        // 其余只读字段即使提交 null 也必须拒绝,避免绕过字段边界并覆盖数据库默认值。
174        for (field_name, value) in &prepared {
175            let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
176                BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
177            })?;
178            let omitted_auto_increment = field_config.auto_increment && value.is_null();
179            let injected_tenant = self
180                .tenant_scope
181                .as_ref()
182                .is_some_and(|(tenant_field, _)| tenant_field == field_name);
183            if !injected_tenant
184                && !omitted_auto_increment
185                && !field_config.permissions.can_write(&self.user_roles_set)
186            {
187                return Err(BaseError::FieldPermissionDenied(
188                    self.table_config.table_name.clone(),
189                    field_name.clone(),
190                    "用户无写入权限".to_string(),
191                ));
192            }
193        }
194
195        // 2. 数据库生成的自增字段未提供或为 null 时,不进入 INSERT 字段列表。
196        for (field_name, field_config) in &self.table_config.fields {
197            if field_config.auto_increment
198                && prepared
199                    .get(field_name)
200                    .map(serde_json::Value::is_null)
201                    .unwrap_or(true)
202            {
203                prepared.remove(field_name);
204            }
205        }
206
207        // 3. 填充默认值(仅缺失时;显式 null 仍受 nullable/required 约束)
208        for (field_name, field_config) in &self.table_config.fields {
209            if field_config.auto_increment {
210                continue;
211            }
212            if let Some(default) = &field_config.default_value {
213                if !prepared.contains_key(field_name) {
214                    prepared.insert(field_name.clone(), default.clone());
215                }
216            }
217        }
218
219        // 4. 填充创建/更新时间戳(列存在且调用方未提供时)
220        if let Some(ts) = &self.table_config.timestamp_fields {
221            let now = chrono::Utc::now().timestamp();
222            for ts_field in [&ts.created_at, &ts.updated_at].into_iter().flatten() {
223                if self.table_config.fields.contains_key(ts_field) {
224                    let missing = prepared.get(ts_field).map(|v| v.is_null()).unwrap_or(true);
225                    if missing {
226                        prepared.insert(ts_field.clone(), Value::Number(now.into()));
227                    }
228                }
229            }
230        }
231
232        // 5. 在补齐后的数据上执行必填/类型/验证器校验
233        for (field_name, field_config) in &self.table_config.fields {
234            if !field_config.permissions.can_write(&self.user_roles_set) {
235                continue;
236            }
237            if field_config.auto_increment && !prepared.contains_key(field_name) {
238                continue;
239            }
240            let value = prepared.get(field_name).unwrap_or(&Value::Null);
241            field_config.validate(value, &self.regex_cache)?;
242        }
243
244        Ok(prepared)
245    }
246
247    /// 执行 UPDATE 操作
248    ///
249    /// 更新表中的数据,包括以下步骤:
250    /// 1. 按表定义验证所有字段值
251    /// 2. 检查用户是否有字段的写入权限
252    /// 3. 构建 UPDATE SQL 语句
253    /// 4. 应用已配置的 WHERE 条件
254    /// 5. 执行更新操作
255    /// 6. 返回影响行数
256    ///
257    /// # 参数
258    ///
259    /// - `data`:要更新的 [`crate::table::Record`]
260    ///
261    /// # 返回值
262    ///
263    /// - `Ok(u64)`:更新成功,返回影响行数
264    /// - `Err(BaseError)`:更新失败,返回错误
265    ///
266    /// # 错误
267    ///
268    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
269    /// - `BaseError::FieldNotFound`:字段不存在
270    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
271    /// - `BaseError::ValidationFailed`:字段值验证失败
272    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
273    ///
274    /// # 示例
275    ///
276    /// ```rust,ignore
277    /// use yang_base::table::Record;
278    /// use serde_json::json;
279    ///
280    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
281    /// let data = Record::new()
282    ///     .set("name", "李四")
283    ///     .set("email", "lisi@example.com");
284    ///
285    /// // 执行更新(需要先设置 WHERE 条件)
286    /// let affected = query
287    ///     .where_eq("id", json!(1))?
288    ///     .update(data)
289    ///     .await?;
290    /// println!("更新成功,影响行数: {}", affected);
291    /// # Ok(())
292    /// # }
293    /// ```
294    pub async fn update(self, data: crate::table::Record) -> Result<u64, BaseError> {
295        let data = self.prepare_update_data(data.into_columns())?;
296        self.compile_db_write_query()?
297            .update(&data)
298            .await
299            .map_err(BaseError::DatabaseExecuteFailed)
300    }
301
302    /// 在事务中执行 UPDATE 操作
303    ///
304    /// 与 [`TableQuery::update`] 一致的字段校验/权限/WHERE 守卫/自动 `updated_at`
305    /// 逻辑,但在事务内执行。
306    ///
307    /// # 错误
308    ///
309    /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
310    /// - 其余同 [`TableQuery::update`]
311    pub async fn update_in_tx(
312        self,
313        tx: &mut yang_db::Transaction,
314        data: crate::table::Record,
315    ) -> Result<u64, BaseError> {
316        let data = self.prepare_update_data(data.into_columns())?;
317        let query = tx.table(&self.table_config.table_ref);
318        self.apply_write_plan(query)?
319            .update(&data)
320            .await
321            .map_err(BaseError::DatabaseExecuteFailed)
322    }
323
324    fn prepare_update_data(
325        &self,
326        data: std::collections::HashMap<String, Value>,
327    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
328        self.validate_update_data(&data)?;
329        self.with_updated_timestamp(data)
330    }
331
332    fn with_updated_timestamp(
333        &self,
334        mut data: std::collections::HashMap<String, Value>,
335    ) -> Result<std::collections::HashMap<String, Value>, BaseError> {
336        if data.is_empty() {
337            return Err(BaseError::ParamInvalid(
338                "data".to_string(),
339                "无可更新字段".to_string(),
340            ));
341        }
342        if let Some(updated_at) = self
343            .table_config
344            .timestamp_fields
345            .as_ref()
346            .and_then(|fields| fields.updated_at.as_ref())
347            .filter(|name| self.table_config.fields.contains_key(*name))
348        {
349            data.insert(
350                updated_at.clone(),
351                Value::Number(chrono::Utc::now().timestamp().into()),
352            );
353        }
354        Ok(data)
355    }
356
357    /// 验证更新数据
358    ///
359    /// 验证所有要更新的字段值的合法性和用户权限
360    ///
361    /// # 参数
362    ///
363    /// - `data`:要更新的数据
364    ///
365    /// # 返回值
366    ///
367    /// - `Ok(())`:验证通过
368    /// - `Err(BaseError)`:验证失败
369    ///
370    /// # 错误
371    ///
372    /// - `BaseError::FieldNotFound`:字段不存在
373    /// - `BaseError::FieldPermissionDenied`:用户无字段写入权限
374    /// - `BaseError::ValidationFailed`:字段值验证失败
375    #[cfg(test)]
376    pub fn validate_update_data(
377        &self,
378        data: &std::collections::HashMap<String, Value>,
379    ) -> Result<(), BaseError> {
380        self.validate_update_data_impl(data)
381    }
382
383    /// 验证更新数据(内部实现)
384    #[cfg(not(test))]
385    fn validate_update_data(
386        &self,
387        data: &std::collections::HashMap<String, Value>,
388    ) -> Result<(), BaseError> {
389        self.validate_update_data_impl(data)
390    }
391
392    /// 验证更新数据的实际实现
393    fn validate_update_data_impl(
394        &self,
395        data: &std::collections::HashMap<String, Value>,
396    ) -> Result<(), BaseError> {
397        if data.is_empty() {
398            return Err(BaseError::ParamInvalid(
399                "data".to_string(),
400                "至少需要一个更新字段".to_string(),
401            ));
402        }
403        // 只验证提供的字段(与 INSERT 不同,UPDATE 不需要验证所有字段)
404        for (field_name, value) in data {
405            if self
406                .tenant_scope
407                .as_ref()
408                .is_some_and(|(tenant_field, _)| tenant_field == field_name)
409            {
410                return Err(BaseError::PermissionDenied(format!(
411                    "禁止修改租户字段: {field_name}"
412                )));
413            }
414            // 1. 检查字段是否存在于表配置中
415            let field_config = self.table_config.get_field(field_name).ok_or_else(|| {
416                BaseError::FieldNotFound(self.table_config.table_name.clone(), field_name.clone())
417            })?;
418
419            // 2. 检查用户是否有写入权限
420            if !field_config.permissions.can_write(&self.user_roles_set) {
421                return Err(BaseError::FieldPermissionDenied(
422                    self.table_config.table_name.clone(),
423                    field_name.clone(),
424                    "用户无写入权限".to_string(),
425                ));
426            }
427
428            // 3. 验证显式提供的字段值。部分更新不要求提交其它必填字段,但若本字段
429            // 被显式设为 null,仍执行 required 约束。
430            field_config.validate(value, &self.regex_cache)?;
431        }
432
433        Ok(())
434    }
435
436    /// 执行 DELETE 操作
437    ///
438    /// 删除表中的数据,支持软删除和物理删除两种模式:
439    /// 1. 如果配置了软删除字段(soft_delete_field),执行 UPDATE 设置删除标记
440    /// 2. 如果未配置软删除字段,执行物理删除
441    /// 3. 应用已配置的 WHERE 条件
442    /// 4. 返回影响行数
443    ///
444    /// # 返回值
445    ///
446    /// - `Ok(u64)`:删除成功,返回影响行数
447    /// - `Err(BaseError)`:删除失败,返回错误
448    ///
449    /// # 错误
450    ///
451    /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
452    /// - `BaseError::DatabaseExecuteFailed`:数据库执行失败
453    ///
454    /// # 示例
455    ///
456    /// ```rust,ignore
457    /// use serde_json::json;
458    /// use yang_base::table::{Field, Table};
459    ///
460    /// # async fn example() -> Result<(), yang_base::error::BaseError> {
461    /// let users = Table::new("users")
462    ///     .fields(vec![
463    ///         Field::id("id"),
464    ///         Field::string("name", 50).required(),
465    ///         Field::soft_delete("deleted_at"),
466    ///     ])
467    ///     .build()?;
468    ///
469    /// // 执行软删除(实际上是 UPDATE deleted_at = <timestamp>)
470    /// let affected = users
471    ///     .bind(pool)
472    ///     .query(["admin"])
473    ///     .where_eq("id", json!(1))?
474    ///     .delete()
475    ///     .await?;
476    /// println!("删除成功,影响行数: {}", affected);
477    /// # Ok(())
478    /// # }
479    /// ```
480    pub async fn delete(self) -> Result<u64, BaseError> {
481        if let Some(soft_delete_field) = &self.table_config.soft_delete_field {
482            let data = self.with_updated_timestamp(std::collections::HashMap::from([(
483                soft_delete_field.clone(),
484                Value::Number(chrono::Utc::now().timestamp().into()),
485            )]))?;
486            return self
487                .compile_db_write_query()?
488                .update(&data)
489                .await
490                .map_err(BaseError::DatabaseExecuteFailed);
491        }
492        self.compile_db_write_query()?
493            .delete()
494            .await
495            .map_err(BaseError::DatabaseExecuteFailed)
496    }
497
498    /// 在事务中执行 DELETE 操作
499    ///
500    /// 与 [`TableQuery::delete`] 一致:配置了软删除字段时走 UPDATE 标记(同样在
501    /// 事务内),否则物理删除;WHERE 守卫与软删语义完全复用。
502    ///
503    /// # 错误
504    ///
505    /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚
506    /// - 其余同 [`TableQuery::delete`]
507    pub async fn delete_in_tx(self, tx: &mut yang_db::Transaction) -> Result<u64, BaseError> {
508        let query = tx.table(&self.table_config.table_ref);
509        if let Some(soft_delete_field) = &self.table_config.soft_delete_field {
510            let data = self.with_updated_timestamp(std::collections::HashMap::from([(
511                soft_delete_field.clone(),
512                Value::Number(chrono::Utc::now().timestamp().into()),
513            )]))?;
514            return self
515                .apply_write_plan(query)?
516                .update(&data)
517                .await
518                .map_err(BaseError::DatabaseExecuteFailed);
519        }
520        self.apply_write_plan(query)?
521            .delete()
522            .await
523            .map_err(BaseError::DatabaseExecuteFailed)
524    }
525}