befly 3.9.39 → 3.10.0

package/docs/reference/table.md

@@ -37,7 +37,7 @@
         - [字段名规范](#字段名规范)
         - [类型联动校验](#类型联动校验)
     - [数据库同步](#数据库同步)
-        - [同步命令](#同步命令)
+        - [触发方式](#触发方式)
         - [同步流程](#同步流程)
         - [变更检测](#变更检测)
         - [安全机制](#安全机制)
@@ -429,13 +429,13 @@ interface FieldDefinition {
 
 以下字段由系统自动创建和管理，**不能**在表定义中使用：
 
-| 字段名       | 类型      | 说明                     |
-| ------------ | --------- | ------------------------ |
-| `id`         | `BIGINT`  | 主键 ID，自增            |
-| `created_at` | `BIGINT`  | 创建时间戳（毫秒）       |
-| `updated_at` | `BIGINT`  | 更新时间戳（毫秒）       |
-| `deleted_at` | `BIGINT`  | 删除时间戳（软删除标记） |
-| `state`      | `TINYINT` | 状态字段                 |
+| 字段名       | 类型     | 说明                     |
+| ------------ | -------- | ------------------------ |
+| `id`         | `BIGINT` | 主键 ID，自增            |
+| `created_at` | `BIGINT` | 创建时间戳（毫秒）       |
+| `updated_at` | `BIGINT` | 更新时间戳（毫秒）       |
+| `deleted_at` | `BIGINT` | 删除时间戳（软删除标记） |
+| `state`      | `BIGINT` | 状态字段                 |
 
 **系统自动创建的索引：**
 
@@ -510,20 +510,19 @@ interface FieldDefinition {
 
 ## 数据库同步
 
-### 同步命令
+### 触发方式
 
-```bash
-# 同步所有表
-bun run sync:db
+服务启动时会在**主进程**自动执行 `syncTable()`。
 
-# 同步指定表
-bun run sync:db --table=user
+如需在代码中手动触发：
 
-# 计划模式（仅输出 SQL，不执行）
-bun run sync:db --plan
+```typescript
+import { syncTable } from "../../sync/syncTable.js";
+import { scanSources } from "../../utils/scanSources.js";
 
-# 强制模式（执行危险变更，如字段长度收缩）
-bun run sync:db --force
+// ctx：BeflyContext（需已具备 ctx.db / ctx.redis / ctx.config）
+const sources = await scanSources();
+await syncTable(ctx, sources.tables);
 ```
 
 ### 同步流程
@@ -556,22 +555,21 @@ bun run sync:db --force
 
 同步时检测以下变更：
 
-| 变更类型 | 说明                         | 自动执行   |
-| -------- | ---------------------------- | ---------- |
-| 长度扩展 | VARCHAR 长度增加             | ✓          |
-| 长度收缩 | VARCHAR 长度减少             | 需 --force |
-| 类型宽化 | INT → BIGINT, VARCHAR → TEXT | ✓          |
-| 类型变更 | 其他类型变更                 | ✗ 禁止     |
-| 默认值   | 默认值变更                   | ✓          |
-| 注释     | 字段注释变更                 | ✓          |
-| 索引     | 添加/删除索引                | ✓          |
+| 变更类型 | 说明                         | 自动执行             |
+| -------- | ---------------------------- | -------------------- |
+| 长度扩展 | VARCHAR 长度增加             | ✓                    |
+| 长度收缩 | VARCHAR 长度减少             | ✗ 跳过（需手动处理） |
+| 类型宽化 | INT → BIGINT, VARCHAR → TEXT | ✓                    |
+| 类型变更 | 其他类型变更                 | ✗ 禁止               |
+| 默认值   | 默认值变更                   | ✓                    |
+| 注释     | 字段注释变更                 | ✓                    |
+| 索引     | 添加/删除索引                | ✓                    |
 
 ### 安全机制
 
 1. **禁止危险类型变更**：不允许从 `BIGINT` 改为 `VARCHAR` 等不兼容变更
 2. **长度收缩保护**：默认跳过长度收缩，避免数据截断
-3. **计划模式**：`--plan` 仅输出 SQL 不执行，用于审查
-4. **保留字段保护**：不允许定义系统保留字段
+3. **保留字段保护**：不允许定义系统保留字段
 
 ---
 

package/hooks/auth.ts

@@ -2,8 +2,8 @@ import type { Hook } from "../types/hook.js";
 
 import { setCtxUser } from "../lib/asyncContext.js";
 
-const hook: Hook = {
-    order: 3,
+export default {
+    deps: ["cors"],
     handler: async (befly, ctx) => {
         const authHeader = ctx.req.headers.get("authorization");
 
@@ -22,5 +22,4 @@ const hook: Hook = {
             ctx.user = {};
         }
     }
-};
-export default hook;
+} satisfies Hook;

package/hooks/cors.ts

@@ -2,7 +2,6 @@ import type { CorsConfig } from "../types/befly.js";
 // 类型导入
 import type { Hook } from "../types/hook.js";
 
-import { beflyConfig } from "../befly.config.js";
 // 相对导入
 import { setCorsOptions } from "../utils/cors.js";
 
@@ -10,8 +9,8 @@ import { setCorsOptions } from "../utils/cors.js";
  * CORS 跨域处理钩子
  * 设置跨域响应头并处理 OPTIONS 预检请求
  */
-const hook: Hook = {
-    order: 2,
+export default {
+    deps: [],
     handler: async (befly, ctx) => {
         const req = ctx.req;
 
@@ -25,7 +24,7 @@ const hook: Hook = {
             credentials: "true"
         };
 
-        const corsConfig = { ...defaultConfig, ...beflyConfig.cors };
+        const corsConfig = Object.assign({}, defaultConfig, befly.config && befly.config.cors ? befly.config.cors : {});
 
         // 设置 CORS 响应头
         const headers = setCorsOptions(req, corsConfig);
@@ -41,5 +40,4 @@ const hook: Hook = {
             return;
         }
     }
-};
-export default hook;
+} satisfies Hook;

package/hooks/parser.ts

@@ -18,8 +18,8 @@ const xmlParser = new XMLParser();
  * - 根据 API 定义的 fields 过滤字段
  * - rawBody: true 时跳过解析，由 handler 自行处理原始请求
  */
-const hook: Hook = {
-    order: 4,
+export default {
+    deps: ["auth"],
     handler: async (befly, ctx) => {
         if (!ctx.api) return;
 
@@ -103,5 +103,4 @@ const hook: Hook = {
             }
         }
     }
-};
-export default hook;
+} satisfies Hook;

package/hooks/permission.ts

@@ -13,8 +13,8 @@ import { ErrorResponse } from "../utils/response.js";
  * - 开发者角色（dev）：最高权限，直接通过
  * - 其他角色：检查 Redis 中的角色权限集合
  */
-const hook: Hook = {
-    order: 6,
+export default {
+    deps: ["validator"],
     handler: async (befly, ctx) => {
         if (!ctx.api) return;
 
@@ -65,5 +65,4 @@ const hook: Hook = {
             return;
         }
     }
-};
-export default hook;
+} satisfies Hook;

package/hooks/validator.ts

@@ -9,8 +9,8 @@ import { ErrorResponse } from "../utils/response.js";
  * 参数验证钩子
  * 根据 API 定义的 fields 和 required 验证请求参数
  */
-const hook: Hook = {
-    order: 8,
+export default {
+    deps: ["parser"],
     handler: async (befly, ctx) => {
         if (!ctx.api) return;
 
@@ -22,7 +22,7 @@ const hook: Hook = {
         // 应用字段默认值
         for (const [field, fieldDef] of Object.entries(ctx.api.fields)) {
             // 字段未传值且定义了默认值时，应用默认值
-            if (ctx.body[field] === undefined && (fieldDef as any)?.default !== undefined) {
+            if (ctx.body[field] === undefined && (fieldDef as any)?.default !== undefined && (fieldDef as any)?.default !== null) {
                 ctx.body[field] = (fieldDef as any).default;
             }
         }
@@ -35,5 +35,4 @@ const hook: Hook = {
             return;
         }
     }
-};
-export default hook;
+} satisfies Hook;

package/lib/cacheHelper.ts

@@ -3,122 +3,79 @@
  * 负责在服务器启动时缓存接口、菜单和角色权限到 Redis
  */
 
-import type { BeflyContext } from "../types/befly.js";
-
-import { makeRouteKey } from "../utils/route.js";
 import { CacheKeys } from "./cacheKeys.js";
 import { Logger } from "./logger.js";
 
+type CacheHelperDb = {
+    tableExists(table: string): Promise<boolean>;
+    getAll(options: any): Promise<{ lists: any[] }>;
+};
+
+type CacheHelperRedis = {
+    setObject<T = any>(key: string, obj: T, ttl?: number | null): Promise<string | null>;
+    getObject<T = any>(key: string): Promise<T | null>;
+    del(key: string): Promise<number>;
+    delBatch(keys: string[]): Promise<number>;
+    sadd(key: string, members: string[]): Promise<number>;
+    saddBatch(items: Array<{ key: string; members: string[] }>): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    sismember(key: string, member: string): Promise<boolean>;
+};
+
+type CacheHelperDeps = {
+    db: CacheHelperDb;
+    redis: CacheHelperRedis;
+};
+
 /**
  * 缓存助手类
  */
 export class CacheHelper {
-    private befly: BeflyContext;
-
-    private static readonly API_ID_IN_CHUNK_SIZE = 1000;
+    private db: CacheHelperDb;
+    private redis: CacheHelperRedis;
 
-    private normalizeNumberIdList(value: unknown): number[] {
-        if (value === null || value === undefined) return [];
+    constructor(deps: CacheHelperDeps) {
+        this.db = deps.db;
+        this.redis = deps.redis;
+    }
 
-        const normalizeSingle = (item: unknown): number | null => {
-            if (typeof item === "number") {
-                if (!Number.isFinite(item)) return null;
-                const intValue = Math.trunc(item);
-                return Number.isSafeInteger(intValue) ? intValue : null;
-            }
-            if (typeof item === "bigint") {
-                const intValue = Number(item);
-                return Number.isSafeInteger(intValue) ? intValue : null;
-            }
-            if (typeof item === "string") {
-                const trimmed = item.trim();
-                if (!trimmed) return null;
-                const intValue = Number.parseInt(trimmed, 10);
-                return Number.isSafeInteger(intValue) ? intValue : null;
-            }
-            return null;
-        };
-
-        if (Array.isArray(value)) {
-            const ids: number[] = [];
-            for (const item of value) {
-                const id = normalizeSingle(item);
-                if (id !== null) ids.push(id);
-            }
-            return ids;
+    private assertApiPathname(value: unknown, errorPrefix: string): string {
+        if (typeof value !== "string") {
+            throw new Error(`${errorPrefix} 必须是字符串`);
         }
 
-        if (typeof value === "string") {
-            const str = value.trim();
-            if (!str) return [];
-
-            if (str.startsWith("[")) {
-                try {
-                    const parsed = JSON.parse(str);
-                    return this.normalizeNumberIdList(parsed);
-                } catch {
-                    // ignore
-                }
-            }
-
-            const ids: number[] = [];
-            const parts = str.split(",");
-            for (const part of parts) {
-                const id = normalizeSingle(part);
-                if (id !== null) ids.push(id);
-            }
-            return ids;
+        const trimmed = value.trim();
+        if (!trimmed) {
+            throw new Error(`${errorPrefix} 不允许为空字符串`);
         }
 
-        const single = normalizeSingle(value);
-        return single === null ? [] : [single];
-    }
-
-    private chunkNumberArray(arr: number[], chunkSize: number): number[][] {
-        if (chunkSize <= 0) {
-            throw new Error(`chunkSize 必须为正整数 (chunkSize: ${chunkSize})`);
+        if (/^(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\b/i.test(trimmed)) {
+            throw new Error(`${errorPrefix} 不允许包含 method 前缀，应为 url.pathname（例如 /api/app/xxx）`);
         }
-        if (arr.length === 0) return [];
 
-        const chunks: number[][] = [];
-        for (let i = 0; i < arr.length; i += chunkSize) {
-            chunks.push(arr.slice(i, i + chunkSize));
+        if (!trimmed.startsWith("/")) {
+            throw new Error(`${errorPrefix} 必须是 pathname（以 / 开头）`);
         }
-        return chunks;
-    }
 
-    private async buildApiPathMapByIds(apiIds: number[]): Promise<Map<number, string>> {
-        const uniqueIds = Array.from(new Set(apiIds));
-        if (uniqueIds.length === 0) {
-            return new Map();
+        if (trimmed.includes(" ")) {
+            throw new Error(`${errorPrefix} 不允许包含空格`);
         }
 
-        const apiMap = new Map<number, string>();
-        const chunks = this.chunkNumberArray(uniqueIds, CacheHelper.API_ID_IN_CHUNK_SIZE);
+        return trimmed;
+    }
 
-        for (const chunk of chunks) {
-            const apis = await this.befly.db.getAll({
-                table: "addon_admin_api",
-                fields: ["id", "method", "path"],
-                where: {
-                    id$in: chunk
-                }
-            });
+    private assertApiPathList(value: unknown, roleCode: string): string[] {
+        if (value === null || value === undefined) return [];
 
-            for (const api of apis.lists) {
-                apiMap.set(api.id, makeRouteKey(api.method, api.path));
-            }
+        if (!Array.isArray(value)) {
+            throw new Error(`角色权限数据不合法：addon_admin_role.apis 必须是字符串数组，roleCode=${roleCode}`);
         }
 
-        return apiMap;
-    }
-
-    /**
-     * 构造函数
-     * @param befly - Befly 上下文
-     */
-    constructor(befly: BeflyContext) {
-        this.befly = befly;
+        const out: string[] = [];
+        for (const item of value) {
+            out.push(this.assertApiPathname(item, `角色权限数据不合法：addon_admin_role.apis 元素，roleCode=${roleCode}`));
+        }
+        return out;
     }
 
     /**
@@ -127,19 +84,19 @@ export class CacheHelper {
     async cacheApis(): Promise<void> {
         try {
             // 检查表是否存在
-            const tableExists = await this.befly.db.tableExists("addon_admin_api");
+            const tableExists = await this.db.tableExists("addon_admin_api");
             if (!tableExists) {
                 Logger.warn("⚠️ 接口表不存在，跳过接口缓存");
                 return;
             }
 
             // 从数据库查询所有接口
-            const apiList = await this.befly.db.getAll({
+            const apiList = await this.db.getAll({
                 table: "addon_admin_api"
             });
 
             // 缓存到 Redis
-            const result = await this.befly.redis.setObject(CacheKeys.apisAll(), apiList.lists);
+            const result = await this.redis.setObject(CacheKeys.apisAll(), apiList.lists);
 
             if (result === null) {
                 Logger.warn("⚠️ 接口缓存失败");
@@ -155,19 +112,19 @@ export class CacheHelper {
     async cacheMenus(): Promise<void> {
         try {
             // 检查表是否存在
-            const tableExists = await this.befly.db.tableExists("addon_admin_menu");
+            const tableExists = await this.db.tableExists("addon_admin_menu");
             if (!tableExists) {
                 Logger.warn("⚠️ 菜单表不存在，跳过菜单缓存");
                 return;
             }
 
             // 从数据库查询所有菜单
-            const menus = await this.befly.db.getAll({
+            const menus = await this.db.getAll({
                 table: "addon_admin_menu"
             });
 
             // 缓存到 Redis
-            const result = await this.befly.redis.setObject(CacheKeys.menusAll(), menus.lists);
+            const result = await this.redis.setObject(CacheKeys.menusAll(), menus.lists);
 
             if (result === null) {
                 Logger.warn("⚠️ 菜单缓存失败");
@@ -185,61 +142,43 @@ export class CacheHelper {
     async rebuildRoleApiPermissions(): Promise<void> {
         try {
             // 检查表是否存在
-            const apiTableExists = await this.befly.db.tableExists("addon_admin_api");
-            const roleTableExists = await this.befly.db.tableExists("addon_admin_role");
+            const roleTableExists = await this.db.tableExists("addon_admin_role");
 
-            if (!apiTableExists || !roleTableExists) {
-                Logger.warn("⚠️ 接口或角色表不存在，跳过角色权限缓存");
+            if (!roleTableExists) {
+                Logger.warn("⚠️ 角色表不存在，跳过角色权限缓存");
                 return;
             }
 
             // 查询所有角色（仅取必要字段）
-            const roles = await this.befly.db.getAll({
+            const roles = await this.db.getAll({
                 table: "addon_admin_role",
                 fields: ["code", "apis"]
             });
 
-            const roleApiIdsMap = new Map<string, number[]>();
-            const allApiIdsSet = new Set<number>();
+            const roleApiPathsMap = new Map<string, string[]>();
 
             for (const role of roles.lists) {
                 if (!role?.code) continue;
-                const apiIds = this.normalizeNumberIdList(role.apis);
-                roleApiIdsMap.set(role.code, apiIds);
-                for (const id of apiIds) {
-                    allApiIdsSet.add(id);
-                }
+                const apiPaths = this.assertApiPathList(role.apis, role.code);
+                roleApiPathsMap.set(role.code, apiPaths);
             }
 
-            const roleCodes = Array.from(roleApiIdsMap.keys());
+            const roleCodes = Array.from(roleApiPathsMap.keys());
             if (roleCodes.length === 0) {
                 Logger.info("✅ 没有需要缓存的角色权限");
                 return;
             }
 
-            // 构建所有需要的 API 映射（按 ID 分块使用 $in，避免全表扫描/避免超长 IN）
-            const allApiIds = Array.from(allApiIdsSet);
-            const apiMap = await this.buildApiPathMapByIds(allApiIds);
-
             // 清理所有角色的缓存 key（保证幂等）
             const roleKeys = roleCodes.map((code) => CacheKeys.roleApis(code));
-            await this.befly.redis.delBatch(roleKeys);
+            await this.redis.delBatch(roleKeys);
 
             // 批量写入新缓存（只写入非空权限）
             const items: Array<{ key: string; members: string[] }> = [];
 
             for (const roleCode of roleCodes) {
-                const apiIds = roleApiIdsMap.get(roleCode) || [];
-                const membersSet = new Set<string>();
-
-                for (const id of apiIds) {
-                    const apiPath = apiMap.get(id);
-                    if (apiPath) {
-                        membersSet.add(apiPath);
-                    }
-                }
-
-                const members = Array.from(membersSet).sort();
+                const apiPaths = roleApiPathsMap.get(roleCode) || [];
+                const members = Array.from(new Set(apiPaths)).sort();
 
                 if (members.length > 0) {
                     items.push({ key: CacheKeys.roleApis(roleCode), members: members });
@@ -247,12 +186,13 @@ export class CacheHelper {
             }
 
             if (items.length > 0) {
-                await this.befly.redis.saddBatch(items);
+                await this.redis.saddBatch(items);
             }
 
             // 极简方案不做版本/ready/meta：重建完成即生效
         } catch (error: any) {
-            Logger.warn({ err: error }, "⚠️ 角色权限缓存异常");
+            Logger.error({ err: error }, "⚠️ 角色权限缓存异常（将阻断启动）");
+            throw error;
         }
     }
 
@@ -261,33 +201,28 @@ export class CacheHelper {
      * - apiIds 为空数组：仅清理缓存（防止残留）
      * - apiIds 非空：使用 $in 最小查询，DEL 后 SADD
      */
-    async refreshRoleApiPermissions(roleCode: string, apiIds: number[]): Promise<void> {
+    async refreshRoleApiPermissions(roleCode: string, apiPaths: string[]): Promise<void> {
         if (!roleCode || typeof roleCode !== "string") {
             throw new Error("roleCode 必须是非空字符串");
         }
-        const normalizedIds = this.normalizeNumberIdList(apiIds);
+        if (!Array.isArray(apiPaths)) {
+            throw new Error("apiPaths 必须是数组");
+        }
+
+        const normalizedPaths = apiPaths.map((p) => this.assertApiPathname(p, `refreshRoleApiPermissions: apiPaths 元素，roleCode=${roleCode}`));
         const roleKey = CacheKeys.roleApis(roleCode);
 
-        // 空数组短路：避免触发 $in 空数组异常，同时保证清理残留
-        if (normalizedIds.length === 0) {
-            await this.befly.redis.del(roleKey);
+        // 空数组短路：保证清理残留
+        if (normalizedPaths.length === 0) {
+            await this.redis.del(roleKey);
             return;
         }
 
-        const apiMap = await this.buildApiPathMapByIds(normalizedIds);
-        const membersSet = new Set<string>();
-        for (const id of normalizedIds) {
-            const apiPath = apiMap.get(id);
-            if (apiPath) {
-                membersSet.add(apiPath);
-            }
-        }
-
-        const members = Array.from(membersSet);
+        const members = Array.from(new Set(normalizedPaths));
 
-        await this.befly.redis.del(roleKey);
+        await this.redis.del(roleKey);
         if (members.length > 0) {
-            await this.befly.redis.sadd(roleKey, members);
+            await this.redis.sadd(roleKey, members);
         }
     }
 
@@ -311,7 +246,7 @@ export class CacheHelper {
      */
     async getApis(): Promise<any[]> {
         try {
-            const apis = await this.befly.redis.getObject<any[]>(CacheKeys.apisAll());
+            const apis = await this.redis.getObject<any[]>(CacheKeys.apisAll());
             return apis || [];
         } catch (error: any) {
             Logger.error({ err: error }, "获取接口缓存失败");
@@ -325,7 +260,7 @@ export class CacheHelper {
      */
     async getMenus(): Promise<any[]> {
         try {
-            const menus = await this.befly.redis.getObject<any[]>(CacheKeys.menusAll());
+            const menus = await this.redis.getObject<any[]>(CacheKeys.menusAll());
             return menus || [];
         } catch (error: any) {
             Logger.error({ err: error }, "获取菜单缓存失败");
@@ -340,7 +275,7 @@ export class CacheHelper {
      */
     async getRolePermissions(roleCode: string): Promise<string[]> {
         try {
-            const permissions = await this.befly.redis.smembers(CacheKeys.roleApis(roleCode));
+            const permissions = await this.redis.smembers(CacheKeys.roleApis(roleCode));
             return permissions || [];
         } catch (error: any) {
             Logger.error({ err: error, roleCode: roleCode }, "获取角色权限缓存失败");
@@ -351,12 +286,13 @@ export class CacheHelper {
     /**
      * 检查角色是否有指定接口权限
      * @param roleCode - 角色代码
-     * @param apiPath - 接口路径（格式：METHOD/path）
+     * @param apiPath - 接口路径（url.pathname，例如 /api/user/login；与 method 无关）
      * @returns 是否有权限
      */
     async checkRolePermission(roleCode: string, apiPath: string): Promise<boolean> {
         try {
-            return await this.befly.redis.sismember(CacheKeys.roleApis(roleCode), apiPath);
+            const pathname = this.assertApiPathname(apiPath, "checkRolePermission: apiPath");
+            return await this.redis.sismember(CacheKeys.roleApis(roleCode), pathname);
         } catch (error: any) {
             Logger.error({ err: error, roleCode: roleCode }, "检查角色权限失败");
             return false;
@@ -370,7 +306,7 @@ export class CacheHelper {
      */
     async deleteRolePermissions(roleCode: string): Promise<boolean> {
         try {
-            const result = await this.befly.redis.del(CacheKeys.roleApis(roleCode));
+            const result = await this.redis.del(CacheKeys.roleApis(roleCode));
             if (result > 0) {
                 Logger.info(`✅ 已删除角色 ${roleCode} 的权限缓存`);
                 return true;

package/lib/cacheKeys.ts

@@ -25,7 +25,7 @@ export class CacheKeys {
     /**
      * 角色接口权限缓存（Set 集合）
      * - key: befly:role:apis:${roleCode}
-     * - member: METHOD/path
+     * - member: url.pathname（例如 /api/user/login；与 method 无关）
      */
     static roleApis(roleCode: string): string {
         return `befly:role:apis:${roleCode}`;