@faapi/next 6.13.0 → 6.15.0

package/README.md

@@ -67,6 +67,36 @@ node dist/main
 | `/api/chat`（faapi WS 路由） | faapi WebSocket handler |
 | `/_next/webpack-hmr` | Next.js HMR |
 
+## 浏览器端请求层（`@faapi/next/client`）
+
+客户端组件（`'use client'`）的 API 请求统一走 `apiCall`，它封装了 fetch + faapi 信封（`{ data }` / `{ error }`）解包，失败一律抛结构化 `ApiError`（携带 `code` / `status` / `message`，`VALIDATION_ERROR` 时附 `issues`）：
+
+```tsx
+'use client';
+import { apiCall, ApiError } from '@faapi/next/client';
+
+async function submit() {
+  try {
+    const user = await apiCall<{ id: number }>('/api/user', { method: 'POST' });
+    toast.success('已保存');
+  } catch (e) {
+    toast.error(e instanceof Error ? e.message : String(e)); // message 恒为可读文案
+  }
+}
+```
+
+### 为什么需要 apiCall
+
+`/api/*` 的错误响应恒为 JSON 信封，但链路其他层会返回 HTML（反代/网关错误页、Next.js 404 页、SSO 登录守卫的 302 重定向）。直接 `res.json()` 会把裸 `Unexpected token '<'` SyntaxError 原文抛上界面。`apiCall` 把这些异常响应转译为可行动的中文提示（502/503 → 服务暂时不可用、504 → 服务响应超时、401 → 登录已过期、登录页重定向 → 登录状态已失效），排障现场（状态码 / URL / body 前 200 字符）留在 `console.error`。`statusMessage` 一并导出，可 fork 自定义文案。
+
+### ⚠️ 必须用 `@faapi/next/client` 子路径导入
+
+主入口 `@faapi/next` 是**服务端插件**（依赖 `@faapi/faapi` 与 next 服务端模块）。客户端组件若误用主入口，会把 `node:fs` / `node:child_process` 等服务端代码拉进浏览器 bundle，导致 Next.js build 失败。客户端代码只从 `@faapi/next/client` 导入；`./client` 入口零 Node 依赖，可安全进入客户端 bundle。
+
+### 已知限制
+
+`apiCall` 按主包 `config.response` 的**默认信封**解包。若你在 `faapi.config.ts` 自定义了 `response.ok` / `response.fail`，请自行包装 apiCall（替换解包段），不要两处各改各的。
+
 ## 许可证
 
 [MIT](https://github.com/faapi/faapi/blob/main/LICENSE)

package/dist/client/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 客户端统一错误类型与响应信封类型。
+ *
+ * 零依赖约束:本模块属于浏览器端代码(@faapi/next/client 子路径),禁止
+ * import @faapi/faapi 及任何 Node 模块——主包含 fs/child_process 等服务端
+ * 依赖,传递性引入会把服务端代码拉进浏览器 bundle,导致 Next.js 客户端
+ * 打包失败。类型独立声明、结构镜像主包,详见 apiError.md。
+ */
+/**
+ * 字段级校验详情,镜像主包 ValidationIssue(path/code/expected/received/message)。
+ *
+ * 服务端 JSON 的形状即客户端类型;主包结构变更时此处需手动同步。
+ */
+interface ApiValidationIssue {
+    /** 字段路径,如 'user.address.city' */
+    path: string;
+    /** 错误码,机器可读的契约,如 'TYPE_MISMATCH' */
+    code: string;
+    /** 期望类型/值,如 'number' */
+    expected: string;
+    /** 实际类型/值,如 'string' */
+    received: string;
+    /** 人类可读的字段级错误描述 */
+    message: string;
+}
+/** 失败信封:{ error: { message, ...code?, ...issues? } }(主包 defaultFail 中 code 省略时不存在) */
+interface ApiErrorBody {
+    error: {
+        code?: string;
+        message: string;
+        issues?: ApiValidationIssue[];
+    };
+}
+/**
+ * faapi 默认响应信封:成功 { data } / 失败 { error }。
+ * 与主包 config.response.ok/fail 的默认实现一致;业务方自定义信封时
+ * 不适用(见 apiCall.md 已知限制)。
+ */
+type ApiEnvelope<T> = Partial<{
+    data: T;
+}> & Partial<ApiErrorBody>;
+/**
+ * API 错误:携带 code/status/issues,调用方可按 code 分支处理。
+ *
+ * 继承 Error,现有 `e instanceof Error ? e.message : String(e)` 的
+ * toast 消费代码不受影响。
+ */
+declare class ApiError extends Error {
+    /** 字符串业务错误码,如 'VALIDATION_ERROR';非信封错误为框架侧兜底码 */
+    readonly code: string;
+    /** HTTP 状态码 */
+    readonly status: number;
+    /** VALIDATION_ERROR 时的字段级校验详情,供表单回显 */
+    readonly issues?: readonly ApiValidationIssue[];
+    constructor(code: string, status: number, message: string, issues?: readonly ApiValidationIssue[]);
+}
+
+/**
+ * 非 JSON 响应(反代错误页/空 body)按状态映射的可行动中文文案。
+ *
+ * 导出供业务方 fork 自定义文案(如英文产品)时组合使用。
+ */
+declare function statusMessage(status: number): string;
+/**
+ * 发起 API 请求并解包 faapi 默认信封,失败一律抛 ApiError。
+ *
+ * 成功返回 body.data;非 JSON/信封错误/空响应转译为结构化错误,
+ * 现场经 console.error 保留(status/url/body 前 200 字符)。
+ * 仅支持主包 config.response 默认信封,自定义信封时业务方自行包装。
+ */
+declare function apiCall<T>(input: string, init?: RequestInit): Promise<T>;
+
+export { type ApiEnvelope, ApiError, type ApiValidationIssue, apiCall, statusMessage };

package/dist/client/index.js

@@ -0,0 +1,60 @@
+// src/client/apiError.ts
+var ApiError = class extends Error {
+  /** 字符串业务错误码,如 'VALIDATION_ERROR';非信封错误为框架侧兜底码 */
+  code;
+  /** HTTP 状态码 */
+  status;
+  /** VALIDATION_ERROR 时的字段级校验详情,供表单回显 */
+  issues;
+  constructor(code, status, message, issues) {
+    super(message);
+    this.name = "ApiError";
+    this.code = code;
+    this.status = status;
+    this.issues = issues;
+  }
+};
+
+// src/client/apiCall.ts
+function statusMessage(status) {
+  if (status === 504) return "\u670D\u52A1\u54CD\u5E94\u8D85\u65F6,\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+  if (status === 502 || status === 503) return "\u670D\u52A1\u6682\u65F6\u4E0D\u53EF\u7528,\u8BF7\u7A0D\u540E\u91CD\u8BD5";
+  if (status === 401) return "\u767B\u5F55\u5DF2\u8FC7\u671F,\u8BF7\u5237\u65B0\u9875\u9762\u91CD\u65B0\u767B\u5F55";
+  return `\u8BF7\u6C42\u5931\u8D25: ${status}`;
+}
+async function apiCall(input, init) {
+  const res = await fetch(input, init);
+  const text = await res.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    console.error("[apiCall] \u975E JSON \u54CD\u5E94", {
+      status: res.status,
+      url: res.url,
+      body: text.slice(0, 200)
+    });
+    if (res.redirected) {
+      throw new ApiError("REDIRECTED", res.status, "\u767B\u5F55\u72B6\u6001\u5DF2\u5931\u6548\uFF0C\u8BF7\u5237\u65B0\u9875\u9762\u91CD\u65B0\u767B\u5F55");
+    }
+    throw new ApiError("NON_JSON_RESPONSE", res.status, statusMessage(res.status));
+  }
+  if (!res.ok || body.error) {
+    throw new ApiError(
+      body.error?.code ?? "HTTP_ERROR",
+      res.status,
+      body.error?.message || statusMessage(res.status),
+      body.error?.issues
+    );
+  }
+  if (body.data === void 0) {
+    throw new ApiError("EMPTY_RESPONSE", res.status, `\u8BF7\u6C42\u5931\u8D25: ${res.status}`);
+  }
+  return body.data;
+}
+export {
+  ApiError,
+  apiCall,
+  statusMessage
+};
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/client/apiError.ts","../../src/client/apiCall.ts"],"sourcesContent":["/**\n * 客户端统一错误类型与响应信封类型。\n *\n * 零依赖约束:本模块属于浏览器端代码(@faapi/next/client 子路径),禁止\n * import @faapi/faapi 及任何 Node 模块——主包含 fs/child_process 等服务端\n * 依赖,传递性引入会把服务端代码拉进浏览器 bundle,导致 Next.js 客户端\n * 打包失败。类型独立声明、结构镜像主包,详见 apiError.md。\n */\n\n/**\n * 字段级校验详情,镜像主包 ValidationIssue(path/code/expected/received/message)。\n *\n * 服务端 JSON 的形状即客户端类型;主包结构变更时此处需手动同步。\n */\nexport interface ApiValidationIssue {\n  /** 字段路径,如 'user.address.city' */\n  path: string;\n  /** 错误码,机器可读的契约,如 'TYPE_MISMATCH' */\n  code: string;\n  /** 期望类型/值,如 'number' */\n  expected: string;\n  /** 实际类型/值,如 'string' */\n  received: string;\n  /** 人类可读的字段级错误描述 */\n  message: string;\n}\n\n/** 失败信封:{ error: { message, ...code?, ...issues? } }(主包 defaultFail 中 code 省略时不存在) */\nexport interface ApiErrorBody {\n  error: {\n    code?: string;\n    message: string;\n    issues?: ApiValidationIssue[];\n  };\n}\n\n/**\n * faapi 默认响应信封:成功 { data } / 失败 { error }。\n * 与主包 config.response.ok/fail 的默认实现一致;业务方自定义信封时\n * 不适用(见 apiCall.md 已知限制)。\n */\nexport type ApiEnvelope<T> = Partial<{ data: T }> & Partial<ApiErrorBody>;\n\n/**\n * API 错误:携带 code/status/issues,调用方可按 code 分支处理。\n *\n * 继承 Error,现有 `e instanceof Error ? e.message : String(e)` 的\n * toast 消费代码不受影响。\n */\nexport class ApiError extends Error {\n  /** 字符串业务错误码,如 'VALIDATION_ERROR';非信封错误为框架侧兜底码 */\n  readonly code: string;\n  /** HTTP 状态码 */\n  readonly status: number;\n  /** VALIDATION_ERROR 时的字段级校验详情,供表单回显 */\n  readonly issues?: readonly ApiValidationIssue[];\n\n  constructor(\n    code: string,\n    status: number,\n    message: string,\n    issues?: readonly ApiValidationIssue[],\n  ) {\n    super(message);\n    this.name = 'ApiError';\n    this.code = code;\n    this.status = status;\n    this.issues = issues;\n  }\n}\n","/**\n * 浏览器端统一请求入口:fetch 封装 + 非 JSON 响应守卫 + faapi 信封解包。\n *\n * 守卫动机:/api/* 的错误响应恒为 JSON 信封,但链路其他层会返回 HTML——\n * 反代/网关错误页(502/504)、Next.js 404 页、SSO 登录守卫 302(fetch 跟随\n * 重定向拿到登录页)。直接 res.json() 会把裸 SyntaxError 原文抛进界面;\n * 这里检测 + 转译为结构化 ApiError,现场留在 console。行为规格见 apiCall.md。\n */\nimport { ApiError, type ApiEnvelope } from './apiError';\n\n/**\n * 非 JSON 响应(反代错误页/空 body)按状态映射的可行动中文文案。\n *\n * 导出供业务方 fork 自定义文案(如英文产品)时组合使用。\n */\nexport function statusMessage(status: number): string {\n  if (status === 504) return '服务响应超时,请稍后重试';\n  if (status === 502 || status === 503) return '服务暂时不可用,请稍后重试';\n  if (status === 401) return '登录已过期,请刷新页面重新登录';\n  return `请求失败: ${status}`;\n}\n\n/**\n * 发起 API 请求并解包 faapi 默认信封,失败一律抛 ApiError。\n *\n * 成功返回 body.data;非 JSON/信封错误/空响应转译为结构化错误,\n * 现场经 console.error 保留(status/url/body 前 200 字符)。\n * 仅支持主包 config.response 默认信封,自定义信封时业务方自行包装。\n */\nexport async function apiCall<T>(input: string, init?: RequestInit): Promise<T> {\n  const res = await fetch(input, init);\n  const text = await res.text();\n\n  let body: ApiEnvelope<T>;\n  try {\n    body = JSON.parse(text) as ApiEnvelope<T>;\n  } catch {\n    // 非 JSON 响应:现场留给排障,错误转译为可行动的文案。\n    console.error('[apiCall] 非 JSON 响应', {\n      status: res.status,\n      url: res.url,\n      body: text.slice(0, 200),\n    });\n    if (res.redirected) {\n      // fetch 跟随重定向后拿到非 JSON(典型:SSO 登录守卫 302 → 登录页)\n      throw new ApiError('REDIRECTED', res.status, '登录状态已失效，请刷新页面重新登录');\n    }\n    throw new ApiError('NON_JSON_RESPONSE', res.status, statusMessage(res.status));\n  }\n\n  if (!res.ok || body.error) {\n    throw new ApiError(\n      body.error?.code ?? 'HTTP_ERROR',\n      res.status,\n      body.error?.message || statusMessage(res.status),\n      body.error?.issues,\n    );\n  }\n\n  if (body.data === undefined) {\n    // {data: null} 合法返回 null;无 data 字段({})视为空响应错误\n    throw new ApiError('EMPTY_RESPONSE', res.status, `请求失败: ${res.status}`);\n  }\n\n  return body.data;\n}\n"],"mappings":";AAiDO,IAAM,WAAN,cAAuB,MAAM;AAAA;AAAA,EAEzB;AAAA;AAAA,EAEA;AAAA;AAAA,EAEA;AAAA,EAET,YACE,MACA,QACA,SACA,QACA;AACA,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AACZ,SAAK,SAAS;AACd,SAAK,SAAS;AAAA,EAChB;AACF;;;ACtDO,SAAS,cAAc,QAAwB;AACpD,MAAI,WAAW,IAAK,QAAO;AAC3B,MAAI,WAAW,OAAO,WAAW,IAAK,QAAO;AAC7C,MAAI,WAAW,IAAK,QAAO;AAC3B,SAAO,6BAAS,MAAM;AACxB;AASA,eAAsB,QAAW,OAAe,MAAgC;AAC9E,QAAM,MAAM,MAAM,MAAM,OAAO,IAAI;AACnC,QAAM,OAAO,MAAM,IAAI,KAAK;AAE5B,MAAI;AACJ,MAAI;AACF,WAAO,KAAK,MAAM,IAAI;AAAA,EACxB,QAAQ;AAEN,YAAQ,MAAM,sCAAuB;AAAA,MACnC,QAAQ,IAAI;AAAA,MACZ,KAAK,IAAI;AAAA,MACT,MAAM,KAAK,MAAM,GAAG,GAAG;AAAA,IACzB,CAAC;AACD,QAAI,IAAI,YAAY;AAElB,YAAM,IAAI,SAAS,cAAc,IAAI,QAAQ,wGAAmB;AAAA,IAClE;AACA,UAAM,IAAI,SAAS,qBAAqB,IAAI,QAAQ,cAAc,IAAI,MAAM,CAAC;AAAA,EAC/E;AAEA,MAAI,CAAC,IAAI,MAAM,KAAK,OAAO;AACzB,UAAM,IAAI;AAAA,MACR,KAAK,OAAO,QAAQ;AAAA,MACpB,IAAI;AAAA,MACJ,KAAK,OAAO,WAAW,cAAc,IAAI,MAAM;AAAA,MAC/C,KAAK,OAAO;AAAA,IACd;AAAA,EACF;AAEA,MAAI,KAAK,SAAS,QAAW;AAE3B,UAAM,IAAI,SAAS,kBAAkB,IAAI,QAAQ,6BAAS,IAAI,MAAM,EAAE;AAAA,EACxE;AAEA,SAAO,KAAK;AACd;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faapi/next",
-  "version": "6.13.0",
+  "version": "6.15.0",
   "description": "Next.js integration for faapi — serve faapi APIs and Next.js pages from a single server",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
     }
   },
   "files": [
@@ -31,11 +35,11 @@
     "vitest": "^4.1.11",
     "ws": "^8.21.0",
     "zod": "^4.4.3",
-    "@faapi/faapi": "6.13.0"
+    "@faapi/faapi": "6.15.0"
   },
   "peerDependencies": {
     "next": ">=13.0.0",
-    "@faapi/faapi": "^6.13.0"
+    "@faapi/faapi": "^6.15.0"
   },
   "peerDependenciesMeta": {
     "next": {