befly 3.14.0 → 3.14.2

package/dist/checks/checkTable.js

@@ -168,11 +168,13 @@ export async function checkTable(tables) {
                     }
                 }
                 else if (fieldType === "string" || fieldType === "array_string" || fieldType === "array_number_string") {
-                    if (fieldMax !== undefined && (fieldMax === null || typeof fieldMax !== "number")) {
-                        Logger.warn(`${tablePrefix}${fileName} 文件 ${colKey} 为 ${fieldType} 类型，` + `最大长度必须为数字，当前为 "${fieldMax}"`);
+                    // 约束：string/array_*_string 必须声明 max。
+                    // 说明：array_*_string 的 max 表示“单个元素字符串长度”，不是数组元素数量。
+                    if (fieldMax === undefined || fieldMax === null || typeof fieldMax !== "number") {
+                        Logger.warn(`${tablePrefix}${fileName} 文件 ${colKey} 为 ${fieldType} 类型，` + `必须设置 max 且类型为数字；其中 array_*_string 的 max 表示单个元素长度，当前为 "${fieldMax}"`);
                         hasError = true;
                     }
-                    else if (fieldMax !== undefined && fieldMax > MAX_VARCHAR_LENGTH) {
+                    else if (fieldMax > MAX_VARCHAR_LENGTH) {
                         Logger.warn(`${tablePrefix}${fileName} 文件 ${colKey} 最大长度 ${fieldMax} 越界，` + `${fieldType} 类型长度必须在 1..${MAX_VARCHAR_LENGTH} 范围内`);
                         hasError = true;
                     }

package/dist/hooks/validator.js

@@ -1,5 +1,6 @@
 // 相对导入
 import { Validator } from "../lib/validator";
+import { normalizeFieldDefinition } from "../utils/normalizeFieldDefinition";
 import { ErrorResponse } from "../utils/response";
 import { isPlainObject, snakeCase } from "../utils/util";
 /**
@@ -22,6 +23,7 @@ const validatorHook = {
             const rawBody = isPlainObject(ctx.body) ? ctx.body : {};
             const nextBody = {};
             for (const [field, fieldDef] of Object.entries(ctx.api.fields)) {
+                const normalized = normalizeFieldDefinition(fieldDef);
                 let value = rawBody[field];
                 if (value === undefined) {
                     const snakeField = snakeCase(field);
@@ -30,8 +32,8 @@ const validatorHook = {
                     }
                 }
                 // 字段未传值且定义了默认值时，应用默认值
-                if (value === undefined && fieldDef?.default !== undefined && fieldDef?.default !== null) {
-                    value = fieldDef.default;
+                if (value === undefined && normalized.default !== null) {
+                    value = normalized.default;
                 }
                 if (value !== undefined) {
                     nextBody[field] = value;

package/dist/index.js

@@ -52,14 +52,14 @@ export class Befly {
         try {
             const serverStartTime = Bun.nanoseconds();
             // 0. 加载配置
-            this.config = await loadBeflyConfig(env.NODE_ENV || "development");
+            this.config = await loadBeflyConfig(env["NODE_ENV"] || "development");
             // 将配置注入到 ctx，供插件/Hook/sync 等按需读取
             this.context.config = this.config;
             // 给插件/Hook/sync 一个统一读取 env 的入口（只从 start 入参注入）
             this.context.env = env;
             const { apis, tables, plugins, hooks, addons } = await scanSources();
             // 让后续 syncMenu 能拿到 addon 的 views 路径等信息
-            this.context.addons = addons;
+            this.context["addons"] = addons;
             await checkApi(apis);
             await checkTable(tables);
             await checkPlugin(plugins);
@@ -88,7 +88,14 @@ export class Befly {
             await syncTable(this.context, tables);
             await syncApi(this.context, apis);
             await syncMenu(this.context, checkedMenus);
-            await syncDev(this.context, { devEmail: this.config.devEmail, devPassword: this.config.devPassword });
+            const devEmail = this.config.devEmail;
+            const devPassword = this.config.devPassword;
+            if (typeof devEmail === "string" && devEmail.length > 0 && typeof devPassword === "string" && devPassword.length > 0) {
+                await syncDev(this.context, { devEmail: devEmail, devPassword: devPassword });
+            }
+            else {
+                Logger.debug("跳过 syncDev：未配置 devEmail/devPassword");
+            }
             // 缓存同步：统一在所有同步完成后执行（cacheApis + cacheMenus + rebuildRoleApiPermissions）
             await syncCache(this.context);
             // 3. 加载钩子
@@ -98,9 +105,11 @@ export class Befly {
             // 6. 启动 HTTP服务器
             const apiFetch = apiHandler(this.apis, this.hooks, this.context);
             const staticFetch = staticHandler(this.config.cors);
+            const port = typeof this.config.appPort === "number" ? this.config.appPort : 3000;
+            const hostname = typeof this.config.appHost === "string" && this.config.appHost.length > 0 ? this.config.appHost : "0.0.0.0";
             const server = Bun.serve({
-                port: this.config.appPort,
-                hostname: this.config.appHost,
+                port: port,
+                hostname: hostname,
                 // 开发模式下启用详细错误信息
                 development: this.config.nodeEnv === "development",
                 // 空闲连接超时时间（秒），防止恶意连接占用资源

package/dist/lib/asyncContext.js

@@ -20,8 +20,8 @@ export function setCtxUser(userId, roleCode, nickname, roleType) {
     const store = storage.getStore();
     if (!store)
         return;
-    store.userId = userId;
-    store.roleCode = roleCode;
-    store.nickname = nickname;
-    store.roleType = roleType;
+    store.userId = userId === undefined ? null : userId;
+    store.roleCode = roleCode === undefined ? null : roleCode;
+    store.nickname = nickname === undefined ? null : nickname;
+    store.roleType = roleType === undefined ? null : roleType;
 }

package/dist/lib/cacheHelper.d.ts

@@ -6,9 +6,9 @@ type CacheHelperDb = {
     tableExists(table: string): Promise<{
         data: boolean;
     }>;
-    getAll(options: any): Promise<{
+    getAll<TItem = unknown>(options: unknown): Promise<{
         data: {
-            lists: any[];
+            lists: TItem[];
         };
     }>;
 };

package/dist/lib/dbHelper.d.ts

@@ -2,8 +2,8 @@
  * 数据库助手 - TypeScript 版本
  * 提供数据库 CRUD 操作的封装
  */
-import type { WhereConditions } from "../types/common";
-import type { QueryOptions, InsertOptions, UpdateOptions, DeleteOptions, ListResult, AllResult, TransactionCallback, DbResult, ListSql } from "../types/database";
+import type { WhereConditions, SqlValue } from "../types/common";
+import type { QueryOptions, InsertOptions, UpdateOptions, DeleteOptions, DbPageResult, DbListResult, TransactionCallback, DbResult, ListSql } from "../types/database";
 import type { DbDialect } from "./dbDialect";
 type RedisCacheLike = {
     getObject<T = any>(key: string): Promise<T | null>;
@@ -42,7 +42,7 @@ export declare class DbHelper {
      * - 复用当前 DbHelper 持有的连接/事务
      * - 统一走 executeWithConn，保持参数校验与错误行为一致
      */
-    unsafe(sqlStr: string, params?: any[]): Promise<DbResult<any>>;
+    unsafe<TResult = unknown>(sqlStr: string, params?: unknown[]): Promise<DbResult<TResult>>;
     /**
      * 检查表是否存在
      * @param tableName - 表名（支持小驼峰，会自动转换为下划线）
@@ -72,6 +72,12 @@ export declare class DbHelper {
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换；联查时可带别名如 'order o'）
      * @param options.fields - 字段列表（联查时需带表别名，如 'o.id', 'u.username'）
      * @param options.joins - 多表联查选项
+     * @returns DbResult<TItem>
+     *
+     * 语义说明（重要）：
+     * - 本方法不再用 `null` 表示“未命中”。
+     * - 当查询未命中（或数据反序列化失败）时，`data` 将返回空对象 `{}`。
+     * - 因此业务侧应通过关键字段判断是否存在（例如 `if (!res.data?.id) { ... }`）。
      * @example
      * // 单表查询
      * getOne({ table: 'userProfile', fields: ['userId', 'userName'] })
@@ -83,7 +89,15 @@ export declare class DbHelper {
      *     where: { 'o.id': 1 }
      * })
      */
-    getOne<T extends Record<string, any> = Record<string, any>>(options: QueryOptions): Promise<DbResult<T | null>>;
+    getOne<TItem extends Record<string, unknown> = Record<string, unknown>>(options: QueryOptions): Promise<DbResult<TItem>>;
+    /**
+     * 语义化别名：getDetail（与 getOne 一致）
+     *
+     * 说明：Befly 早期业务侧习惯用 getDetail 表达“查详情”；这里不引入新的查询逻辑，直接复用 getOne。
+     *
+     * 语义说明：与 getOne 完全一致，未命中时 `data` 返回 `{}`。
+     */
+    getDetail<TItem extends Record<string, unknown> = Record<string, unknown>>(options: QueryOptions): Promise<DbResult<TItem>>;
     /**
      * 查询列表（带分页）
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换；联查时可带别名）
@@ -106,7 +120,7 @@ export declare class DbHelper {
      *     limit: 10
      * })
      */
-    getList<T extends Record<string, any> = Record<string, any>>(options: QueryOptions): Promise<DbResult<ListResult<T>, ListSql>>;
+    getList<TItem extends Record<string, unknown> = Record<string, unknown>>(options: QueryOptions): Promise<DbResult<DbPageResult<TItem>, ListSql>>;
     /**
      * 查询所有数据（不分页，有上限保护）
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换；联查时可带别名）
@@ -124,23 +138,25 @@ export declare class DbHelper {
      *     where: { 'o.state': 1 }
      * })
      */
-    getAll<T extends Record<string, any> = Record<string, any>>(options: Omit<QueryOptions, "page" | "limit">): Promise<DbResult<AllResult<T>, ListSql>>;
+    getAll<TItem extends Record<string, unknown> = Record<string, unknown>>(options: Omit<QueryOptions, "page" | "limit">): Promise<DbResult<DbListResult<TItem>, ListSql>>;
     /**
      * 插入数据（自动生成 ID、时间戳、state）
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
      */
-    insData(options: InsertOptions): Promise<DbResult<number>>;
+    insData<TInsert extends Record<string, SqlValue> = Record<string, SqlValue>>(options: Omit<InsertOptions, "data"> & {
+        data: TInsert | TInsert[];
+    }): Promise<DbResult<number>>;
     /**
      * 批量插入数据（真正的批量操作）
      * 使用 INSERT INTO ... VALUES (...), (...), (...) 语法
      * 自动生成系统字段并包装在事务中
      * @param table - 表名（支持小驼峰或下划线格式，会自动转换）
      */
-    insBatch(table: string, dataList: Record<string, any>[]): Promise<DbResult<number[]>>;
+    insBatch<TInsert extends Record<string, SqlValue> = Record<string, SqlValue>>(table: string, dataList: TInsert[]): Promise<DbResult<number[]>>;
     delForceBatch(table: string, ids: number[]): Promise<DbResult<number>>;
     updBatch(table: string, dataList: Array<{
         id: number;
-        data: Record<string, any>;
+        data: Record<string, unknown>;
     }>): Promise<DbResult<number>>;
     /**
      * 更新数据（强制更新时间戳，系统字段不可修改）
@@ -171,11 +187,11 @@ export declare class DbHelper {
      * 执行事务
      * 使用 Bun SQL 的 begin 方法开启事务
      */
-    trans<T = any>(callback: TransactionCallback<T>): Promise<T>;
+    trans<TResult = unknown>(callback: TransactionCallback<TResult, DbHelper>): Promise<TResult>;
     /**
      * 执行原始 SQL
      */
-    query(sql: string, params?: any[]): Promise<DbResult<any>>;
+    query<TResult = unknown>(sql: string, params?: unknown[]): Promise<DbResult<TResult>>;
     /**
      * 检查数据是否存在（优化性能）
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换）
@@ -185,9 +201,9 @@ export declare class DbHelper {
      * 查询单个字段值（带字段名验证）
      * @param field - 字段名（支持小驼峰或下划线格式）
      */
-    getFieldValue<T = any>(options: Omit<QueryOptions, "fields"> & {
+    getFieldValue<TValue = unknown>(options: Omit<QueryOptions, "fields"> & {
         field: string;
-    }): Promise<DbResult<T | null>>;
+    }): Promise<DbResult<TValue | null>>;
     /**
      * 自增字段（安全实现，防止 SQL 注入）
      * @param table - 表名（支持小驼峰或下划线格式，会自动转换）

package/dist/lib/dbHelper.js

@@ -28,7 +28,7 @@ export class DbHelper {
     constructor(options) {
         this.redis = options.redis;
         this.sql = options.sql || null;
-        this.isTransaction = !!options.sql;
+        this.isTransaction = Boolean(options.sql);
         // 默认使用 MySQL 方言（当前 core 的表结构/语法也主要基于 MySQL）
         this.dialect = options.dialect ? options.dialect : new MySqlDialect();
     }
@@ -217,10 +217,11 @@ export class DbHelper {
      */
     async getCount(options) {
         const { table, where, joins, tableQualifier } = await this.prepareQueryOptions(options);
+        const hasJoins = Array.isArray(joins) && joins.length > 0;
         const builder = this.createSqlBuilder()
             .selectRaw("COUNT(*) as count")
             .from(table)
-            .where(DbUtils.addDefaultStateFilter(where, tableQualifier, !!joins));
+            .where(DbUtils.addDefaultStateFilter(where, tableQualifier, hasJoins));
         // 添加 JOIN
         this.applyJoins(builder, joins);
         const { sql, params } = builder.toSelectSql();
@@ -236,6 +237,12 @@ export class DbHelper {
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换；联查时可带别名如 'order o'）
      * @param options.fields - 字段列表（联查时需带表别名，如 'o.id', 'u.username'）
      * @param options.joins - 多表联查选项
+     * @returns DbResult<TItem>
+     *
+     * 语义说明（重要）：
+     * - 本方法不再用 `null` 表示“未命中”。
+     * - 当查询未命中（或数据反序列化失败）时，`data` 将返回空对象 `{}`。
+     * - 因此业务侧应通过关键字段判断是否存在（例如 `if (!res.data?.id) { ... }`）。
      * @example
      * // 单表查询
      * getOne({ table: 'userProfile', fields: ['userId', 'userName'] })
@@ -249,10 +256,11 @@ export class DbHelper {
      */
     async getOne(options) {
         const { table, fields, where, joins, tableQualifier } = await this.prepareQueryOptions(options);
+        const hasJoins = Array.isArray(joins) && joins.length > 0;
         const builder = this.createSqlBuilder()
             .select(fields)
             .from(table)
-            .where(DbUtils.addDefaultStateFilter(where, tableQualifier, !!joins));
+            .where(DbUtils.addDefaultStateFilter(where, tableQualifier, hasJoins));
         // 添加 JOIN
         this.applyJoins(builder, joins);
         const { sql, params } = builder.toSelectSql();
@@ -262,7 +270,7 @@ export class DbHelper {
         const row = result?.[0] || null;
         if (!row) {
             return {
-                data: null,
+                data: {},
                 sql: execRes.sql
             };
         }
@@ -271,17 +279,28 @@ export class DbHelper {
         const deserialized = DbUtils.deserializeArrayFields(camelRow);
         if (!deserialized) {
             return {
-                data: null,
+                data: {},
                 sql: execRes.sql
             };
         }
         // 转换 BIGINT 字段（id, pid 等）为数字类型
-        const data = convertBigIntFields([deserialized])[0];
+        const convertedList = convertBigIntFields([deserialized]);
+        const data = convertedList[0] ?? deserialized;
         return {
             data: data,
             sql: execRes.sql
         };
     }
+    /**
+     * 语义化别名：getDetail（与 getOne 一致）
+     *
+     * 说明：Befly 早期业务侧习惯用 getDetail 表达“查详情”；这里不引入新的查询逻辑，直接复用 getOne。
+     *
+     * 语义说明：与 getOne 完全一致，未命中时 `data` 返回 `{}`。
+     */
+    async getDetail(options) {
+        return await this.getOne(options);
+    }
     /**
      * 查询列表（带分页）
      * @param options.table - 表名（支持小驼峰或下划线格式，会自动转换；联查时可带别名）
@@ -314,7 +333,7 @@ export class DbHelper {
             throw new Error(`每页数量必须在 1 到 1000 之间 (table: ${options.table}, page: ${prepared.page}, limit: ${prepared.limit})`);
         }
         // 构建查询
-        const whereFiltered = DbUtils.addDefaultStateFilter(prepared.where, prepared.tableQualifier, !!prepared.joins);
+        const whereFiltered = DbUtils.addDefaultStateFilter(prepared.where, prepared.tableQualifier, Array.isArray(prepared.joins) && prepared.joins.length > 0);
         // 查询总数
         const countBuilder = this.createSqlBuilder().selectRaw("COUNT(*) as total").from(prepared.table).where(whereFiltered);
         // 添加 JOIN（计数也需要）
@@ -389,8 +408,21 @@ export class DbHelper {
         // 添加硬性上限保护，防止内存溢出
         const MAX_LIMIT = 10000;
         const WARNING_LIMIT = 1000;
-        const prepared = await this.prepareQueryOptions({ ...options, page: 1, limit: 10 });
-        const whereFiltered = DbUtils.addDefaultStateFilter(prepared.where, prepared.tableQualifier, !!prepared.joins);
+        const prepareOptions = {
+            table: options.table,
+            page: 1,
+            limit: 10
+        };
+        if (options.fields !== undefined)
+            prepareOptions.fields = options.fields;
+        if (options.where !== undefined)
+            prepareOptions.where = options.where;
+        if (options.joins !== undefined)
+            prepareOptions.joins = options.joins;
+        if (options.orderBy !== undefined)
+            prepareOptions.orderBy = options.orderBy;
+        const prepared = await this.prepareQueryOptions(prepareOptions);
+        const whereFiltered = DbUtils.addDefaultStateFilter(prepared.where, prepared.tableQualifier, Array.isArray(prepared.joins) && prepared.joins.length > 0);
         // 查询真实总数
         const countBuilder = this.createSqlBuilder().selectRaw("COUNT(*) as total").from(prepared.table).where(whereFiltered);
         // 添加 JOIN（计数也需要）
@@ -468,7 +500,7 @@ export class DbHelper {
         const { sql, params } = builder.toInsertSql(snakeTable, processed);
         // 执行
         const execRes = await this.executeWithConn(sql, params);
-        const insertedId = processed.id || execRes.data?.lastInsertRowid || 0;
+        const insertedId = processed["id"] || execRes.data?.lastInsertRowid || 0;
         return {
             data: insertedId,
             sql: execRes.sql
@@ -504,7 +536,11 @@ export class DbHelper {
         const now = Date.now();
         // 处理所有数据（自动添加系统字段）
         const processedList = dataList.map((data, index) => {
-            return DbUtils.buildInsertRow({ data: data, id: ids[index], now: now });
+            const id = ids[index];
+            if (typeof id !== "number") {
+                throw new Error(`批量插入生成 ID 失败：ids[${index}] 不是 number (table: ${snakeTable})`);
+            }
+            return DbUtils.buildInsertRow({ data: data, id: id, now: now });
         });
         // 入口校验：保证进入 SqlBuilder 的批量数据结构一致且无 undefined
         const insertFields = SqlCheck.assertBatchInsertRowsConsistent(processedList, { table: snakeTable });
@@ -730,24 +766,29 @@ export class DbHelper {
      * @param field - 字段名（支持小驼峰或下划线格式）
      */
     async getFieldValue(options) {
-        const { field, ...queryOptions } = options;
+        const field = options.field;
         // 验证字段名格式（只允许字母、数字、下划线）
         if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(field)) {
             throw new Error(`无效的字段名: ${field}，只允许字母、数字和下划线`);
         }
-        const oneRes = await this.getOne({
-            ...queryOptions,
-            fields: [field]
-        });
+        const oneOptions = {
+            table: options.table
+        };
+        if (options.where !== undefined)
+            oneOptions.where = options.where;
+        if (options.joins !== undefined)
+            oneOptions.joins = options.joins;
+        if (options.orderBy !== undefined)
+            oneOptions.orderBy = options.orderBy;
+        if (options.page !== undefined)
+            oneOptions.page = options.page;
+        if (options.limit !== undefined)
+            oneOptions.limit = options.limit;
+        oneOptions.fields = [field];
+        const oneRes = await this.getOne(oneOptions);
         const result = oneRes.data;
-        if (!result) {
-            return {
-                data: null,
-                sql: oneRes.sql
-            };
-        }
         // 尝试直接访问字段（小驼峰）
-        if (field in result) {
+        if (Object.hasOwn(result, field)) {
             return {
                 data: result[field],
                 sql: oneRes.sql
@@ -755,7 +796,7 @@ export class DbHelper {
         }
         // 转换为小驼峰格式再尝试访问（支持用户传入下划线格式）
         const camelField = field.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
-        if (camelField !== field && camelField in result) {
+        if (camelField !== field && Object.hasOwn(result, camelField)) {
             return {
                 data: result[camelField],
                 sql: oneRes.sql
@@ -763,7 +804,7 @@ export class DbHelper {
         }
         // 转换为下划线格式再尝试访问（支持用户传入小驼峰格式）
         const snakeField = field.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
-        if (snakeField !== field && snakeField in result) {
+        if (snakeField !== field && Object.hasOwn(result, snakeField)) {
             return {
                 data: result[snakeField],
                 sql: oneRes.sql

package/dist/lib/dbUtils.js

@@ -10,18 +10,44 @@ export class DbUtils {
             throw new Error("tableRef 不能为空");
         }
         const parts = trimmed.split(/\s+/).filter((p) => p.length > 0);
+        if (parts.length === 0) {
+            throw new Error("tableRef 不能为空");
+        }
         if (parts.length > 2) {
             throw new Error(`不支持的表引用格式（包含过多片段）。请使用最简形式：table 或 table alias 或 schema.table 或 schema.table alias (tableRef: ${trimmed})`);
         }
         const namePart = parts[0];
-        const aliasPart = parts.length === 2 ? parts[1] : null;
+        if (typeof namePart !== "string" || namePart.trim() === "") {
+            throw new Error(`tableRef 解析失败：缺少表名 (tableRef: ${trimmed})`);
+        }
+        let aliasPart = null;
+        if (parts.length === 2) {
+            const alias = parts[1];
+            if (typeof alias !== "string" || alias.trim() === "") {
+                throw new Error(`tableRef 解析失败：缺少 alias (tableRef: ${trimmed})`);
+            }
+            aliasPart = alias;
+        }
         const nameSegments = namePart.split(".");
         if (nameSegments.length > 2) {
             throw new Error(`不支持的表引用格式（schema 层级过深） (tableRef: ${trimmed})`);
         }
-        const schema = nameSegments.length === 2 ? nameSegments[0] : null;
-        const table = nameSegments.length === 2 ? nameSegments[1] : nameSegments[0];
-        return { schema: schema, table: table, alias: aliasPart };
+        if (nameSegments.length === 2) {
+            const schema = nameSegments[0];
+            const table = nameSegments[1];
+            if (typeof schema !== "string" || schema.trim() === "") {
+                throw new Error(`tableRef 解析失败：schema 为空 (tableRef: ${trimmed})`);
+            }
+            if (typeof table !== "string" || table.trim() === "") {
+                throw new Error(`tableRef 解析失败：table 为空 (tableRef: ${trimmed})`);
+            }
+            return { schema: schema, table: table, alias: aliasPart };
+        }
+        const table = nameSegments[0];
+        if (typeof table !== "string" || table.trim() === "") {
+            throw new Error(`tableRef 解析失败：table 为空 (tableRef: ${trimmed})`);
+        }
+        return { schema: null, table: table, alias: aliasPart };
     }
     /**
      * 规范化表引用：只 snakeCase schema/table，本身 alias 保持原样。
@@ -122,7 +148,15 @@ export class DbUtils {
             if (typeof item !== "string" || !item.includes("#")) {
                 return item;
             }
-            const [field, direction] = item.split("#");
+            const parts = item.split("#");
+            if (parts.length !== 2) {
+                return item;
+            }
+            const field = parts[0];
+            const direction = parts[1];
+            if (typeof field !== "string" || typeof direction !== "string") {
+                return item;
+            }
             return `${snakeCase(field.trim())}#${direction.trim()}`;
         });
     }
@@ -134,15 +168,28 @@ export class DbUtils {
         // 处理别名 AS
         if (field.toUpperCase().includes(" AS ")) {
             const parts = field.split(/\s+AS\s+/i);
-            const fieldPart = parts[0].trim();
-            const aliasPart = parts[1].trim();
-            return `${DbUtils.processJoinField(fieldPart)} AS ${aliasPart}`;
+            const fieldPart = parts[0];
+            const aliasPart = parts[1];
+            if (typeof fieldPart !== "string" || typeof aliasPart !== "string") {
+                return field;
+            }
+            return `${DbUtils.processJoinField(fieldPart.trim())} AS ${aliasPart.trim()}`;
         }
         // 处理表别名.字段名（JOIN 模式下，点号前面通常是别名，不应被 snakeCase 改写）
         if (field.includes(".")) {
             const parts = field.split(".");
-            const tableName = parts[0];
-            const fieldName = parts[1];
+            if (parts.length < 2) {
+                return snakeCase(field);
+            }
+            // 防御：避免 a..b / a. / .a 等输入
+            if (parts.some((p) => p.trim() === "")) {
+                return field;
+            }
+            const fieldName = parts[parts.length - 1];
+            const tableName = parts.slice(0, parts.length - 1).join(".");
+            if (typeof fieldName !== "string" || typeof tableName !== "string") {
+                return snakeCase(field);
+            }
             return `${tableName.trim()}.${snakeCase(fieldName)}`;
         }
         // 普通字段
@@ -160,8 +207,18 @@ export class DbUtils {
             const operator = key.substring(lastDollarIndex);
             if (fieldPart.includes(".")) {
                 const parts = fieldPart.split(".");
-                const tableName = parts[0];
-                const fieldName = parts[1];
+                if (parts.length < 2) {
+                    return `${snakeCase(fieldPart)}${operator}`;
+                }
+                // 防御：避免 a..b / a. / .a 等输入
+                if (parts.some((p) => p.trim() === "")) {
+                    return `${snakeCase(fieldPart)}${operator}`;
+                }
+                const fieldName = parts[parts.length - 1];
+                const tableName = parts.slice(0, parts.length - 1).join(".");
+                if (typeof fieldName !== "string" || typeof tableName !== "string") {
+                    return `${snakeCase(fieldPart)}${operator}`;
+                }
                 return `${tableName.trim()}.${snakeCase(fieldName)}${operator}`;
             }
             return `${snakeCase(fieldPart)}${operator}`;
@@ -169,8 +226,18 @@ export class DbUtils {
         // 处理表名.字段名
         if (key.includes(".")) {
             const parts = key.split(".");
-            const tableName = parts[0];
-            const fieldName = parts[1];
+            if (parts.length < 2) {
+                return snakeCase(key);
+            }
+            // 防御：避免 a..b / a. / .a 等输入
+            if (parts.some((p) => p.trim() === "")) {
+                return snakeCase(key);
+            }
+            const fieldName = parts[parts.length - 1];
+            const tableName = parts.slice(0, parts.length - 1).join(".");
+            if (typeof fieldName !== "string" || typeof tableName !== "string") {
+                return snakeCase(key);
+            }
             return `${tableName.trim()}.${snakeCase(fieldName)}`;
         }
         // 普通字段
@@ -206,7 +273,15 @@ export class DbUtils {
             if (typeof item !== "string" || !item.includes("#")) {
                 return item;
             }
-            const [field, direction] = item.split("#");
+            const parts = item.split("#");
+            if (parts.length !== 2) {
+                return item;
+            }
+            const field = parts[0];
+            const direction = parts[1];
+            if (typeof field !== "string" || typeof direction !== "string") {
+                return item;
+            }
             return `${DbUtils.processJoinField(field.trim())}#${direction.trim()}`;
         });
     }
@@ -352,10 +427,10 @@ export class DbUtils {
         for (const [key, value] of Object.entries(userData)) {
             result[key] = value;
         }
-        result.id = options.id;
-        result.created_at = options.now;
-        result.updated_at = options.now;
-        result.state = 1;
+        result["id"] = options.id;
+        result["created_at"] = options.now;
+        result["updated_at"] = options.now;
+        result["state"] = 1;
         return result;
     }
     static buildUpdateRow(options) {
@@ -365,7 +440,7 @@ export class DbUtils {
         for (const [key, value] of Object.entries(userData)) {
             result[key] = value;
         }
-        result.updated_at = options.now;
+        result["updated_at"] = options.now;
         return result;
     }
     static buildPartialUpdateData(options) {