smart-question-bank

配置模块使用说明

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

数据库配置

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

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

使用示例：

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://

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

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

获取配置实例

from app.config import get_config

config = get_config()

获取配置项值

from app.config import get_config_value

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

注册配置变更回调

from app.config import on_config_change

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

on_config_change(callback)

异常处理

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

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=dev

# 生产环境
# ENV=prod

注意：

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

Windows 系统

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

   :: 开发环境
   set ENV=dev
   
   :: 生产环境
   set ENV=prod
   

2. 永久设置：

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

macOS/Linux 系统

# 开发环境
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}
  • 控制台输出：彩色格式（{time} | {level} | {module}:{line} - {message}）
  • 旧日志压缩：自动压缩为 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

使用示例：

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. 异常处理：

   • 日志初始化失败时会抛出异常
   • 日志写入失败时会自动重试