@lark-apaas/fullstack-nestjs-core 1.0.3-alpha.13 → 1.0.3-alpha.14

package/README.md

@@ -1,12 +1,15 @@
 # @lark-apaas/fullstack-nestjs-core
 
-FullStack NestJS Core 是一个为 NestJS 应用提供核心功能的工具包，包括 CSRF 保护、用户上下文管理和开发工具等。
+FullStack NestJS Core 是一个为 NestJS 全栈应用提供核心功能的工具包，包括平台集成、CSRF 保护、用户上下文管理和开发工具等。
 
 ## 特性
 
+- **平台模块**: 一站式集成 Config、Logger、Database、Auth 等核心功能
 - **CSRF 保护**: 提供完整的 CSRF Token 生成和验证机制
 - **用户上下文**: 自动从请求头中提取并注入用户上下文信息
-- **开发工具**: 自动生成 Swagger 文档、OpenAPI JSON 和客户端 SDK
+- **视图上下文**: 将用户信息和 CSRF Token 注入到模板渲染上下文
+- **开发工具**: 自动生成 Swagger 文档、OpenAPI JSON 和 TypeScript 客户端 SDK
+- **应用配置**: 一键配置 Logger、Cookie Parser、全局前缀等
 
 ## 安装
 
@@ -27,226 +30,330 @@ yarn add @lark-apaas/fullstack-nestjs-core
 
 ## 快速开始
 
-### 1. CSRF 保护
+### 方案 1: 使用 PlatformModule（推荐）
 
-CSRF 保护由两个中间件组成：`CsrfTokenMiddleware` 用于生成 token，`CsrfMiddleware` 用于验证 token。
+最简单的方式是使用 `PlatformModule`，它会自动集成所有核心功能：
 
-#### 使用默认配置
+```typescript
+import { Module } from '@nestjs/common';
+import { PlatformModule } from '@lark-apaas/fullstack-nestjs-core';
+
+@Module({
+  imports: [
+    PlatformModule.forRoot({
+      enableCsrf: true,           // 是否启用 CSRF 保护，默认 true
+      csrfRoutes: '/api/*',       // CSRF 保护的路由，默认 '/api/*'
+      alwaysNeedLogin: true,      // 是否所有路由都需要登录，默认 true
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`PlatformModule` 自动集成：
+- ✅ ConfigModule (环境变量配置)
+- ✅ LoggerModule (日志系统)
+- ✅ DataPaasModule (数据库连接)
+- ✅ AuthNPaasModule (认证系统)
+- ✅ UserContextMiddleware (用户上下文)
+- ✅ CsrfTokenMiddleware + CsrfMiddleware (CSRF 保护)
+- ✅ ViewContextMiddleware (视图上下文)
+- ✅ ValidationPipe (全局验证管道)
+
+### 方案 2: 使用 configureApp 辅助函数
+
+在 `main.ts` 中使用 `configureApp` 快速配置应用：
 
 ```typescript
-import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
-import { CsrfTokenMiddleware, CsrfMiddleware } from '@lark-apaas/fullstack-nestjs-core';
+import { NestFactory } from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
+import { configureApp } from '@lark-apaas/fullstack-nestjs-core';
+import { AppModule } from './app.module';
 
-@Module({})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    // 直接应用中间件，使用默认配置
-    consumer
-      .apply(CsrfTokenMiddleware)
-      .forRoutes('*'); // 所有路由都生成 token
+async function bootstrap() {
+  const app = await NestFactory.create<NestExpressApplication>(AppModule);
 
-    consumer
-      .apply(CsrfMiddleware)
-      .forRoutes('*'); // 所有路由都验证 CSRF token
-  }
+  // 一键配置：Logger、CookieParser、GlobalPrefix、DevTools
+  await configureApp(app);
+
+  await app.listen(3000);
 }
+bootstrap();
 ```
 
-#### 自定义配置（可选）
+`configureApp` 会自动：
+- ✅ 注册 AppLogger
+- ✅ 注册 cookie-parser 中间件
+- ✅ 根据 `CLIENT_BASE_PATH` 环境变量设置全局前缀
+- ✅ 在非生产环境自动挂载 `DevToolsV2Module`
+
+### 方案 3: 手动配置各个模块
 
-如需自定义配置，可在应用中间件前调用 `configure` 方法：
+如果需要更细粒度的控制，可以单独使用各个模块：
 
 ```typescript
 import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
-import { CsrfTokenMiddleware, CsrfMiddleware } from '@lark-apaas/fullstack-nestjs-core';
+import {
+  CsrfTokenMiddleware,
+  CsrfMiddleware,
+  UserContextMiddleware,
+  ViewContextMiddleware,
+} from '@lark-apaas/fullstack-nestjs-core';
 
 @Module({})
 export class AppModule implements NestModule {
   configure(consumer: MiddlewareConsumer) {
-    // 自定义配置 CSRF Token 生成中间件
-    CsrfTokenMiddleware.configure({
-      cookieKey: 'CSRF-TOKEN',        // 默认: 'suda-csrf-token'
-      cookieMaxAge: 86400000,         // 默认: 2592000000 (30天)
-      cookiePath: '/',                // 默认: '/'
-    });
-
-    // 自定义配置 CSRF 验证中间件
-    CsrfMiddleware.configure({
-      headerKey: 'X-CSRF-TOKEN',      // 默认: 'x-suda-csrf-token'
-      cookieKey: 'CSRF-TOKEN',        // 默认: 'suda-csrf-token'
-    });
+    // 用户上下文中间件
+    consumer
+      .apply(UserContextMiddleware)
+      .forRoutes('*');
 
-    // 应用中间件
+    // CSRF Token 生成（用于视图渲染）
     consumer
       .apply(CsrfTokenMiddleware)
+      .exclude('/api/(.*)')
       .forRoutes('*');
 
+    // 视图上下文注入
     consumer
-      .apply(CsrfMiddleware)
+      .apply(ViewContextMiddleware)
+      .exclude('/api/(.*)')
       .forRoutes('*');
+
+    // CSRF 验证（用于 API 保护）
+    consumer
+      .apply(CsrfMiddleware)
+      .forRoutes('/api/*');
   }
 }
 ```
 
-**注意**: 如果使用自定义的 `cookieKey`，需要确保 `CsrfTokenMiddleware` 和 `CsrfMiddleware` 配置的 `cookieKey` 一致。
+## 核心模块
 
-### 2. 用户上下文
+### PlatformModule
 
-自动从请求头中提取用户信息并注入到请求对象中。
+全局平台模块，集成了所有核心功能。
 
-```typescript
-import { Module, NestModule, MiddlewareConsumer } from '@nestjs/common';
-import { UserContextMiddleware } from '@lark-apaas/fullstack-nestjs-core';
+#### 配置选项
 
-@Module({})
-export class AppModule implements NestModule {
-  configure(consumer: MiddlewareConsumer) {
-    consumer
-      .apply(UserContextMiddleware)
-      .forRoutes('*');
-  }
-}
-```
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| enableCsrf | boolean | `true` | 是否启用 CSRF 保护 |
+| csrfRoutes | string \| string[] | `'/api/*'` | CSRF 保护应用的路由 |
+| alwaysNeedLogin | boolean | `true` | 是否所有路由都需要登录 |
 
-在控制器中使用：
+#### 使用示例
 
 ```typescript
-import { Controller, Get, Req } from '@nestjs/common';
-import { Request } from 'express';
-
-@Controller()
-export class AppController {
-  @Get()
-  getUser(@Req() req: Request) {
-    // 访问用户上下文
-    const { userId, tenantId, appId } = req.userContext;
-    return { userId, tenantId, appId };
-  }
-}
+@Module({
+  imports: [
+    PlatformModule.forRoot({
+      enableCsrf: true,
+      csrfRoutes: ['/api/*', '/admin/*'],
+      alwaysNeedLogin: false,
+    }),
+  ],
+})
+export class AppModule {}
 ```
 
-### 3. 开发工具模块
+### DevToolsV2Module（推荐）
+
+使用 `@hey-api/openapi-ts` 生成高质量的 TypeScript 客户端 SDK。
+
+**新特性：**
+- ✅ 使用最新的 `@hey-api/openapi-ts` 生成器
+- ✅ 自动注入 `baseURL` 配置到生成的客户端
+- ✅ 自动给所有生成的文件添加 `// @ts-nocheck` 注释
+
+#### 配置选项
 
-在开发环境中自动生成 Swagger 文档和客户端 SDK。
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| basePath | string | `'/'` | API 基础路径 |
+| docsPath | string | `'/api/docs'` | Swagger UI 的挂载路径 |
+| openapiOut | string | `'./client/src/api/gen/openapi.json'` | OpenAPI JSON 输出路径 |
+| needSetupServer | boolean | `false` | 是否挂载 Swagger UI 服务器 |
+| needGenerateClientSdk | boolean | `true` | 是否生成客户端 SDK |
+| clientSdkOut | string | `'./client/src/api/gen'` | 客户端 SDK 输出目录 |
+| swaggerOptions | object | - | Swagger 文档配置 |
+
+#### 使用示例
 
 ```typescript
 import { NestFactory } from '@nestjs/core';
-import { DevToolsModule } from '@lark-apaas/fullstack-nestjs-core';
+import { DevToolsV2Module } from '@lark-apaas/fullstack-nestjs-core';
 import { AppModule } from './app.module';
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
 
-  // 挂载开发工具
-  await DevToolsModule.mount(app, {
-    docsPath: 'api-docs',
-    openapiOut: './openapi.json',
-    needSetupServer: true,
-    needGenerateClientSdk: true,
-    clientSdkOut: './src/sdk',
-    swaggerOptions: {
-      title: 'My API',
-      version: '1.0.0',
-      customSiteTitle: 'My API Documentation',
-    },
-  });
+  // 在开发环境挂载开发工具
+  if (process.env.NODE_ENV !== 'production') {
+    await DevToolsV2Module.mount(app, {
+      basePath: '/app',
+      docsPath: '/api_docs',
+      needSetupServer: true,
+      needGenerateClientSdk: true,
+      swaggerOptions: {
+        title: 'My API',
+        version: '1.0.0',
+      },
+    });
+  }
 
   await app.listen(3000);
 }
 bootstrap();
 ```
 
-## API 文档
+#### 生成的文件
+
+```
+client/src/api/gen/
+├── openapi.json              # OpenAPI 规范文件
+├── client.config.ts          # 客户端配置（自动生成 baseURL）
+├── types.gen.ts              # TypeScript 类型定义
+├── sdk.gen.ts                # SDK 函数
+└── client/
+    └── client.gen.ts         # Axios 客户端
+```
+
+所有生成的 `.ts` 文件都会自动添加 `// @ts-nocheck` 注释，避免类型检查错误。
+
+### DevToolsModule（旧版）
+
+使用 `openapi-typescript-codegen` 生成客户端 SDK（不推荐，建议迁移到 `DevToolsV2Module`）。
+
+```typescript
+import { DevToolsModule } from '@lark-apaas/fullstack-nestjs-core';
+
+await DevToolsModule.mount(app, {
+  docsPath: 'api-docs',
+  openapiOut: './openapi.json',
+  needSetupServer: true,
+  needGenerateClientSdk: true,
+  clientSdkOut: './src/sdk',
+});
+```
+
+## 中间件
 
 ### CsrfTokenMiddleware
 
-生成 CSRF Token 并设置到 Cookie 中。
+生成 CSRF Token 并设置到 Cookie 中，用于视图渲染场景。
 
-#### 配置选项 (CsrfTokenOptions)
+#### 配置选项
 
 | 选项 | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| cookieKey | string | `'suda-csrf-token'` | Cookie 中存储 CSRF Token 的键名 |
-| cookieMaxAge | number | `2592000000` (30天) | Cookie 的过期时间（毫秒） |
-| cookiePath | string | `'/'` | Cookie 的路径 |
+| cookieKey | string | `'suda-csrf-token'` | Cookie 中存储 Token 的键名 |
+| cookieMaxAge | number | `2592000000` (30天) | Cookie 过期时间（毫秒） |
+| cookiePath | string | `'/'` | Cookie 路径 |
 
-#### 静态方法
+#### 使用示例
 
-- `configure(opts: CsrfTokenOptions)`: 配置中间件选项
+```typescript
+CsrfTokenMiddleware.configure({
+  cookieKey: 'my-csrf-token',
+  cookieMaxAge: 86400000, // 1天
+});
+
+consumer
+  .apply(CsrfTokenMiddleware)
+  .exclude('/api/(.*)')
+  .forRoutes('*');
+```
 
 ### CsrfMiddleware
 
-验证请求中的 CSRF Token。
+验证请求中的 CSRF Token，用于保护 API 接口。
 
-#### 配置选项 (CsrfOptions)
+#### 配置选项
 
 | 选项 | 类型 | 默认值 | 描述 |
 |------|------|--------|------|
-| headerKey | string | `'x-suda-csrf-token'` | 请求头中 CSRF Token 的键名 |
-| cookieKey | string | `'suda-csrf-token'` | Cookie 中 CSRF Token 的键名 |
+| headerKey | string | `'x-suda-csrf-token'` | 请求头中 Token 的键名 |
+| cookieKey | string | `'suda-csrf-token'` | Cookie 中 Token 的键名 |
 
-#### 静态方法
+#### 使用示例
 
-- `configure(opts: CsrfOptions)`: 配置中间件选项
-
-#### 验证规则
-
-1. 检查 Cookie 中是否存在 CSRF Token
-2. 检查请求头中是否存在 CSRF Token
-3. 验证两者是否匹配
+```typescript
+CsrfMiddleware.configure({
+  headerKey: 'x-my-csrf-token',
+  cookieKey: 'my-csrf-token',
+});
+
+consumer
+  .apply(CsrfMiddleware)
+  .forRoutes('/api/*');
+```
 
-如果任何一步验证失败，将返回 403 Forbidden。
+**注意**: 确保 `CsrfTokenMiddleware` 和 `CsrfMiddleware` 的 `cookieKey` 配置一致。
 
 ### UserContextMiddleware
 
-从请求头中提取用户上下文信息。
+从请求头中提取用户上下文信息并注入到 `req.userContext`。
 
 #### 注入的上下文
 
 ```typescript
 req.userContext = {
-  userId: string | undefined;    // 用户 ID
-  tenantId: string | undefined;  // 租户 ID
-  appId: string;                 // 应用 ID
+  userId: string | undefined;    // 用户 ID（来自 x-user-id 请求头）
+  tenantId: string | undefined;  // 租户 ID（来自 x-tenant-id 请求头）
+  appId: string;                 // 应用 ID（来自 x-app-id 请求头）
+}
+```
+
+#### 使用示例
+
+```typescript
+@Controller()
+export class AppController {
+  @Get('profile')
+  getProfile(@Req() req: Request) {
+    const { userId, tenantId, appId } = req.userContext;
+    return { userId, tenantId, appId };
+  }
 }
 ```
 
-### DevToolsModule
+### ViewContextMiddleware
 
-开发工具模块，用于生成 API 文档和客户端 SDK。
+将用户上下文和 CSRF Token 注入到 `res.locals`，用于模板渲染。
 
-#### 配置选项 (DevToolsOptions)
+#### 注入的变量
 
-| 选项 | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| basePath | string | - | 基础路径 |
-| docsPath | string | - | Swagger UI 的挂载路径 |
-| openapiOut | string | - | OpenAPI JSON 文件的输出路径 |
-| needSetupServer | boolean | - | 是否需要挂载 Swagger UI |
-| needGenerateClientSdk | boolean | - | 是否生成客户端 SDK |
-| clientSdkOut | string | - | 客户端 SDK 的输出目录 |
-| swaggerOptions | object | - | Swagger 文档配置 |
-| swaggerOptions.title | string | - | Swagger 文档标题 |
-| swaggerOptions.version | string | - | API 版本号 |
-| swaggerOptions.customSiteTitle | string | - | 自定义站点标题 |
-| swaggerOptions.customCss | string | - | 自定义 CSS 样式 |
+```typescript
+res.locals = {
+  csrfToken: string;   // CSRF Token
+  userId: string;      // 用户 ID
+  tenantId: string;    // 租户 ID
+  appId: string;       // 应用 ID
+}
+```
 
-#### 静态方法
+#### 使用示例
 
-- `mount(app: INestApplication, opts?: DevToolsOptions)`: 挂载开发工具到应用
+```typescript
+// 在模板引擎中可以直接使用这些变量
+// EJS 示例：
+<input type="hidden" name="_csrf" value="<%= csrfToken %>">
+<div>User ID: <%= userId %></div>
+```
 
 ## TypeScript 支持
 
 本包完全使用 TypeScript 编写，并提供完整的类型定义。
 
-扩展 Express Request 类型：
+### 扩展 Express Request 类型
 
 ```typescript
 declare global {
   namespace Express {
     interface Request {
       csrfToken?: string;
-      userContext?: {
+      userContext: {
         userId?: string;
         tenantId?: string;
         appId: string;
@@ -256,6 +363,13 @@ declare global {
 }
 ```
 
+## 环境变量
+
+| 变量名 | 描述 | 默认值 |
+|--------|------|--------|
+| CLIENT_BASE_PATH | 应用的全局路径前缀 | - |
+| NODE_ENV | 运行环境 | - |
+
 ## 许可证
 
 MIT
@@ -266,3 +380,4 @@ MIT
 - nestjs
 - server
 - typescript
+- fullstack

package/dist/index.cjs

@@ -171,6 +171,12 @@ var ViewContextMiddleware = class {
   use(req, res, next) {
     const { userId, tenantId, appId } = req.userContext;
     const csrfToken = req.csrfToken;
+    req.__platform_data__ = {
+      csrfToken: csrfToken ?? "",
+      userId: userId ?? "",
+      appId: appId ?? "",
+      tenantId
+    };
     res.locals = {
       ...res.locals ?? {},
       csrfToken: csrfToken ?? "",
@@ -364,8 +370,6 @@ PlatformModule = _ts_decorate5([
 
 // src/setup.ts
 var import_nestjs_logger2 = require("@lark-apaas/nestjs-logger");
-var import_path = require("path");
-var import_hbs = require("hbs");
 var import_cookie_parser = __toESM(require("cookie-parser"), 1);
 
 // src/modules/devtool-v2/index.ts
@@ -513,15 +517,12 @@ var DevToolsV2Module = class {
 };
 
 // src/setup.ts
-async function configureApp(app, options) {
+async function configureApp(app) {
   app.useLogger(app.get(import_nestjs_logger2.AppLogger));
   app.flushLogs();
   app.use((0, import_cookie_parser.default)());
   const globalPrefix = process.env.CLIENT_BASE_PATH ?? "";
   app.setGlobalPrefix(globalPrefix);
-  app.setBaseViewsDir((0, import_path.join)(process.cwd(), options?.viewsDir ?? "dist/client"));
-  app.setViewEngine("html");
-  app.engine("html", import_hbs.__express);
   if (process.env.NODE_ENV !== "production") {
     await DevToolsV2Module.mount(app, {
       basePath: process.env.CLIENT_BASE_PATH,

package/dist/index.d.cts

@@ -4,19 +4,6 @@ import { Request, Response, NextFunction } from 'express';
 export * from '@lark-apaas/nestjs-authnpaas';
 export * from '@lark-apaas/nestjs-datapaas';
 
-declare global {
-  namespace Express {
-    interface Request {
-      csrfToken?: string;
-      userContext: {
-        userId?: string;
-        tenantId?: number;
-        appId?: string;
-      }
-    }
-  }
-}
-
 /**
  * PlatformModule 配置选项
  */
@@ -47,9 +34,7 @@ declare class PlatformModule implements NestModule {
     configure(consumer: MiddlewareConsumer): void;
 }
 
-declare function configureApp(app: NestExpressApplication, options?: {
-    viewsDir?: string;
-}): Promise<void>;
+declare function configureApp(app: NestExpressApplication): Promise<void>;
 
 interface DevToolsOptions$1 {
     basePath?: string;

package/dist/index.d.ts

@@ -4,19 +4,6 @@ import { Request, Response, NextFunction } from 'express';
 export * from '@lark-apaas/nestjs-authnpaas';
 export * from '@lark-apaas/nestjs-datapaas';
 
-declare global {
-  namespace Express {
-    interface Request {
-      csrfToken?: string;
-      userContext: {
-        userId?: string;
-        tenantId?: number;
-        appId?: string;
-      }
-    }
-  }
-}
-
 /**
  * PlatformModule 配置选项
  */
@@ -47,9 +34,7 @@ declare class PlatformModule implements NestModule {
     configure(consumer: MiddlewareConsumer): void;
 }
 
-declare function configureApp(app: NestExpressApplication, options?: {
-    viewsDir?: string;
-}): Promise<void>;
+declare function configureApp(app: NestExpressApplication): Promise<void>;
 
 interface DevToolsOptions$1 {
     basePath?: string;

package/dist/index.js

@@ -129,6 +129,12 @@ var ViewContextMiddleware = class {
   use(req, res, next) {
     const { userId, tenantId, appId } = req.userContext;
     const csrfToken = req.csrfToken;
+    req.__platform_data__ = {
+      csrfToken: csrfToken ?? "",
+      userId: userId ?? "",
+      appId: appId ?? "",
+      tenantId
+    };
     res.locals = {
       ...res.locals ?? {},
       csrfToken: csrfToken ?? "",
@@ -322,8 +328,6 @@ PlatformModule = _ts_decorate5([
 
 // src/setup.ts
 import { AppLogger as AppLogger2 } from "@lark-apaas/nestjs-logger";
-import { join as join3 } from "path";
-import { __express as hbsExpressEngine } from "hbs";
 import cookieParser from "cookie-parser";
 
 // src/modules/devtool-v2/index.ts
@@ -471,15 +475,12 @@ var DevToolsV2Module = class {
 };
 
 // src/setup.ts
-async function configureApp(app, options) {
+async function configureApp(app) {
   app.useLogger(app.get(AppLogger2));
   app.flushLogs();
   app.use(cookieParser());
   const globalPrefix = process.env.CLIENT_BASE_PATH ?? "";
   app.setGlobalPrefix(globalPrefix);
-  app.setBaseViewsDir(join3(process.cwd(), options?.viewsDir ?? "dist/client"));
-  app.setViewEngine("html");
-  app.engine("html", hbsExpressEngine);
   if (process.env.NODE_ENV !== "production") {
     await DevToolsV2Module.mount(app, {
       basePath: process.env.CLIENT_BASE_PATH,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-nestjs-core",
-  "version": "1.0.3-alpha.13",
+  "version": "1.0.3-alpha.14",
   "description": "FullStack Nestjs Core",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,7 +45,6 @@
     "@lark-apaas/nestjs-datapaas": "^1.0.1",
     "@lark-apaas/nestjs-logger": "^1.0.0",
     "cookie-parser": "^1.4.7",
-    "hbs": "^4.2.0",
     "openapi-typescript-codegen": "^0.29.0"
   },
   "devDependencies": {
@@ -54,7 +53,6 @@
     "@nestjs/swagger": "^7.4.2",
     "@types/cookie-parser": "^1.4.9",
     "@types/express": "^5.0.3",
-    "@types/hbs": "^4.0.5",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.2",
     "drizzle-orm": "0.44.6",