yang-base 0.1.2

个人使用构建后端服务器
Documentation
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
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
//! 全局数据库访问器
//!
//! 提供线程安全的全局数据库实例访问。
//!
//! # 设计说明
//!
//! GlobalDatabase 是对 yang-db::Database 的封装,使用 OnceLock 实现全局单例模式。
//! 所有数据库操作都通过 yang-db 库实现,确保类型安全和统一的数据库访问接口。
//!
//! # 示例
//!
//! ```rust,ignore
//! use yang_base::database::GlobalDatabase;
//! use yang_db::DatabaseConfig;
//!
//! // 初始化全局数据库
//! GlobalDatabase::init("mysql://user:pass@localhost/db", DatabaseConfig::default()).await?;
//!
//! // 使用查询构建器
//! let users = GlobalDatabase::table("users")?
//!     .field("id")
//!     .field("name")
//!     .select::<User>()
//!     .await?;
//!
//! // 执行原生查询
//! let result: Vec<User> = GlobalDatabase::query("SELECT * FROM users").await?;
//!
//! // 执行原生语句
//! let affected = GlobalDatabase::execute("DELETE FROM users WHERE id = 1").await?;
//!
//! // 使用事务
//! let mut tx = GlobalDatabase::transaction().await?;
//! tx.execute("INSERT INTO users (name) VALUES ('Alice')").await?;
//! tx.commit().await?;
//! ```

use crate::error::BaseError;
use std::sync::OnceLock;
use yang_db::{Database, DatabaseConfig, QueryBuilder, Transaction};

/// 全局数据库实例
///
/// 使用 OnceLock 确保线程安全的单例模式
static GLOBAL_DB: OnceLock<Database> = OnceLock::new();

/// 全局数据库访问器
///
/// 封装 yang-db::Database,提供全局静态访问接口。
/// 所有数据库操作都通过 yang-db 库实现。
pub struct GlobalDatabase;

impl GlobalDatabase {
    /// 初始化全局数据库
    ///
    /// # 参数
    ///
    /// - `url`: 数据库连接字符串,格式:`mysql://user:password@host:port/database`
    /// - `config`: 数据库配置,包含连接池参数
    ///
    /// # 返回
    ///
    /// - `Ok(())`: 初始化成功
    /// - `Err(BaseError)`: 初始化失败
    ///
    /// # 错误
    ///
    /// - `DatabaseConnectionFailed`: 数据库连接失败(包装 DbError 保留错误链)
    /// - `DatabaseAlreadyInitialized`: 数据库已经初始化
    ///
    /// # 说明
    ///
    /// 使用 yang-db::Database::connect_with_config 创建数据库连接。
    /// 此方法只能调用一次,重复调用将返回错误。
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// use yang_base::database::GlobalDatabase;
    /// use yang_db::DatabaseConfig;
    ///
    /// let config = DatabaseConfig::default()
    ///     .with_min_connections(2)
    ///     .with_max_lifetime(Some(1800));
    ///
    /// GlobalDatabase::init("mysql://root:password@localhost/test", config).await?;
    /// ```
    pub async fn init(url: &str, config: DatabaseConfig) -> Result<(), BaseError> {
        // 使用 yang-db::Database::connect_with_config 创建数据库连接
        let db = Database::connect_with_config(url, config)
            .await
            .map_err(BaseError::DatabaseConnectionFailed)?;

        // 设置全局数据库实例
        GLOBAL_DB
            .set(db)
            .map_err(|_| BaseError::DatabaseAlreadyInitialized)?;

        log::info!("全局数据库已初始化");
        Ok(())
    }

    /// 获取全局数据库实例
    ///
    /// # 返回
    ///
    /// - `Ok(&'static Database)`: yang-db::Database 实例的静态引用
    /// - `Err(BaseError)`: 数据库未初始化
    ///
    /// # 错误
    ///
    /// - `DatabaseNotInitialized`: 数据库未初始化,需要先调用 `init` 方法
    ///
    /// # API 一致性说明 (A-M4)
    ///
    /// 本方法名为 `get()`,而 Redis 对等方法名为
    /// [`GlobalRedis::client()`](crate::database::GlobalRedis::client)。
    /// 这是历史命名不对称,未来应统一为同一种命名风格(例如都叫 `get()` 或都叫
    /// `client()`)。
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// let db = GlobalDatabase::get()?;
    /// let builder = db.table("users");
    /// ```
    pub fn get() -> Result<&'static Database, BaseError> {
        GLOBAL_DB.get().ok_or(BaseError::DatabaseNotInitialized)
    }

    /// 选择表,返回查询构建器
    ///
    /// # 参数
    ///
    /// - `table_name`: 表名
    ///
    /// # 返回
    ///
    /// - `Ok(QueryBuilder)`: yang-db 查询构建器
    /// - `Err(BaseError)`: 数据库未初始化
    ///
    /// # 说明
    ///
    /// 调用 yang-db::Database::table 方法创建查询构建器。
    /// 返回的 QueryBuilder 可以链式调用各种查询方法。
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// // 查询用户
    /// let users = GlobalDatabase::table("users")?
    ///     .field("id")
    ///     .field("name")
    ///     .where_eq("status", 1)
    ///     .select::<User>()
    ///     .await?;
    ///
    /// // 插入数据
    /// GlobalDatabase::table("users")?
    ///     .insert(vec![
    ///         ("name", "Alice"),
    ///         ("email", "alice@example.com"),
    ///     ])
    ///     .await?;
    /// ```
    pub fn table(table_name: &str) -> Result<QueryBuilder<'static>, BaseError> {
        Ok(Self::get()?.table(table_name))
    }

    /// 执行原生 SELECT 查询
    ///
    /// # 参数
    ///
    /// - `sql`: SQL 查询语句
    ///
    /// # 返回
    ///
    /// - `Ok(Vec<T>)`: 查询结果列表
    /// - `Err(BaseError)`: 查询失败
    ///
    /// # 类型参数
    ///
    /// - `T`: 结果类型,必须实现 `sqlx::FromRow` trait
    ///
    /// # 错误
    ///
    /// - `DatabaseNotInitialized`: 数据库未初始化
    /// - `DatabaseQueryFailed`: 查询执行失败
    ///
    /// # 说明
    ///
    /// 调用 yang-db::Database::query 方法执行原生 SQL 查询。
    /// 适用于复杂查询或查询构建器无法满足的场景。
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// #[derive(sqlx::FromRow)]
    /// struct User {
    ///     id: i32,
    ///     name: String,
    /// }
    ///
    /// let users: Vec<User> = GlobalDatabase::query(
    ///     "SELECT id, name FROM users WHERE status = 1"
    /// ).await?;
    /// ```
    #[allow(deprecated)]
    pub async fn query<T>(sql: &str) -> Result<Vec<T>, BaseError>
    where
        T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
    {
        Self::get()?
            .query(sql)
            .await
            .map_err(BaseError::DatabaseQueryFailed)
    }

    /// 执行参数化 SELECT 查询
    ///
    /// # 参数
    ///
    /// - `sql`: 包含 `?` 占位符的 SQL 查询语句
    /// - `params`: 按占位符顺序绑定的参数
    pub async fn query_with_params<T>(
        sql: &str,
        params: Vec<serde_json::Value>,
    ) -> Result<Vec<T>, BaseError>
    where
        T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin,
    {
        Self::get()?
            .query_with_params(sql, params)
            .await
            .map_err(BaseError::DatabaseQueryFailed)
    }

    /// 执行原生 INSERT/UPDATE/DELETE 查询
    ///
    /// # 参数
    ///
    /// - `sql`: SQL 语句
    ///
    /// # 返回
    ///
    /// - `Ok(u64)`: 受影响的行数
    /// - `Err(BaseError)`: 执行失败
    ///
    /// # 错误
    ///
    /// - `DatabaseNotInitialized`: 数据库未初始化
    /// - `DatabaseExecuteFailed`: 语句执行失败
    ///
    /// # 说明
    ///
    /// 调用 yang-db::Database::execute 方法执行原生 SQL 语句。
    /// 适用于 INSERT、UPDATE、DELETE 等修改数据的操作。
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// // 插入数据
    /// let affected = GlobalDatabase::execute(
    ///     "INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com')"
    /// ).await?;
    ///
    /// // 更新数据
    /// let affected = GlobalDatabase::execute(
    ///     "UPDATE users SET status = 1 WHERE id = 1"
    /// ).await?;
    ///
    /// // 删除数据
    /// let affected = GlobalDatabase::execute(
    ///     "DELETE FROM users WHERE id = 1"
    /// ).await?;
    /// ```
    #[allow(deprecated)]
    pub async fn execute(sql: &str) -> Result<u64, BaseError> {
        Self::get()?
            .execute(sql)
            .await
            .map_err(BaseError::DatabaseExecuteFailed)
    }

    /// 执行参数化 INSERT/UPDATE/DELETE 查询
    ///
    /// # 参数
    ///
    /// - `sql`: 包含 `?` 占位符的 SQL 语句
    /// - `params`: 按占位符顺序绑定的参数
    pub async fn execute_with_params(
        sql: &str,
        params: Vec<serde_json::Value>,
    ) -> Result<u64, BaseError> {
        Self::get()?
            .execute_with_params(sql, params)
            .await
            .map_err(BaseError::DatabaseExecuteFailed)
    }

    /// 开始事务
    ///
    /// # 返回
    ///
    /// - `Ok(Transaction)`: yang-db 事务对象
    /// - `Err(BaseError)`: 开始事务失败
    ///
    /// # 错误
    ///
    /// - `DatabaseNotInitialized`: 数据库未初始化
    /// - `DatabaseTransactionFailed`: 开始事务失败
    ///
    /// # 说明
    ///
    /// 调用 yang-db::Database::transaction 方法创建事务。
    /// 事务中的所有操作要么全部成功,要么全部回滚。
    ///
    /// # 示例
    ///
    /// ```rust,ignore
    /// // 开始事务
    /// let mut tx = GlobalDatabase::transaction().await?;
    ///
    /// // 在事务中执行操作
    /// tx.execute("INSERT INTO users (name) VALUES ('Alice')").await?;
    /// tx.execute("INSERT INTO logs (action) VALUES ('user_created')").await?;
    ///
    /// // 提交事务
    /// tx.commit().await?;
    ///
    /// // 或者回滚事务
    /// // tx.rollback().await?;
    /// ```
    pub async fn transaction() -> Result<Transaction, BaseError> {
        Self::get()?
            .transaction()
            .await
            .map_err(BaseError::DatabaseTransactionFailed)
    }

    /// 数据库健康检查
    ///
    /// 通过执行 `SELECT 1` 验证数据库连接是否可用。查询返回非空结果即视为健康。
    ///
    /// # 返回
    ///
    /// - `Ok(true)`: 数据库连接正常
    /// - `Ok(false)`: 查询成功但未返回结果(异常状态)
    /// - `Err(BaseError)`: 数据库未初始化或查询失败
    ///
    /// # 错误
    ///
    /// - `DatabaseNotInitialized`: 数据库未初始化,需要先调用 `init` 方法
    /// - `DatabaseQueryFailed`: 健康检查查询执行失败
    pub async fn health_check() -> Result<bool, BaseError> {
        let rows = Self::query::<(i64,)>("SELECT 1").await?;
        Ok(!rows.is_empty())
    }

    /// 获取数据库连接池状态快照
    ///
    /// 转发 yang-db `Database::pool_status`,与 [`GlobalRedis::pool_status`](crate::database::GlobalRedis)
    /// 对称。用于监控连接池水位、排查连接耗尽。
    ///
    /// # 返回
    ///
    /// - `Ok(PoolStatus)`: 连接池状态(max_size/size/available/waiting)
    /// - `Err(BaseError::DatabaseNotInitialized)`: 数据库未初始化
    pub fn pool_status() -> Result<yang_db::PoolStatus, BaseError> {
        Ok(Self::get()?.pool_status())
    }

    /// 优雅关闭全局数据库连接池(I3):停止发放新连接、等待在途连接归还后关闭。
    ///
    /// 供编排式停机([`crate::lifecycle`])调用。`OnceLock` 单例不重置,仅原地 drain
    /// 连接池——**停机后不应再 dispatch**,再用会得到连接池关闭错误。未初始化时为 no-op。
    pub async fn close() {
        if let Some(db) = GLOBAL_DB.get() {
            db.close().await;
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_database_not_initialized() {
        // 测试未初始化时获取数据库实例
        let result = GlobalDatabase::get();
        assert!(result.is_err());
        assert!(matches!(result, Err(BaseError::DatabaseNotInitialized)));
    }

    #[test]
    fn test_table_not_initialized() {
        // 测试未初始化时调用 table 方法
        let result = GlobalDatabase::table("users");
        assert!(result.is_err());
        assert!(matches!(result, Err(BaseError::DatabaseNotInitialized)));
    }

    #[tokio::test]
    async fn test_query_with_params_not_initialized() {
        // 测试未初始化时调用参数化查询方法
        let result = GlobalDatabase::query_with_params::<(i32,)>(
            "SELECT id FROM users WHERE id = ?",
            vec![serde_json::json!(1)],
        )
        .await;
        assert!(result.is_err());
        assert!(matches!(result, Err(BaseError::DatabaseNotInitialized)));
    }

    #[tokio::test]
    async fn test_execute_with_params_not_initialized() {
        // 测试未初始化时调用参数化执行方法
        let result = GlobalDatabase::execute_with_params(
            "DELETE FROM users WHERE id = ?",
            vec![serde_json::json!(1)],
        )
        .await;
        assert!(result.is_err());
        assert!(matches!(result, Err(BaseError::DatabaseNotInitialized)));
    }
}