befly 3.0.0 → 3.0.1

package/utils/sqlBuilder.ts

@@ -1,10 +1,9 @@
 /**
- * SQL 构建器 - TypeScript 版本
- * 提供类型安全的 SQL 查询构建功能
+ * SQL 构造器 - TypeScript 版本
+ * 提供链式 API 构建 SQL 查询
  */
 
-import type { OrderDirection, SqlValue } from '../types/common.js';
-import type { SqlQuery, WhereOperator, WhereConditions, InsertData, UpdateData } from '../types/database';
+import type { WhereConditions, SqlValue, OrderByField } from '../types/common.js';
 
 /**
  * SQL 构建器类
@@ -113,7 +112,120 @@ export class SqlBuilder {
      */
     private _validateParam(value: any): void {
         if (value === undefined) {
-            throw new Error('参数值不能为 undefined');
+            throw new Error(`参数值不能为 undefined`);
+        }
+    }
+
+    /**
+     * 处理单个操作符条件
+     */
+    private _applyOperator(fieldName: string, operator: WhereOperator, value: any): void {
+        const escapedField = this._escapeField(fieldName);
+
+        switch (operator) {
+            case '$ne':
+            case '$not':
+                this._validateParam(value);
+                this._where.push(`${escapedField} != ?`);
+                this._params.push(value);
+                break;
+
+            case '$in':
+                if (!Array.isArray(value)) {
+                    throw new Error(`$in 操作符的值必须是数组 (operator: ${operator})`);
+                }
+                if (value.length === 0) {
+                    throw new Error(`$in 操作符的数组不能为空。提示：空数组会导致查询永远不匹配任何记录，这通常不是预期行为。请检查查询条件或移除该字段。`);
+                }
+                const placeholders = value.map(() => '?').join(',');
+                this._where.push(`${escapedField} IN (${placeholders})`);
+                this._params.push(...value);
+                break;
+
+            case '$nin':
+            case '$notIn':
+                if (!Array.isArray(value)) {
+                    throw new Error(`$nin/$notIn 操作符的值必须是数组 (operator: ${operator})`);
+                }
+                if (value.length === 0) {
+                    throw new Error(`$nin/$notIn 操作符的数组不能为空。提示：空数组会导致查询匹配所有记录，这通常不是预期行为。请检查查询条件或移除该字段。`);
+                }
+                const placeholders2 = value.map(() => '?').join(',');
+                this._where.push(`${escapedField} NOT IN (${placeholders2})`);
+                this._params.push(...value);
+                break;
+
+            case '$like':
+                this._validateParam(value);
+                this._where.push(`${escapedField} LIKE ?`);
+                this._params.push(value);
+                break;
+
+            case '$notLike':
+                this._validateParam(value);
+                this._where.push(`${escapedField} NOT LIKE ?`);
+                this._params.push(value);
+                break;
+
+            case '$gt':
+                this._validateParam(value);
+                this._where.push(`${escapedField} > ?`);
+                this._params.push(value);
+                break;
+
+            case '$gte':
+                this._validateParam(value);
+                this._where.push(`${escapedField} >= ?`);
+                this._params.push(value);
+                break;
+
+            case '$lt':
+                this._validateParam(value);
+                this._where.push(`${escapedField} < ?`);
+                this._params.push(value);
+                break;
+
+            case '$lte':
+                this._validateParam(value);
+                this._where.push(`${escapedField} <= ?`);
+                this._params.push(value);
+                break;
+
+            case '$between':
+                if (Array.isArray(value) && value.length === 2) {
+                    this._validateParam(value[0]);
+                    this._validateParam(value[1]);
+                    this._where.push(`${escapedField} BETWEEN ? AND ?`);
+                    this._params.push(value[0], value[1]);
+                }
+                break;
+
+            case '$notBetween':
+                if (Array.isArray(value) && value.length === 2) {
+                    this._validateParam(value[0]);
+                    this._validateParam(value[1]);
+                    this._where.push(`${escapedField} NOT BETWEEN ? AND ?`);
+                    this._params.push(value[0], value[1]);
+                }
+                break;
+
+            case '$null':
+                if (value === true) {
+                    this._where.push(`${escapedField} IS NULL`);
+                }
+                break;
+
+            case '$notNull':
+                if (value === true) {
+                    this._where.push(`${escapedField} IS NOT NULL`);
+                }
+                break;
+
+            default:
+                // 等于条件
+                this._validateParam(value);
+                this._where.push(`${escapedField} = ?`);
+                this._params.push(value);
         }
     }
 
@@ -158,159 +270,14 @@ export class SqlBuilder {
                 // 一级属性格式：age$gt, role$in 等
                 const lastDollarIndex = key.lastIndexOf('$');
                 const fieldName = key.substring(0, lastDollarIndex);
-                const escapedFieldName = this._escapeField(fieldName);
                 const operator = ('$' + key.substring(lastDollarIndex + 1)) as WhereOperator;
-
-                switch (operator) {
-                    case '$ne':
-                    case '$not':
-                        this._validateParam(value);
-                        this._where.push(`${escapedFieldName} != ?`);
-                        this._params.push(value);
-                        break;
-                    case '$in':
-                        if (Array.isArray(value) && value.length > 0) {
-                            const placeholders = value.map(() => '?').join(',');
-                            this._where.push(`${escapedFieldName} IN (${placeholders})`);
-                            this._params.push(...value);
-                        }
-                        break;
-                    case '$nin':
-                    case '$notIn':
-                        if (Array.isArray(value) && value.length > 0) {
-                            const placeholders = value.map(() => '?').join(',');
-                            this._where.push(`${escapedFieldName} NOT IN (${placeholders})`);
-                            this._params.push(...value);
-                        }
-                        break;
-                    case '$like':
-                        this._validateParam(value);
-                        this._where.push(`${escapedFieldName} LIKE ?`);
-                        this._params.push(value);
-                        break;
-                    case '$notLike':
-                        this._validateParam(value);
-                        this._where.push(`${escapedFieldName} NOT LIKE ?`);
-                        this._params.push(value);
-                        break;
-                    case '$gt':
-                        this._validateParam(value);
-                        this._where.push(`${escapedFieldName} > ?`);
-                        this._params.push(value);
-                        break;
-                    case '$gte':
-                        this._validateParam(value);
-                        this._where.push(`${escapedFieldName} >= ?`);
-                        this._params.push(value);
-                        break;
-                    case '$lt':
-                        this._validateParam(value);
-                        this._where.push(`${escapedFieldName} < ?`);
-                        this._params.push(value);
-                        break;
-                    case '$lte':
-                        this._validateParam(value);
-                        this._where.push(`${escapedFieldName} <= ?`);
-                        this._params.push(value);
-                        break;
-                    case '$between':
-                        if (Array.isArray(value) && value.length === 2) {
-                            this._where.push(`${escapedFieldName} BETWEEN ? AND ?`);
-                            this._params.push(value[0], value[1]);
-                        }
-                        break;
-                    case '$notBetween':
-                        if (Array.isArray(value) && value.length === 2) {
-                            this._where.push(`${escapedFieldName} NOT BETWEEN ? AND ?`);
-                            this._params.push(value[0], value[1]);
-                        }
-                        break;
-                    case '$null':
-                        if (value === true) {
-                            this._where.push(`${escapedFieldName} IS NULL`);
-                        }
-                        break;
-                    case '$notNull':
-                        if (value === true) {
-                            this._where.push(`${escapedFieldName} IS NOT NULL`);
-                        }
-                        break;
-                    default:
-                        this._validateParam(value);
-                        this._where.push(`${escapedFieldName} = ?`);
-                        this._params.push(value);
-                }
+                this._applyOperator(fieldName, operator, value);
             } else {
                 // 检查值是否为对象（嵌套条件）
                 if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
                     // 嵌套条件：如 { age: { $gt: 18 } }
-                    const escapedKey = this._escapeField(key);
                     for (const [op, val] of Object.entries(value)) {
-                        switch (op as WhereOperator) {
-                            case '$ne':
-                            case '$not':
-                                this._validateParam(val);
-                                this._where.push(`${escapedKey} != ?`);
-                                this._params.push(val);
-                                break;
-                            case '$gt':
-                                this._validateParam(val);
-                                this._where.push(`${escapedKey} > ?`);
-                                this._params.push(val);
-                                break;
-                            case '$gte':
-                                this._validateParam(val);
-                                this._where.push(`${escapedKey} >= ?`);
-                                this._params.push(val);
-                                break;
-                            case '$lt':
-                                this._validateParam(val);
-                                this._where.push(`${escapedKey} < ?`);
-                                this._params.push(val);
-                                break;
-                            case '$lte':
-                                this._validateParam(val);
-                                this._where.push(`${escapedKey} <= ?`);
-                                this._params.push(val);
-                                break;
-                            case '$like':
-                                this._validateParam(val);
-                                this._where.push(`${escapedKey} LIKE ?`);
-                                this._params.push(val);
-                                break;
-                            case '$notLike':
-                                this._validateParam(val);
-                                this._where.push(`${escapedKey} NOT LIKE ?`);
-                                this._params.push(val);
-                                break;
-                            case '$in':
-                                if (Array.isArray(val) && val.length > 0) {
-                                    const placeholders = val.map(() => '?').join(',');
-                                    this._where.push(`${escapedKey} IN (${placeholders})`);
-                                    this._params.push(...val);
-                                }
-                                break;
-                            case '$nin':
-                            case '$notIn':
-                                if (Array.isArray(val) && val.length > 0) {
-                                    const placeholders = val.map(() => '?').join(',');
-                                    this._where.push(`${escapedKey} NOT IN (${placeholders})`);
-                                    this._params.push(...val);
-                                }
-                                break;
-                            case '$null':
-                                if (val) {
-                                    this._where.push(`${escapedKey} IS NULL`);
-                                } else {
-                                    this._where.push(`${escapedKey} IS NOT NULL`);
-                                }
-                                break;
-                            default:
-                                // 未知操作符，按等于处理
-                                this._validateParam(val);
-                                this._where.push(`${escapedKey} = ?`);
-                                this._params.push(val);
-                        }
+                        this._applyOperator(key, op as WhereOperator, val);
                     }
                 } else {
                     // 简单的等于条件
@@ -323,6 +290,16 @@ export class SqlBuilder {
         });
     }
 
+    /**
+     * 获取 WHERE 条件（供 DbHelper 使用）
+     */
+    getWhereConditions(): { sql: string; params: SqlValue[] } {
+        return {
+            sql: this._where.length > 0 ? this._where.join(' AND ') : '',
+            params: [...this._params]
+        };
+    }
+
     /**
      * SELECT 字段
      */
@@ -342,7 +319,7 @@ export class SqlBuilder {
      */
     from(table: string): this {
         if (typeof table !== 'string' || !table.trim()) {
-            throw new Error('FROM 表名必须是非空字符串');
+            throw new Error(`FROM 表名必须是非空字符串 (table: ${table})`);
         }
         this._from = this._escapeTable(table.trim());
         return this;
@@ -370,7 +347,7 @@ export class SqlBuilder {
      */
     leftJoin(table: string, on: string): this {
         if (typeof table !== 'string' || typeof on !== 'string') {
-            throw new Error('JOIN 表名和条件必须是字符串');
+            throw new Error(`JOIN 表名和条件必须是字符串 (table: ${table}, on: ${on})`);
         }
         const escapedTable = this._escapeTable(table);
         this._joins.push(`LEFT JOIN ${escapedTable} ON ${on}`);
@@ -388,7 +365,7 @@ export class SqlBuilder {
 
         fields.forEach((item) => {
             if (typeof item !== 'string' || !item.includes('#')) {
-                throw new Error('orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"）');
+                throw new Error(`orderBy 字段必须是 "字段#方向" 格式的字符串（例如："name#ASC", "id#DESC"） (item: ${item})`);
             }
 
             const [fieldName, direction] = item.split('#');
@@ -396,11 +373,11 @@ export class SqlBuilder {
             const cleanDir = direction.trim().toUpperCase() as OrderDirection;
 
             if (!cleanField) {
-                throw new Error('orderBy 中字段名不能为空');
+                throw new Error(`orderBy 中字段名不能为空 (item: ${item})`);
             }
 
             if (!['ASC', 'DESC'].includes(cleanDir)) {
-                throw new Error('ORDER BY 方向必须是 ASC 或 DESC');
+                throw new Error(`ORDER BY 方向必须是 ASC 或 DESC (direction: ${cleanDir})`);
             }
 
             const escapedField = this._escapeField(cleanField);
@@ -438,12 +415,12 @@ export class SqlBuilder {
      */
     limit(count: number, offset?: number): this {
         if (typeof count !== 'number' || count < 0) {
-            throw new Error('LIMIT 数量必须是非负数');
+            throw new Error(`LIMIT 数量必须是非负数 (count: ${count})`);
         }
         this._limit = Math.floor(count);
         if (offset !== undefined && offset !== null) {
             if (typeof offset !== 'number' || offset < 0) {
-                throw new Error('OFFSET 必须是非负数');
+                throw new Error(`OFFSET 必须是非负数 (offset: ${offset})`);
             }
             this._offset = Math.floor(offset);
         }
@@ -455,7 +432,7 @@ export class SqlBuilder {
      */
     offset(count: number): this {
         if (typeof count !== 'number' || count < 0) {
-            throw new Error('OFFSET 必须是非负数');
+            throw new Error(`OFFSET 必须是非负数 (count: ${count})`);
         }
         this._offset = Math.floor(count);
         return this;
@@ -509,23 +486,23 @@ export class SqlBuilder {
      */
     toInsertSql(table: string, data: InsertData): SqlQuery {
         if (!table || typeof table !== 'string') {
-            throw new Error('INSERT 需要表名');
+            throw new Error(`INSERT 需要表名 (table: ${table})`);
         }
 
         if (!data || typeof data !== 'object') {
-            throw new Error('INSERT 需要数据');
+            throw new Error(`INSERT 需要数据 (table: ${table}, data: ${JSON.stringify(data)})`);
         }
 
         const escapedTable = this._escapeTable(table);
 
         if (Array.isArray(data)) {
             if (data.length === 0) {
-                throw new Error('插入数据不能为空');
+                throw new Error(`插入数据不能为空 (table: ${table})`);
             }
 
             const fields = Object.keys(data[0]);
             if (fields.length === 0) {
-                throw new Error('插入数据必须至少有一个字段');
+                throw new Error(`插入数据必须至少有一个字段 (table: ${table})`);
             }
 
             const escapedFields = fields.map((field) => this._escapeField(field));
@@ -539,7 +516,7 @@ export class SqlBuilder {
         } else {
             const fields = Object.keys(data);
             if (fields.length === 0) {
-                throw new Error('插入数据必须至少有一个字段');
+                throw new Error(`插入数据必须至少有一个字段 (table: ${table})`);
             }
 
             const escapedFields = fields.map((field) => this._escapeField(field));

package/utils/validate.ts

@@ -3,8 +3,9 @@
  * 提供类型安全的字段验证功能
  */
 
-import { isType } from './typeHelper.js';
-import { parseRule } from './tableHelper.js';
+import { isType } from './helper.js';
+import { parseRule } from './helper.js';
+import { RegexAliases } from '../config/regexAliases.js';
 import type { TableDefinition, FieldRule, ParsedFieldRule } from '../types/common.js';
 import type { ValidationResult, ValidationError } from '../types/validator';
 
@@ -104,12 +105,42 @@ export class Validator {
         }
     }
 
+    /**
+     * 解析 regex 别名
+     * 如果 regex 以 @ 开头，则从别名表中获取实际正则表达式
+     * @param regex - 原始 regex 或别名（如 @number）
+     * @returns 实际的正则表达式字符串
+     */
+    private resolveRegexAlias(regex: string | null): string | null {
+        if (!regex || typeof regex !== 'string') {
+            return regex;
+        }
+
+        // 检查是否是别名（以 @ 开头）
+        if (regex.startsWith('@')) {
+            const aliasName = regex.substring(1);
+            const resolvedRegex = RegexAliases[aliasName as keyof typeof RegexAliases];
+
+            if (resolvedRegex) {
+                return resolvedRegex;
+            }
+
+            // 别名不存在，返回原值（让后续验证报错）
+            return regex;
+        }
+
+        return regex;
+    }
+
     /**
      * 验证单个字段的值
      */
     private validateFieldValue(value: any, rule: FieldRule, fieldName: string): ValidationError {
         const parsed = parseRule(rule);
-        const { name, type, min, max, regex } = parsed;
+        let { name, type, min, max, regex } = parsed;
+
+        // 解析 regex 别名
+        regex = this.resolveRegexAlias(regex);
 
         switch (type.toLowerCase()) {
             case 'number':
@@ -118,8 +149,9 @@ export class Validator {
                 return this.validateString(value, name, min, max, regex, fieldName);
             case 'text':
                 return this.validateString(value, name, min, max, regex, fieldName);
-            case 'array':
-                return this.validateArray(value, label, min, max, regex, fieldName);
+            case 'array_string':
+            case 'array_text':
+                return this.validateArray(value, name, min, max, regex, fieldName);
             default:
                 return `字段 ${fieldName} 的类型 ${type} 不支持`;
         }
@@ -255,13 +287,22 @@ export class Validator {
      */
     static validateSingleValue(value: any, rule: string): { valid: boolean; value: any; errors: string[] } {
         const parsed = parseRule(rule);
-        const { name, type, min, max, regex, default: defaultValue } = parsed;
+        let { name, type, min, max, regex, default: defaultValue } = parsed;
+
+        // 解析 regex 别名
+        if (regex && typeof regex === 'string' && regex.startsWith('@')) {
+            const aliasName = regex.substring(1);
+            const resolvedRegex = RegexAliases[aliasName as keyof typeof RegexAliases];
+            if (resolvedRegex) {
+                regex = resolvedRegex;
+            }
+        }
 
         // 处理 undefined/null 值，使用默认值
         if (value === undefined || value === null) {
             if (defaultValue !== 'null' && defaultValue !== null) {
                 // 特殊处理数组类型的默认值字符串
-                if (type === 'array' && typeof defaultValue === 'string') {
+                if ((type === 'array_string' || type === 'array_text') && typeof defaultValue === 'string') {
                     if (defaultValue === '[]') {
                         return { valid: true, value: [], errors: [] };
                     }
@@ -281,7 +322,7 @@ export class Validator {
             // 如果没有默认值，根据类型返回默认值
             if (type === 'number') {
                 return { valid: true, value: 0, errors: [] };
-            } else if (type === 'array') {
+            } else if (type === 'array_string' || type === 'array_text') {
                 return { valid: true, value: [], errors: [] };
             } else if (type === 'string' || type === 'text') {
                 return { valid: true, value: '', errors: [] };
@@ -347,7 +388,8 @@ export class Validator {
                 }
                 break;
 
-            case 'array':
+            case 'array_string':
+            case 'array_text':
                 if (!Array.isArray(convertedValue)) {
                     errors.push(`${name || '值'}必须是数组`);
                 }

package/apis/health/info.ts

@@ -1,64 +0,0 @@
-/**
- * 健康检查接口 - TypeScript 版本
- * 检查服务器、Redis、数据库等状态
- */
-
-import { Env } from '../../config/env.js';
-import { Api } from '../../utils/api.js';
-import { Yes } from '../../utils/index.js';
-import type { BeflyContext } from '../../types/befly.js';
-import type { HealthInfo } from '../../types/api.js';
-
-export default Api('健康检查', {
-    fields: {},
-    required: [],
-    handler: async (befly: BeflyContext, ctx: any) => {
-        const info: HealthInfo = {
-            status: 'ok',
-            timestamp: new Date().toISOString(),
-            uptime: process.uptime(),
-            memory: process.memoryUsage(),
-            runtime: 'Bun',
-            version: Bun.version,
-            platform: process.platform,
-            arch: process.arch
-        };
-
-        // 检查 Redis 连接状态
-        if (Env.REDIS_ENABLE === 1) {
-            if (befly.redis) {
-                try {
-                    await befly.redis.getRedisClient().ping();
-                    info.redis = '已连接';
-                } catch (error: any) {
-                    info.redis = '未连接';
-                    info.redisError = error.message;
-                }
-            } else {
-                info.redis = '未开启';
-            }
-        } else {
-            info.redis = '禁用';
-        }
-
-        // 检查数据库连接状态
-        if (Env.DB_ENABLE === 1) {
-            if (befly.db) {
-                try {
-                    // 执行简单查询测试连接
-                    await befly.db.query('SELECT 1');
-                    info.database = '已连接';
-                } catch (error: any) {
-                    info.database = '未连接';
-                    info.databaseError = error.message;
-                }
-            } else {
-                info.database = '未开启';
-            }
-        } else {
-            info.database = '禁用';
-        }
-
-        return Yes('健康检查成功', info);
-    }
-});

package/apis/tool/tokenCheck.ts

@@ -1,51 +0,0 @@
-/**
- * 令牌检测接口 - TypeScript 版本
- * 验证 JWT 令牌是否有效
- */
-
-import { Env } from '../../config/env.js';
-import { Api } from '../../utils/api.js';
-import { Yes, No } from '../../utils/index.js';
-import { Jwt } from '../../utils/jwt.js';
-import type { BeflyContext } from '../../types/befly.js';
-import type { JwtPayload } from '../../utils/jwt.js';
-import type { TokenCheckData } from '../../types/api.js';
-
-export default Api('令牌检测', {
-    fields: {},
-    required: [],
-    handler: async (befly: BeflyContext, ctx: any) => {
-        // 从 Authorization 头获取 token
-        const authHeader = ctx.req?.headers?.get('authorization') || '';
-        const token = authHeader.split(' ')[1] || '';
-
-        if (!token) {
-            return No('令牌不能为空');
-        }
-
-        try {
-            // 验证令牌
-            const jwtData = await Jwt.verify(token);
-
-            // 计算剩余有效期
-            const expiresIn = jwtData.exp ? jwtData.exp - Math.floor(Date.now() / 1000) : undefined;
-
-            const data: TokenCheckData = {
-                valid: true,
-                payload: jwtData,
-                expiresIn
-            };
-
-            return Yes('令牌有效', data);
-        } catch (error: any) {
-            // 针对预期的令牌错误，返回友好提示（非致命错误）
-            if (error.message.includes('expired')) {
-                return No('令牌已过期', { expired: true });
-            } else if (error.message.includes('invalid')) {
-                return No('令牌无效', { invalid: true });
-            }
-            // 其他未知错误向上抛出，由路由层统一处理
-            throw error;
-        }
-    }
-});