## 配置模块使用说明

配置模块提供了统一的配置管理接口，主要功能包括：

### 数据库配置

项目使用 SQLAlchemy ORM 框架连接 MySQL 数据库，主要配置项如下：

```python
class DatabaseConfig:
    host: str = "localhost"  # 数据库主机
    port: int = 3306         # 数据库端口
    user: str = "root"       # 数据库用户名
    password: str = ""       # 数据库密码
    name: str = "question_bank"  # 数据库名称
```

使用示例：

```python
from app.database.database import Database

# 初始化数据库连接
Database.initialize()

# 使用上下文管理器管理会话
with db.session() as session:
    # 执行查询
    users = db.execute_query("SELECT * FROM users WHERE age > :age", {"age": 18})

    # 执行非查询
    affected_rows = db.execute_non_query(
        "UPDATE users SET status = :status WHERE id = :id",
        {"status": "active", "id": 1}
    )

    # 批量操作
    user_data = [
        {"name": "Alice", "age": 25},
        {"name": "Bob", "age": 30}
    ]
    inserted_rows = db.batch_execute(
        "INSERT INTO users (name, age) VALUES (:name, :age)",
        user_data
    )

# 兼容旧版接口
from app.database.db_mysql import get_db
db = next(get_db())
result = db.execute("SELECT * FROM users")
db.commit()
```

新特性说明：

1. 单例模式：确保全局只有一个数据库连接实例
2. 上下文管理器：自动管理会话生命周期，异常时自动回滚
3. 常用操作封装：
   - execute_query：执行查询，返回字典列表
   - execute_non_query：执行非查询，返回影响行数
   - batch_execute：批量执行，返回总影响行数
4. 新增 initialize()方法：显式初始化数据库连接
5. 保持对旧版接口的兼容

注意事项：

1. 数据库连接字符串格式：mysql+pymysql://{user}:{password}@{host}:{port}/{name}?charset=utf8mb4
2. 数据库连接池配置：
   - pool_pre_ping: True # 每次使用连接前检查连接是否有效
   - pool_recycle: 3600 # 连接池回收时间（秒）
3. MySQL 驱动说明：
   - PyMySQL：纯 Python 实现的 MySQL 驱动，兼容性好
   - mysqlclient：C 扩展实现的 MySQL 驱动，性能更好
   - 默认使用 PyMySQL，如需使用 mysqlclient：
     - 安装 mysqlclient：pip install mysqlclient
     - 修改连接字符串前缀为 mysql://

配置模块提供了统一的配置管理接口，主要功能包括：

- 获取配置实例
- 获取配置项值
- 注册配置变更回调

### 获取配置实例

```python
from app.config import get_config

config = get_config()
```

### 获取配置项值

```python
from app.config import get_config_value

# 获取配置项值，如果不存在则返回默认值
value = get_config_value('key', default='default_value')
```

### 注册配置变更回调

```python
from app.config import on_config_change

def callback():
    print('配置已变更')

on_config_change(callback)
```

### 异常处理

所有接口都可能会抛出`RuntimeError`异常，建议在使用时进行捕获处理：

```python
try:
    config = get_config()
except RuntimeError as e:
    print(f'获取配置失败：{e}')
```

## 环境配置说明

项目支持多环境配置，通过不同的配置文件管理：

- application.yml：基础配置
- application-dev.yml：开发环境配置
- application-prod.yml：生产环境配置

### 配置优先级

1. 环境特定配置（application-{env}.yml）
2. 基础配置（application.yml）

### 环境切换

通过设置环境变量`APP_ENV`来切换环境：

#### 项目级设置（推荐）

在项目根目录下创建`.env`文件，内容如下：

```env
# 开发环境
ENV=dev

# 生产环境
# ENV=prod
```

注意：

1. 该设置仅对当前项目有效
2. .env 文件应添加到.gitignore 中，避免将环境配置提交到代码库
3. 如果同时存在系统环境变量和.env 文件，.env 文件的优先级更高

#### Windows 系统

1. 临时设置（仅当前命令行窗口有效）：

```cmd
:: 开发环境
set ENV=dev

:: 生产环境
set ENV=prod
```

2. 永久设置：

- 右键点击"此电脑" -> "属性" -> "高级系统设置"
- 点击"环境变量"按钮
- 在"系统变量"或"用户变量"中新建变量：
  - 变量名：ENV
  - 变量值：dev（开发环境）或 prod（生产环境）

#### macOS/Linux 系统

```bash
# 开发环境
export ENV=dev

# 生产环境
export ENV=prod
```

### 各环境主要差异

| 配置项               | 开发环境          | 生产环境            |
| -------------------- | ----------------- | ------------------- |
| app.debug            | true              | false               |
| database.host        | localhost         | db.prod.example.com |
| database.name        | question_bank_dev | question_bank_prod  |
| logging.path         | logs              | /var/log/app        |
| logging.level        | DEBUG             | INFO                |
| logging.retention    | 7 天              | 30 天               |
| logging.max_size     | 10MB              | 100MB               |
| logging.backup_count | 5                 | 30                  |

## 日志配置说明

项目使用 loguru 库进行日志管理，主要特性包括：

- 开发环境：

  - 日志级别：DEBUG
  - 日志路径：logs/
  - 日志文件：app\_{time:YYYY-MM-DD}.log（按日期自动分割）
  - 日志保留：7 天
  - 日志格式：{time:YYYY-MM-DD HH:mm:ss.SSS} | {level} | {module}:{line} - {message}
  - 控制台输出：彩色格式（<green>{time}</green> | <level>{level}</level> | <cyan>{module}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>）
  - 旧日志压缩：自动压缩为 zip 格式
  - 最大文件大小：10MB

- 生产环境：
  - 日志级别：INFO
  - 日志路径：/var/log/app
  - 日志文件：app\_{time:YYYY-MM-DD}.log（按日期自动分割）
  - 日志保留：30 天
  - 日志格式：{time:YYYY-MM-DD HH:mm:ss.SSS} | {level} | {module}:{line} - {message}
  - 控制台输出：简洁格式
  - 旧日志压缩：自动压缩为 zip 格式
  - 最大文件大小：100MB

使用示例：

```python
from app.logger import logger

logger.info("这是一条信息日志")
logger.error("这是一条错误日志", exc_info=True)
```

## 新增日志功能说明

1. 按日期分割日志文件：

   - 每天生成一个新的日志文件，文件名格式为 app_YYYY-MM-DD.log
   - 自动处理日志文件切换，无需重启应用

2. 自动清理旧日志：

   - 开发环境保留最近 7 天的日志
   - 生产环境保留最近 30 天的日志
   - 超过保留期限的日志文件会被自动删除

3. 日志压缩：

   - 旧日志文件会被自动压缩为 zip 格式保存
   - 压缩后的文件名格式为 app_YYYY-MM-DD.log.zip

4. 线程安全：

   - 日志写入操作是线程安全的
   - 支持多线程并发写入日志

5. 异常处理：
   - 日志初始化失败时会抛出异常
   - 日志写入失败时会自动重试