1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
use crate::error::DbError;
use crate::mysql::query_builder::QueryBuilder;
use log;
use sqlx::Transaction as SqlxTransaction;
/// 数据库事务
pub struct Transaction {
tx: Option<SqlxTransaction<'static, sqlx::MySql>>,
enable_logging: bool,
}
impl Transaction {
/// 创建新的事务实例
pub(crate) fn new(tx: SqlxTransaction<'static, sqlx::MySql>, enable_logging: bool) -> Self {
Self {
tx: Some(tx),
enable_logging,
}
}
/// 提交事务
pub async fn commit(mut self) -> Result<(), DbError> {
if self.enable_logging {
log::debug!("提交事务");
}
if let Some(tx) = self.tx.take() {
tx.commit().await?;
}
Ok(())
}
/// 回滚事务
pub async fn rollback(mut self) -> Result<(), DbError> {
if self.enable_logging {
log::debug!("回滚事务");
}
if let Some(tx) = self.tx.take() {
tx.rollback().await?;
}
Ok(())
}
/// 执行原生 SQL
///
/// ⚠️ 安全警告:此方法接受裸 SQL 字符串,不进行参数化处理。调用方必须确保 SQL
/// 字符串不包含用户输入,否则存在 SQL 注入风险。请优先使用 [`execute_with_params`]。
#[deprecated(
since = "0.1.0",
note = "使用 execute_with_params 替代,避免 SQL 注入风险"
)]
pub async fn execute(&mut self, sql: &str) -> Result<u64, DbError> {
if self.enable_logging {
log::debug!("事务中执行: {}", sql);
}
if let Some(tx) = &mut self.tx {
let result = sqlx::query(sql).execute(&mut **tx).await?;
Ok(result.rows_affected())
} else {
Err(DbError::TransactionError("事务已提交或回滚".to_string()))
}
}
/// 执行带参数的原生 SQL(参数化查询,防止 SQL 注入)
///
/// # 参数
/// - sql: SQL 语句,使用 `?` 作为参数占位符
/// - params: 参数列表,使用 `serde_json::Value` 类型
///
/// # 返回
/// - Ok(u64): 受影响的行数
/// - Err(DbError): 执行失败错误
///
/// # 示例
///
/// ```no_run
/// use yang_db::Database;
/// use serde_json::json;
///
/// # async fn example() -> Result<(), yang_db::DbError> {
/// let db = Database::connect("mysql://root:password@localhost/test").await?;
/// let mut tx = db.transaction().await?;
/// let params = vec![json!("张三"), json!("张三@example.com")];
/// tx.execute_with_params("INSERT INTO users (name, email) VALUES (?, ?)", params).await?;
/// tx.commit().await?;
/// # Ok(())
/// # }
/// ```
pub async fn execute_with_params(
&mut self,
sql: &str,
params: Vec<serde_json::Value>,
) -> Result<u64, DbError> {
if self.enable_logging {
log::debug!("事务中执行参数化语句: {}, 参数数量: {}", sql, params.len());
}
if let Some(tx) = &mut self.tx {
// 构建查询并逐一绑定参数
let mut query = sqlx::query(sql);
for param in ¶ms {
query = bind_json_param_tx(query, param);
}
let result = query.execute(&mut **tx).await?;
Ok(result.rows_affected())
} else {
Err(DbError::TransactionError("事务已提交或回滚".to_string()))
}
}
/// 执行带参数的原生 SELECT 查询(参数化查询,防止 SQL 注入)
///
/// # 参数
/// - sql: SQL 查询语句,使用 `?` 作为参数占位符
/// - params: 参数列表,使用 `serde_json::Value` 类型
///
/// # 返回
/// - Ok(Vec<T>): 查询结果列表
/// - Err(DbError): 查询失败错误
///
/// # 示例
///
/// ```no_run
/// use yang_db::Database;
/// use serde_json::json;
///
/// # async fn example() -> Result<(), yang_db::DbError> {
/// let db = Database::connect("mysql://root:password@localhost/test").await?;
/// let mut tx = db.transaction().await?;
/// let params = vec![json!(1i64)];
/// // let users: Vec<User> = tx.query_with_params("SELECT * FROM users WHERE id = ?", params).await?;
/// tx.commit().await?;
/// # Ok(())
/// # }
/// ```
pub async fn query_with_params<T>(
&mut self,
sql: &str,
params: Vec<serde_json::Value>,
) -> Result<Vec<T>, DbError>
where
T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
{
if self.enable_logging {
log::debug!("事务中执行参数化查询: {}, 参数数量: {}", sql, params.len());
}
if let Some(tx) = &mut self.tx {
// 构建查询并逐一绑定参数
let mut query = sqlx::query_as::<_, T>(sql);
for param in ¶ms {
query = bind_json_param_as_tx(query, param);
}
let rows = query.fetch_all(&mut **tx).await?;
Ok(rows)
} else {
Err(DbError::TransactionError("事务已提交或回滚".to_string()))
}
}
/// 在当前事务中执行普通 QueryBuilder SELECT。
pub async fn select<T>(&mut self, query: QueryBuilder<'_>) -> Result<Vec<T>, DbError>
where
T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
{
self.select_with_optional_lock(query, None).await
}
/// 在当前事务中执行 `FOR UPDATE` SELECT。
pub async fn select_for_update<T>(&mut self, query: QueryBuilder<'_>) -> Result<Vec<T>, DbError>
where
T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
{
self.select_locked(query, crate::RowLock::ForUpdate).await
}
/// 在当前事务中执行 `FOR SHARE` SELECT。
pub async fn select_for_share<T>(&mut self, query: QueryBuilder<'_>) -> Result<Vec<T>, DbError>
where
T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
{
self.select_locked(query, crate::RowLock::ForShare).await
}
/// 在当前事务中按指定模式执行行锁 SELECT。
pub async fn select_locked<T>(
&mut self,
query: QueryBuilder<'_>,
lock: crate::RowLock,
) -> Result<Vec<T>, DbError>
where
T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
{
self.select_with_optional_lock(query, Some(lock)).await
}
async fn select_with_optional_lock<T>(
&mut self,
query: QueryBuilder<'_>,
lock: Option<crate::RowLock>,
) -> Result<Vec<T>, DbError>
where
T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
{
let (sql, params) = query.render_for_transaction(lock)?;
if self.enable_logging {
log::debug!("事务中执行 SELECT: {}, 参数: {:?}", sql, params);
}
let tx = self
.tx
.as_mut()
.ok_or_else(|| DbError::TransactionError("事务已提交或回滚".to_string()))?;
let mut sql_query = sqlx::query_as::<_, T>(&sql);
for param in ¶ms {
sql_query = crate::mysql::query_builder::bind_param(sql_query, param);
}
Ok(sql_query.fetch_all(&mut **tx).await?)
}
/// 选择表,返回事务中的查询构建器
///
/// # 参数
/// - table_name: 表名
///
/// # 返回
/// - QueryBuilder: 与连接池路径共享的事务查询构建器
///
/// # 示例
/// ```no_run
/// use yang_db::Database;
/// use serde_json::json;
///
/// # async fn example() -> Result<(), yang_db::DbError> {
/// let db = Database::connect("mysql://root:password@localhost/test").await?;
/// let mut tx = db.transaction().await?;
///
/// // 在事务中插入数据
/// let user_data = json!({"name": "张三", "email": "zhangsan@example.com"});
/// let user_id = tx.table(yang_db::table!("users")).insert(&user_data).await?;
///
/// // 在事务中更新数据
/// let update_data = json!({"status": 1});
/// tx.table(yang_db::table!("users"))
/// .where_and(yang_db::field!("id"), yang_db::CompareOp::Eq, user_id)?
/// .update(&update_data)
/// .await?;
///
/// // 提交事务
/// tx.commit().await?;
/// # Ok(())
/// # }
/// ```
pub fn table(&mut self, table: &crate::TableRef) -> QueryBuilder<'_> {
let enable_logging = self.enable_logging;
QueryBuilder::new_transaction(self, table.as_str(), enable_logging)
}
/// 借出底层 sqlx 连接(受控逃生舱,供同 workspace 上层在事务内执行自构建的参数化语句)
///
/// 上层(如 yang-base 受保护层)已持有自己构建好的、参数全部 `?` 绑定的
/// SQL 与参数,需要在**同一事务**里执行以保证原子性。`Transaction` 自身
/// 仅提供 `insert/update/delete` 三个高层方法,无法承载受保护层的权限/软删/
/// 校验语义,故开放此逃生舱让上层直接拿到 `&mut MySqlConnection` 执行。
///
/// 标记 `#[doc(hidden)]`:非稳定公开 API,仅供 workspace 内部桥接使用,
/// 调用方必须保证 SQL 标识符安全(值侧由 `?` 绑定,标识符由调用方转义)。
///
/// # 返回
/// - `Some(&mut MySqlConnection)`:事务仍处于活动状态
/// - `None`:事务已 `commit`/`rollback`,连接不再可用
// SAFETY: 此方法暴露底层数据库连接,调用方可执行任意 SQL。
// 仅限 workspace 内部桥接使用,外部代码不得调用。
#[doc(hidden)]
pub fn executor(&mut self) -> Option<&mut sqlx::MySqlConnection> {
// `SqlxTransaction` 通过 DerefMut 解引用为底层 MySqlConnection
self.tx.as_deref_mut()
}
}
impl Drop for Transaction {
fn drop(&mut self) {
if self.tx.is_some() {
log::warn!(
"事务被丢弃而未提交/回滚——底层将自动回滚。请显式调用 commit() 或 rollback()。"
);
}
}
}
fn bind_json_param_tx<'q>(
query: sqlx::query::Query<'q, sqlx::MySql, sqlx::mysql::MySqlArguments>,
param: &serde_json::Value,
) -> sqlx::query::Query<'q, sqlx::MySql, sqlx::mysql::MySqlArguments> {
match param {
serde_json::Value::String(value) => query.bind(value.clone()),
serde_json::Value::Number(value) => match crate::json_param::classify_json_number(value) {
Some(crate::json_param::JsonNumber::Int(i)) => query.bind(i),
Some(crate::json_param::JsonNumber::Uint(u)) => query.bind(u.to_string()),
Some(crate::json_param::JsonNumber::Float(f)) => query.bind(f.to_string()),
None => query.bind(Option::<String>::None),
},
serde_json::Value::Bool(value) => query.bind(*value),
serde_json::Value::Null => query.bind(Option::<String>::None),
other => query.bind(other.to_string()),
}
}
fn bind_json_param_as_tx<'q, T>(
query: sqlx::query::QueryAs<'q, sqlx::MySql, T, sqlx::mysql::MySqlArguments>,
param: &serde_json::Value,
) -> sqlx::query::QueryAs<'q, sqlx::MySql, T, sqlx::mysql::MySqlArguments>
where
T: for<'row> sqlx::FromRow<'row, sqlx::mysql::MySqlRow>,
{
match param {
serde_json::Value::String(value) => query.bind(value.clone()),
serde_json::Value::Number(value) => match crate::json_param::classify_json_number(value) {
Some(crate::json_param::JsonNumber::Int(i)) => query.bind(i),
Some(crate::json_param::JsonNumber::Uint(u)) => query.bind(u.to_string()),
Some(crate::json_param::JsonNumber::Float(f)) => query.bind(f.to_string()),
None => query.bind(Option::<String>::None),
},
serde_json::Value::Bool(value) => query.bind(*value),
serde_json::Value::Null => query.bind(Option::<String>::None),
other => query.bind(other.to_string()),
}
}