docs: 更新项目文档，完善需求和技术细节

2025-08-31 23:29:26 +08:00
parent fcce470415
commit 028a458283
35 changed files with 13517 additions and 0 deletions
--- a/backend/utils/dbConnector.js
+++ b/backend/utils/dbConnector.js
@@ -0,0 +1,152 @@
+/**
+ * 数据库连接工具类
+ * 封装MySQL数据库连接和基本操作
+ */
+
+const mysql = require('mysql2/promise');
+const databaseConfig = require('../config/database');
+
+class DBConnector {
+  constructor() {
+    this.pool = null;
+    this.connection = null;
+    this.init();
+  }
+
+  /**
+   * 初始化数据库连接池
+   */
+  init() {
+    try {
+      this.pool = mysql.createPool({
+        host: databaseConfig.host,
+        port: databaseConfig.port,
+        user: databaseConfig.username,
+        password: databaseConfig.password,
+        database: databaseConfig.database,
+        connectionLimit: databaseConfig.pool.max,
+        acquireTimeout: databaseConfig.pool.acquire,
+        timeout: databaseConfig.pool.idle,
+        charset: 'utf8mb4',
+        timezone: '+08:00',
+        decimalNumbers: true,
+        supportBigNumbers: true,
+        bigNumberStrings: false
+      });
+
+      console.log('✅ 数据库连接池初始化成功');
+    } catch (error) {
+      console.error('❌ 数据库连接池初始化失败:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * 获取数据库连接
+   * @returns {Promise} 数据库连接对象
+   */
+  async getConnection() {
+    try {
+      this.connection = await this.pool.getConnection();
+      return this.connection;
+    } catch (error) {
+      console.error('❌ 获取数据库连接失败:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * 执行SQL查询
+   * @param {string} sql - SQL语句
+   * @param {Array} params - 参数数组
+   * @returns {Promise} 查询结果
+   */
+  async query(sql, params = []) {
+    let connection;
+    try {
+      connection = await this.getConnection();
+      const [rows] = await connection.execute(sql, params);
+      return rows;
+    } catch (error) {
+      console.error('❌ SQL执行失败:', error.message);
+      console.error('SQL:', sql);
+      console.error('参数:', params);
+      throw error;
+    } finally {
+      if (connection) {
+        connection.release();
+      }
+    }
+  }
+
+  /**
+   * 开启事务
+   * @returns {Promise} 事务连接对象
+   */
+  async beginTransaction() {
+    try {
+      const connection = await this.getConnection();
+      await connection.beginTransaction();
+      return connection;
+    } catch (error) {
+      console.error('❌ 开启事务失败:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * 提交事务
+   * @param {Object} connection - 事务连接对象
+   */
+  async commitTransaction(connection) {
+    try {
+      await connection.commit();
+      connection.release();
+    } catch (error) {
+      console.error('❌ 提交事务失败:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * 回滚事务
+   * @param {Object} connection - 事务连接对象
+   */
+  async rollbackTransaction(connection) {
+    try {
+      await connection.rollback();
+      connection.release();
+    } catch (error) {
+      console.error('❌ 回滚事务失败:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * 关闭连接池
+   */
+  async close() {
+    if (this.pool) {
+      await this.pool.end();
+      console.log('✅ 数据库连接池已关闭');
+    }
+  }
+
+  /**
+   * 健康检查
+   * @returns {Promise<boolean>} 数据库连接状态
+   */
+  async healthCheck() {
+    try {
+      const result = await this.query('SELECT 1 as status');
+      return result[0].status === 1;
+    } catch (error) {
+      return false;
+    }
+  }
+}
+
+// 创建全局数据库连接实例
+const dbConnector = new DBConnector();
+
+module.exports = dbConnector;