befly 3.9.36 → 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 中使用，用于提前拦截请求：

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "befly",
-    "version": "3.9.36",
+    "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": "ac556f0341ab02b800afd8ba0639a5754fcbaf4a",
+    "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
         };
     }
 };