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}