befly 3.0.0 → 3.0.1

package/scripts/syncDb/table.ts

@@ -8,7 +8,8 @@
  */
 
 import { Logger } from '../../utils/logger.js';
-import { parseRule } from '../../utils/tableHelper.js';
+import { toSnakeCase } from '../../utils/helper.js';
+import { parseRule } from '../../utils/helper.js';
 import { IS_MYSQL, IS_PG, IS_SQLITE, SYSTEM_INDEX_FIELDS, CHANGE_TYPE_LABELS, typeMapping } from './constants.js';
 import { quoteIdentifier, logFieldChange, resolveDefaultValue, generateDefaultSql, isStringOrArrayType, getSqlType } from './helpers.js';
 import { buildIndexSQL, generateDDLClause, isPgCompatibleTypeChange } from './ddl.js';
@@ -56,13 +57,16 @@ export async function modifyTable(sql: SQL, tableName: string, fields: Record<st
     const indexActions = [];
 
     for (const [fieldKey, fieldRule] of Object.entries(fields)) {
-        if (existingColumns[fieldKey]) {
-            const comparison = compareFieldDefinition(existingColumns[fieldKey], fieldRule, fieldKey);
+        // 转换字段名为下划线格式（用于与数据库字段对比）
+        const dbFieldName = toSnakeCase(fieldKey);
+
+        if (existingColumns[dbFieldName]) {
+            const comparison = compareFieldDefinition(existingColumns[dbFieldName], fieldRule, dbFieldName);
             if (comparison.length > 0) {
                 for (const c of comparison) {
                     // 使用统一的日志格式函数和常量标签
                     const changeLabel = CHANGE_TYPE_LABELS[c.type] || '未知';
-                    logFieldChange(tableName, fieldKey, c.type, c.current, c.expected, changeLabel);
+                    logFieldChange(tableName, dbFieldName, c.type, c.current, c.expected, changeLabel);
 
                     // 全量计数：全局累加
                     if (c.type === 'datatype') globalCount.typeChanges++;
@@ -74,9 +78,9 @@ export async function modifyTable(sql: SQL, tableName: string, fields: Record<st
                 const parsed = parseRule(fieldRule);
                 const { name: fieldName, type: fieldType, max: fieldMax, default: fieldDefault } = parsed;
 
-                if (isStringOrArrayType(fieldType) && existingColumns[fieldKey].length) {
-                    if (existingColumns[fieldKey].length! > fieldMax) {
-                        Logger.warn(`[跳过危险变更] ${tableName}.${fieldKey} 长度收缩 ${existingColumns[fieldKey].length} -> ${fieldMax} 已被跳过（设置 SYNC_DISALLOW_SHRINK=0 可放开）`);
+                if (isStringOrArrayType(fieldType) && existingColumns[dbFieldName].length) {
+                    if (existingColumns[dbFieldName].length! > fieldMax) {
+                        Logger.warn(`[跳过危险变更] ${tableName}.${dbFieldName} 长度收缩 ${existingColumns[dbFieldName].length} -> ${fieldMax} 已被跳过（设置 SYNC_DISALLOW_SHRINK=0 可放开）`);
                     }
                 }
 
@@ -87,9 +91,9 @@ export async function modifyTable(sql: SQL, tableName: string, fields: Record<st
 
                 // 严格限制：除 string/array 互转外，禁止任何字段类型变更；一旦发现，立即终止同步
                 if (hasTypeChange) {
-                    const currentSqlType = String(existingColumns[fieldKey].type || '').toLowerCase();
+                    const currentSqlType = String(existingColumns[dbFieldName].type || '').toLowerCase();
                     const newSqlType = String(typeMapping[fieldType] || '').toLowerCase();
-                    const errorMsg = [`禁止字段类型变更: ${tableName}.${fieldKey}`, `当前类型: ${currentSqlType}`, `目标类型: ${newSqlType}`, `说明: 仅允许 string<->array 互相切换，其他类型变更需要手动处理`].join('\n');
+                    const errorMsg = [`禁止字段类型变更: ${tableName}.${dbFieldName}`, `当前类型: ${currentSqlType}`, `目标类型: ${newSqlType}`, `说明: 仅允许 string<->array 互相切换，其他类型变更需要手动处理`].join('\n');
                     throw new Error(errorMsg);
                 }
 
@@ -108,11 +112,11 @@ export async function modifyTable(sql: SQL, tableName: string, fields: Record<st
 
                     if (v !== null && v !== '') {
                         if (IS_PG) {
-                            defaultClauses.push(`ALTER COLUMN "${fieldKey}" SET DEFAULT ${v}`);
+                            defaultClauses.push(`ALTER COLUMN "${dbFieldName}" SET DEFAULT ${v}`);
                         } else if (IS_MYSQL && onlyDefaultChanged) {
                             // MySQL 的 TEXT/BLOB 不允许 DEFAULT，跳过 text 类型
                             if (fieldType !== 'text') {
-                                defaultClauses.push(`ALTER COLUMN \`${fieldKey}\` SET DEFAULT ${v}`);
+                                defaultClauses.push(`ALTER COLUMN \`${dbFieldName}\` SET DEFAULT ${v}`);
                             }
                         }
                     }
@@ -121,15 +125,15 @@ export async function modifyTable(sql: SQL, tableName: string, fields: Record<st
                 // 若不仅仅是默认值变化，继续生成修改子句
                 if (!onlyDefaultChanged) {
                     let skipModify = false;
-                    if (hasLengthChange && isStringOrArrayType(fieldType) && existingColumns[fieldKey].length) {
-                        const oldLen = existingColumns[fieldKey].length!;
+                    if (hasLengthChange && isStringOrArrayType(fieldType) && existingColumns[dbFieldName].length) {
+                        const oldLen = existingColumns[dbFieldName].length!;
                         const isShrink = oldLen > fieldMax;
                         if (isShrink) skipModify = true;
                     }
 
                     if (hasTypeChange) {
-                        if (IS_PG && isPgCompatibleTypeChange(existingColumns[fieldKey].type, typeMapping[fieldType].toLowerCase())) {
-                            Logger.info(`[PG兼容类型变更] ${tableName}.${fieldKey} ${existingColumns[fieldKey].type} -> ${typeMapping[fieldType].toLowerCase()} 允许执行`);
+                        if (IS_PG && isPgCompatibleTypeChange(existingColumns[dbFieldName].type, typeMapping[fieldType].toLowerCase())) {
+                            Logger.info(`[PG兼容类型变更] ${tableName}.${dbFieldName} ${existingColumns[dbFieldName].type} -> ${typeMapping[fieldType].toLowerCase()} 允许执行`);
                         }
                     }
 
@@ -141,7 +145,7 @@ export async function modifyTable(sql: SQL, tableName: string, fields: Record<st
             const parsed = parseRule(fieldRule);
             const { name: fieldName, type: fieldType, max: fieldMax, default: fieldDefault } = parsed;
             const lenPart = isStringOrArrayType(fieldType) ? ` 长度:${parseInt(String(fieldMax))}` : '';
-            Logger.info(`[新增字段] ${tableName}.${fieldKey} 类型:${fieldType}${lenPart} 默认:${fieldDefault ?? 'NULL'}`);
+            Logger.info(`[新增字段] ${tableName}.${dbFieldName} 类型:${fieldType}${lenPart} 默认:${fieldDefault ?? 'NULL'}`);
             addClauses.push(generateDDLClause(fieldKey, fieldRule, true));
             changed = true;
             globalCount.addFields++;
@@ -160,14 +164,17 @@ export async function modifyTable(sql: SQL, tableName: string, fields: Record<st
 
     // 检查业务字段索引
     for (const [fieldKey, fieldRule] of Object.entries(fields)) {
+        // 转换字段名为下划线格式
+        const dbFieldName = toSnakeCase(fieldKey);
+
         const parsed = parseRule(fieldRule);
-        const indexName = `idx_${fieldKey}`;
+        const indexName = `idx_${dbFieldName}`;
         if (parsed.index === 1 && !existingIndexes[indexName]) {
-            indexActions.push({ action: 'create', indexName, fieldName: fieldKey });
+            indexActions.push({ action: 'create', indexName, fieldName: dbFieldName });
             changed = true;
             globalCount.indexCreate++;
         } else if (!(parsed.index === 1) && existingIndexes[indexName] && existingIndexes[indexName].length === 1) {
-            indexActions.push({ action: 'drop', indexName, fieldName: fieldKey });
+            indexActions.push({ action: 'drop', indexName, fieldName: dbFieldName });
             changed = true;
             globalCount.indexDrop++;
         }
@@ -177,13 +184,16 @@ export async function modifyTable(sql: SQL, tableName: string, fields: Record<st
     const commentActions = [];
     if (IS_PG) {
         for (const [fieldKey, fieldRule] of Object.entries(fields)) {
-            if (existingColumns[fieldKey]) {
+            // 转换字段名为下划线格式
+            const dbFieldName = toSnakeCase(fieldKey);
+
+            if (existingColumns[dbFieldName]) {
                 const parsed = parseRule(fieldRule);
                 const { name: fieldName } = parsed;
-                const curr = existingColumns[fieldKey].comment || '';
+                const curr = existingColumns[dbFieldName].comment || '';
                 const want = fieldName && fieldName !== 'null' ? String(fieldName) : '';
                 if (want !== curr) {
-                    commentActions.push(`COMMENT ON COLUMN "${tableName}"."${fieldKey}" IS ${want ? `'${want}'` : 'NULL'}`);
+                    commentActions.push(`COMMENT ON COLUMN "${tableName}"."${dbFieldName}" IS ${want ? `'${want}'` : 'NULL'}`);
                     changed = true;
                 }
             }

package/scripts/syncDb/tableCreate.ts

@@ -13,7 +13,7 @@ import { Logger } from '../../utils/logger.js';
 import { IS_MYSQL, IS_PG, MYSQL_TABLE_CONFIG } from './constants.js';
 import { quoteIdentifier } from './helpers.js';
 import { buildSystemColumnDefs, buildBusinessColumnDefs, buildIndexSQL } from './ddl.js';
-import { parseRule } from '../../utils/tableHelper.js';
+import { parseRule, toSnakeCase } from '../../utils/helper.js';
 import type { SQL } from 'bun';
 
 // 是否为计划模式（从环境变量读取）
@@ -47,9 +47,12 @@ async function addPostgresComments(sql: SQL, tableName: string, fields: Record<s
 
     // 业务字段注释
     for (const [fieldKey, fieldRule] of Object.entries(fields)) {
+        // 转换字段名为下划线格式
+        const dbFieldName = toSnakeCase(fieldKey);
+
         const parsed = parseRule(fieldRule);
         const { name: fieldName } = parsed;
-        const stmt = `COMMENT ON COLUMN "${tableName}"."${fieldKey}" IS '${fieldName}'`;
+        const stmt = `COMMENT ON COLUMN "${tableName}"."${dbFieldName}" IS '${fieldName}'`;
         if (IS_PLAN) {
             Logger.info(`[计划] ${stmt}`);
         } else {
@@ -81,9 +84,12 @@ async function createTableIndexes(sql: SQL, tableName: string, fields: Record<st
 
     // 业务字段索引
     for (const [fieldKey, fieldRule] of Object.entries(fields)) {
+        // 转换字段名为下划线格式
+        const dbFieldName = toSnakeCase(fieldKey);
+
         const parsed = parseRule(fieldRule);
         if (parsed.index === 1) {
-            const stmt = buildIndexSQL(tableName, `idx_${fieldKey}`, fieldKey, 'create');
+            const stmt = buildIndexSQL(tableName, `idx_${dbFieldName}`, dbFieldName, 'create');
             if (IS_PLAN) {
                 Logger.info(`[计划] ${stmt}`);
             } else {

package/scripts/syncDb/tests/constants.test.ts

@@ -82,7 +82,8 @@ describe('syncDb/constants', () => {
             expect(typeMapping.number).toBeDefined();
             expect(typeMapping.string).toBeDefined();
             expect(typeMapping.text).toBeDefined();
-            expect(typeMapping.array).toBeDefined();
+            expect(typeMapping.array_string).toBeDefined();
+            expect(typeMapping.array_text).toBeDefined();
         });
 
         test('不同数据库的类型映射应不同', () => {

package/scripts/syncDb.ts

@@ -1,9 +1,10 @@
-import { SyncDb } from './syncDb/index.js';
-
-// 如果直接运行此脚本
-if (import.meta.main) {
-    SyncDb().catch((error) => {
-        console.error('❌ 数据库同步失败:', error);
-        process.exit(1);
-    });
-}
+import { SyncDb } from './syncDb/index.js';
+import { Logger } from '../utils/logger.js';
+
+// 如果直接运行此脚本
+if (import.meta.main) {
+    SyncDb().catch((error) => {
+        Logger.error('数据库同步失败', error);
+        process.exit(1);
+    });
+}

package/types/addon.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Addon 配置类型定义
+ */
+
+/**
+ * Addon 作者信息
+ */
+export interface AddonAuthor {
+    /** 作者名称 */
+    name: string;
+    /** 作者邮箱 */
+    email?: string;
+    /** 作者网站 */
+    url?: string;
+}
+
+/**
+ * Addon 配置
+ */
+export interface AddonConfig {
+    /** Addon 唯一标识（小写、短横线或下划线），例如 "admin"、"demo" */
+    name: string;
+
+    /** Addon 人类可读名称，例如 "管理后台" */
+    title: string;
+
+    /** 版本号（语义化版本），例如 "1.0.0" */
+    version?: string;
+
+    /** 简短描述 */
+    description?: string;
+
+    /** 作者信息 */
+    author?: AddonAuthor | string;
+
+    /** 源码仓库链接 */
+    repo?: string;
+
+    /** 关键词（用于搜索和分类） */
+    keywords?: string[];
+
+    /** 主入口文件路径（相对于 addon 目录），例如 "index.ts" */
+    entry?: string;
+
+    /** 是否默认启用 */
+    enabled?: boolean;
+
+    /** 依赖的其他 addon 或核心包 */
+    dependencies?: Record<string, string>;
+
+    /** 许可证 */
+    license?: string;
+}

package/types/api.d.ts

@@ -99,26 +99,29 @@ export interface ApiOptions {
  * API 路由配置
  */
 export interface ApiRoute<T = any, R = any> {
-    /** HTTP 方法 */
-    method: HttpMethod;
-
-    /** 接口名称 */
+    /** 接口名称（必填） */
     name: string;
 
-    /** 路由路径（运行时生成） */
-    route?: string;
+    /** 处理器函数（必填） */
+    handler: ApiHandler<T, R>;
 
-    /** 认证类型 */
-    auth: boolean | string | string[];
+    /** HTTP 方法（可选，默认 POST） */
+    method?: HttpMethod;
 
-    /** 字段定义（验证规则） */
-    fields: TableDefinition;
+    /** 认证类型（可选，默认 true）
+     * - true: 需要登录
+     * - false: 公开访问（无需登录）
+     */
+    auth?: boolean;
 
-    /** 必填字段 */
-    required: string[];
+    /** 字段定义（验证规则）（可选，默认 {}） */
+    fields?: TableDefinition;
 
-    /** 处理器函数 */
-    handler: ApiHandler<T, R>;
+    /** 必填字段（可选，默认 []） */
+    required?: string[];
+
+    /** 路由路径（运行时生成） */
+    route?: string;
 }
 
 /**

package/types/befly.d.ts

@@ -8,9 +8,8 @@ import type { KeyValue } from './common.js';
 import type { Logger } from '../utils/logger.js';
 import type { Jwt } from '../utils/jwt.js';
 import type { Validator } from '../utils/validate.js';
-import type { SqlHelper } from '../utils/sqlHelper.js';
+import type { DbHelper } from '../utils/dbHelper.js';
 import type { Crypto2 } from '../utils/crypto.js';
-import type { Tool } from '../utils/tool.js';
 
 /**
  * Befly 应用选项
@@ -79,14 +78,11 @@ export interface Befly {
     validator: Validator;
 
     /** SQL 管理器 */
-    sql: SqlHelper;
+    sql: DbHelper;
 
     /** 加密工具 */
     crypto: Crypto2;
 
-    /** 通用工具 */
-    tool: Tool;
-
     /** 数据库连接 */
     db: any;
 

package/types/context.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 请求上下文类型定义
+ * 实现代码位于 utils/requestContext.ts
+ */
+
+// 重新导出 RequestContext 类
+export { RequestContext } from '../utils/requestContext.js';

package/types/database.d.ts

@@ -17,16 +17,12 @@ export interface QueryOptions {
     fields?: string[];
     /** WHERE 条件 */
     where?: WhereConditions;
-    /** 排序 */
-    orderBy?: string;
+    /** 排序（格式：["字段#ASC", "字段#DESC"]） */
+    orderBy?: string[];
     /** 页码（从 1 开始） */
     page?: number;
     /** 每页数量 */
     limit?: number;
-    /** 是否包含已删除数据 */
-    includeDeleted?: boolean;
-    /** 自定义 state 条件 */
-    customState?: WhereConditions;
 }
 
 /**
@@ -49,8 +45,6 @@ export interface UpdateOptions {
     data: Record<string, any>;
     /** WHERE 条件 */
     where: WhereConditions;
-    /** 是否包含已删除数据 */
-    includeDeleted?: boolean;
 }
 
 /**
@@ -61,8 +55,6 @@ export interface DeleteOptions {
     table: string;
     /** WHERE 条件 */
     where: WhereConditions;
-    /** 是否物理删除（false=软删除，true=物理删除） */
-    hard?: boolean;
 }
 
 /**
@@ -84,7 +76,7 @@ export interface ListResult<T = any> {
 /**
  * 事务回调函数
  */
-export type TransactionCallback<T = any> = (trans: SqlHelper) => Promise<T>;
+export type TransactionCallback<T = any> = (trans: DbHelper) => Promise<T>;
 
 /**
  * SQL 查询结果
@@ -154,10 +146,11 @@ export interface SyncStats {
 }
 
 /**
- * SqlHelper 接口（前向声明）
+ * DbHelper 接口（前向声明）
  */
-export interface SqlHelper {
-    getDetail<T = any>(options: QueryOptions): Promise<T | null>;
+export interface DbHelper {
+    getCount(options: Omit<QueryOptions, 'fields' | 'page' | 'limit' | 'orderBy'>): Promise<number>;
+    getOne<T = any>(options: QueryOptions): Promise<T | null>;
     getList<T = any>(options: QueryOptions): Promise<ListResult<T>>;
     getAll<T = any>(options: Omit<QueryOptions, 'page' | 'limit'>): Promise<T[]>;
     insData(options: InsertOptions): Promise<number>;
@@ -175,6 +168,8 @@ export interface SqlClientOptions {
     max?: number;
     /** 是否使用 BigInt */
     bigint?: boolean;
+    /** 连接超时时间（毫秒），默认 5000ms */
+    connectionTimeout?: number;
     /** 其他自定义选项 */
     [key: string]: any;
 }