befly 3.9.35 → 3.9.37

package/docs/api.md

@@ -282,6 +282,116 @@ befly.tool.No(msg: string, data?: any, other?: Record<string, any>)
 }
 ```
 
+### Raw - 原始响应
+
+用于第三方回调等需要自定义响应格式的场景，直接返回 `Response` 对象。自动识别数据类型并设置正确的 Content-Type。
+
+```typescript
+befly.tool.Raw(ctx: RequestContext, data: Record<string, any> | string, options?: ResponseOptions)
+```
+
+**参数说明：**
+
+| 参数    | 类型                          | 必填 | 默认值 | 说明                     |
+| ------- | ----------------------------- | ---- | ------ | ------------------------ |
+| ctx     | RequestContext                | 是   | -      | 请求上下文               |
+| data    | Record<string, any> \| string | 是   | -      | 响应数据（对象或字符串） |
+| options | ResponseOptions               | 否   | {}     | 响应选项                 |
+
+**ResponseOptions 选项：**
+
+| 属性        | 类型                   | 默认值   | 说明                                     |
+| ----------- | ---------------------- | -------- | ---------------------------------------- |
+| status      | number                 | 200      | HTTP 状态码                              |
+| contentType | string                 | 自动判断 | Content-Type，默认根据 data 类型自动判断 |
+| headers     | Record<string, string> | {}       | 额外的响应头                             |
+
+**Content-Type 自动判断规则：**
+
+| data 类型             | 自动 Content-Type |
+| --------------------- | ----------------- |
+| 对象                  | application/json  |
+| 字符串（以 `<` 开头） | application/xml   |
+| 字符串（其他）        | text/plain        |
+
+**使用示例：**
+
+```typescript
+// JSON 响应（自动）
+return befly.tool.Raw(ctx, { code: 'SUCCESS', message: '成功' });
+
+// 纯文本响应（自动）- 支付宝回调
+return befly.tool.Raw(ctx, 'success');
+
+// XML 响应（自动判断）
+return befly.tool.Raw(ctx, '<xml><return_code>SUCCESS</return_code></xml>');
+
+// XML 响应（手动指定）
+return befly.tool.Raw(ctx, xmlString, { contentType: 'application/xml' });
+
+// 自定义状态码
+return befly.tool.Raw(ctx, { error: 'Not Found' }, { status: 404 });
+
+// 自定义响应头
+return befly.tool.Raw(
+    ctx,
+    { code: 'SUCCESS' },
+    {
+        headers: { 'X-Custom-Header': 'value' }
+    }
+);
+```
+
+**完整回调示例：**
+
+```typescript
+// 微信支付回调
+export default {
+    name: '微信支付回调',
+    auth: false,
+    rawBody: true,
+    handler: async (befly, ctx) => {
+        if (!befly.weixin) {
+            return befly.tool.Raw(ctx, { code: 'SYSTEM_ERROR', message: 'weixin 插件未配置' });
+        }
+
+        // 处理成功
+        return befly.tool.Raw(ctx, { code: 'SUCCESS', message: '' });
+    }
+};
+
+// 支付宝回调
+export default {
+    name: '支付宝回调',
+    auth: false,
+    rawBody: true,
+    handler: async (befly, ctx) => {
+        // 支付宝要求返回纯文本 "success"
+        return befly.tool.Raw(ctx, 'success');
+    }
+};
+
+// 微信公众号 XML 回调
+export default {
+    name: '微信公众号回调',
+    auth: false,
+    rawBody: true,
+    handler: async (befly, ctx) => {
+        // 返回 XML 格式响应
+        const xml = `<xml>
+            <ToUserName><![CDATA[${fromUser}]]></ToUserName>
+            <FromUserName><![CDATA[${toUser}]]></FromUserName>
+            <CreateTime>${Date.now()}</CreateTime>
+            <MsgType><![CDATA[text]]></MsgType>
+            <Content><![CDATA[收到]]></Content>
+        </xml>`;
+        return befly.tool.Raw(ctx, xml);
+    }
+};
+```
+
+**注意**：`Raw` 返回的是 `Response` 对象，会直接作为 HTTP 响应返回，不经过 `FinalResponse` 处理。
+
 ### ErrorResponse - Hook 中断响应
 
 在 Hook 中使用，用于提前拦截请求：
@@ -575,6 +685,233 @@ interface FieldDefinition {
 
 ---
 
+## rawBody 原始请求体
+
+### 概述
+
+`rawBody` 参数用于控制 `parser` 钩子的行为。当设置 `rawBody: true` 时，框架会**完全跳过请求体解析**，`ctx.body` 为空对象 `{}`，handler 可以通过 `ctx.req` 获取原始请求自行处理。
+
+这对于需要**手动验签、解密**的场景非常重要，如微信支付回调需要原始请求体来验证 RSA 签名。
+
+### 工作原理
+
+#### 默认行为（rawBody: false）
+
+```typescript
+// API 定义
+export default {
+    name: '更新用户',
+    fields: {
+        id: '@id',
+        username: { name: '用户名', type: 'string', max: 50 }
+    },
+    handler: async (befly, ctx) => {
+        // ctx.body 只包含 fields 中定义的字段
+    }
+};
+
+// 请求参数
+{ id: 1, username: 'test', email: 'test@qq.com', role: 'admin' }
+
+// ctx.body 实际值（过滤后）
+{ id: 1, username: 'test' }
+// email 和 role 被过滤掉了
+```
+
+#### rawBody 模式（rawBody: true）
+
+```typescript
+// API 定义
+export default {
+    name: '微信支付回调',
+    method: 'POST',
+    auth: false,
+    rawBody: true, // 跳过解析，保留原始请求
+    handler: async (befly, ctx) => {
+        // ctx.body 为空对象 {}
+        // 通过 ctx.req 获取原始请求自行处理
+
+        // 获取原始请求体（用于验签）
+        const rawBody = await ctx.req.text();
+
+        // 解析数据
+        const data = JSON.parse(rawBody);
+
+        // 处理业务逻辑...
+    }
+};
+```
+
+### 处理流程
+
+| rawBody        | parser 钩子行为                 | ctx.body     | 使用场景           |
+| -------------- | ------------------------------- | ------------ | ------------------ |
+| `false` (默认) | 解析 JSON/XML，根据 fields 过滤 | 解析后的对象 | 普通 CRUD          |
+| `true`         | **完全跳过**，不解析请求体      | `{}` 空对象  | 回调验签、手动解密 |
+
+### 适用场景
+
+| 场景         | rawBody | 说明                           |
+| ------------ | ------- | ------------------------------ |
+| 微信支付回调 | `true`  | 需要原始请求体验证 RSA 签名    |
+| 支付宝回调   | `true`  | 需要原始请求体验证签名         |
+| Webhook      | `true`  | 需要原始请求体验证 HMAC 签名   |
+| 加密数据接口 | `true`  | 需要手动解密请求体             |
+| 文件上传     | `true`  | 需要原始请求体处理二进制数据   |
+| 普通 CRUD    | `false` | 标准增删改查（默认）           |
+| 批量操作     | `false` | 使用空 fields 即可保留所有字段 |
+
+### 示例代码
+
+#### 微信支付 V3 回调（需要验签和解密）
+
+```typescript
+// apis/webhook/wechatPayV3.ts
+export default {
+    name: '微信支付V3回调',
+    method: 'POST',
+    auth: false,
+    rawBody: true, // 跳过解析，保留原始请求
+    handler: async (befly, ctx) => {
+        // 1. 获取原始请求体（用于验签）
+        const rawBody = await ctx.req.text();
+
+        // 2. 获取微信签名头
+        const signature = ctx.req.headers.get('Wechatpay-Signature');
+        const timestamp = ctx.req.headers.get('Wechatpay-Timestamp');
+        const nonce = ctx.req.headers.get('Wechatpay-Nonce');
+        const serial = ctx.req.headers.get('Wechatpay-Serial');
+
+        // 3. 验证签名
+        const verifyMessage = `${timestamp}\n${nonce}\n${rawBody}\n`;
+        if (!verifyRsaSign(verifyMessage, signature, serial)) {
+            return { code: 'FAIL', message: '签名验证失败' };
+        }
+
+        // 4. 解析并解密数据
+        const notification = JSON.parse(rawBody);
+        const { ciphertext, nonce: decryptNonce, associated_data } = notification.resource;
+        const decrypted = decryptAesGcm(ciphertext, decryptNonce, associated_data);
+        const payResult = JSON.parse(decrypted);
+
+        // 5. 处理支付结果
+        if (payResult.trade_state === 'SUCCESS') {
+            await befly.db.updData({
+                table: 'order',
+                where: { orderNo: payResult.out_trade_no },
+                data: {
+                    payStatus: 1,
+                    payTime: Date.now(),
+                    transactionId: payResult.transaction_id
+                }
+            });
+        }
+
+        return { code: 'SUCCESS', message: '' };
+    }
+};
+```
+
+#### GitHub Webhook（HMAC 签名验证）
+
+```typescript
+// apis/webhook/github.ts
+import { createHmac } from 'crypto';
+
+export default {
+    name: 'GitHub Webhook',
+    method: 'POST',
+    auth: false,
+    rawBody: true,
+    handler: async (befly, ctx) => {
+        // 获取原始请求体
+        const rawBody = await ctx.req.text();
+
+        // 获取 GitHub 签名
+        const signature = ctx.req.headers.get('X-Hub-Signature-256');
+        if (!signature) {
+            return befly.tool.No('缺少签名');
+        }
+
+        // 验证 HMAC 签名
+        const secret = process.env.GITHUB_WEBHOOK_SECRET;
+        const hmac = createHmac('sha256', secret);
+        const expectedSignature = 'sha256=' + hmac.update(rawBody).digest('hex');
+
+        if (signature !== expectedSignature) {
+            return befly.tool.No('签名验证失败');
+        }
+
+        // 解析数据
+        const payload = JSON.parse(rawBody);
+        const event = ctx.req.headers.get('X-GitHub-Event');
+
+        // 处理不同事件
+        if (event === 'push') {
+            befly.logger.info({ ref: payload.ref }, 'GitHub Push 事件');
+        }
+
+        return befly.tool.Yes('处理成功');
+    }
+};
+```
+
+#### 加密数据接口
+
+```typescript
+// apis/secure/receive.ts
+export default {
+    name: '接收加密数据',
+    auth: false,
+    rawBody: true,
+    handler: async (befly, ctx) => {
+        // 获取加密的请求体
+        const encryptedBody = await ctx.req.text();
+
+        // 解密数据
+        const decrypted = befly.cipher.decrypt(encryptedBody);
+        const data = JSON.parse(decrypted);
+
+        // 处理解密后的数据
+        // ...
+
+        return befly.tool.Yes('处理成功');
+    }
+};
+```
+
+### 批量操作的替代方案
+
+对于批量导入等场景，**不需要使用 rawBody**，使用空 `fields` 即可保留所有字段：
+
+```typescript
+// apis/user/batchImport.ts
+export default {
+    name: '批量导入用户',
+    // 不定义 fields，或 fields: {}，会保留所有请求参数
+    handler: async (befly, ctx) => {
+        const { users } = ctx.body; // 正常解析
+
+        if (!Array.isArray(users) || users.length === 0) {
+            return befly.tool.No('用户列表不能为空');
+        }
+
+        // 批量插入...
+        return befly.tool.Yes('导入成功');
+    }
+};
+```
+
+### 注意事项
+
+1. **请求体只能读取一次**：`ctx.req.text()` 或 `ctx.req.json()` 只能调用一次，第二次调用会返回空
+2. **ctx.body 为空**：`rawBody: true` 时 `ctx.body = {}`，所有数据需要从 `ctx.req` 获取
+3. **validator 钩子**：如果定义了 `required` 字段，validator 仍会检查 `ctx.body`（此时为空），建议 rawBody 接口不定义 required
+4. **安全性**：手动处理请求时务必做好验签和数据验证
+5. **Content-Type 无限制**：rawBody 模式不检查 Content-Type，支持任意格式
+
+---
+
 ## 实际案例
 
 ### 案例一：公开接口（无需认证）

package/hooks/parser.ts

@@ -16,20 +16,25 @@ const xmlParser = new XMLParser();
  * - GET 请求：解析 URL 查询参数
  * - POST 请求：解析 JSON 或 XML 请求体
  * - 根据 API 定义的 fields 过滤字段
+ * - rawBody: true 时跳过解析，由 handler 自行处理原始请求
  */
 const hook: Hook = {
     order: 4,
     handler: async (befly, ctx) => {
         if (!ctx.api) return;
 
+        // rawBody 模式：跳过解析，保留原始请求供 handler 自行处理
+        // 适用于：微信回调、支付回调、webhook 等需要手动解密/验签的场景
+        if (ctx.api.rawBody) {
+            ctx.body = {};
+            return;
+        }
+
         // GET 请求：解析查询参数
         if (ctx.req.method === 'GET') {
             const url = new URL(ctx.req.url);
             const params = Object.fromEntries(url.searchParams);
-            // rawBody 模式：保留完整请求参数，不过滤字段
-            if (ctx.api.rawBody) {
-                ctx.body = params;
-            } else if (isPlainObject(ctx.api.fields) && !isEmpty(ctx.api.fields)) {
+            if (isPlainObject(ctx.api.fields) && !isEmpty(ctx.api.fields)) {
                 ctx.body = pickFields(params, Object.keys(ctx.api.fields));
             } else {
                 ctx.body = params;
@@ -37,7 +42,7 @@ const hook: Hook = {
         } else if (ctx.req.method === 'POST') {
             // POST 请求：解析请求体
             const contentType = ctx.req.headers.get('content-type') || '';
-            // 获取 URL 查询参数（POST 请求也可能带参数，如微信回调）
+            // 获取 URL 查询参数（POST 请求也可能带参数）
             const url = new URL(ctx.req.url);
             const queryParams = Object.fromEntries(url.searchParams);
 
@@ -47,10 +52,7 @@ const hook: Hook = {
                     const body = (await ctx.req.json()) as Record<string, any>;
                     // 合并 URL 参数和请求体（请求体优先）
                     const merged = { ...queryParams, ...body };
-                    // rawBody 模式：保留完整请求体，不过滤字段
-                    if (ctx.api.rawBody) {
-                        ctx.body = merged;
-                    } else if (isPlainObject(ctx.api.fields) && !isEmpty(ctx.api.fields)) {
+                    if (isPlainObject(ctx.api.fields) && !isEmpty(ctx.api.fields)) {
                         ctx.body = pickFields(merged, Object.keys(ctx.api.fields));
                     } else {
                         ctx.body = merged;
@@ -64,10 +66,7 @@ const hook: Hook = {
                     const body = rootKey && typeof parsed[rootKey] === 'object' ? parsed[rootKey] : parsed;
                     // 合并 URL 参数和请求体（请求体优先）
                     const merged = { ...queryParams, ...body };
-                    // rawBody 模式：保留完整请求体，不过滤字段
-                    if (ctx.api.rawBody) {
-                        ctx.body = merged;
-                    } else if (isPlainObject(ctx.api.fields) && !isEmpty(ctx.api.fields)) {
+                    if (isPlainObject(ctx.api.fields) && !isEmpty(ctx.api.fields)) {
                         ctx.body = pickFields(merged, Object.keys(ctx.api.fields));
                     } else {
                         ctx.body = merged;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.9.35",
+    "version": "3.9.37",
     "description": "Befly - 为 Bun 专属打造的 TypeScript API 接口框架核心引擎",
     "type": "module",
     "private": false,
@@ -65,16 +65,16 @@
         "bun": ">=1.3.0"
     },
     "dependencies": {
-        "befly-shared": "^1.2.7",
+        "befly-shared": "^1.2.8",
         "chalk": "^5.6.2",
-        "es-toolkit": "^1.42.0",
+        "es-toolkit": "^1.43.0",
         "fast-jwt": "^6.1.0",
         "fast-xml-parser": "^5.3.3",
         "pathe": "^2.0.3",
         "pino": "^10.1.0",
         "pino-roll": "^4.0.0"
     },
-    "gitHead": "4b7ea2e7f6d7b5c7454f34c30794473d8bb021de",
+    "gitHead": "e078b94f087ddf21f289b55ab86c0b8dce105807",
     "devDependencies": {
         "typescript": "^5.9.3"
     }

package/plugins/tool.ts

@@ -5,6 +5,7 @@
 
 // 类型导入
 import type { Plugin } from '../types/plugin.js';
+import type { RequestContext } from '../types/context.js';
 
 /**
  * 成功响应
@@ -38,11 +39,86 @@ export function No(msg: string, data: any = null, other: Record<string, any> = {
     };
 }
 
+/**
+ * 响应选项
+ */
+interface ResponseOptions {
+    /** HTTP 状态码，默认 200 */
+    status?: number;
+    /** Content-Type，默认根据 data 类型自动判断 */
+    contentType?: string;
+    /** 额外的响应头 */
+    headers?: Record<string, string>;
+}
+
+/**
+ * 统一响应函数
+ *
+ * 自动识别数据类型并设置正确的 Content-Type：
+ * - 对象 → application/json
+ * - 字符串 → text/plain
+ * - 可通过 options.contentType 手动指定
+ *
+ * @param ctx 请求上下文
+ * @param data 响应数据（对象或字符串）
+ * @param options 响应选项
+ * @returns Response 对象
+ *
+ * @example
+ * // JSON 响应（自动）
+ * return Raw(ctx, { code: 'SUCCESS', message: '成功' });
+ *
+ * // 纯文本响应（自动）
+ * return Raw(ctx, 'success');
+ *
+ * // XML 响应（手动指定）
+ * return Raw(ctx, xmlString, { contentType: 'application/xml' });
+ *
+ * // 自定义状态码和额外头
+ * return Raw(ctx, { error: 'Not Found' }, {
+ *   status: 404,
+ *   headers: { 'X-Custom': 'value' }
+ * });
+ */
+export function Raw(ctx: RequestContext, data: Record<string, any> | string, options: ResponseOptions = {}): Response {
+    const { status = 200, contentType, headers = {} } = options;
+
+    // 自动判断 Content-Type
+    let finalContentType = contentType;
+    let body: string;
+
+    if (typeof data === 'string') {
+        // 字符串类型
+        body = data;
+        if (!finalContentType) {
+            // 自动判断：XML 或纯文本
+            finalContentType = data.trim().startsWith('<') ? 'application/xml' : 'text/plain';
+        }
+    } else {
+        // 对象类型，JSON 序列化
+        body = JSON.stringify(data);
+        finalContentType = finalContentType || 'application/json';
+    }
+
+    // 合并响应头
+    const responseHeaders = {
+        ...ctx.corsHeaders,
+        'Content-Type': finalContentType,
+        ...headers
+    };
+
+    return new Response(body, {
+        status: status,
+        headers: responseHeaders
+    });
+}
+
 const plugin: Plugin = {
     handler: () => {
         return {
             Yes: Yes,
-            No: No
+            No: No,
+            Raw: Raw
         };
     }
 };

package/util.ts

@@ -90,7 +90,7 @@ export function ErrorResponse(ctx: RequestContext, msg: string, code: number = 1
     // 记录拦截日志
     if (ctx.requestId) {
         const duration = Date.now() - ctx.now;
-        const user = ctx.user?.id ? `[User:${ctx.user.id}]` : '[Guest]';
+        const user = ctx.user?.id ? `[User:${ctx.user.id} ${ctx.user.nickname}]` : '[Guest]';
         Logger.info(`[${ctx.requestId}] ${ctx.route} ${user} ${duration}ms [${msg}]`);
     }
 
@@ -117,7 +117,7 @@ export function FinalResponse(ctx: RequestContext): Response {
     // 记录请求日志
     if (ctx.api && ctx.requestId) {
         const duration = Date.now() - ctx.now;
-        const user = ctx.user?.id ? `[User:${ctx.user.id}]` : '[Guest]';
+        const user = ctx.user?.id ? `[User:${ctx.user.id}  ${ctx.user.nickname}]` : '[Guest]';
         Logger.info(`[${ctx.requestId}] ${ctx.route} ${user} ${duration}ms`);
     }