添加说明文件

* db:
  优化 精简MySQL连接日志命名空间
  添加 MySQL连接是否enbale的配置处理
  优化 Redis连接未启用时日志修改为警告

README.md

@@ -27,6 +27,11 @@ npm start
 
 ## 版本说明
 
+### v1.0.1
+* 添加 数据库连接【MySQL】
+* 添加 数据库连接【Redis】
+* 添加 服务【Captcha】人机验证
+
 ### v1.0.0 
 * 构建 基础框架
 * 添加 API中间件【MountIP】
@@ -37,4 +42,4 @@ npm start
 * master 主分支，主要用于版本发布
 * dev 通用开发分支
 * db 数据库分支，专注数据库连接的开发
-* captcha 验证码分支，专注人机验证的开发
+* service 服务分支，专注各种服务的开发

package.json

@@ -15,6 +15,8 @@
     "@types/node": "^22.6.1",
     "cors": "^2.8.5",
     "express": "^4.21.0",
+    "ioredis": "^5.4.1",
+    "mysql2": "^3.11.3",
     "typescript": "^5.6.2"
   },
   "devDependencies": {

src/api/CheckCaptcha.ts

@@ -0,0 +1,35 @@
+import { API, RequestData } from "@lib/API/API";
+import ServerStdResponse from "@lib/ServerResponse/ServerStdResponse";
+import { Response } from "express";
+import CaptchaSession from "@lib/Service/CaptchaSession";
+// 验证人机验证
+class CheckCaptcha extends API {
+    constructor() {
+        super('POST', '/captcha');
+    }
+
+    public async onRequset(data: RequestData, res: Response): Promise<void> {
+        // 获取session以及angle
+        const { session, angle } = data;
+        if (!session || !angle) {
+            res.json({ ...ServerStdResponse.ERROR });
+            return;
+        }
+        switch (await CaptchaSession.check(session, angle)) {
+            case 0:// 验证已过期或服务器错误
+                res.json({ ...ServerStdResponse.ERROR, message: 'expired or server error' });
+                break;
+            case 1:// 通过验证
+                res.json(ServerStdResponse.OK);
+                break;
+            case -1:// 超过最大允许尝试次数
+                res.json({ ...ServerStdResponse.ERROR, message: 'max try count' });
+                break;
+            case -2:// 角度差异过大
+                res.json({ ...ServerStdResponse.ERROR, message: 'error angle' });
+                break;
+        }
+    }
+}
+
+export default CheckCaptcha;

src/api/GetCaptcha.ts

@@ -0,0 +1,30 @@
+import { API, RequestData } from "@lib/API/API";
+import ServerStdResponse from "@lib/ServerResponse/ServerStdResponse";
+import { Response } from "express";
+import crypto from 'crypto'
+import CaptchaSession from "@lib/Service/CaptchaSession";
+// 获取人机验证
+class GetCaptcha extends API {
+    constructor() {
+        super('GET', '/captcha');
+    }
+
+    public async onRequset(data: RequestData, res: Response): Promise<void> {
+        // 生成角度及session
+        const angle = Math.floor(60 + 240 * Math.random());
+        const session = crypto.createHash('md5').update(`${Math.random()} ${Date.now()}`).digest('hex');
+
+        // 存储验证信息
+        if (await CaptchaSession.add(session, angle)) {
+            res.json({...ServerStdResponse.OK, data: {
+                session,
+                // ... other data
+            }})
+        } else {
+            this.logger.error(`Failed to store session [${session}] and rotation angle [${angle}]`);
+            res.json(ServerStdResponse.ERROR);
+        }
+    }
+}
+
+export default GetCaptcha;

src/api/GetTest.ts

@@ -1,4 +1,4 @@
-import { API } from "@lib/API/API";
+import { API, RequestData } from "@lib/API/API";
 import MountIP, { MountIPRequestData } from "@lib/APIMiddleware/MountIP";
 import MountUserAgent, { MountUserAgentRequestDate } from "@lib/APIMiddleware/MountUserAgent";
 import Unbind from "@lib/APIMiddleware/Unbind";
@@ -10,7 +10,7 @@ class GetTest extends API {
         super('GET', '/test', MountIP, MountUserAgent, Unbind);
     }
 
-    public async onRequset(data: MountIPRequestData | MountUserAgentRequestDate, res: Response): Promise<void> {
+    public async onRequset(data: MountIPRequestData & MountUserAgentRequestDate, res: Response): Promise<void> {
         this.logger.info(`request ip: ${data._ip}  useragent: ${data._userAgent}`)
         res.json(ServerStdResponse.OK);
     }

src/api/isPassedCaptcha.ts

@@ -0,0 +1,25 @@
+import { API, RequestData } from "@lib/API/API";
+import ServerStdResponse from "@lib/ServerResponse/ServerStdResponse";
+import { Response } from "express";
+import CaptchaSession from "@lib/Service/CaptchaSession";
+// 检查人机验证是否通过
+class isPassedCaptcha extends API {
+    constructor() {
+        super('GET', '/isPassedCaptcha');
+    }
+
+    public async onRequset(data: RequestData, res: Response): Promise<void> {
+        // 获取session
+        const { session } = data;
+        if (!session) {
+            res.json({ ...ServerStdResponse.ERROR });
+            return;
+        }
+        if (await CaptchaSession.isPassed(session))
+            res.json(ServerStdResponse.OK);
+        else
+            res.json({ ...ServerStdResponse.ERROR, message: 'not passed' })
+    }
+}
+
+export default isPassedCaptcha;

src/config.ts

@@ -4,6 +4,29 @@ const config = {
         allowedHeaders: ['Content-Type'],
         methods: ['GET', 'POST']
     },
+    mysql: {
+        enable: false,
+        host: 'localhost',
+        port: 3306,
+        database: '',
+        user: 'root',
+        password: ''
+    },
+    redis: {
+        enable: false,
+        host: 'localhost',
+        port: 6379,
+        password: '' // localhost
+    },
+    service: {
+        captchaSession: {
+            useRedis: false,
+            allowMaxTryCount: 5,
+            allowMaxAngleDiff: 8,
+            allowReuseCount: 2,
+            expriedTimeSec: 60,
+        }
+    },
     API_Port: 8080
 };
 export default config;

src/index.ts

@@ -1,13 +1,25 @@
 import { APILoader } from "@lib/API/APILoader";
 import Logger from '@lib/Logger/Logger'
 import config from "./config";
+import MySQLConnection from "@lib/Database/MySQLConnection";
+import RedisConnection from "@lib/Database/RedisConnection";
+MySQLConnection
+RedisConnection
+// import API
 import GetTest from "./api/GetTest";
+import GetCaptcha from "./api/GetCaptcha";
+import CheckCaptcha from "./api/CheckCaptcha";
+import isPassedCaptcha from "./api/isPassedCaptcha";
 const logger = new Logger('Server')
+
 async function main(): Promise<void> {
     logger.info('Starting...');
     const apiLoader = new APILoader(config.cors);
-    // loadAPI
+    // addAPI
     apiLoader.add(GetTest);
+    apiLoader.add(GetCaptcha);
+    apiLoader.add(CheckCaptcha);
+    apiLoader.add(isPassedCaptcha);
 
     await apiLoader.start(config.API_Port);
     logger.info('Server started successfully')

src/lib/API/API.ts

@@ -5,6 +5,10 @@ interface MiddlewareFunction {
     (req: Request, res: Response, next: NextFunction): void;
 }
 
+interface RequestData {
+    [key: string]: any
+}
+
 abstract class API {
 
     protected logger: Logger;
@@ -21,8 +25,8 @@ abstract class API {
     }
 
     // to override
-    public abstract onRequset(data: any, res: Response): Promise<void>;
+    public abstract onRequset(data: RequestData, res: Response): Promise<void>;
 }
 
 export { API };
-export type { MiddlewareFunction };
+export type { MiddlewareFunction, RequestData };

src/lib/APIMiddleware/MountIP.ts

@@ -1,5 +1,6 @@
 import { Request, Response, NextFunction } from "express"
 import Logger from "@lib/Logger/Logger";
+import { RequestData } from "@lib/API/API";
 const logger = new Logger('API', 'Middleware', 'MountIP');
 
 // 挂载IP，将请求的ip地址挂载到data._ip属性下
@@ -20,9 +21,8 @@ let MountIP = (req: Request, res: Response, next: NextFunction) => {
 export default MountIP;
 
 
-interface MountIPRequestData {
-    _ip: string,
-    [key: string | number | symbol]: any
-}
+interface MountIPRequestData extends RequestData {
+    _ip: string;
+} 
 
 export type { MountIPRequestData };

src/lib/APIMiddleware/MountUserAgent.ts

@@ -1,5 +1,6 @@
 import { Request, Response, NextFunction } from "express"
 import Logger from "@lib/Logger/Logger";
+import { RequestData } from "@lib/API/API";
 const logger = new Logger('API', 'Middleware', 'MountUserAgent')
 
 // 挂载用户代理，将请求的请求代理挂载到data._userAgent属性下
@@ -12,9 +13,8 @@ let MountUserAgent = (req: Request, res: Response, next: NextFunction) => {
 export default MountUserAgent;
 
 
-interface MountUserAgentRequestDate {
+interface MountUserAgentRequestDate extends RequestData {
     _userAgent: string,
-    [key: string | number | symbol]: any
 }
 
 export type { MountUserAgentRequestDate };

src/lib/Database/MySQLConnection.ts

@@ -0,0 +1,104 @@
+/**
+ * @file MySQLConnection.ts
+ * @version 1.0.1
+ * @description MySQL数据库连接池
+ * 
+ * 该文件提供了MySQL数据库连接池的实现，包括以下功能：
+ * - 创建数据库连接池
+ * - 自动测试数据库连接
+ * - 数据库基础错误处理
+ * 
+ * ## 配置项说明
+ * 在 `config.ts` 文件中，可以配置以下选项：
+ * - `enable`: 是否启用 MySQL 数据库
+ * - `host`: 数据库主机地址
+ * - `port`: 数据库端口号
+ * - `database`: 数据库名称
+ * - `user`: 数据库用户名
+ * - `password`: 数据库密码
+ * 
+ */
+import mysql from "mysql2/promise";
+import Logger from "@lib/Logger/Logger";
+import config from "../../config";
+
+class MySQLConnectPool {
+    private pool: any;
+    private logger = new Logger('MySQL');
+
+    constructor() {
+        if (!config.mysql.enable) {
+            this.logger.warn('Database is disabled, initialization terminated');
+            return;
+        }
+        this.pool = this.createConnectPool();
+        this.logger.info("Database connection pool created")
+        setTimeout(async () => {
+            let res = await this.testConnection();
+            if (res)
+                this.logger.info("Database test successful")
+            else
+                this.logger.error("Database test failed")
+        }, 10);
+    }
+
+    private createConnectPool() {
+        return mysql.createPool({
+            host: config.mysql.host,
+            database: config.mysql.database,
+            port: config.mysql.port,
+            user: config.mysql.user,
+            password: config.mysql.password,
+            waitForConnections: true,
+            connectionLimit: 10,
+            queueLimit: 0
+        })
+    }
+
+    private async testConnection() {
+        try {
+            let res = await this.execute("SELECT 1 + 1 As result");
+            if (res[0].result == 2)
+                return 1;
+            else
+                return 0;
+        } catch (error) {
+            this.logger.error(`An error occurred during the database test: ` + error);
+            return 0;
+        }
+
+    }
+
+    /**
+     * 执行SQL查询
+     * @param sql SQL语句
+     * @param values 可选的查询参数列表
+     * @param database 可选的数据库
+     * @returns Promise<any | undefined> 查询结果
+     */
+    public async execute(sql: string, values?: any[], database?: string): Promise<any | undefined> {
+        let connection: any;
+        try {
+            connection = await this.pool.getConnection();
+
+            // 如果指定了数据库，则更改当前连接的数据库
+            if (database) {
+                await connection.changeUser({ database });
+            }
+
+            let [rows, fields] = await connection.execute(sql, values);
+            return rows;
+        } catch (error) {
+            this.logger.error("An error occurred in the database: " + error, '\n##', sql, '\n##', JSON.stringify(values));
+            return undefined;
+        } finally {
+            if (database)
+                await connection.changeUser({ database: config.mysql.database });// 恢复默认数据库
+            if (connection)
+                connection.release();
+        }
+    }
+}
+
+const MySQLConnection = new MySQLConnectPool();
+export default MySQLConnection;

src/lib/Database/RedisConnection.ts

@@ -0,0 +1,67 @@
+/**
+ * @file RedisConnection.ts
+ * @version 1.0.1
+ * @description Redis数据库连接池
+ * 
+ * 该文件提供了Redis数据库连接池的实现，包括以下功能：
+ * - 创建数据库连接池
+ * - 自动测试数据库连接
+ * - 导出原生Redis连接池对象（注意需要自行进行错误处理）
+ * 
+ * ## 配置项说明
+ * 在 `config.ts` 文件中，可以配置以下选项：
+ * - `enable`: 是否启用 Redis 数据库
+ * - `host`: 数据库主机地址
+ * - `port`: 数据库端口号
+ * - `password`: 数据库密码，如果没有请保留空串
+ */
+import Redis from 'ioredis';
+import config from '../../config';
+import Logger from '@lib/Logger/Logger';
+
+class _RedisConnection {
+    private pool?: Redis
+    private logger = new Logger('Redis')
+
+    constructor() {
+        if (!config.redis.enable) {
+            this.logger.warn('Database is disabled, initialization terminated');
+            return;
+        }
+
+        try {
+            this.pool = new Redis({
+                port: config.redis.port,
+                host: config.redis.host,
+                password: config.redis.password,
+                maxRetriesPerRequest: 10,
+            });
+            this.logger.info('Database connection pool created')
+        } catch (error) {
+            this.logger.error('Failed to create database connection pool: ' + error)
+        }
+        setTimeout(async () => {
+            if (this.pool == undefined)
+                return;
+            try {
+                let res = await this.pool.set('redis_test', '1');
+                if (res)
+                    this.logger.info('Database test successful')
+                else
+                    throw new Error('Unexpected return value')
+            } catch (error) {
+                this.logger.error('Database test failed: ' + error)
+            }
+
+        }, 10);
+    }
+
+    public getPool(): Redis {
+        return <Redis>this.pool;
+    }
+}
+
+const _redisConnection = new _RedisConnection();
+const RedisConnection = _redisConnection.getPool();
+export default RedisConnection;
+export type { Redis };

src/lib/Service/CaptchaSession.ts

@@ -0,0 +1,231 @@
+/**
+ * @file CaptchaSession.ts
+ * @version 1.0.1
+ * @description 人机验证服务
+ * 
+ * 该文件提供了“Session-角度”结构存储的通用验证方案
+ * - 存储和检索验证数据
+ * - 自动清理过期的验证会话
+ * - 允许采用本地存储的方案，即允许不依赖Redis
+ * 
+ * ## 配置项说明
+ * 
+ * 在 `config.ts` 文件中，可以配置以下选项：
+ * - `useRedis`: 是否使用 Redis 存储验证数据
+ * - `allowMaxTryCount`: 允许的最大尝试次数
+ * - `allowMaxAngleDiff`: 允许的最大角度偏差
+ * - `expriedTimeSec`: 验证会话的过期时间（秒）
+ * - `allowReuseCount`: 允许check方法验证通过后，重复使用isPassed方法进行验证的次数
+ * - `refreshExpiryOnUse`: 使用后是否刷新过期时间
+ * 
+ * ## 注意事项
+ * 
+ * - 请确保在 `config.ts` 文件中正确配置 Redis 和其他选项。
+ * - 如果使用 Redis，请确保 Redis 服务已启动并可用。
+ * - 定期检查日志文件，以确保服务正常运行。
+ */
+import Logger from '@lib/Logger/Logger';
+import type { Redis } from '@lib/Database/RedisConnection';
+import config from 'src/config';
+interface CaptchaSessionRedisDataJSON {
+    rotateDeg: number;
+    tryCount: number;
+    isPassed: boolean;
+    allowReuseCount: number;
+    expiredTimestamp?: number;
+}
+
+interface CaptchaSessionPoolDataJSON extends CaptchaSessionRedisDataJSON {
+    expiredTimestamp: number;
+}
+
+type CaptchaPool = {
+    [key: string]: CaptchaSessionPoolDataJSON;
+}
+
+class _CaptchaSession {
+    private readonly useRedis: boolean = config.service.captchaSession.useRedis;
+    private readonly logger = new Logger('Service', 'captchaSession');
+    private readonly AllowMaxTryCount: number = config.service.captchaSession.allowMaxTryCount;
+    private readonly AllowMaxAngleDiff: number = config.service.captchaSession.allowMaxAngleDiff;
+    private readonly AllowReuseCount: number = config.service.captchaSession.allowReuseCount;
+    private readonly ExpriedTimeSec: number = config.service.captchaSession.expriedTimeSec;
+    private readonly RedisCommonKey: string = 'Service:captchaSession:';
+    private redisConnection?: Redis;
+    private captchaPool?: CaptchaPool;
+
+    constructor() {
+        new Promise(async (resolve) => {
+            if (this.useRedis) {
+                this.redisConnection = (await import('@lib/Database/RedisConnection')).default;
+                this.logger.info('Redis service has been enabled');
+            } else {
+                this.captchaPool = {};
+                this.logger.info('CaptchaPool init, Redis service is disabled');
+                // 需要手动进行过期项的处理
+                setInterval(() => {
+                    this.logger.info('Starting automatic cleanup of expired items');
+                    this.cleanupExpiredItems();
+                    this.logger.info('Automatic cleanup completed');
+                }, 1000 * 60 * 30);
+            }
+            this.logger.info('Rotation image verification service has started');
+            resolve(undefined);
+        })
+    }
+
+    private cleanupExpiredItems(): void {
+        const now = Date.now();
+        for (const session in this.captchaPool) {
+            if (this.captchaPool.hasOwnProperty(session)) {
+                const item = this.captchaPool[session];
+                if (item && (now > item.expiredTimestamp)) {
+                    delete this.captchaPool[session];
+                }
+            }
+        }
+    }
+
+    // get需要实现过期时间管理
+    private async get(session: string): Promise<CaptchaSessionRedisDataJSON | undefined> {
+        try {
+            if (this.useRedis) {
+                let redisRes = await this.redisConnection!.get(this.RedisCommonKey + session);
+                if (!redisRes)
+                    return;
+                return JSON.parse(redisRes);
+            }
+
+            let poolRes = this.captchaPool![session];
+            if (!poolRes)
+                return;
+            // 如果不来自Redis，则需要处理是否过期
+            if (!this.useRedis && Date.now() > poolRes.expiredTimestamp)
+                return;
+            return poolRes;
+        } catch (error) {
+            this.logger.error(`Error occurred while retrieving session [${session}]: ${error}`);
+            return;
+        }
+    }
+
+    private async remove(session: string): Promise<void> {
+        try {
+            if (this.useRedis)
+                await this.redisConnection!.del(this.RedisCommonKey + session);
+            else
+                delete this.captchaPool![session];
+        } catch (error) {
+            this.logger.error(`Failed to delete session [${session}]`);
+        }
+    }
+
+    /**
+     * 
+     * @param session 验证会话标识符
+     * @param rotateDeg 图片旋转角度
+     * @param reuseCount 可选，允许重复使用的次数
+     * @returns true存储成功 false存储失败
+     */
+    public async add(session: string, rotateDeg: number, reuseCount?: number): Promise<boolean> {
+        const result: CaptchaSessionRedisDataJSON = {
+            rotateDeg: rotateDeg,
+            tryCount: 0,
+            allowReuseCount: reuseCount || this.AllowReuseCount,
+            isPassed: false,
+        }
+
+        try {
+            if (this.useRedis) {
+                const res = await this.redisConnection!.set(this.RedisCommonKey + session, JSON.stringify(result));
+                if (res && res === 'OK') {
+                    this.redisConnection!.expire(this.RedisCommonKey + session, this.ExpriedTimeSec);
+                    this.logger.info(`Session [${session}] and rotation angle [${rotateDeg}] have been stored`);
+                    return true;
+                }
+                this.logger.error(`Failed to store session [${session}] and rotation angle [${rotateDeg}]`);
+                return false;
+            }
+            this.captchaPool![session] = {
+                ...result,
+                expiredTimestamp: Date.now() + this.ExpriedTimeSec * 1000
+            }
+            this.logger.info(`Session [${session}] and rotation angle [${rotateDeg}] have been stored`);
+            return true;
+        } catch (error) {
+            this.logger.error(`Failed to store session [${session}] and rotation angle [${rotateDeg}]: ${error}`);
+            return false;
+        }
+    }
+
+    /**
+     * 
+     * @param session 验证会话标识符
+     * @returns true已验证过期 false未通过
+     */
+    public async isPassed(session: string): Promise<boolean> {
+        const result = await this.get(session);
+        if (!result)
+            return false;
+        if (!result.isPassed)
+            return false;
+
+        // 验证通过，允许重复使用次数-1
+        result.allowReuseCount--;
+        if(result.allowReuseCount == 0)
+            this.remove(session);
+        else if(this.useRedis){
+            await this.redisConnection!.del(this.RedisCommonKey + session);
+            await this.redisConnection!.set(this.RedisCommonKey + session, JSON.stringify(result));
+            this.redisConnection!.expire(this.RedisCommonKey + session, this.ExpriedTimeSec);
+        }
+        return true;
+    }
+
+    /**
+     * 
+     * @param session 验证会话标识符
+     * @param rotateDeg 图片旋转角度
+     * @returns 0验证已过期或服务器错误 1通过验证 -1超过最大允许尝试次数 -2角度差异过大
+     */
+    public async check(session: string, rotateDeg: number): Promise<number> {
+        try {
+            let result = await this.get(session);
+            if (!result) {
+                return 0;
+            }
+            if (result.isPassed) {
+                this.logger.info(`Session [${session}] has already been verified, no need to verify again`);
+                return 1;
+            }
+            if (Math.abs(result.rotateDeg - rotateDeg) <= this.AllowMaxAngleDiff) {
+                result.isPassed = true;
+                if (this.useRedis) {
+                    await this.redisConnection!.del(this.RedisCommonKey + session);
+                    await this.redisConnection!.set(this.RedisCommonKey + session, JSON.stringify(result));
+                    this.redisConnection!.expire(this.RedisCommonKey + session, this.ExpriedTimeSec);
+                } else {
+                    result.expiredTimestamp = Date.now() + this.ExpriedTimeSec * 1000;
+                }
+                return 1;
+            }
+            // 角度偏差过大，尝试次数记录+1
+            result.tryCount++;
+            if (result.tryCount >= this.AllowMaxTryCount) {
+                // 已达最大尝试次数
+                this.remove(session);
+                return -1;
+            }
+            // 允许下一次尝试
+            if (this.useRedis)
+                this.redisConnection!.set(this.RedisCommonKey + session, JSON.stringify(result));
+            return -2;
+        } catch (error) {
+            this.logger.error(`Error occurred while checking session [${session}]: ${error}`);
+            return 0;
+        }
+    }
+}
+
+const CaptchaSession = new _CaptchaSession();
+export default CaptchaSession;