@lark-apaas/coding-template-nestjs-react-fullstack 0.1.45 → 0.1.47-alpha.20260923111704

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-template-nestjs-react-fullstack",
-  "version": "0.1.45",
+  "version": "0.1.47-alpha.20260923111704",
   "description": "NestJS + React fullstack template for miaoda coding",
   "type": "module",
   "files": [

package/template/client/src/api/error.ts

@@ -0,0 +1,84 @@
+import type { AxiosResponse } from 'axios';
+import type { ApiErrorResponse } from '@shared/api.interface';
+
+export interface ApiErrorOptions {
+  /** 当前操作失败时的安全 UI 提示，不能使用异常、details、stack 或 cause 拼接。 */
+  fallbackMessage: string;
+  /** 仅在已核实端点的旧响应文案是用户可见合同后，由调用方显式启用。 */
+  allowLegacyUserMessage?: boolean;
+}
+
+/** 失败始终作为异常传递；status 和原始响应 / rejected error 保存在 cause。 */
+export class ApiRequestError extends Error {
+  public readonly cause: unknown;
+
+  constructor(message: string, public readonly status: number | undefined, cause: unknown) {
+    super(message);
+    this.name = 'ApiRequestError';
+    this.cause = cause;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isResponse(value: unknown): value is { status: number; data: unknown; headers?: unknown } {
+  return isRecord(value) && typeof value.status === 'number' && Number.isFinite(value.status);
+}
+
+function normalizedMessage(value: unknown): string | undefined {
+  if (typeof value === 'string') return value.trim() || undefined;
+  if (!Array.isArray(value) || !value.every((item: unknown) => typeof item === 'string')) return undefined;
+  return value.map((item: string) => item.trim()).filter(Boolean).join('；') || undefined;
+}
+
+function contentTypeOf(headers: unknown): string | undefined {
+  if (!isRecord(headers)) return undefined;
+  const get = headers.get;
+  if (typeof get === 'function') {
+    const value = get.call(headers, 'content-type');
+    if (typeof value === 'string') return value;
+  }
+  const entry = Object.entries(headers).find(([name]) => name.toLowerCase() === 'content-type');
+  return typeof entry?.[1] === 'string' ? entry[1] : undefined;
+}
+
+function isJsonResponse(response: { headers?: unknown }): boolean {
+  const contentType = contentTypeOf(response.headers);
+  if (!contentType) return false;
+  const mediaType = contentType.split(';', 1)[0].trim();
+  return /^application\/(?:json|[a-z0-9!#$%&'*+.^_`|~-]+\+json)$/i.test(mediaType);
+}
+
+function userMessage(response: { status: number; data: unknown; headers?: unknown }, options: ApiErrorOptions): string | undefined {
+  if (response.status < 400 || response.status >= 500 || !isJsonResponse(response)) return undefined;
+  const data = response.data;
+  if (!isRecord(data)) return undefined;
+  if (isRecord(data.error)) {
+    if (data.error.userFacing === true) {
+      const message: ApiErrorResponse['error']['message'] | undefined =
+        typeof data.error.message === 'string' ? data.error.message : undefined;
+      return normalizedMessage(message);
+    }
+    if (data.error.userFacing === false) return undefined;
+  }
+  return options.allowLegacyUserMessage ? normalizedMessage(data.message) : undefined;
+}
+
+/** 兼容 axios reject 与当前 SDK 降级成 resolve 的非 2xx response；无网络响应则安全回退。 */
+export function toApiRequestError(error: unknown, options: ApiErrorOptions): ApiRequestError {
+  if (error instanceof ApiRequestError) return error;
+  const response = isRecord(error) && isResponse(error.response) ? error.response : isResponse(error) ? error : undefined;
+  return new ApiRequestError(
+    (response && userMessage(response, options)) || options.fallbackMessage,
+    response?.status,
+    error,
+  );
+}
+
+/** 只返回真正成功的 data；resolved 的 403 等非 2xx 必须抛出。SDK 的 401 登录拦截器仍先行执行。 */
+export function requireApiSuccess<T>(response: AxiosResponse<T>, options: ApiErrorOptions): T {
+  if (response.status >= 200 && response.status < 300) return response.data;
+  throw toApiRequestError(response, options);
+}

package/template/client/src/api/index.ts

@@ -1,19 +1,22 @@
-import { logger } from '@lark-apaas/client-toolkit/logger';
-import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBackend';
+export { ApiRequestError, requireApiSuccess, toApiRequestError } from './error';
 
-
-// Add more API functions here, use axios instance (`axiosForBackend`) to make requests.
-// 
-// 使用示例：
+// Add more API functions here. 先核对服务端路径 / method / 响应形状；不要把失败返回成成功数据。
+// 使用示例（此处只演示调用方式，按真实 Controller 替换接口）：
+// import { logger } from '@lark-apaas/client-toolkit/logger';
+// import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBackend';
+// import { requireApiSuccess, toApiRequestError } from './error';
 // export async function getUserData(userId: string) {
+//   const errorOptions = { fallbackMessage: '获取用户数据失败，请稍后重试' };
 //   try {
-//     const response = await axiosForBackend({
-//       url: `/api/users/${userId}`,
-//       method: 'GET'
-//     });
-//     return response.data;
+//     const response = await axiosForBackend({ url: `/api/users/${userId}`, method: 'GET' });
+//     return requireApiSuccess(response, errorOptions); // resolved 403 等非 2xx 也会抛错
 //   } catch (error) {
+//     const apiError = toApiRequestError(error, errorOptions); // rejected 4xx / 网络错误
 //     logger.error('获取用户数据失败', error);
-//     throw error;
+//     throw apiError; // 页面 catch 可展示 apiError.message，状态和原始错误在 status / cause
 //   }
 // }
+
+// 有已核实的旧端点将顶层 message:string|string[] 定义为用户文案时，才显式传
+// { fallbackMessage: '操作失败，请稍后重试', allowLegacyUserMessage: true }；默认只认 error.userFacing: true。
+// 401 登录跳转由 axiosForBackend 自带拦截器负责，不在此处自行模拟登录。

package/template/package-lock.json

@@ -34,7 +34,7 @@
         "@hookform/resolvers": "^5.2.2",
         "@lark-apaas/client-toolkit": "^1.2.72",
         "@lark-apaas/coding-preset-vite-react": "^1.0.25",
-        "@lark-apaas/fullstack-presets": "^1.1.24",
+        "@lark-apaas/fullstack-presets": "^1.1.25",
         "@nestjs/cli": "^10.4.9",
         "@radix-ui/react-accordion": "^1.2.12",
         "@radix-ui/react-alert-dialog": "^1.1.15",
@@ -1735,9 +1735,9 @@
       }
     },
     "node_modules/@lark-apaas/fullstack-presets": {
-      "version": "1.1.24",
-      "resolved": "https://registry.npmmirror.com/@lark-apaas/fullstack-presets/-/fullstack-presets-1.1.24.tgz",
-      "integrity": "sha512-Iq1Xsv65qAI555d7eJ+0PcuVUgmNnAjjBDNuHOmocFpqeXfpbNqgVN7cE6mZchjsSRtML762QFQLKxw9NyMsxw==",
+      "version": "1.1.25",
+      "resolved": "https://registry.npmmirror.com/@lark-apaas/fullstack-presets/-/fullstack-presets-1.1.25.tgz",
+      "integrity": "sha512-NeS9AHBbk7FMlFjrB5QP4OWHWazO3vXLtoPxLiY25U0oUsl+TUZQI7p+Bud+bCDd/ZUUzvzLnf8jQbBt8np+Kg==",
       "dev": true,
       "license": "MIT",
       "dependencies": {

package/template/package.json

@@ -54,7 +54,7 @@
     "@hookform/resolvers": "^5.2.2",
     "@lark-apaas/client-toolkit": "^1.2.72",
     "@lark-apaas/coding-preset-vite-react": "^1.0.25",
-    "@lark-apaas/fullstack-presets": "^1.1.24",
+    "@lark-apaas/fullstack-presets": "^1.1.25",
     "@nestjs/cli": "^10.4.9",
     "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-alert-dialog": "^1.1.15",

package/template/server/common/filters/error-response.ts

@@ -0,0 +1,92 @@
+import { HttpException, HttpStatus } from '@nestjs/common';
+import type { ApiErrorResponse } from '../interfaces/api_response.interface';
+import { HTTP_STATUS_TO_RESPONSE_CODE_MAP, ResponseCode } from '../constants/api_response_code';
+import { BusinessException } from '../interfaces/exception.interface';
+
+/** 状态对应的固定安全文案，不读取任意异常的 message / response / cause。 */
+function safeStatusMessage(status: number): string {
+  switch (status) {
+    case HttpStatus.BAD_REQUEST:
+    case HttpStatus.UNPROCESSABLE_ENTITY:
+      return '请求参数有误';
+    case HttpStatus.UNAUTHORIZED:
+      return '请先登录';
+    case HttpStatus.FORBIDDEN:
+      return '无操作权限';
+    case HttpStatus.NOT_FOUND:
+      return '资源不存在';
+    case HttpStatus.CONFLICT:
+      return '请求冲突';
+    case HttpStatus.TOO_MANY_REQUESTS:
+      return '请求过于频繁';
+    default:
+      return status >= 500 ? '服务暂不可用' : '请求失败';
+  }
+}
+
+export function createErrorResponse(exception: unknown): {
+  httpStatus: number;
+  body: ApiErrorResponse;
+} {
+  const timestamp = Date.now();
+  if (exception instanceof BusinessException) {
+    const httpStatus = exception.httpStatus;
+    return {
+      httpStatus,
+      body: {
+        error: {
+          code: exception.code,
+          message: exception.message.trim() || safeStatusMessage(httpStatus),
+          userFacing: true,
+          details: exception.details,
+          fieldErrors: exception.fieldErrors,
+          timestamp,
+        },
+      },
+    };
+  }
+  if (exception instanceof HttpException) {
+    const httpStatus = exception.getStatus();
+    return {
+      httpStatus,
+      body: {
+        error: {
+          code:
+            HTTP_STATUS_TO_RESPONSE_CODE_MAP[httpStatus] ??
+            (httpStatus >= 500 ? ResponseCode.INTERNAL_ERROR : ResponseCode.BAD_REQUEST),
+          message: safeStatusMessage(httpStatus),
+          userFacing: false,
+          timestamp,
+        },
+      },
+    };
+  }
+  if (typeof exception === 'object' && exception !== null && 'code' in exception && exception.code === '22P02') {
+    // 非法 UUID 保留原来的 not-found 语义，但不是用户可见的业务文案。
+    return {
+      httpStatus: HttpStatus.NOT_FOUND,
+      body: {
+        error: {
+          code: ResponseCode.NOT_FOUND,
+          message: safeStatusMessage(HttpStatus.NOT_FOUND),
+          userFacing: false,
+          timestamp,
+        },
+      },
+    };
+  }
+  return {
+    httpStatus: HttpStatus.INTERNAL_SERVER_ERROR,
+    body: {
+      error: {
+        code: ResponseCode.INTERNAL_ERROR,
+        message: safeStatusMessage(HttpStatus.INTERNAL_SERVER_ERROR),
+        userFacing: false,
+        ...(process.env.NODE_ENV === 'development' && exception instanceof Error
+          ? { stack: exception.stack, cause: typeof exception.cause === 'string' ? exception.cause : undefined }
+          : {}),
+        timestamp,
+      },
+    },
+  };
+}

package/template/server/common/filters/exception.filter.ts

@@ -1,78 +1,15 @@
-import { ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';
+import { ExceptionFilter, Catch, ArgumentsHost } from '@nestjs/common';
 import type { Response } from 'express';
-import { BusinessException } from '../interfaces/exception.interface';
-import { HTTP_STATUS_TO_RESPONSE_CODE_MAP, ResponseCode } from '../constants/api_response_code';
-import { ApiErrorResponse } from '../interfaces/api_response.interface';
+import { createErrorResponse } from './error-response';
 
 // 全局异常过滤器，用于捕获所有未处理的异常
 @Catch()
 export class GlobalExceptionFilter implements ExceptionFilter {
   catch(exception: unknown, host: ArgumentsHost) {
-    const ctx = host.switchToHttp();
-    const response = ctx.getResponse<Response>();
-     
-    // 如果响应头已发送，则不处理
-    if (response.headersSent) {
-      return;
-    }
+    const response = host.switchToHttp().getResponse<Response>();
+    if (response.headersSent) return;
 
-    let errorResponse: Omit<ApiErrorResponse, 'httpStatus'>;
-    let httpStatus: HttpStatus;
-
-    if (exception instanceof BusinessException) {
-      // 业务异常
-      httpStatus = exception.httpStatus;
-      errorResponse = {
-        error: {
-          code: exception.code,
-          message: exception.message,
-          details: exception.details,
-          fieldErrors: exception.fieldErrors,
-          timestamp: Date.now(),
-        },
-      };
-    } else if (exception instanceof HttpException) {
-      // HTTP异常
-      httpStatus = exception.getStatus() as HttpStatus;
-      const exceptionResponse = exception.getResponse();
-
-      errorResponse = {
-        error: {
-          code: HTTP_STATUS_TO_RESPONSE_CODE_MAP[httpStatus],
-          message: typeof exceptionResponse === 'string' ? exceptionResponse : exception.message,
-          details: typeof exceptionResponse === 'object' ? JSON.stringify(exceptionResponse) : undefined,
-          timestamp: Date.now(),
-        },
-      };
-    } else if (
-      typeof exception === 'object' &&
-      exception !== null &&
-      (exception as { code?: unknown }).code === '22P02'
-    ) {
-      // Postgres invalid_text_representation：路径/查询参数与列类型不匹配（最常见是非法 UUID）
-      // 与「合法 UUID 但记录不存在」走同一条 not-found 语义，避免 500 噪声
-      httpStatus = HttpStatus.NOT_FOUND;
-      errorResponse = {
-        error: {
-          code: ResponseCode.NOT_FOUND,
-          message: '资源不存在',
-          timestamp: Date.now(),
-        },
-      };
-    } else {
-      // 未知异常
-      httpStatus = HttpStatus.INTERNAL_SERVER_ERROR;
-      errorResponse = {
-        error: {
-          code: ResponseCode.INTERNAL_ERROR,
-          message: '服务器内部错误',
-          stack: (exception as Error).stack,
-          cause: (exception as Error).cause as string,
-          timestamp: Date.now(),
-        },
-      };
-    }
-
-    response.status(httpStatus).json(errorResponse);
+    const { httpStatus, body } = createErrorResponse(exception);
+    response.status(httpStatus).json(body);
   }
 }

package/template/server/common/interfaces/api_response.interface.ts

@@ -1,21 +1,2 @@
-// 错误统一响应
-export interface ApiErrorResponse {
-  /** 错误详情 */
-  error: {
-    /** 错误代码 */
-    code: string;
-    /** 错误消息 */
-    message: string;
-    /** 错误详情 */
-    details?: string;
-    /** 字段验证错误 */
-    fieldErrors?: Record<string, string[]>;
-    /** 调用栈（仅开发环境） */
-    stack?: string;
-    /** 错误原因 */
-    cause?: string;
-    /** 错误发生时间 */
-    timestamp?: number;
-  };
-}
-
+// 旧的服务端导入路径保持可用；实际合同由 shared 统一维护。
+export type { ApiErrorResponse } from '../../../shared/api.interface';

package/template/server/common/interfaces/exception.interface.ts

@@ -1,6 +1,6 @@
 // 业务异常类
 import { HttpStatus } from '@nestjs/common';
-import { RESPONSE_CODE_TO_HTTP_STATUS_MAP, ResponseCode } from '../constants/api_response_code';
+import { ResponseCode } from '../constants/api_response_code';
 
 export class BusinessException extends Error {
   constructor(
@@ -14,6 +14,6 @@ export class BusinessException extends Error {
     this.name = 'BusinessException';
   }
   getHttpStatus(): HttpStatus {
-    return RESPONSE_CODE_TO_HTTP_STATUS_MAP[this.code];
+    return this.httpStatus;
   }
 }

package/template/shared/api.interface.ts

@@ -1 +1,16 @@
-/* 前后端共享的类型写在这里 */
+/** 全栈模板的错误响应合同；成功响应仍由业务接口各自定义。 */
+export interface ApiErrorResponse {
+  error: {
+    code: string;
+    /** 仅 userFacing 为 true 时可作为 UI 文案；其他情况由调用方提供安全提示。 */
+    message: string;
+    /** 只由本模板 Filter 为受控 BusinessException 设为 true。 */
+    userFacing: boolean;
+    /** 以下字段仅用于诊断，绝不能拼接到 UI 文案。 */
+    details?: string;
+    fieldErrors?: Record<string, string[]>;
+    stack?: string;
+    cause?: string;
+    timestamp?: number;
+  };
+}