yang-base 0.6.0

个人使用构建后端服务器
Documentation
# GlobalDatabase 实现说明


## 概述


GlobalDatabase 是对 yang-db::Database 的封装,提供线程安全的全局数据库访问接口。

## 实现特性


### 1. 全局单例模式


使用 `std::sync::OnceLock` 实现线程安全的全局单例:

```rust
static GLOBAL_DB: OnceLock<Database> = OnceLock::new();
```

### 2. 核心方法


#### init - 初始化全局数据库


```rust
pub async fn init(url: &str, config: DatabaseConfig) -> Result<(), BaseError>
```

- 使用 `yang-db::Database::connect_with_config` 创建数据库连接
- 只能调用一次,重复调用返回 `DatabaseAlreadyInitialized` 错误
- 连接失败返回 `DatabaseConnectionFailed` 错误

#### get - 获取数据库实例


```rust
pub fn get() -> Result<&'static Database, BaseError>
```

- 返回全局数据库实例的静态引用
- 未初始化时返回 `DatabaseNotInitialized` 错误

#### table - 创建查询构建器


```rust
pub fn table(table_name: &str) -> Result<QueryBuilder<'static>, BaseError>
```

- 调用 `yang-db::Database::table` 方法
- 返回 yang-db 的 QueryBuilder,支持链式调用

#### query - 执行 SELECT 查询


```rust
pub async fn query<T>(sql: &str) -> Result<Vec<T>, BaseError>
where
    T: for<'r> sqlx::FromRow<'r, sqlx::mysql::MySqlRow> + Send + Unpin
```

- 调用 `yang-db::Database::query` 方法
- 适用于原生 SQL 查询

#### execute - 执行 INSERT/UPDATE/DELETE


```rust
pub async fn execute(sql: &str) -> Result<u64, BaseError>
```

- 调用 `yang-db::Database::execute` 方法
- 返回受影响的行数

#### transaction - 开始事务


```rust
pub async fn transaction() -> Result<Transaction, BaseError>
```

- 调用 `yang-db::Database::transaction` 方法
- 返回 yang-db 的 Transaction 对象

## 使用示例


### 基本使用


```rust
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?;
```

### 事务使用


```rust
// 开始事务
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?;
```

## 错误处理


所有方法都返回 `Result<T, BaseError>`,主要错误类型:

- `DatabaseNotInitialized`: 数据库未初始化
- `DatabaseAlreadyInitialized`: 数据库已初始化(重复初始化)
- `DatabaseConnectionFailed`: 数据库连接失败
- `DatabaseQueryFailed`: 查询执行失败
- `DatabaseExecuteFailed`: 语句执行失败
- `DatabaseTransactionFailed`: 事务操作失败

## 测试


### 单元测试


位于 `src/database/global.rs` 的 `tests` 模块:

- `test_database_not_initialized`: 测试未初始化时的错误处理
- `test_table_not_initialized`: 测试未初始化时调用 table 方法

### 集成测试


位于 `tests/database_test.rs`:

- `test_global_database_init`: 测试数据库初始化(需要真实数据库)

### 示例代码


位于 `examples/database_example.rs`:

- 完整的使用示例,包括初始化、查询、事务等操作

## 设计决策


### 为什么使用 OnceLock?


1. **线程安全**: OnceLock 提供线程安全的单次初始化
2. **零成本抽象**: 初始化后访问没有额外开销
3. **标准库支持**: 不需要额外依赖

### 为什么封装 yang-db?


1. **统一接口**: 提供全局访问点,简化使用
2. **错误转换**: 将 yang-db 错误转换为 BaseError
3. **日志记录**: 在关键操作点添加日志
4. **扩展性**: 未来可以添加连接池监控、性能统计等功能

## 相关需求


此实现满足以下需求:

- 需求 6.1: 提供全局静态访问接口
- 需求 6.2: 存储数据库连接实例
- 需求 6.3: 封装 yang-db 的 Database 类型
- 需求 6.4: 返回可用的数据库连接
- 需求 6.5: 未初始化时返回错误
- 需求 13.1: 提供 table 方法返回 QueryBuilder
- 需求 13.2: 提供 query 方法执行原生查询
- 需求 13.3: 提供 execute 方法执行原生语句
- 需求 13.4: 提供 transaction 方法开始事务
- 需求 13.5: 封装所有 yang-db 的 Database 方法
- 需求 15.2: 使用线程安全的方式存储数据库连接
- 需求 15.3: 正确处理并发请求

## 后续任务


下一步需要实现:

- DatabaseInitializer 结构体(任务 4.2)
- 数据库管理集成测试(任务 4.3)