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}