@faapi/faapi 1.2.1 → 1.3.0

package/dist/index.d.ts

@@ -87,6 +87,31 @@ interface CookieOptions {
     secure?: boolean;
     sameSite?: 'Strict' | 'Lax' | 'None';
 }
+/**
+ * ctx.fail() 的参数类型(对象形式,status 和 code 均可省略)
+ *
+ * - status: HTTP 状态码(可选,省略时默认 500)
+ * - code: 业务错误码(可选,省略时响应 body 里不含 code 字段)
+ * - message: 人类可读错误描述(必填)
+ *
+ * status 和 code 是两个独立维度,无关联:
+ * - status 控制 HTTP 状态码
+ * - code 是 body 里的业务错误码字段
+ *
+ * ```ts
+ * ctx.fail({ message: '出错' })                                  // HTTP 500, { error: { message: '出错' } }
+ * ctx.fail({ status: 404, message: '用户不存在' })                // HTTP 404, { error: { message: '用户不存在' } }
+ * ctx.fail({ status: 404, code: 'USER_NOT_FOUND', message: '用户不存在' }) // HTTP 404, { error: { code: 'USER_NOT_FOUND', message: '用户不存在' } }
+ * ```
+ */
+interface FailOptions {
+    /** HTTP 状态码(可选,省略时默认 500) */
+    status?: number;
+    /** 业务错误码(可选,省略时响应 body 里不含 code 字段) */
+    code?: string;
+    /** 人类可读错误描述 */
+    message: string;
+}
 /**
  * ctx.config 的类型：用户自定义业务配置
  *
@@ -192,6 +217,41 @@ interface FaapiContext {
      * ```
      */
     sse(): SseWriter;
+    /**
+     * 显式包装成功响应(返回 Response 对象)
+     *
+     * 用 config.response.ok 包裹 data 并返回 Response。
+     * 等价于 handler 直接 `return data`(框架自动包裹),但显式调用语义更清晰。
+     *
+     * 返回 Response 对象,不会被框架自动包裹再次包装(避免双重包裹)。
+     *
+     * ```ts
+     * // 以下两种写法等价(假设配置了 response.ok = (data) => ({ data })):
+     * export function GET() {
+     *   return { id: 1 };              // 自动包裹 → { data: { id: 1 } }
+     * }
+     * export function GET2(ctx) {
+     *   return ctx.ok({ id: 1 });      // 显式包裹 → { data: { id: 1 } }
+     * }
+     * ```
+     */
+    ok(data: unknown): Response;
+    /**
+     * 返回错误响应(对象形式参数,status 和 code 均可省略)
+     *
+     * @param options.status  HTTP 状态码(可选,省略时默认 500)
+     * @param options.code    业务错误码(可选,省略时响应 body 里不含 code 字段)
+     * @param options.message 人类可读错误描述(必填)
+     *
+     * status 和 code 独立无关联:status 控制 HTTP 状态码,code 是 body 里的业务错误码字段。
+     *
+     * ```ts
+     * return ctx.fail({ message: '出错' });                                   // HTTP 500, { error: { message: '出错' } }
+     * return ctx.fail({ status: 404, message: '用户不存在' });                 // HTTP 404, { error: { message: '用户不存在' } }
+     * return ctx.fail({ status: 404, code: 'USER_NOT_FOUND', message: '用户不存在' }); // HTTP 404, { error: { code: 'USER_NOT_FOUND', message: '用户不存在' } }
+     * ```
+     */
+    fail(options: FailOptions): Response;
     /**
      * 读取 cookie 值
      */
@@ -562,6 +622,50 @@ interface LifecycleContext {
     /** 服务器实例 */
     server: node_http.Server;
 }
+/**
+ * 统一响应包装配置
+ *
+ * 配置后,框架自动:
+ * - 成功响应:handler return 非 Response 的值时,用 ok 函数包裹
+ * - 错误响应:ctx.fail() 用 fail 函数包装 body
+ *
+ * 未配置 response 时,使用框架默认实现:
+ * - ok: (data) => ({ data })
+ * - fail: ({ status, code, message }) => 省略的字段不放入 error 对象
+ *
+ * ```ts
+ * import type { FaapiConfig } from '@faapi/faapi';
+ * export default {
+ *   response: {
+ *     // 自定义成功包装(默认 { data })
+ *     ok: (data) => ({ code: 0, data }),
+ *     // 自定义错误包装(默认 { error: { message, ...code?, ...status? } })
+ *     fail: ({ status, code, message }) => ({ error: { code, message } }),
+ *   },
+ * } satisfies FaapiConfig;
+ * ```
+ */
+interface ResponseConfig {
+    /**
+     * 成功响应包装函数
+     *
+     * handler return 非 Response 的值时调用。
+     * 默认: (data) => ({ data })
+     */
+    ok?: (data: unknown) => unknown;
+    /**
+     * 错误响应包装函数
+     *
+     * ctx.fail() 调用时使用,接收 { status?, code?, message }。
+     * status 和 code 均可能为 undefined(用户调用 ctx.fail 时省略则不传),
+     * 默认实现只把非 undefined 的字段放入 error 对象。
+     */
+    fail?: (error: {
+        status?: number;
+        code?: string;
+        message: string;
+    }) => unknown;
+}
 /**
  * faapi 配置文件类型
  *
@@ -604,6 +708,29 @@ interface FaapiConfig {
     logger?: LoggerOptions | boolean;
     /** HTTP/2 配置，false 禁用（默认 http/1.1） */
     http2?: Http2Options | boolean;
+    /**
+     * 统一响应包装配置
+     *
+     * 配置后,框架自动包裹 handler 返回值:
+     * - 成功响应:handler return 非 Response → 用 ok 函数包裹(默认 `{ data }`)
+     * - 错误响应:ctx.fail() 用 fail 函数包装(默认 `{ error: { message, ...code? } }`)
+     *
+     * 未配置 response 时,使用框架默认实现(见 ResponseConfig)。
+     * 配置 response 后,ok/fail 各字段均可选,按需覆盖。
+     *
+     * ```ts
+     * import type { FaapiConfig } from '@faapi/faapi';
+     * export default {
+     *   response: {
+     *     ok: (data) => ({ code: 0, data }),
+     *     fail: ({ status, code, message }) => ({ error: { code, message } }),
+     *   },
+     * } satisfies FaapiConfig;
+     * ```
+     *
+     * 详见 `src/config/configTypes.md` 统一响应包装章节。
+     */
+    response?: ResponseConfig;
     /**
      * 全局中间件：对所有路由（HTTP + WebSocket 握手）生效
      *
@@ -1405,4 +1532,4 @@ type ProdApp = AppBase;
  */
 declare function createProdApp(options?: CreateAppOptions): Promise<ProdApp>;
 
-export { type ProdApp as App, type CorsOptions, type CreateAppOptions, type DevApp, type FaapiConfig, type FaapiContext, type FaapiContextConfig, FaapiError, type FaapiMiddleware, type FaapiPlugin, type HandlerTypeInfo, type HelmetOptions, type InjectOptions, type InjectResponse, type Injector, type InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LoggerOptions, MessageQueue, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type RouteInfo, type RouteInputSchema, type RouteManifest, RouteNotFoundError, type RouteOutputSchema, type RouteParamSchema, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type SseEvent, type SseWriter, type TestServer, type TestServerOptions, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, type WsTestClient, type WsTestClientOptions, collectRouteSchemaSources, connectWs, cors, createProdApp as createApp, createContext, createDevApp, createProdApp, createProgram, createTestServer, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, invokeHandler, loadConfig, loadEnv, logger, resolveTypeNode, waitForWsOpen };
+export { type ProdApp as App, type CorsOptions, type CreateAppOptions, type DevApp, type FaapiConfig, type FaapiContext, type FaapiContextConfig, FaapiError, type FaapiMiddleware, type FaapiPlugin, type FailOptions, type HandlerTypeInfo, type HelmetOptions, type InjectOptions, type InjectResponse, type Injector, type InjectorMap, InternalError, type LifecycleContext, type LifecycleHooks, type LoggerOptions, MessageQueue, MethodNotAllowedError, ModuleLoadError, type PluginContext, type PluginDeclaration, type ProdApp, type PropertyType, type RequestHandler, type ResponseConfig, type RouteInfo, type RouteInputSchema, type RouteManifest, RouteNotFoundError, type RouteOutputSchema, type RouteParamSchema, type RouteSchemaSource, type RuntimeType, SchemaExtractionError, type SseEvent, type SseWriter, type TestServer, type TestServerOptions, type TypeConstraint, type UpgradeHandler, ValidationError, type ValidationErrorCode, type ValidationIssue, type WsContext, type WsEventHandlers, type WsHandler, type WsSocket, type WsTestClient, type WsTestClientOptions, collectRouteSchemaSources, connectWs, cors, createProdApp as createApp, createContext, createDevApp, createProdApp, createProgram, createTestServer, extractTypeInfo, getInputTypeForMethod, helmet, invalidateProgramCache, invokeHandler, loadConfig, loadEnv, logger, resolveTypeNode, waitForWsOpen };

package/dist/index.js

@@ -1873,6 +1873,41 @@ function createContext(request, params, config = {}, ip = "") {
       ctxWithSse.__sseResponse = writer.response;
       ctxWithSse.__sseWriter = writer;
       return writer;
+    },
+    /**
+     * 显式包装成功响应(返回 Response,不会被自动包裹再次包装)
+     *
+     * 用 config.response.ok(或默认 (data) => ({ data })) 包裹 data 并返回 JSON Response。
+     * handler 也可直接 return data,框架会自动用 ok 包裹,两者等价。
+     */
+    ok(data) {
+      const responseConfig = config.response;
+      const okFn = responseConfig?.ok ?? ((d) => ({ data: d }));
+      const body = okFn(data);
+      return ctx.json(body);
+    },
+    /**
+     * 返回错误响应(对象形式参数,status 和 code 均可省略)
+     *
+     * - status 省略时 HTTP 状态码默认 500
+     * - code 省略时响应 body 里不含 code 字段(默认 fail 函数只放非 undefined 的字段)
+     * - status 和 code 独立无关联
+     *
+     * body 用 config.response.fail(或默认实现)包装。
+     */
+    fail(options) {
+      const responseConfig = config.response;
+      const failFn = responseConfig?.fail ?? ((e) => {
+        const error = { message: e.message };
+        if (e.code !== void 0) error.code = e.code;
+        return { error };
+      });
+      const body = failFn({
+        status: options.status,
+        code: options.code,
+        message: options.message
+      });
+      return ctx.json(body, options.status ?? 500);
     }
   };
   const extend = config?.extendContext;
@@ -2052,6 +2087,12 @@ async function injectParamsAsync(handler, ctx, body, injectors) {
 }
 
 // src/runtime/invokeHandler.ts
+function wrapResult(result, ctx) {
+  if (result instanceof Response) return result;
+  const responseConfig = ctx.config.response;
+  const okFn = responseConfig?.ok ?? ((d) => ({ data: d }));
+  return okFn(result);
+}
 function mergeMeta(response, meta) {
   const hasMeta = meta.status !== void 0 || Object.keys(meta.headers).length > 0 || meta.setCookies.length > 0;
   if (!hasMeta) return response;
@@ -2116,7 +2157,7 @@ async function invokeHandler(handler, ctx, body, middlewares, injectors) {
       const result = await injectParamsAsync(handler, ctx, body, injectors);
       const sseResponse = pickSseAndAutoClose();
       if (sseResponse) return sseResponse;
-      return toResponse(result, meta);
+      return toResponse(wrapResult(result, ctx), meta);
     } catch (err) {
       autoCloseSseOnError();
       throw err;
@@ -2127,7 +2168,7 @@ async function invokeHandler(handler, ctx, body, middlewares, injectors) {
       const result = await injectParamsAsync(handler, ctx, body, injectors);
       const sseResponse = pickSseAndAutoClose();
       if (sseResponse) return sseResponse;
-      return toResponse(result, meta);
+      return toResponse(wrapResult(result, ctx), meta);
     } catch (err) {
       autoCloseSseOnError();
       throw err;
@@ -3900,7 +3941,8 @@ var FAAPI_CONFIG_KEYS = /* @__PURE__ */ new Set([
   "helmet",
   "bodyLimit",
   "logger",
-  "http2"
+  "http2",
+  "response"
 ]);
 function isFaapiConfigKey(key) {
   return FAAPI_CONFIG_KEYS.has(key);
@@ -4006,41 +4048,40 @@ async function createAppBase(options) {
       } = injectOpts ?? {};
       const queryStr = query ? "?" + new URLSearchParams(Object.entries(query).map(([k, v]) => [k, String(v)])).toString() : "";
       return new Promise((resolve, reject) => {
-        const mockRes = {
-          statusCode: 200,
-          _headers: {},
-          _body: Buffer.alloc(0),
-          setHeader(name, value) {
-            this._headers[name.toLowerCase()] = value;
-          },
-          appendHeader(name, value) {
-            const key = name.toLowerCase();
-            const existing = this._headers[key];
-            this._headers[key] = existing ? `${existing}, ${value}` : value;
-          },
-          writeHead(status, headers) {
-            this.statusCode = status;
-            if (headers) {
-              Object.assign(this._headers, headers);
-            }
-          },
-          end(data) {
-            const buf = Buffer.isBuffer(data) ? data : Buffer.from(data ?? "");
-            this._body = buf;
-            resolve({
-              status: this.statusCode,
-              headers: new Headers(this._headers),
-              body: this.parseBody()
-            });
-          },
-          parseBody() {
-            try {
-              return JSON.parse(this._body.toString());
-            } catch {
-              return this._body.toString();
-            }
+        const chunks = [];
+        const mockRes = new PassThrough();
+        mockRes.statusCode = 200;
+        mockRes._headers = {};
+        mockRes.setHeader = function(name, value) {
+          this._headers[name.toLowerCase()] = value;
+        };
+        mockRes.appendHeader = function(name, value) {
+          const key = name.toLowerCase();
+          const existing = this._headers[key];
+          this._headers[key] = existing ? `${existing}, ${value}` : value;
+        };
+        mockRes.writeHead = function(status, headers) {
+          this.statusCode = status;
+          if (headers) {
+            Object.assign(this._headers, headers);
           }
         };
+        mockRes.on("data", (chunk) => chunks.push(chunk));
+        mockRes.on("error", reject);
+        mockRes.on("finish", () => {
+          const body2 = Buffer.concat(chunks);
+          let parsed;
+          try {
+            parsed = JSON.parse(body2.toString());
+          } catch {
+            parsed = body2.toString();
+          }
+          resolve({
+            status: mockRes.statusCode,
+            headers: new Headers(mockRes._headers),
+            body: parsed
+          });
+        });
         const listeners = server.listeners("request");
         const handler = listeners[listeners.length - 1];
         if (typeof handler !== "function") {