@lark-apaas/coding-template-nestjs-react-fullstack 0.1.0-alpha.1

package/template/scripts/lint.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const fs = require('node:fs');
+
+const cwd = process.cwd();
+
+function getBinName(name) {
+  return process.platform === 'win32' ? `${name}.cmd` : name;
+}
+
+function runCommand(command, args) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd,
+      stdio: 'inherit',
+      shell: false,
+    });
+
+    child.on('close', (code) => resolve(code || 0));
+    child.on('error', () => resolve(1));
+  });
+}
+
+function normalizeProjectFile(filePath) {
+  const absolutePath = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(cwd, filePath);
+
+  if (!fs.existsSync(absolutePath)) {
+    console.warn(`[lint] Skip missing file: ${filePath}`);
+    return null;
+  }
+
+  const relativePath = path.relative(cwd, absolutePath);
+  if (relativePath.startsWith('..')) {
+    console.warn(`[lint] Skip file outside project: ${filePath}`);
+    return null;
+  }
+
+  return relativePath.split(path.sep).join('/');
+}
+
+function parseFilesArg(argv) {
+  const filesIndex = argv.indexOf('--files');
+  if (filesIndex === -1) {
+    return null;
+  }
+
+  return argv.slice(filesIndex + 1).filter(Boolean);
+}
+
+function isEslintTarget(filePath) {
+  return /\.(c|m)?(j|t)sx?$/.test(filePath);
+}
+
+function isTypeCheckTarget(filePath) {
+  return /\.(ts|tsx|mts|cts)$/.test(filePath);
+}
+
+function isStylelintTarget(filePath) {
+  return filePath.endsWith('.css');
+}
+
+async function runDefaultLint() {
+  const code = await runCommand(getBinName('npx'), [
+    'concurrently',
+    'npm run eslint',
+    'npm run type:check',
+    'npm run stylelint',
+  ]);
+  process.exit(code);
+}
+
+async function runSelectiveLint(inputFiles) {
+  const normalizedFiles = Array.from(
+    new Set(inputFiles.map(normalizeProjectFile).filter(Boolean)),
+  );
+
+  if (normalizedFiles.length === 0) {
+    console.log('[lint] No supported project files found');
+    process.exit(0);
+  }
+
+  const eslintFiles = normalizedFiles.filter(isEslintTarget);
+  const stylelintFiles = normalizedFiles.filter(isStylelintTarget);
+  const typeCheckFiles = normalizedFiles.filter(isTypeCheckTarget);
+
+  const clientTypeFiles = [];
+  const serverTypeFiles = [];
+
+  for (const filePath of typeCheckFiles) {
+    if (filePath.startsWith('client/')) {
+      clientTypeFiles.push(filePath);
+    } else if (filePath.startsWith('server/')) {
+      serverTypeFiles.push(filePath);
+    } else if (filePath.startsWith('shared/')) {
+      clientTypeFiles.push(filePath);
+      serverTypeFiles.push(filePath);
+    }
+  }
+
+  const tasks = [];
+
+  if (eslintFiles.length > 0) {
+    tasks.push(runCommand(getBinName('npx'), ['eslint', '--quiet', ...eslintFiles]));
+  }
+
+  if (stylelintFiles.length > 0) {
+    tasks.push(runCommand(getBinName('npx'), ['stylelint', '--quiet', ...stylelintFiles]));
+  }
+
+  if (clientTypeFiles.length > 0) {
+    tasks.push(runCommand(getBinName('npm'), ['run', 'type:check:client']));
+  }
+
+  if (serverTypeFiles.length > 0) {
+    tasks.push(runCommand(getBinName('npm'), ['run', 'type:check:server']));
+  }
+
+  if (tasks.length === 0) {
+    console.log('[lint] No supported files matched for lint');
+    process.exit(0);
+  }
+
+  const results = await Promise.all(tasks);
+  process.exit(results.some(code => code !== 0) ? 1 : 0);
+}
+
+async function main() {
+  const files = parseFilesArg(process.argv.slice(2));
+  if (files === null) {
+    await runDefaultLint();
+    return;
+  }
+
+  if (files.length === 0) {
+    console.error('[lint] --files requires at least one file path');
+    process.exit(1);
+  }
+
+  await runSelectiveLint(files);
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[lint] Failed to run lint: ${message}`);
+  process.exit(1);
+});

package/template/scripts/prune-smart.js

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+// This file is auto-generated by @lark-apaas/fullstack-cli
+
+const { nodeFileTrace } = require('@vercel/nft');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.resolve(__dirname, '..');
+const DIST_SERVER_DIR = path.join(ROOT_DIR, 'dist/server');
+const ROOT_PACKAGE_JSON = path.join(ROOT_DIR, 'package.json');
+const ROOT_NODE_MODULES = path.join(ROOT_DIR, 'node_modules');
+const OUT_NODE_MODULES = path.join(DIST_SERVER_DIR, 'node_modules');
+const OUT_PACKAGE_JSON = path.join(DIST_SERVER_DIR, 'package.json');
+
+// Server 入口文件
+const SERVER_ENTRY = path.join(DIST_SERVER_DIR, 'main.js');
+
+// Node.js 内置模块列表
+const BUILTIN_MODULES = new Set([
+  'assert', 'buffer', 'child_process', 'cluster', 'crypto', 'dgram', 'dns',
+  'events', 'fs', 'http', 'http2', 'https', 'net', 'os', 'path', 'stream',
+  'string_decoder', 'timers', 'tls', 'url', 'util', 'v8', 'vm', 'zlib',
+  'async_hooks', 'perf_hooks', 'worker_threads', 'inspector', 'trace_events'
+]);
+
+/**
+ * 从完整路径中提取 npm 包名（优化版）
+ */
+const nodeModulesSep = 'node_modules' + path.sep;
+function extractPackageName(filePath) {
+  const idx = filePath.lastIndexOf(nodeModulesSep);
+  if (idx === -1) return null;
+
+  const afterNodeModules = filePath.slice(idx + nodeModulesSep.length);
+  const slashIdx = afterNodeModules.indexOf(path.sep);
+
+  // 处理 scoped package (@xxx/yyy)
+  if (afterNodeModules[0] === '@') {
+    const secondSlash = afterNodeModules.indexOf(path.sep, slashIdx + 1);
+    return secondSlash === -1
+      ? afterNodeModules
+      : afterNodeModules.slice(0, secondSlash);
+  }
+
+  return slashIdx === -1 ? afterNodeModules : afterNodeModules.slice(0, slashIdx);
+}
+
+/**
+ * 递归删除目录
+ */
+function removeDir(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * 递归复制目录（优化版：优先使用硬链接）
+ */
+function copyDir(src, dest, stats = { hardLinks: 0, copies: 0 }) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, stats);
+    } else {
+      try {
+        // 优先使用硬链接（CI 环境中安全，速度快，节省空间）
+        fs.linkSync(srcPath, destPath);
+        stats.hardLinks++;
+      } catch {
+        // 硬链接失败时回退到复制（如跨文件系统）
+        fs.copyFileSync(srcPath, destPath);
+        stats.copies++;
+      }
+    }
+  }
+
+  return stats;
+}
+
+/**
+ * 选择性复制包
+ */
+function copyPackagesSelectively(packages, rootNodeModules, outNodeModules) {
+  const copiedCount = { success: 0, failed: 0 };
+  const fileStats = { hardLinks: 0, copies: 0 };
+
+  // 确保输出目录存在
+  if (fs.existsSync(outNodeModules)) {
+    removeDir(outNodeModules);
+  }
+  fs.mkdirSync(outNodeModules, { recursive: true });
+
+  // 复制每个包
+  for (const pkg of packages) {
+    const srcPath = path.join(rootNodeModules, pkg);
+    const destPath = path.join(outNodeModules, pkg);
+
+    if (!fs.existsSync(srcPath)) {
+      copiedCount.failed++;
+      continue;
+    }
+
+    try {
+      // 确保父目录存在（处理 scoped packages）
+      const destDir = path.dirname(destPath);
+      if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
+      }
+
+      // 复制包目录，收集统计信息
+      copyDir(srcPath, destPath, fileStats);
+      copiedCount.success++;
+    } catch (err) {
+      console.error(`   ⚠️  复制失败: ${pkg} - ${err.message}`);
+      copiedCount.failed++;
+    }
+  }
+
+  return { copiedCount, fileStats };
+}
+
+/**
+ * 主函数：智能裁剪
+ */
+async function smartPrune() {
+  console.log('🔍 开始智能依赖分析...\n');
+
+  const totalStartTime = Date.now();
+
+  // 1. 检查入口文件是否存在
+  if (!fs.existsSync(SERVER_ENTRY)) {
+    console.error(`❌ 入口文件不存在: ${SERVER_ENTRY}`);
+    console.error('   请先运行 npm run build:server');
+    process.exit(1);
+  }
+
+  console.log(`📂 分析入口文件: ${path.relative(ROOT_DIR, SERVER_ENTRY)}`);
+
+  // 2. 使用 @vercel/nft 追踪依赖
+  console.log('🔎 追踪实际依赖...');
+  const analyzeStart = Date.now();
+
+  const { fileList } = await nodeFileTrace([SERVER_ENTRY], {
+    base: ROOT_DIR,
+    processCwd: ROOT_DIR,
+    ts: false, // 禁用 TS 解析
+    conditions: ['node', 'production'], // 只解析 Node.js 生产环境的导出
+    exportsOnly: true, // 只使用 package.json 的 exports 字段
+    analysis: {
+      emitGlobs: false, // 禁用 glob 分析
+      computeFileReferences: false, // 禁用文件引用计算
+      evaluatePureExpressions: false, // 禁用纯表达式求值
+    },
+  });
+
+  const analyzeElapsed = Date.now() - analyzeStart;
+  console.log(`   ✅ 分析完成，耗时: ${analyzeElapsed}ms\n`);
+
+  // 3. 提取 npm 包名（优化：减少字符串操作）
+  const requiredPackages = new Set();
+
+  for (const file of fileList) {
+    // 快速跳过非 node_modules 文件
+    if (!file.includes('node_modules')) continue;
+
+    const pkgName = extractPackageName(file);
+    if (pkgName && !BUILTIN_MODULES.has(pkgName)) {
+      requiredPackages.add(pkgName);
+    }
+  }
+
+  console.log(`📦 静态分析需要 ${requiredPackages.size} 个 npm 包`);
+
+  // 4. 处理 actionPlugins（动态加载的插件，无法被静态分析追踪）
+  const originalPackage = JSON.parse(fs.readFileSync(ROOT_PACKAGE_JSON, 'utf8'));
+  const actionPlugins = originalPackage.actionPlugins || {};
+  const actionPluginNames = Object.keys(actionPlugins);
+
+  if (actionPluginNames.length > 0) {
+    console.log(`🔌 发现 ${actionPluginNames.length} 个 Action 插件，添加到依赖列表...`);
+
+    for (const pluginName of actionPluginNames) {
+      requiredPackages.add(pluginName);
+
+      // 检查插件的 peerDependencies，也添加进去
+      const pluginPkgPath = path.join(ROOT_NODE_MODULES, pluginName, 'package.json');
+      if (fs.existsSync(pluginPkgPath)) {
+        try {
+          const pluginPkg = JSON.parse(fs.readFileSync(pluginPkgPath, 'utf8'));
+          if (pluginPkg.peerDependencies) {
+            for (const peerDep of Object.keys(pluginPkg.peerDependencies)) {
+              requiredPackages.add(peerDep);
+            }
+          }
+        } catch {
+          // 忽略解析错误
+        }
+      }
+    }
+
+    console.log(`   ✅ 插件: ${actionPluginNames.join(', ')}`);
+  }
+
+  console.log(`📦 总共需要 ${requiredPackages.size} 个 npm 包\n`);
+
+  // 5. 选择性复制包（只复制需要的）
+  console.log('📋 选择性复制 node_modules（仅复制需要的包）...');
+  const copyStart = Date.now();
+
+  const sortedPackages = Array.from(requiredPackages).sort();
+  const { copiedCount, fileStats } = copyPackagesSelectively(sortedPackages, ROOT_NODE_MODULES, OUT_NODE_MODULES);
+
+  const copyElapsed = Date.now() - copyStart;
+  console.log(`   ✅ 复制完成，耗时: ${copyElapsed}ms`);
+  console.log(`   成功: ${copiedCount.success} 个包，失败: ${copiedCount.failed} 个`);
+  console.log(`   硬链接: ${fileStats.hardLinks} 个文件，复制: ${fileStats.copies} 个文件\n`);
+
+  // 6. 生成精简版 package.json
+  // 优化：直接构建 dependencies，避免多次对象展开
+  const prunedDependencies = {};
+  const allDeps = originalPackage.dependencies || {};
+  const allDevDeps = originalPackage.devDependencies || {};
+
+  for (const pkg of requiredPackages) {
+    // 优先从 dependencies/devDependencies 获取版本，其次从 actionPlugins 获取
+    const version = allDeps[pkg] || allDevDeps[pkg] || actionPlugins[pkg];
+    if (version) {
+      prunedDependencies[pkg] = version;
+    }
+  }
+
+  const prunedPackage = {
+    name: originalPackage.name,
+    version: originalPackage.version,
+    private: true,
+    dependencies: prunedDependencies,
+    scripts: {
+      start: originalPackage.scripts?.start || 'node main.js'
+    },
+    engines: originalPackage.engines
+  };
+
+  fs.writeFileSync(OUT_PACKAGE_JSON, JSON.stringify(prunedPackage, null, 2));
+
+  const totalElapsed = Date.now() - totalStartTime;
+
+  // 7. 输出统计信息
+  console.log('='.repeat(60));
+  console.log('📊 智能裁剪统计:');
+  console.log('='.repeat(60));
+  console.log(`  需要的包数量:   ${requiredPackages.size}`);
+  if (actionPluginNames.length > 0) {
+    console.log(`  Action 插件:    ${actionPluginNames.length} 个`);
+  }
+  console.log(`  成功复制:       ${copiedCount.success} 个包`);
+  console.log(`  失败:           ${copiedCount.failed} 个包`);
+  console.log(`  硬链接文件:     ${fileStats.hardLinks} 个`);
+  console.log(`  复制文件:       ${fileStats.copies} 个`);
+  console.log(`  分析耗时:       ${analyzeElapsed}ms`);
+  console.log(`  复制耗时:       ${copyElapsed}ms`);
+  console.log(`  总耗时:         ${totalElapsed}ms`);
+  console.log('='.repeat(60) + '\n');
+
+  console.log('✅ 智能裁剪完成！');
+  console.log(`📍 精简的 package.json 已保存到: ${OUT_PACKAGE_JSON}\n`);
+}
+
+// 运行智能裁剪
+smartPrune().catch(err => {
+  console.error('❌ 智能裁剪失败:', err);
+  process.exit(1);
+});

package/template/scripts/run.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+# This file is auto-generated by @lark-apaas/fullstack-cli
+
+# 生产环境下，启动服务
+npm run start

package/template/server/app.module.ts

@@ -0,0 +1,27 @@
+import { APP_FILTER } from '@nestjs/core';
+import { Module } from '@nestjs/common';
+import { PlatformModule } from '@lark-apaas/fullstack-nestjs-core';
+
+import { GlobalExceptionFilter } from './common/filters/exception.filter';
+import { ViewModule } from './modules/view/view.module';
+
+@Module({
+  imports: [
+    // 平台 Module，提供平台能力
+    PlatformModule.forRoot(),
+    // ====== @route-section: business-modules START ======
+    // Place all business modules here.Do NOT add fallback modules here.
+    // ====== @route-section: business-modules END ======
+
+    // ⚠️ @route-order: last
+    // ViewModule is the fallback route module, must be registered last.
+    ViewModule,
+  ],
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: GlobalExceptionFilter,
+    },
+  ],
+})
+export class AppModule {}

package/template/server/common/constants/api_response_code.ts

@@ -0,0 +1,54 @@
+import { HttpStatus } from '@nestjs/common';
+
+// 业务状态码与HTTP状态码的映射
+export enum ResponseCode {
+  // 成功状态
+  SUCCESS = 'SUCCESS',
+  CREATED = 'CREATED',
+  ACCEPTED = 'ACCEPTED',
+  NO_CONTENT = 'NO_CONTENT',
+
+  // 客户端错误
+  BAD_REQUEST = 'BAD_REQUEST',
+  UNAUTHORIZED = 'UNAUTHORIZED',
+  FORBIDDEN = 'FORBIDDEN',
+  NOT_FOUND = 'NOT_FOUND',
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  CONFLICT = 'CONFLICT',
+  TOO_MANY_REQUESTS = 'TOO_MANY_REQUESTS',
+
+  // 服务端错误
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+  BAD_GATEWAY = 'BAD_GATEWAY',
+  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
+
+  // 业务错误
+  BUSINESS_ERROR = 'BUSINESS_ERROR',
+}
+
+// 状态码映射配置
+export const RESPONSE_CODE_TO_HTTP_STATUS_MAP: Record<ResponseCode, number> = {
+  [ResponseCode.SUCCESS]: HttpStatus.OK,
+  [ResponseCode.CREATED]: HttpStatus.CREATED,
+  [ResponseCode.ACCEPTED]: HttpStatus.ACCEPTED,
+  [ResponseCode.NO_CONTENT]: HttpStatus.NO_CONTENT,
+
+  [ResponseCode.BAD_REQUEST]: HttpStatus.BAD_REQUEST,
+  [ResponseCode.UNAUTHORIZED]: HttpStatus.UNAUTHORIZED,
+  [ResponseCode.FORBIDDEN]: HttpStatus.FORBIDDEN,
+  [ResponseCode.NOT_FOUND]: HttpStatus.NOT_FOUND,
+  [ResponseCode.VALIDATION_ERROR]: HttpStatus.UNPROCESSABLE_ENTITY,
+  [ResponseCode.CONFLICT]: HttpStatus.CONFLICT,
+  [ResponseCode.TOO_MANY_REQUESTS]: HttpStatus.TOO_MANY_REQUESTS,
+
+  [ResponseCode.INTERNAL_ERROR]: HttpStatus.INTERNAL_SERVER_ERROR,
+  [ResponseCode.BAD_GATEWAY]: HttpStatus.BAD_GATEWAY,
+  [ResponseCode.SERVICE_UNAVAILABLE]: HttpStatus.SERVICE_UNAVAILABLE,
+
+  [ResponseCode.BUSINESS_ERROR]: HttpStatus.UNPROCESSABLE_ENTITY, // 通用业务错误状态码
+};
+
+// 自动生成的HTTP状态码映射
+export const HTTP_STATUS_TO_RESPONSE_CODE_MAP: Record<number, ResponseCode> = Object.fromEntries(
+  Object.entries(RESPONSE_CODE_TO_HTTP_STATUS_MAP).map(([code, status]) => [status, code as ResponseCode]),
+) as Record<number, ResponseCode>;

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

@@ -0,0 +1,78 @@
+import { ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus } 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';
+
+// 全局异常过滤器，用于捕获所有未处理的异常
+@Catch()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.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);
+  }
+}

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

@@ -0,0 +1,21 @@
+// 错误统一响应
+export interface ApiErrorResponse {
+  /** 错误详情 */
+  error: {
+    /** 错误代码 */
+    code: string;
+    /** 错误消息 */
+    message: string;
+    /** 错误详情 */
+    details?: string;
+    /** 字段验证错误 */
+    fieldErrors?: Record<string, string[]>;
+    /** 调用栈（仅开发环境） */
+    stack?: string;
+    /** 错误原因 */
+    cause?: string;
+    /** 错误发生时间 */
+    timestamp?: number;
+  };
+}
+

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

@@ -0,0 +1,19 @@
+// 业务异常类
+import { HttpStatus } from '@nestjs/common';
+import { RESPONSE_CODE_TO_HTTP_STATUS_MAP, ResponseCode } from '../constants/api_response_code';
+
+export class BusinessException extends Error {
+  constructor(
+    public readonly code: ResponseCode,
+    public readonly message: string,
+    public readonly httpStatus: HttpStatus = HttpStatus.BAD_REQUEST,
+    public readonly details?: string,
+    public readonly fieldErrors?: Record<string, string[]>,
+  ) {
+    super(message);
+    this.name = 'BusinessException';
+  }
+  getHttpStatus(): HttpStatus {
+    return RESPONSE_CODE_TO_HTTP_STATUS_MAP[this.code];
+  }
+}