befly 3.9.38 → 3.9.39

package/docs/{hook.md → hooks/hook.md}

@@ -72,7 +72,7 @@ Befly Hook 系统是请求处理的中间件机制，采用串联模式依次执
 ### 基础结构
 
 ```typescript
-import type { Hook } from 'befly/types/hook';
+import type { Hook } from "befly/types/hook";
 
 const hook: Hook = {
     // 执行顺序（数字越小越先执行）
@@ -195,6 +195,13 @@ interface Hook {
 
 ## 内置钩子
 
+内置钩子除本页总览外，也提供分文档说明（更聚焦配置与行为）：
+
+- [cors Hook](./cors.md)
+- [auth Hook](./auth.md)
+- [parser Hook](./parser.md)
+- [rateLimit Hook](./rateLimit.md)
+
 ### cors - 跨域处理
 
 处理 CORS 跨域请求，设置响应头。
@@ -208,12 +215,12 @@ 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 || {}) };
@@ -222,7 +229,7 @@ const hook: Hook = {
         ctx.corsHeaders = setCorsOptions(req, corsConfig);
 
         // 处理 OPTIONS 预检请求
-        if (req.method === 'OPTIONS') {
+        if (req.method === "OPTIONS") {
             ctx.response = new Response(null, {
                 status: 204,
                 headers: ctx.corsHeaders
@@ -236,7 +243,7 @@ const hook: Hook = {
 **配置**：
 
 ```json
-// befly.local.json
+// befly.development.json
 {
     "cors": {
         "origin": "https://example.com",
@@ -259,9 +266,9 @@ const hook: Hook = {
 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 {
@@ -297,7 +304,7 @@ const hook: Hook = {
         if (!ctx.api) return;
 
         // GET 请求：解析查询参数
-        if (ctx.req.method === 'GET') {
+        if (ctx.req.method === "GET") {
             const url = new URL(ctx.req.url);
             const params = Object.fromEntries(url.searchParams);
 
@@ -310,17 +317,17 @@ const hook: Hook = {
             }
         }
         // POST 请求：解析 JSON/XML
-        else if (ctx.req.method === 'POST') {
-            const contentType = ctx.req.headers.get('content-type') || '';
+        else if (ctx.req.method === "POST") {
+            const contentType = ctx.req.headers.get("content-type") || "";
 
-            if (contentType.includes('application/json')) {
+            if (contentType.includes("application/json")) {
                 const body = await ctx.req.json();
                 // 过滤字段...
                 ctx.body = pickFields(body, Object.keys(ctx.api.fields));
-            } else if (contentType.includes('application/xml')) {
+            } else if (contentType.includes("application/xml")) {
                 // XML 解析...
             } else {
-                ctx.response = ErrorResponse(ctx, '无效的请求参数格式');
+                ctx.response = ErrorResponse(ctx, "无效的请求参数格式");
                 return;
             }
         }
@@ -350,9 +357,9 @@ const hook: Hook = {
             requestId: ctx.requestId,
             route: ctx.route,
             ip: ctx.ip,
-            userId: ctx.user?.id || '',
-            nickname: ctx.user?.nickname || '',
-            roleCode: ctx.user?.roleCode || ''
+            userId: ctx.user?.id || "",
+            nickname: ctx.user?.nickname || "",
+            roleCode: ctx.user?.roleCode || ""
         };
 
         // 截断大请求体
@@ -360,7 +367,7 @@ const hook: Hook = {
             logData.body = truncateBody(ctx.body);
         }
 
-        Logger.info(logData, '请求日志');
+        Logger.info(logData, "请求日志");
     }
 };
 ```
@@ -388,7 +395,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);
             return;
         }
     }
@@ -410,6 +417,8 @@ const hook: Hook = {
 
 ```typescript
 // hooks/permission.ts
+import { CacheKeys } from "befly/lib/cacheKeys";
+
 const hook: Hook = {
     order: 6,
     handler: async (befly, ctx) => {
@@ -422,25 +431,28 @@ const hook: Hook = {
 
         // 2. 用户未登录
         if (!ctx.user || !ctx.user.id) {
-            ctx.response = ErrorResponse(ctx, '未登录');
+            ctx.response = ErrorResponse(ctx, "未登录");
             return;
         }
 
         // 3. 开发者权限（最高权限）
-        if (ctx.user.roleCode === 'dev') {
+        if (ctx.user.roleCode === "dev") {
             return;
         }
 
         // 4. 角色权限检查
         let hasPermission = false;
         if (ctx.user.roleCode && befly.redis) {
-            const apiPath = `${ctx.req.method}${new URL(ctx.req.url).pathname}`;
-            const roleApisKey = RedisKeys.roleApis(ctx.user.roleCode);
+            // 统一格式：METHOD/path（与写入缓存保持一致）
+            const apiPath = normalizeApiPath(ctx.req.method, new URL(ctx.req.url).pathname);
+
+            // 极简方案：每个角色一个 Set，直接判断成员是否存在
+            const roleApisKey = CacheKeys.roleApis(ctx.user.roleCode);
             hasPermission = await befly.redis.sismember(roleApisKey, apiPath);
         }
 
         if (!hasPermission) {
-            ctx.response = ErrorResponse(ctx, '无权访问');
+            ctx.response = ErrorResponse(ctx, "无权访问");
             return;
         }
     }
@@ -462,12 +474,12 @@ const hook: Hook = {
 
 ```typescript
 // hooks/myHook.ts（项目钩子名：app_myHook）
-import type { Hook } from 'befly/types/hook';
+import type { Hook } from "befly/types/hook";
 
 const hook: Hook = {
     order: 10,
     handler: async (befly, ctx) => {
-        befly.logger.info({ route: ctx.route }, '自定义钩子执行');
+        befly.logger.info({ route: ctx.route }, "自定义钩子执行");
     }
 };
 
@@ -482,17 +494,17 @@ export default hook;
 
 ```typescript
 // hooks/blacklist.ts
-import type { Hook } from 'befly/types/hook';
-import { ErrorResponse } from 'befly/util';
+import type { Hook } from "befly/types/hook";
+import { ErrorResponse } from "befly/utils/response";
 
 const hook: Hook = {
     order: 1, // 最先执行
     handler: async (befly, ctx) => {
         // IP 黑名单检查
-        const blacklist = ['192.168.1.100', '10.0.0.1'];
+        const blacklist = ["192.168.1.100", "10.0.0.1"];
 
         if (blacklist.includes(ctx.ip)) {
-            ctx.response = ErrorResponse(ctx, '您的 IP 已被禁止访问', 403);
+            ctx.response = ErrorResponse(ctx, "您的 IP 已被禁止访问", 403);
             return;
         }
     }
@@ -507,10 +519,51 @@ export default hook;
 
 基于 Redis 的请求限流：
 
+> 说明：Befly Core 已内置 `rateLimit` 钩子（默认启用）。
+>
+> 默认行为：按 IP 对所有 API 进行限流（默认阈值：$1000/60$，即 60 秒最多 1000 次）。
+>
+> - 关闭：`rateLimit.enable = 0`
+> - 覆盖：配置 `rules`（更细粒度）或调整 `defaultLimit/defaultWindow`
+> - 跳过：配置 `skipRoutes`（命中后直接跳过限流，优先级最高）
+>
+> 规则选择：当多条 `rules` 同时命中时，会优先选择更“具体”的规则（精确 > 前缀 > 通配）；
+> 同等具体度按 `rules` 的先后顺序。
+>
+> key 行为：当 `key = user` 且请求上下文中没有 `ctx.user.id` 时，会回退为按 IP 计数，避免所有匿名请求共享同一个计数桶。
+
+配置示例（`configs/befly.common.json`）：
+
+```json
+{
+    "rateLimit": {
+        "enable": 1,
+        "defaultLimit": 1000,
+        "defaultWindow": 60,
+        "key": "ip",
+        "skipRoutes": ["/api/health", "GET/api/metrics"],
+        "rules": [
+            {
+                "route": "/api/auth/*",
+                "limit": 20,
+                "window": 60,
+                "key": "ip"
+            },
+            {
+                "route": "POST/api/order/create",
+                "limit": 5,
+                "window": 60,
+                "key": "user"
+            }
+        ]
+    }
+}
+```
+
 ```typescript
 // hooks/rateLimit.ts
-import type { Hook } from 'befly/types/hook';
-import { ErrorResponse } from 'befly/util';
+import type { Hook } from "befly/types/hook";
+import { ErrorResponse } from "befly/utils/response";
 
 const hook: Hook = {
     order: 7,
@@ -524,17 +577,12 @@ const hook: Hook = {
         // 限流 key：IP + 路由
         const key = `ratelimit:${ctx.ip}:${ctx.route}`;
 
-        // 获取当前计数
-        const count = await befly.redis.incr(key);
-
-        // 首次请求设置过期时间
-        if (count === 1) {
-            await befly.redis.expire(key, window);
-        }
+        // 原子计数 + 首次设置过期
+        const count = await befly.redis.incrWithExpire(key, window);
 
         // 超过限制
         if (count > limit) {
-            ctx.response = ErrorResponse(ctx, '请求过于频繁，请稍后再试', 429);
+            ctx.response = ErrorResponse(ctx, "请求过于频繁，请稍后再试", 1);
             return;
         }
     }
@@ -551,22 +599,22 @@ export default hook;
 
 ```typescript
 // hooks/audit.ts
-import type { Hook } from 'befly/types/hook';
+import type { Hook } from "befly/types/hook";
 
 const hook: Hook = {
     order: 100, // 在 handler 执行后
     handler: async (befly, ctx) => {
         // 只记录写操作
-        if (!ctx.api || ctx.req.method === 'GET') return;
+        if (!ctx.api || ctx.req.method === "GET") return;
         if (!ctx.user?.id) return;
 
         // 记录审计日志
         try {
             await befly.db.insData({
-                table: 'audit_log',
+                table: "audit_log",
                 data: {
                     userId: ctx.user.id,
-                    username: ctx.user.username || '',
+                    username: ctx.user.username || "",
                     route: ctx.route,
                     method: ctx.req.method,
                     ip: ctx.ip,
@@ -575,7 +623,7 @@ const hook: Hook = {
                 }
             });
         } catch (error) {
-            befly.logger.error({ err: error }, '审计日志记录失败');
+            befly.logger.error({ err: error }, "审计日志记录失败");
         }
     }
 };
@@ -590,7 +638,7 @@ export default hook;
 设置 `ctx.response` 可以中断后续 Hook 和 API Handler 的执行：
 
 ```typescript
-import { ErrorResponse } from 'befly/util';
+import { ErrorResponse } from "befly/utils/response";
 
 const hook: Hook = {
     order: 5,
@@ -598,7 +646,7 @@ const hook: Hook = {
         // 条件判断
         if (someCondition) {
             // 设置 response 中断请求
-            ctx.response = ErrorResponse(ctx, '请求被拦截', 1);
+            ctx.response = ErrorResponse(ctx, "请求被拦截", 1);
             return; // 必须 return
         }
 
@@ -625,7 +673,7 @@ ErrorResponse(ctx, msg, code?, data?, detail?)
 在配置文件中设置 `disableHooks` 数组：
 
 ```json
-// befly.local.json
+// befly.development.json
 {
     "disableHooks": ["requestLogger", "permission"]
 }
@@ -678,7 +726,7 @@ const hook: Hook = {
         try {
             await someOperation();
         } catch (error) {
-            befly.logger.error({ err: error }, '钩子执行失败');
+            befly.logger.error({ err: error }, "钩子执行失败");
             // 根据业务决定是否中断请求
         }
     }
@@ -699,7 +747,7 @@ const hook: Hook = {
 
 ### 5. 性能考虑
 
-```typescript
+````typescript
 // ✅ 推荐：异步操作使用 Promise
 const hook: Hook = {
     handler: async (befly, ctx) => {
@@ -707,7 +755,42 @@ const hook: Hook = {
         const [result1, result2] = await Promise.all([operation1(), operation2()]);
     }
 };
-```
+
+### 6. 直接使用字段，避免多余变量
+
+仅用于“转发参数 / 改名 / 只用一次”的中间变量不要定义；优先直接使用来源对象字段（例如 `ctx.body.xxx`、`payload.xxx`）。
+
+```typescript
+// ❌ 避免：只为转发参数而改名/多一层
+const hook: Hook = {
+    handler: async (befly, ctx) => {
+        const payload = await befly.jwt.verify(token); // token 解析略
+        const userId = payload.id;
+        setCtxUser(userId, payload.roleCode, payload.nickname, payload.roleType);
+    }
+};
+
+// ✅ 推荐：直接转发字段
+const hook2: Hook = {
+    handler: async (befly, ctx) => {
+        const payload = await befly.jwt.verify(token); // token 解析略
+        setCtxUser(payload.id, payload.roleCode, payload.nickname, payload.roleType);
+    }
+};
+
+// ✅ 例外：需要类型收窄/非空校验/复用（>=2 次）时再定义变量
+const hook3: Hook = {
+    handler: async (befly, ctx) => {
+        const payload = await befly.jwt.verify(token); // token 解析略
+        const userId = payload.id;
+        if (typeof userId !== "number") return;
+
+        setCtxUser(userId, payload.roleCode, payload.nickname, payload.roleType);
+    }
+};
+````
+
+````
 
 ---
 
@@ -727,11 +810,11 @@ const hook: Hook = {
         await befly.db.getOne({
             /* ... */
         });
-        await befly.redis.get('key');
-        befly.logger.info('日志');
+        await befly.redis.get("key");
+        befly.logger.info("日志");
     }
 };
-```
+````
 
 ### Q3: 如何在钩子间传递数据？
 
@@ -739,7 +822,7 @@ const hook: Hook = {
 
 ```typescript
 // 钩子 A（order: 10）
-ctx.customData = { key: 'value' };
+ctx.customData = { key: "value" };
 
 // 钩子 B（order: 20）
 const data = ctx.customData;

package/docs/hooks/parser.md

@@ -0,0 +1,19 @@
+# parser Hook - 参数解析
+
+> 解析请求体/查询参数，产出统一的 `ctx.body`。
+
+## 作用
+
+- GET：解析 URL 查询参数
+- POST：解析 JSON（必要时也会支持 XML 等格式，取决于框架实现）
+- 将解析结果写入 `ctx.body`
+
+## 行为要点
+
+- 解析失败（格式错误）时会提前中断请求，并返回安全的错误信息
+- 该 hook 只负责“把数据变成 ctx.body”，字段校验由后续 `validator` 完成
+
+## 常见问题
+
+- Q: 为什么 `ctx.body` 里没有某些字段？
+    - A: 可能被 fields/required 体系过滤/校验拦截了；请检查 `validator` 与 API 的 `fields/required` 配置。

package/docs/hooks/rateLimit.md

@@ -0,0 +1,47 @@
+# rateLimit Hook - 全局限流
+
+> 按路由与身份维度进行限流（默认启用）。
+
+## 默认行为
+
+- **默认启用**：`rateLimit.enable = 1`
+- 无规则时：使用兜底配置（默认阈值由框架默认配置提供）
+- `OPTIONS` 请求：不计数也不拦截
+
+## 配置
+
+```json
+{
+    "rateLimit": {
+        "enable": 1,
+        "rules": [
+            {
+                "route": "/api/auth/*",
+                "limit": 10,
+                "window": 60,
+                "key": "ip"
+            }
+        ],
+        "skipRoutes": ["GET/api/health"]
+    }
+}
+```
+
+### route 匹配
+
+- 支持精确、前缀、通配（更具体的规则优先）
+
+### key 维度
+
+- `ip`：按 IP 限流
+- `user`：按用户限流；当缺失 `ctx.user.id` 时会回退为按 IP 计数
+- `ip_user`：IP + 用户组合
+
+### skipRoutes
+
+命中后直接跳过限流：**不计数也不拦截**。
+
+## 存储
+
+- 优先使用 Redis（分布式一致）
+- 无 Redis 时降级为进程内计数