Skip to main content

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}