yang_base/table/table_query/read.rs
1//! 读取执行(`mysql` feature):select/all/optional/one/count/paginate 及事务内变体。
2
3#![cfg(feature = "mysql")]
4
5use super::TableQuery;
6use crate::error::BaseError;
7use serde::Serialize;
8
9/// 数据库执行方法(需要启用 `mysql` feature)
10impl TableQuery {
11 /// 执行分页查询操作
12 ///
13 /// 执行分页查询,包括以下步骤:
14 /// 1. 执行 COUNT(*) 查询获取总记录数
15 /// 2. 计算 LIMIT 和 OFFSET
16 /// 3. 执行数据查询
17 /// 4. 计算总页数
18 /// 5. 构建并返回 PaginatedResult
19 ///
20 /// # 类型参数
21 ///
22 /// - `T`:结果类型,必须实现 `sqlx::FromRow` 和 `Serialize` trait
23 ///
24 /// # 返回值
25 ///
26 /// - `Ok(PaginatedResult<T>)`:查询成功,返回分页结果
27 /// - `Err(BaseError)`:查询失败,返回错误
28 ///
29 /// # 错误
30 ///
31 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
32 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
33 ///
34 pub(crate) fn with_effective_pagination(self) -> Result<(Self, usize, usize), BaseError> {
35 let page = self.query_params.page.unwrap_or(1);
36 let page_size = self
37 .query_params
38 .page_size
39 .unwrap_or(crate::table::query_params::DEFAULT_QUERY_PAGE_SIZE);
40 let query = self.page(page, page_size)?;
41
42 Ok((query, page, page_size))
43 }
44
45 /// 执行分页查询。
46 ///
47 /// 未显式设置分页时会使用默认页码和默认每页大小,并确保数据查询带有 `LIMIT/OFFSET`。
48 pub(crate) async fn paginate<T>(self) -> Result<crate::table::PaginatedResult<T>, BaseError>
49 where
50 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin + Serialize,
51 {
52 // 1. 检查数据库连接池是否存在
53 let _pool = self
54 .pool
55 .as_ref()
56 .ok_or(BaseError::DatabaseNotInitialized)?;
57
58 // 2. 获取分页参数,如果未设置则使用默认值,并写回数据查询
59 let (query, page, page_size) = self.with_effective_pagination()?;
60
61 // 3. 执行 COUNT(*) 查询获取总记录数
62 let total = query.count_internal().await?;
63
64 // 4. 如果总记录数为 0,直接返回空结果
65 if total == 0 {
66 return Ok(crate::table::PaginatedResult::empty(page, page_size));
67 }
68
69 // 5. 执行数据查询
70 let data = query.select().await?;
71
72 // 6. 构建并返回 PaginatedResult
73 Ok(crate::table::PaginatedResult::new(
74 data, total, page, page_size,
75 ))
76 }
77
78 /// 执行分页查询并返回 schema-first [`Record`](crate::table::Record)。
79 pub async fn paginate_records(
80 self,
81 ) -> Result<crate::table::PaginatedResult<crate::table::Record>, BaseError> {
82 self.paginate::<crate::table::Record>().await
83 }
84
85 /// 执行 COUNT 查询获取总记录数(内部方法,供 paginate 使用)
86 ///
87 /// 构建 COUNT(*) SQL 语句,应用已配置的 WHERE 条件,执行查询并返回总记录数。
88 /// 返回 `usize` 以与 `PaginatedResult::new` 的 `total: usize` 参数直接匹配;
89 /// 公开接口 `count()` 通过 `as u64` 适配。
90 ///
91 /// # 返回值
92 ///
93 /// - `Ok(usize)`:查询成功,返回总记录数
94 /// - `Err(BaseError)`:查询失败,返回错误
95 ///
96 /// # 错误
97 ///
98 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
99 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
100 async fn count_internal(&self) -> Result<usize, BaseError> {
101 // COUNT 会泄露表基数,因此与 SELECT 使用相同的可读权限守卫。
102 self.ensure_readable_projection()?;
103 // 分页只约束当前页数据,不应改变总记录数。尤其是 OFFSET > 0 时,
104 // MySQL 会把 COUNT(*) 的唯一结果行跳过,进而把非空结果误判为 0。
105 let mut count_query = self.clone();
106 count_query.query_params.page = None;
107 count_query.query_params.page_size = None;
108 let count = count_query
109 .compile_db_query()?
110 .count()
111 .await
112 .map_err(BaseError::DatabaseQueryFailed)?;
113 usize::try_from(count).map_err(|_| {
114 BaseError::DatabaseQueryFailed(yang_db::DbError::QueryError(
115 "COUNT 结果超出 usize 范围".to_string(),
116 ))
117 })
118 }
119
120 /// 执行 COUNT 查询获取总记录数
121 ///
122 /// 构建 COUNT(*) SQL 语句,应用已配置的 WHERE 条件,执行查询并返回总记录数。
123 ///
124 /// # 返回值
125 ///
126 /// - `Ok(u64)`:查询成功,返回总记录数
127 /// - `Err(BaseError)`:查询失败,返回错误
128 ///
129 /// # 错误
130 ///
131 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
132 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
133 ///
134 /// # 示例
135 ///
136 /// ```rust,ignore
137 /// let total = query
138 /// .where_eq("status", serde_json::json!("active"))?
139 /// .count()
140 /// .await?;
141 ///
142 /// println!("总记录数: {}", total);
143 /// ```
144 pub async fn count(self) -> Result<u64, BaseError> {
145 self.count_internal().await.map(|n| n as u64)
146 }
147
148 /// 执行 SELECT 查询操作
149 ///
150 /// 使用 sqlx 构建 SELECT 语句,应用已配置的字段选择、WHERE 条件和排序规则,
151 /// 执行查询并将结果反序列化为指定的泛型类型 T。
152 ///
153 /// # 类型参数
154 ///
155 /// - `T`:结果类型,必须实现 `sqlx::FromRow` trait
156 ///
157 /// # 返回值
158 ///
159 /// - `Ok(Vec<T>)`:查询成功,返回结果列表
160 /// - `Err(BaseError)`:查询失败,返回错误
161 ///
162 /// # 错误
163 ///
164 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
165 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
166 ///
167 pub(crate) async fn select<T>(self) -> Result<Vec<T>, BaseError>
168 where
169 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
170 {
171 self.compile_db_query()?
172 .select::<T>()
173 .await
174 .map_err(BaseError::DatabaseQueryFailed)
175 }
176
177 /// 查询全部匹配记录。
178 pub async fn all(self) -> Result<Vec<crate::table::Record>, BaseError> {
179 self.select::<crate::table::Record>().await
180 }
181
182 /// 在事务中执行 SELECT 查询并返回多条记录
183 ///
184 /// 与 [`TableQuery::select`] 完全一致的建句与权限/软删逻辑,但在调用方提供的
185 /// `yang_db::Transaction` 内执行,使「读-改-写」场景的读取与后续写入处于同一
186 /// 事务、看到一致快照。
187 ///
188 /// # 参数
189 ///
190 /// - `tx`:由 [`ActionContext::begin_transaction`](crate::action::ActionContext::begin_transaction)
191 /// 或 [`Tools`](crate::tools::Tools) 所有数据库实例创建的活动事务
192 ///
193 /// # 错误
194 ///
195 /// - `BaseError::DatabaseTransactionFailed`:事务已提交/回滚,连接不可用
196 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
197 pub(crate) async fn select_in_tx<T>(
198 self,
199 tx: &mut yang_db::Transaction,
200 ) -> Result<Vec<T>, BaseError>
201 where
202 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
203 {
204 let query = tx.table(&self.table_config.table_ref);
205 self.apply_db_plan(query)?
206 .select::<T>()
207 .await
208 .map_err(BaseError::DatabaseQueryFailed)
209 }
210
211 /// 在事务中查询全部匹配记录。
212 pub async fn all_in_tx(
213 self,
214 tx: &mut yang_db::Transaction,
215 ) -> Result<Vec<crate::table::Record>, BaseError> {
216 self.select_in_tx::<crate::table::Record>(tx).await
217 }
218
219 /// 执行查询并返回可选的单条记录
220 ///
221 /// 执行 SELECT 查询,返回第一条匹配记录,如果没有匹配记录则返回 None。
222 /// 通常与 `where_eq` 等条件方法配合使用,用于按主键查询单条记录。
223 ///
224 /// # 类型参数
225 ///
226 /// - `T`:结果类型,必须实现 `sqlx::FromRow` trait
227 ///
228 /// # 返回值
229 ///
230 /// - `Ok(Some(T))`:找到匹配记录
231 /// - `Ok(None)`:没有匹配记录
232 /// - `Err(BaseError)`:查询失败
233 ///
234 /// # 错误
235 ///
236 /// - `BaseError::DatabaseNotInitialized`:数据库未初始化
237 /// - `BaseError::DatabaseQueryFailed`:查询执行失败
238 ///
239 /// # 示例
240 ///
241 /// ```rust,ignore
242 /// use yang_base::table::Record;
243 ///
244 /// # async fn example() -> Result<(), yang_base::error::BaseError> {
245 /// // 按主键查询单条记录
246 /// let row: Option<Record> = query
247 /// .where_eq("id", serde_json::json!(1))?
248 /// .fetch_optional()
249 /// .await?;
250 ///
251 /// match row {
252 /// Some(r) => println!("找到记录: {:?}", r.columns),
253 /// None => println!("记录不存在"),
254 /// }
255 /// # Ok(())
256 /// # }
257 /// ```
258 pub(crate) async fn fetch_optional<T>(self) -> Result<Option<T>, BaseError>
259 where
260 T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
261 {
262 self.compile_db_query()?
263 .find::<T>()
264 .await
265 .map_err(BaseError::DatabaseQueryFailed)
266 }
267
268 /// 查询可选单条记录。
269 pub async fn optional(self) -> Result<Option<crate::table::Record>, BaseError> {
270 self.fetch_optional::<crate::table::Record>().await
271 }
272
273 /// 查询单条记录;没有匹配记录时返回 [`BaseError::RecordNotFound`]。
274 pub async fn one(self) -> Result<crate::table::Record, BaseError> {
275 let table_name = self.table_config.table_name.clone();
276 self.optional()
277 .await?
278 .ok_or_else(|| BaseError::RecordNotFound(format!("表 {table_name} 中没有匹配记录")))
279 }
280}