befly 3.9.38 → 3.9.40

package/docs/{validator.md → reference/validator.md}

@@ -33,7 +33,7 @@ Validator 是 Befly 的参数验证系统，提供：
 ### 基本结构
 
 ```typescript
-import { Validator } from '../lib/validator.js';
+import { Validator } from "../lib/validator.js";
 
 class Validator {
     // 验证数据对象
@@ -50,18 +50,18 @@ class Validator {
 
 ```typescript
 const data = {
-    email: 'test@example.com',
+    email: "test@example.com",
     age: 25,
-    name: 'John'
+    name: "John"
 };
 
 const rules = {
-    email: { name: '邮箱', type: 'string', min: 5, max: 100, regexp: '@email' },
-    age: { name: '年龄', type: 'number', min: 0, max: 150 },
-    name: { name: '姓名', type: 'string', min: 2, max: 50 }
+    email: { name: "邮箱", type: "string", min: 5, max: 100, regexp: "@email" },
+    age: { name: "年龄", type: "number", min: 0, max: 150 },
+    name: { name: "姓名", type: "string", min: 2, max: 50 }
 };
 
-const result = Validator.validate(data, rules, ['email', 'name']);
+const result = Validator.validate(data, rules, ["email", "name"]);
 
 if (result.failed) {
     console.log(result.firstError); // 第一条错误信息
@@ -77,14 +77,14 @@ if (result.failed) {
 
 ```typescript
 const fieldDef = {
-    name: '年龄',
-    type: 'number',
+    name: "年龄",
+    type: "number",
     min: 0,
     max: 150,
     default: 0
 };
 
-const result = Validator.single('25', fieldDef);
+const result = Validator.single("25", fieldDef);
 
 if (!result.error) {
     console.log(result.value); // 25 (已转换为 number)
@@ -199,18 +199,18 @@ if (!result.error) {
 ```typescript
 // 使用别名
 {
-    regexp: '@email';
+    regexp: "@email";
 } // 邮箱格式
 {
-    regexp: '@phone';
+    regexp: "@phone";
 } // 手机号格式
 {
-    regexp: '@url';
+    regexp: "@url";
 } // URL 格式
 
 // 直接使用正则
 {
-    regexp: '^[a-z]+$';
+    regexp: "^[a-z]+$";
 } // 小写字母
 ```
 
@@ -319,7 +319,7 @@ const hook: Hook = {
         const result = Validator.validate(ctx.body, ctx.api.fields, ctx.api.required || []);
 
         if (result.code !== 0) {
-            ctx.response = ErrorResponse(ctx, result.firstError || '参数验证失败', 1, null, result.fieldErrors);
+            ctx.response = ErrorResponse(ctx, result.firstError || "参数验证失败", 1, null, result.fieldErrors);
         }
     }
 };
@@ -342,17 +342,17 @@ const hook: Hook = {
 ```typescript
 // apis/user/login.ts
 export default {
-    name: '用户登录',
-    method: 'POST',
+    name: "用户登录",
+    method: "POST",
     auth: false,
     fields: {
-        email: { name: '邮箱', type: 'string', min: 5, max: 100, regexp: '@email' },
-        password: { name: '密码', type: 'string', min: 6, max: 100 }
+        email: { name: "邮箱", type: "string", min: 5, max: 100, regexp: "@email" },
+        password: { name: "密码", type: "string", min: 6, max: 100 }
     },
-    required: ['email', 'password'],
+    required: ["email", "password"],
     handler: async (befly, ctx) => {
         // ctx.body.email 和 ctx.body.password 已验证
-        return Yes('登录成功');
+        return Yes("登录成功");
     }
 } as ApiRoute;
 ```
@@ -362,16 +362,16 @@ export default {
 可以引用表定义中的字段：
 
 ```typescript
-import { adminTable } from '../../../tables/admin.js';
+import { adminTable } from "../../../tables/admin.js";
 
 export default {
-    name: '创建管理员',
+    name: "创建管理员",
     fields: {
         email: adminTable.email, // 引用表字段
         password: adminTable.password,
         nickname: adminTable.nickname
     },
-    required: ['email', 'password'],
+    required: ["email", "password"],
     handler: async (befly, ctx) => {
         // ...
     }
@@ -381,14 +381,14 @@ export default {
 ### 使用公共字段
 
 ```typescript
-import { Fields } from '../../../config/fields.js';
+import { Fields } from "../../../config/fields.js";
 
 export default {
-    name: '获取列表',
+    name: "获取列表",
     fields: {
         ...Fields.page, // 分页字段
         ...Fields.limit,
-        keyword: { name: '关键词', type: 'string', max: 50 }
+        keyword: { name: "关键词", type: "string", max: 50 }
     },
     handler: async (befly, ctx) => {
         // ...
@@ -461,18 +461,18 @@ interface SingleResult {
 
 ```typescript
 const data = {
-    username: 'john',
+    username: "john",
     age: 25,
-    email: 'john@example.com'
+    email: "john@example.com"
 };
 
 const rules = {
-    username: { name: '用户名', type: 'string', min: 2, max: 20 },
-    age: { name: '年龄', type: 'number', min: 0, max: 150 },
-    email: { name: '邮箱', type: 'string', regexp: '@email' }
+    username: { name: "用户名", type: "string", min: 2, max: 20 },
+    age: { name: "年龄", type: "number", min: 0, max: 150 },
+    email: { name: "邮箱", type: "string", regexp: "@email" }
 };
 
-const result = Validator.validate(data, rules, ['username', 'email']);
+const result = Validator.validate(data, rules, ["username", "email"]);
 // result.code === 0
 ```
 
@@ -480,13 +480,13 @@ const result = Validator.validate(data, rules, ['username', 'email']);
 
 ```typescript
 const data = {
-    age: '25', // 字符串
-    score: '98.5' // 字符串
+    age: "25", // 字符串
+    score: "98.5" // 字符串
 };
 
 const rules = {
-    age: { name: '年龄', type: 'number', min: 0 },
-    score: { name: '分数', type: 'number', min: 0, max: 100 }
+    age: { name: "年龄", type: "number", min: 0 },
+    score: { name: "分数", type: "number", min: 0, max: 100 }
 };
 
 // 验证通过，'25' 会被转换为 25
@@ -497,31 +497,31 @@ const result = Validator.validate(data, rules);
 
 ```typescript
 const data = {
-    tags: ['vue', 'react', 'angular'],
+    tags: ["vue", "react", "angular"],
     ids: [1, 2, 3]
 };
 
 const rules = {
-    tags: { name: '标签', type: 'array_string', min: 1, max: 10 },
-    ids: { name: 'ID列表', type: 'array_string', min: 1 }
+    tags: { name: "标签", type: "array_string", min: 1, max: 10 },
+    ids: { name: "ID列表", type: "array_string", min: 1 }
 };
 
-const result = Validator.validate(data, rules, ['tags']);
+const result = Validator.validate(data, rules, ["tags"]);
 ```
 
 ### 示例 4：正则验证
 
 ```typescript
 const data = {
-    phone: '13812345678',
-    email: 'test@example.com',
-    code: 'ABC123'
+    phone: "13812345678",
+    email: "test@example.com",
+    code: "ABC123"
 };
 
 const rules = {
-    phone: { name: '手机号', type: 'string', regexp: '@phone' },
-    email: { name: '邮箱', type: 'string', regexp: '@email' },
-    code: { name: '验证码', type: 'string', regexp: '^[A-Z0-9]{6}$' }
+    phone: { name: "手机号", type: "string", regexp: "@phone" },
+    email: { name: "邮箱", type: "string", regexp: "@email" },
+    code: { name: "验证码", type: "string", regexp: "^[A-Z0-9]{6}$" }
 };
 
 const result = Validator.validate(data, rules);
@@ -531,9 +531,9 @@ const result = Validator.validate(data, rules);
 
 ```typescript
 // 验证并转换单个值
-const ageResult = Validator.single('25', {
-    name: '年龄',
-    type: 'number',
+const ageResult = Validator.single("25", {
+    name: "年龄",
+    type: "number",
     min: 0,
     max: 150
 });
@@ -543,9 +543,9 @@ if (!ageResult.error) {
 }
 
 // 空值使用默认值
-const emptyResult = Validator.single('', {
-    name: '数量',
-    type: 'number',
+const emptyResult = Validator.single("", {
+    name: "数量",
+    type: "number",
     default: 10
 });
 console.log(emptyResult.value); // 10
@@ -573,7 +573,7 @@ A: 目前只支持扁平对象验证。嵌套对象需要在 handler 中手动
 
 ### Q: 正则别名可以扩展吗？
 
-A: 正则别名定义在 `befly-shared/regex` 中，可以直接使用自定义正则字符串，不需要扩展别名。
+A: 正则别名定义在 `befly/lib/regex` 中，可以直接使用自定义正则字符串，不需要扩展别名。
 
 ### Q: 类型转换失败会怎样？
 
@@ -605,14 +605,14 @@ handler: async (befly, ctx) => {
 
     // cleanData 只包含有效值
     await befly.db.updData({
-        table: 'user',
+        table: "user",
         data: cleanData,
         where: { id: ctx.user.userId }
     });
 
-    return Yes('更新成功');
+    return Yes("更新成功");
 };
 ```
 
 > **注意**：数据库操作（insData、updData 等）会自动过滤 null/undefined 值，通常不需要手动调用 cleanFields。
-> 详见 [database.md](./database.md#nullundefined-值自动过滤)。
+> 详见 [database.md](../plugins/database.md#nullundefined-值自动过滤)。

package/hooks/auth.ts

@@ -1,17 +1,21 @@
-import type { Hook } from '../types/hook.js';
+import type { Hook } from "../types/hook.js";
+
+import { setCtxUser } from "../lib/asyncContext.js";
 
 const hook: Hook = {
     order: 3,
     handler: async (befly, ctx) => {
-        const authHeader = ctx.req.headers.get('authorization');
+        const authHeader = ctx.req.headers.get("authorization");
 
-        if (authHeader && authHeader.startsWith('Bearer ')) {
+        if (authHeader && authHeader.startsWith("Bearer ")) {
             const token = authHeader.substring(7);
 
             try {
                 const payload = await befly.jwt.verify(token);
                 ctx.user = payload;
-            } catch (error: any) {
+
+                setCtxUser(payload.id, payload.roleCode, payload.nickname, payload.roleType);
+            } catch {
                 ctx.user = {};
             }
         } else {

package/hooks/cors.ts

@@ -1,10 +1,10 @@
-// 相对导入
-import { setCorsOptions } from '../util.js';
-import { beflyConfig } from '../befly.config.js';
-
+import type { CorsConfig } from "../types/befly.js";
 // 类型导入
-import type { Hook } from '../types/hook.js';
-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";
 
 /**
  * CORS 跨域处理钩子
@@ -17,15 +17,15 @@ const hook: Hook = {
 
         // 合并默认配置和用户配置
         const defaultConfig: CorsConfig = {
-            origin: '*',
-            methods: 'GET, POST, PUT, DELETE, OPTIONS',
-            allowedHeaders: 'Content-Type, Authorization, authorization, token',
-            exposedHeaders: 'Content-Range, X-Content-Range, Authorization, authorization, token',
+            origin: "*",
+            methods: "GET, POST, PUT, DELETE, OPTIONS",
+            allowedHeaders: "Content-Type, Authorization, authorization, token",
+            exposedHeaders: "Content-Range, X-Content-Range, Authorization, authorization, token",
             maxAge: 86400,
-            credentials: 'true'
+            credentials: "true"
         };
 
-        const corsConfig = { ...defaultConfig, ...(beflyConfig.cors || {}) };
+        const corsConfig = { ...defaultConfig, ...beflyConfig.cors };
 
         // 设置 CORS 响应头
         const headers = setCorsOptions(req, corsConfig);
@@ -33,7 +33,7 @@ const hook: Hook = {
         ctx.corsHeaders = headers;
 
         // 处理 OPTIONS 预检请求
-        if (req.method === 'OPTIONS') {
+        if (req.method === "OPTIONS") {
             ctx.response = new Response(null, {
                 status: 204,
                 headers: headers

package/hooks/parser.ts

@@ -1,13 +1,13 @@
+// 类型导入
+import type { Hook } from "../types/hook.js";
+
 // 外部依赖
-import { isPlainObject, isEmpty } from 'es-toolkit/compat';
-import { pickFields } from 'befly-shared/pickFields';
-import { XMLParser } from 'fast-xml-parser';
+import { isPlainObject, isEmpty } from "es-toolkit/compat";
+import { XMLParser } from "fast-xml-parser";
 
 // 相对导入
-import { ErrorResponse } from '../util.js';
-
-// 类型导入
-import type { Hook } from '../types/hook.js';
+import { pickFields } from "../utils/pickFields.js";
+import { ErrorResponse } from "../utils/response.js";
 
 const xmlParser = new XMLParser();
 
@@ -31,7 +31,7 @@ const hook: Hook = {
         }
 
         // GET 请求：解析查询参数
-        if (ctx.req.method === 'GET') {
+        if (ctx.req.method === "GET") {
             const url = new URL(ctx.req.url);
             const params = Object.fromEntries(url.searchParams);
             if (isPlainObject(ctx.api.fields) && !isEmpty(ctx.api.fields)) {
@@ -39,16 +39,16 @@ const hook: Hook = {
             } else {
                 ctx.body = params;
             }
-        } else if (ctx.req.method === 'POST') {
+        } else if (ctx.req.method === "POST") {
             // POST 请求：解析请求体
-            const contentType = ctx.req.headers.get('content-type') || '';
+            const contentType = ctx.req.headers.get("content-type") || "";
             // 获取 URL 查询参数（POST 请求也可能带参数）
             const url = new URL(ctx.req.url);
             const queryParams = Object.fromEntries(url.searchParams);
 
             try {
                 // JSON 格式
-                if (contentType.includes('application/json')) {
+                if (contentType.includes("application/json")) {
                     const body = (await ctx.req.json()) as Record<string, any>;
                     // 合并 URL 参数和请求体（请求体优先）
                     const merged = { ...queryParams, ...body };
@@ -57,13 +57,13 @@ const hook: Hook = {
                     } else {
                         ctx.body = merged;
                     }
-                } else if (contentType.includes('application/xml') || contentType.includes('text/xml')) {
+                } else if (contentType.includes("application/xml") || contentType.includes("text/xml")) {
                     // XML 格式
                     const text = await ctx.req.text();
                     const parsed = xmlParser.parse(text) as Record<string, any>;
                     // 提取根节点内容（如 xml），使 body 扁平化
                     const rootKey = Object.keys(parsed)[0];
-                    const body = rootKey && typeof parsed[rootKey] === 'object' ? parsed[rootKey] : parsed;
+                    const body = rootKey && typeof parsed[rootKey] === "object" ? parsed[rootKey] : parsed;
                     // 合并 URL 参数和请求体（请求体优先）
                     const merged = { ...queryParams, ...body };
                     if (isPlainObject(ctx.api.fields) && !isEmpty(ctx.api.fields)) {
@@ -73,12 +73,32 @@ const hook: Hook = {
                     }
                 } else {
                     // 不支持的 Content-Type
-                    ctx.response = ErrorResponse(ctx, '无效的请求参数格式', 1, null, { location: 'content-type', value: contentType });
+                    ctx.response = ErrorResponse(
+                        ctx,
+                        "无效的请求参数格式",
+                        1,
+                        null,
+                        {
+                            location: "content-type",
+                            value: contentType
+                        },
+                        "parser"
+                    );
                     return;
                 }
-            } catch (e: any) {
-                // 解析失败
-                ctx.response = ErrorResponse(ctx, '无效的请求参数格式', 1, null, { location: 'body', error: e.message });
+            } catch {
+                // 解析失败：属于客户端输入错误，返回安全 detail（不回传异常栈/原始 body）
+                ctx.response = ErrorResponse(
+                    ctx,
+                    "无效的请求参数格式",
+                    1,
+                    null,
+                    {
+                        location: "body",
+                        reason: contentType.includes("application/json") ? "invalid_json" : contentType.includes("xml") ? "invalid_xml" : "invalid_body"
+                    },
+                    "parser"
+                );
                 return;
             }
         }

package/hooks/permission.ts

@@ -1,9 +1,10 @@
-// 相对导入
-import { ErrorResponse } from '../util.js';
-import { RedisKeys } from 'befly-shared/redisKeys';
-
 // 类型导入
-import type { Hook } from '../types/hook.js';
+import type { Hook } from "../types/hook.js";
+
+import { CacheKeys } from "../lib/cacheKeys.js";
+import { Logger } from "../lib/logger.js";
+// 相对导入
+import { ErrorResponse } from "../utils/response.js";
 
 /**
  * 权限检查钩子
@@ -24,32 +25,43 @@ const hook: Hook = {
 
         // 2. 用户未登录
         if (!ctx.user || !ctx.user.id) {
-            ctx.response = ErrorResponse(ctx, '未登录');
+            ctx.response = ErrorResponse(ctx, "未登录", 1, null, null, "auth");
             return;
         }
 
         // 3. 开发者权限（最高权限）
-        if (ctx.user.roleCode === 'dev') {
+        if (ctx.user.roleCode === "dev") {
             return;
         }
 
         // 4. 角色权限检查
         let hasPermission = false;
         if (ctx.user.roleCode && befly.redis) {
+            // apiPath 在 apiHandler 中已统一生成并写入 ctx.route
+            const apiPath = ctx.route;
+            const roleCode = ctx.user.roleCode;
+
             try {
-                // 验证角色权限
-                const apiPath = `${ctx.req.method}${new URL(ctx.req.url).pathname}`;
-                const roleApisKey = RedisKeys.roleApis(ctx.user.roleCode);
+                // 极简方案：每个角色一个 Set，直接判断成员是否存在
+                const roleApisKey = CacheKeys.roleApis(roleCode);
                 hasPermission = await befly.redis.sismember(roleApisKey, apiPath);
-            } catch (error) {
-                // Redis 异常时降级为拒绝访问
-                befly.logger.warn({ err: error, route: ctx.route }, 'Redis 权限检查失败');
+            } catch (err: any) {
+                // Redis 异常：记录到 error 日志文件（不回传给客户端），并降级为拒绝访问
+                Logger.error(
+                    {
+                        event: "hook_permission_redis_error",
+                        apiPath: apiPath,
+                        roleCode: roleCode,
+                        err: err
+                    },
+                    "hook permission redis error"
+                );
                 hasPermission = false;
             }
         }
 
         if (!hasPermission) {
-            ctx.response = ErrorResponse(ctx, '无权访问');
+            ctx.response = ErrorResponse(ctx, "无权访问", 1, null, null, "permission");
             return;
         }
     }