Skip to main content

yang_base/database/
global.rs

1//! 全局数据库访问器
2//!
3//! 提供线程安全的全局数据库实例访问。
4//!
5//! # 设计说明
6//!
7//! GlobalDatabase 是对 yang-db::Database 的封装,使用 OnceLock 实现全局单例模式。
8//! 所有数据库操作都通过 yang-db 库实现,确保类型安全和统一的数据库访问接口。
9//!
10//! # 示例
11//!
12//! ```rust,ignore
13//! use yang_base::database::GlobalDatabase;
14//! use yang_db::DatabaseConfig;
15//!
16//! // 初始化全局数据库
17//! GlobalDatabase::init("mysql://user:pass@localhost/db", DatabaseConfig::default()).await?;
18//!
19//! // 使用查询构建器
20//! let users = GlobalDatabase::table("users")?
21//!     .field("id")
22//!     .field("name")
23//!     .select::<User>()
24//!     .await?;
25//!
26//! // 执行原生查询
27//! let result: Vec<User> = GlobalDatabase::query("SELECT * FROM users").await?;
28//!
29//! // 执行原生语句
30//! let affected = GlobalDatabase::execute("DELETE FROM users WHERE id = 1").await?;
31//!
32//! // 使用事务
33//! let mut tx = GlobalDatabase::transaction().await?;
34//! tx.execute("INSERT INTO users (name) VALUES ('Alice')").await?;
35//! tx.commit().await?;
36//! ```
37
38use crate::error::BaseError;
39use std::sync::OnceLock;
40use yang_db::{Database, DatabaseConfig, QueryBuilder, Transaction};
41
42/// 全局数据库实例
43///
44/// 使用 OnceLock 确保线程安全的单例模式
45static GLOBAL_DB: OnceLock<Database> = OnceLock::new();
46
47/// 全局数据库访问器
48///
49/// 封装 yang-db::Database,提供全局静态访问接口。
50/// 所有数据库操作都通过 yang-db 库实现。
51pub struct GlobalDatabase;
52
53impl GlobalDatabase {
54    /// 初始化全局数据库
55    ///
56    /// # 参数
57    ///
58    /// - `url`: 数据库连接字符串,格式:`mysql://user:password@host:port/database`
59    /// - `config`: 数据库配置,包含连接池参数
60    ///
61    /// # 返回
62    ///
63    /// - `Ok(())`: 初始化成功
64    /// - `Err(BaseError)`: 初始化失败
65    ///
66    /// # 错误
67    ///
68    /// - `DatabaseConnectionFailed`: 数据库连接失败(包装 DbError 保留错误链)
69    /// - `DatabaseAlreadyInitialized`: 数据库已经初始化
70    ///
71    /// # 说明
72    ///
73    /// 使用 yang-db::Database::connect_with_config 创建数据库连接。
74    /// 此方法只能调用一次,重复调用将返回错误。
75    ///
76    /// # 示例
77    ///
78    /// ```rust,ignore
79    /// use yang_base::database::GlobalDatabase;
80    /// use yang_db::DatabaseConfig;
81    ///
82    /// let config = DatabaseConfig::default()
83    ///     .with_min_connections(2)
84    ///     .with_max_lifetime(Some(1800));
85    ///
86    /// GlobalDatabase::init("mysql://root:password@localhost/test", config).await?;
87    /// ```
88    pub async fn init(url: &str, config: DatabaseConfig) -> Result<(), BaseError> {
89        // 使用 yang-db::Database::connect_with_config 创建数据库连接
90        let db = Database::connect_with_config(url, config)
91            .await
92            .map_err(BaseError::DatabaseConnectionFailed)?;
93
94        // 设置全局数据库实例
95        GLOBAL_DB
96            .set(db)
97            .map_err(|_| BaseError::DatabaseAlreadyInitialized)?;
98
99        log::info!("全局数据库已初始化");
100        Ok(())
101    }
102
103    /// 获取全局数据库实例
104    ///
105    /// # 返回
106    ///
107    /// - `Ok(&'static Database)`: yang-db::Database 实例的静态引用
108    /// - `Err(BaseError)`: 数据库未初始化
109    ///
110    /// # 错误
111    ///
112    /// - `DatabaseNotInitialized`: 数据库未初始化,需要先调用 `init` 方法
113    ///
114    /// # API 一致性说明 (A-M4)
115    ///
116    /// 本方法名为 `get()`,而 Redis 对等方法名为
117    /// [`GlobalRedis::client()`](crate::database::GlobalRedis::client)。
118    /// 这是历史命名不对称,未来应统一为同一种命名风格(例如都叫 `get()` 或都叫
119    /// `client()`)。
120    ///
121    /// # 示例
122    ///
123    /// ```rust,ignore
124    /// let db = GlobalDatabase::get()?;
125    /// let builder = db.table("users");
126    /// ```
127    pub fn get() -> Result<&'static Database, BaseError> {
128        GLOBAL_DB.get().ok_or(BaseError::DatabaseNotInitialized)
129    }
130
131    /// 选择表,返回查询构建器
132    ///
133    /// # 参数
134    ///
135    /// - `table_name`: 表名
136    ///
137    /// # 返回
138    ///
139    /// - `Ok(QueryBuilder)`: yang-db 查询构建器
140    /// - `Err(BaseError)`: 数据库未初始化
141    ///
142    /// # 说明
143    ///
144    /// 调用 yang-db::Database::table 方法创建查询构建器。
145    /// 返回的 QueryBuilder 可以链式调用各种查询方法。
146    ///
147    /// # 示例
148    ///
149    /// ```rust,ignore
150    /// // 查询用户
151    /// let users = GlobalDatabase::table("users")?
152    ///     .field("id")
153    ///     .field("name")
154    ///     .where_eq("status", 1)
155    ///     .select::<User>()
156    ///     .await?;
157    ///
158    /// // 插入数据
159    /// GlobalDatabase::table("users")?
160    ///     .insert(vec![
161    ///         ("name", "Alice"),
162    ///         ("email", "alice@example.com"),
163    ///     ])
164    ///     .await?;
165    /// ```
166    pub fn table(table_name: &str) -> Result<QueryBuilder<'static>, BaseError> {
167        Ok(Self::get()?.table(table_name))
168    }
169
170    /// 执行原生 SELECT 查询
171    ///
172    /// # 参数
173    ///
174    /// - `sql`: SQL 查询语句
175    ///
176    /// # 返回
177    ///
178    /// - `Ok(Vec<T>)`: 查询结果列表
179    /// - `Err(BaseError)`: 查询失败
180    ///
181    /// # 类型参数
182    ///
183    /// - `T`: 结果类型,必须实现 `sqlx::FromRow` trait
184    ///
185    /// # 错误
186    ///
187    /// - `DatabaseNotInitialized`: 数据库未初始化
188    /// - `DatabaseQueryFailed`: 查询执行失败
189    ///
190    /// # 说明
191    ///
192    /// 调用 yang-db::Database::query 方法执行原生 SQL 查询。
193    /// 适用于复杂查询或查询构建器无法满足的场景。
194    ///
195    /// # 示例
196    ///
197    /// ```rust,ignore
198    /// #[derive(sqlx::FromRow)]
199    /// struct User {
200    ///     id: i32,
201    ///     name: String,
202    /// }
203    ///
204    /// let users: Vec<User> = GlobalDatabase::query(
205    ///     "SELECT id, name FROM users WHERE status = 1"
206    /// ).await?;
207    /// ```
208    #[allow(deprecated)]
209    pub async fn query<T>(sql: &str) -> Result<Vec<T>, BaseError>
210    where
211        T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
212    {
213        Self::get()?
214            .query(sql)
215            .await
216            .map_err(BaseError::DatabaseQueryFailed)
217    }
218
219    /// 执行参数化 SELECT 查询
220    ///
221    /// # 参数
222    ///
223    /// - `sql`: 包含 `?` 占位符的 SQL 查询语句
224    /// - `params`: 按占位符顺序绑定的参数
225    pub async fn query_with_params<T>(
226        sql: &str,
227        params: Vec<serde_json::Value>,
228    ) -> Result<Vec<T>, BaseError>
229    where
230        T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
231    {
232        Self::get()?
233            .query_with_params(sql, params)
234            .await
235            .map_err(BaseError::DatabaseQueryFailed)
236    }
237
238    /// 执行原生 INSERT/UPDATE/DELETE 查询
239    ///
240    /// # 参数
241    ///
242    /// - `sql`: SQL 语句
243    ///
244    /// # 返回
245    ///
246    /// - `Ok(u64)`: 受影响的行数
247    /// - `Err(BaseError)`: 执行失败
248    ///
249    /// # 错误
250    ///
251    /// - `DatabaseNotInitialized`: 数据库未初始化
252    /// - `DatabaseExecuteFailed`: 语句执行失败
253    ///
254    /// # 说明
255    ///
256    /// 调用 yang-db::Database::execute 方法执行原生 SQL 语句。
257    /// 适用于 INSERT、UPDATE、DELETE 等修改数据的操作。
258    ///
259    /// # 示例
260    ///
261    /// ```rust,ignore
262    /// // 插入数据
263    /// let affected = GlobalDatabase::execute(
264    ///     "INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')"
265    /// ).await?;
266    ///
267    /// // 更新数据
268    /// let affected = GlobalDatabase::execute(
269    ///     "UPDATE users SET status = 1 WHERE id = 1"
270    /// ).await?;
271    ///
272    /// // 删除数据
273    /// let affected = GlobalDatabase::execute(
274    ///     "DELETE FROM users WHERE id = 1"
275    /// ).await?;
276    /// ```
277    #[allow(deprecated)]
278    pub async fn execute(sql: &str) -> Result<u64, BaseError> {
279        Self::get()?
280            .execute(sql)
281            .await
282            .map_err(BaseError::DatabaseExecuteFailed)
283    }
284
285    /// 执行参数化 INSERT/UPDATE/DELETE 查询
286    ///
287    /// # 参数
288    ///
289    /// - `sql`: 包含 `?` 占位符的 SQL 语句
290    /// - `params`: 按占位符顺序绑定的参数
291    pub async fn execute_with_params(
292        sql: &str,
293        params: Vec<serde_json::Value>,
294    ) -> Result<u64, BaseError> {
295        Self::get()?
296            .execute_with_params(sql, params)
297            .await
298            .map_err(BaseError::DatabaseExecuteFailed)
299    }
300
301    /// 开始事务
302    ///
303    /// # 返回
304    ///
305    /// - `Ok(Transaction)`: yang-db 事务对象
306    /// - `Err(BaseError)`: 开始事务失败
307    ///
308    /// # 错误
309    ///
310    /// - `DatabaseNotInitialized`: 数据库未初始化
311    /// - `DatabaseTransactionFailed`: 开始事务失败
312    ///
313    /// # 说明
314    ///
315    /// 调用 yang-db::Database::transaction 方法创建事务。
316    /// 事务中的所有操作要么全部成功,要么全部回滚。
317    ///
318    /// # 示例
319    ///
320    /// ```rust,ignore
321    /// // 开始事务
322    /// let mut tx = GlobalDatabase::transaction().await?;
323    ///
324    /// // 在事务中执行操作
325    /// tx.execute("INSERT INTO users (name) VALUES ('Alice')").await?;
326    /// tx.execute("INSERT INTO logs (action) VALUES ('user_created')").await?;
327    ///
328    /// // 提交事务
329    /// tx.commit().await?;
330    ///
331    /// // 或者回滚事务
332    /// // tx.rollback().await?;
333    /// ```
334    pub async fn transaction() -> Result<Transaction, BaseError> {
335        Self::get()?
336            .transaction()
337            .await
338            .map_err(BaseError::DatabaseTransactionFailed)
339    }
340
341    /// 数据库健康检查
342    ///
343    /// 通过执行 `SELECT 1` 验证数据库连接是否可用。查询返回非空结果即视为健康。
344    ///
345    /// # 返回
346    ///
347    /// - `Ok(true)`: 数据库连接正常
348    /// - `Ok(false)`: 查询成功但未返回结果(异常状态)
349    /// - `Err(BaseError)`: 数据库未初始化或查询失败
350    ///
351    /// # 错误
352    ///
353    /// - `DatabaseNotInitialized`: 数据库未初始化,需要先调用 `init` 方法
354    /// - `DatabaseQueryFailed`: 健康检查查询执行失败
355    pub async fn health_check() -> Result<bool, BaseError> {
356        let rows = Self::query::<(i64,)>("SELECT 1").await?;
357        Ok(!rows.is_empty())
358    }
359
360    /// 获取数据库连接池状态快照
361    ///
362    /// 转发 yang-db `Database::pool_status`,与 [`GlobalRedis::pool_status`](crate::database::GlobalRedis)
363    /// 对称。用于监控连接池水位、排查连接耗尽。
364    ///
365    /// # 返回
366    ///
367    /// - `Ok(PoolStatus)`: 连接池状态(max_size/size/available/waiting)
368    /// - `Err(BaseError::DatabaseNotInitialized)`: 数据库未初始化
369    pub fn pool_status() -> Result<yang_db::PoolStatus, BaseError> {
370        Ok(Self::get()?.pool_status())
371    }
372
373    /// 优雅关闭全局数据库连接池(I3):停止发放新连接、等待在途连接归还后关闭。
374    ///
375    /// 供编排式停机([`crate::lifecycle`])调用。`OnceLock` 单例不重置,仅原地 drain
376    /// 连接池——**停机后不应再 dispatch**,再用会得到连接池关闭错误。未初始化时为 no-op。
377    pub async fn close() {
378        if let Some(db) = GLOBAL_DB.get() {
379            db.close().await;
380        }
381    }
382}
383
384#[cfg(test)]
385mod tests {
386    use super::*;
387
388    #[test]
389    fn test_database_not_initialized() {
390        // 测试未初始化时获取数据库实例
391        let result = GlobalDatabase::get();
392        assert!(result.is_err());
393        assert!(matches!(result, Err(BaseError::DatabaseNotInitialized)));
394    }
395
396    #[test]
397    fn test_table_not_initialized() {
398        // 测试未初始化时调用 table 方法
399        let result = GlobalDatabase::table("users");
400        assert!(result.is_err());
401        assert!(matches!(result, Err(BaseError::DatabaseNotInitialized)));
402    }
403
404    #[tokio::test]
405    async fn test_query_with_params_not_initialized() {
406        // 测试未初始化时调用参数化查询方法
407        let result = GlobalDatabase::query_with_params::<(i32,)>(
408            "SELECT id FROM users WHERE id = ?",
409            vec![serde_json::json!(1)],
410        )
411        .await;
412        assert!(result.is_err());
413        assert!(matches!(result, Err(BaseError::DatabaseNotInitialized)));
414    }
415
416    #[tokio::test]
417    async fn test_execute_with_params_not_initialized() {
418        // 测试未初始化时调用参数化执行方法
419        let result = GlobalDatabase::execute_with_params(
420            "DELETE FROM users WHERE id = ?",
421            vec![serde_json::json!(1)],
422        )
423        .await;
424        assert!(result.is_err());
425        assert!(matches!(result, Err(BaseError::DatabaseNotInitialized)));
426    }
427}