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
//! 读路径执行:`find` / `select` / 标量值读取。
use super::bind::{bind_param, bind_scalar_param};
use super::{QueryBuilder, QueryExecutor, SqlGenerator};
impl<'a> QueryBuilder<'a> {
/// 查询单条记录
///
/// 自动添加 LIMIT 1 到查询,返回单条记录或 None
///
/// # 类型参数
/// - T: 结果类型,必须实现 FromRow trait
///
/// # 返回
/// - Ok(Some(T)): 查询成功,返回单条记录
/// - Ok(None): 查询成功,但没有匹配的记录
/// - Err(DbError): 查询执行失败
///
/// # 示例
/// ```no_run
/// use yang_db::Database;
/// use serde::{Deserialize, Serialize};
///
/// #[derive(Debug, Serialize, Deserialize, sqlx::FromRow)]
/// struct User {
/// id: i32,
/// name: String,
/// }
///
/// # async fn example() -> Result<(), yang_db::DbError> {
/// let db = Database::connect("mysql://root:password@localhost/test").await?;
/// let user: Option<User> = db.table(yang_db::table!("users"))
/// .where_and(yang_db::field!("id"), yang_db::CompareOp::Eq, 1)?
/// .find()
/// .await?;
///
/// match user {
/// Some(u) => println!("找到用户: {:?}", u),
/// None => println!("用户不存在"),
/// }
/// # Ok(())
/// # }
/// ```
#[tracing::instrument(
name = "db.query",
skip_all,
fields(db.system = "mysql", db.operation = "select", db.collection = %self.table, otel.kind = "client")
)]
pub async fn find<T>(mut self) -> Result<Option<T>, crate::error::DbError>
where
T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
{
// 自动添加 LIMIT 1
self.limit = Some(1);
// 生成 SQL 语句
let mut generator = SqlGenerator::new();
generator.build_select(&self)?;
let sql = generator.get_sql();
let params = generator.get_params();
// 记录日志
if self.enable_logging {
log::debug!("执行 find() 查询: {}", sql);
log::debug!("参数: {:?}", params);
}
// 构建查询
let mut query = sqlx::query_as::<_, T>(sql);
// 绑定参数
for param in params {
query = bind_param(query, param);
}
// pool 与事务共享同一份查询计划,只在最终执行器上分流。
let result = match self.executor {
QueryExecutor::Pool(pool) => query.fetch_optional(pool).await,
QueryExecutor::Transaction(transaction) => {
let connection = transaction.executor().ok_or_else(|| {
crate::error::DbError::TransactionError("事务已提交或回滚".to_string())
})?;
query.fetch_optional(&mut *connection).await
}
};
match result {
Ok(row) => {
if self.enable_logging {
if row.is_some() {
log::debug!("find() 查询成功,返回 1 条记录");
} else {
log::debug!("find() 查询成功,未找到匹配记录");
}
}
Ok(row)
}
Err(e) => {
log::error!("find() 查询失败: {}", e);
Err(crate::error::DbError::from(e))
}
}
}
/// 查询多条记录
///
/// 执行 SELECT 查询并返回所有匹配的记录
///
/// # 类型参数
/// - T: 结果类型,必须实现 FromRow trait
///
/// # 返回
/// - Ok(Vec<T>): 查询成功,返回匹配的记录列表(可能为空)
/// - Err(DbError): 查询执行失败
///
/// # 示例
/// ```no_run
/// use yang_db::Database;
/// use serde::{Deserialize, Serialize};
///
/// #[derive(Debug, Serialize, Deserialize, sqlx::FromRow)]
/// struct User {
/// id: i32,
/// name: String,
/// }
///
/// # async fn example() -> Result<(), yang_db::DbError> {
/// let db = Database::connect("mysql://root:password@localhost/test").await?;
/// let users: Vec<User> = db.table(yang_db::table!("users"))
/// .where_and(yang_db::field!("status"), yang_db::CompareOp::Eq, 1)?
/// .order(yang_db::field!("name"), yang_db::SortOrder::Asc)
/// .select()
/// .await?;
///
/// println!("找到 {} 个用户", users.len());
/// for user in users {
/// println!("用户: {:?}", user);
/// }
/// # Ok(())
/// # }
/// ```
#[tracing::instrument(
name = "db.query",
skip_all,
fields(db.system = "mysql", db.operation = "select", db.collection = %self.table, otel.kind = "client")
)]
pub async fn select<T>(self) -> Result<Vec<T>, crate::error::DbError>
where
T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
{
// 生成 SQL 语句
let mut generator = SqlGenerator::new();
generator.build_select(&self)?;
let sql = generator.get_sql();
let params = generator.get_params();
// 记录日志
if self.enable_logging {
log::debug!("执行 select() 查询: {}", sql);
log::debug!("参数: {:?}", params);
}
// 构建查询
let mut query = sqlx::query_as::<_, T>(sql);
// 绑定参数
for param in params {
query = bind_param(query, param);
}
// pool 与事务共享同一份查询计划,只在最终执行器上分流。
let result = match self.executor {
QueryExecutor::Pool(pool) => query.fetch_all(pool).await,
QueryExecutor::Transaction(transaction) => {
let connection = transaction.executor().ok_or_else(|| {
crate::error::DbError::TransactionError("事务已提交或回滚".to_string())
})?;
query.fetch_all(&mut *connection).await
}
};
match result {
Ok(rows) => {
if self.enable_logging {
log::debug!("select() 查询成功,返回 {} 条记录", rows.len());
}
Ok(rows)
}
Err(e) => {
log::error!("select() 查询失败: {}", e);
Err(crate::error::DbError::from(e))
}
}
}
/// 标量查询助手(内部)
///
/// 统一 `value` / `sum` / `avg` / `min` / `max` 五个方法的样板:清空字段选择、
/// 只选 `select_expr`、自动加 `LIMIT 1`、生成 SELECT、绑定参数、执行单行单值查询。
///
/// 类型参数 `C` 为 sqlx 解码目标类型:`value` 传 `T`(NULL 列触发解码错误的语义保持不变),
/// 聚合函数传 `Option<U>`(外层再 `Option::flatten`)。生成的 SQL 与参数与各方法原实现逐字节一致。
pub(super) async fn fetch_scalar<C>(
mut self,
select_expr: &str,
) -> Result<Option<C>, crate::error::DbError>
where
C: for<'r> sqlx::Decode<'r, sqlx::MySql> + sqlx::Type<sqlx::MySql> + Send + Unpin,
{
// 清空现有字段选择,只选择指定表达式
self.fields.clear();
self.fields.push(select_expr.to_string());
// 自动添加 LIMIT 1
self.limit = Some(1);
// 生成 SQL 语句
let mut generator = SqlGenerator::new();
generator.build_select(&self)?;
let sql = generator.get_sql();
let params = generator.get_params();
if self.enable_logging {
log::debug!("执行标量查询: {}", sql);
log::debug!("参数: {:?}", params);
}
// query_scalar 直接获取单个值;bind_scalar_param 对任意输出类型通用
let mut query = sqlx::query_scalar::<_, C>(sql);
for param in params {
query = bind_scalar_param(query, param);
}
let result = match self.executor {
QueryExecutor::Pool(pool) => query.fetch_optional(pool).await,
QueryExecutor::Transaction(transaction) => {
let connection = transaction.executor().ok_or_else(|| {
crate::error::DbError::TransactionError("事务已提交或回滚".to_string())
})?;
query.fetch_optional(&mut *connection).await
}
};
match result {
Ok(value) => Ok(value),
Err(e) => {
log::error!("标量查询失败: {}", e);
Err(crate::error::DbError::from(e))
}
}
}
/// 查询单个字段值
///
/// 执行 SELECT 查询并返回指定字段的单个值。自动添加 LIMIT 1 到查询。
///
/// # 参数
/// - field: 要查询的字段名
///
/// # 类型参数
/// - T: 字段值类型,必须实现 sqlx::Decode 和 sqlx::Type trait
///
/// # 返回
/// - Ok(Some(T)): 查询成功,返回字段值
/// - Ok(None): 查询成功,但没有匹配的记录
/// - Err(DbError): 查询执行失败
///
/// # 示例
/// ```no_run
/// use yang_db::Database;
///
/// # async fn example() -> Result<(), yang_db::DbError> {
/// let db = Database::connect("mysql://root:password@localhost/test").await?;
///
/// // 查询用户名
/// let name: Option<String> = db.table(yang_db::table!("users"))
/// .where_and(yang_db::field!("id"), yang_db::CompareOp::Eq, 1)?
/// .value(yang_db::field!("name"))
/// .await?;
///
/// match name {
/// Some(n) => println!("用户名: {}", n),
/// None => println!("用户不存在"),
/// }
///
/// // 查询用户 ID
/// let user_id: Option<i64> = db.table(yang_db::table!("users"))
/// .where_and(yang_db::field!("status"), yang_db::CompareOp::Eq, 1)?
/// .value(yang_db::field!("id"))
/// .await?;
///
/// println!("用户 ID: {:?}", user_id);
/// # Ok(())
/// # }
/// ```
#[tracing::instrument(
name = "db.query",
skip_all,
fields(db.system = "mysql", db.operation = "select", db.collection = %self.table, otel.kind = "client")
)]
pub async fn value<T>(self, field: &crate::FieldRef) -> Result<Option<T>, crate::error::DbError>
where
T: for<'r> sqlx::Decode<'r, sqlx::MySql> + sqlx::Type<sqlx::MySql> + Send + Unpin,
{
if self.enable_logging {
log::debug!("执行 value() 查询,字段: {}", field.as_str());
}
// 直接解码为 T(NULL 列触发解码错误的语义保持不变)
// 验证需求: ID-1 — field 按设计接受 SQL 表达式,与 field() 一致;
// 若字段来自不可信输入,调用方需先通过 quote_identifier 转义
let field = crate::mysql::identifier::quote_identifier(field.as_str())?;
self.fetch_scalar::<T>(&field).await
}
}