@lark-apaas/fullstack-nestjs-core 1.1.70 → 1.1.71

package/README.md

@@ -1,6 +1,6 @@
 # @lark-apaas/fullstack-nestjs-core
 
-FullStack NestJS Core 是一个为 NestJS 全栈应用提供核心功能的工具包，包括平台集成、CSRF 保护、用户上下文管理和开发工具等。
+FullStack NestJS Core 是一个为 NestJS 全栈应用提供核心功能的工具包，包括平台集成、CSRF 保护、用户上下文管理等。
 
 ## 特性
 
@@ -10,7 +10,6 @@ FullStack NestJS Core 是一个为 NestJS 全栈应用提供核心功能的工
 - **用户上下文**: 自动从请求头中提取并注入用户上下文信息
 - **视图上下文**: 将用户信息和 CSRF Token 注入到模板渲染上下文
 - **旧路径兼容**: 灰度迁移期间自动将旧路径 302 重定向到新路径，实现平滑过渡
-- **开发工具**: 自动生成 Swagger 文档、OpenAPI JSON 和 TypeScript 客户端 SDK
 - **应用配置**: 一键配置 Logger、Cookie Parser、全局前缀等
 
 ## 安装
@@ -77,7 +76,7 @@ import { AppModule } from './app.module';
 async function bootstrap() {
   const app = await NestFactory.create<NestExpressApplication>(AppModule);
 
-  // 一键配置：Logger、CookieParser、GlobalPrefix、DevTools
+  // 一键配置：Logger、CookieParser、GlobalPrefix
   await configureApp(app);
 
   await app.listen(3000);
@@ -89,7 +88,9 @@ bootstrap();
 - ✅ 注册 AppLogger
 - ✅ 注册 cookie-parser 中间件
 - ✅ 根据 `CLIENT_BASE_PATH` 环境变量设置全局前缀
-- ✅ 在非生产环境自动挂载 `DevToolsV2Module`
+- ✅ 开发态（`NODE_ENV !== 'production'`）且未传 `disableSwagger: true` 时，自动生成 OpenAPI 及客户端 SDK（兼容旧模板），生成失败不阻塞启动
+
+生产态不会生成，也不会加载 DevTools。新模板默认传 `disableSwagger: true`，开发态同样不加载。
 
 ### 方案 3: 手动配置各个模块
 
@@ -161,85 +162,15 @@ export class AppModule implements NestModule {
 export class AppModule {}
 ```
 
-### DevToolsV2Module（推荐）
-
-使用 `@hey-api/openapi-ts` 生成高质量的 TypeScript 客户端 SDK。
-
-**新特性：**
-- ✅ 使用最新的 `@hey-api/openapi-ts` 生成器
-- ✅ 自动注入 `baseURL` 配置到生成的客户端
-- ✅ 自动给所有生成的文件添加 `// @ts-nocheck` 注释
-
-#### 配置选项
-
-| 选项 | 类型 | 默认值 | 描述 |
-|------|------|--------|------|
-| 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 文档配置 |
-
-#### 使用示例
+### DevTools 旧接口兼容（已废弃）
 
-```typescript
-import { NestFactory } from '@nestjs/core';
-import { DevToolsV2Module } from '@lark-apaas/fullstack-nestjs-core';
-import { AppModule } from './app.module';
+新模板已不使用 OpenAPI/客户端 SDK 生成（`gen:openapi` 为空操作，`configureApp` 传 `disableSwagger: true`）。旧模板应用仍通过 `scripts/gen-openapi.ts` 及开发态自动生成使用该能力，Core 对此保持兼容。
 
-async function bootstrap() {
-  const app = await NestFactory.create(AppModule);
-
-  // 在开发环境挂载开发工具
-  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',
-      },
-    });
-  }
+Core 保留 `DevToolsModule`、`DevToolsV2Module` 及对应 Options 类型，仅用于兼容老应用已有的导入和显式调用；模块导出已标记为 deprecated。新应用无需接入，旧应用也无需为适配本次升级新增 `mount()` 调用。
 
-  await app.listen(3000);
-}
-bootstrap();
-```
-
-#### 生成的文件
-
-```
-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',
-});
-```
+- 导入 Core 或读取旧导出不会加载 DevTools；`configureApp` 只在开发态且未禁用时才加载并生成。
+- 除上述开发态自动生成外，只有应用代码或自定义脚本实际调用 `mount()` 时，才加载并执行生成器，产生相应耗时。
+- Core 继续声明 DevTools 运行时依赖，保证旧的显式调用在安装及产物裁剪后仍可解析；依赖存在不代表启动时会加载。
 
 ## HTTP 客户端
 

package/dist/index.cjs

@@ -34411,8 +34411,8 @@ __export(index_exports, {
   CanRole: () => import_nestjs_authzpaas2.CanRole,
   CsrfMiddleware: () => CsrfMiddleware,
   CsrfTokenMiddleware: () => CsrfTokenMiddleware,
-  DevToolsModule: () => import_nestjs_openapi_devtools2.DevToolsModule,
-  DevToolsV2Module: () => import_nestjs_openapi_devtools2.DevToolsV2Module,
+  DevToolsModule: () => DevToolsModule,
+  DevToolsV2Module: () => DevToolsV2Module,
   FileService: () => FileService,
   HtmlHotUpdateModule: () => HtmlHotUpdateModule,
   HtmlHotUpdateService: () => HtmlHotUpdateService,
@@ -36606,7 +36606,31 @@ PlatformModule = _ts_decorate16([
 var import_nestjs_logger3 = require("@lark-apaas/nestjs-logger");
 var import_cookie_parser = __toESM(require("cookie-parser"), 1);
 var import_express = __toESM(require_express2(), 1);
-var import_nestjs_openapi_devtools = require("@lark-apaas/nestjs-openapi-devtools");
+
+// src/compat/devtools.ts
+var import_node_module = require("module");
+var import_meta = {};
+function loadTools() {
+  const requireTools = (0, import_node_module.createRequire)(typeof __filename === "string" ? __filename : import_meta.url);
+  return requireTools("@lark-apaas/nestjs-openapi-devtools");
+}
+__name(loadTools, "loadTools");
+var DevToolsModule = class {
+  static {
+    __name(this, "DevToolsModule");
+  }
+  static async mount(app, opts = {}) {
+    return loadTools().DevToolsModule.mount(app, opts);
+  }
+};
+var DevToolsV2Module = class {
+  static {
+    __name(this, "DevToolsV2Module");
+  }
+  static async mount(app, opts = {}) {
+    return loadTools().DevToolsV2Module.mount(app, opts);
+  }
+};
 
 // src/middlewares/legacy-path-redirect/index.ts
 var LEGACY_ROUTE_PATTERNS = [
@@ -36815,11 +36839,10 @@ async function configureApp(app, perms = defaultPerms) {
   app.set("trust proxy", true);
   if (process.env.NODE_ENV !== "production" && perms.disableSwagger !== true) {
     try {
-      await import_nestjs_openapi_devtools.DevToolsV2Module.mount(app, {
+      await DevToolsV2Module.mount(app, {
         basePath: process.env.CLIENT_BASE_PATH,
         docsPath: "/api_docs"
       });
-      console.log("App Started Successfully.");
     } catch (err) {
       console.error("[OpenAPI] OpenAPI \u751F\u6210\u5931\u8D25:", err);
     }
@@ -36829,7 +36852,6 @@ async function configureApp(app, perms = defaultPerms) {
 __name(configureApp, "configureApp");
 
 // src/index.ts
-var import_nestjs_openapi_devtools2 = require("@lark-apaas/nestjs-openapi-devtools");
 __reExport(index_exports, require("@lark-apaas/nestjs-authnpaas"), module.exports);
 __reExport(index_exports, require("@lark-apaas/nestjs-capability"), module.exports);
 __reExport(index_exports, require("@lark-apaas/nestjs-datapaas"), module.exports);

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { NestModule, DynamicModule, MiddlewareConsumer, OnModuleInit, NestMiddleware } from '@nestjs/common';
+import { NestModule, DynamicModule, MiddlewareConsumer, OnModuleInit, INestApplication, NestMiddleware } from '@nestjs/common';
 import { HttpClientConfig, PlatformPluginOptions, HttpClient } from '@lark-apaas/http-client';
 import { AuthZPaasModuleOptions } from '@lark-apaas/nestjs-authzpaas';
 export { AddMembersParams, AuthZPaasModule, AuthorizationSDK, Can, CanRole, ChatSimpleDTO, CommonParam, CreateRoleParams, CreateRoleResponse, DepartmentDTO, DepartmentEntity, DepartmentSimpleDTO, FilterParams, ForceRoleDTO, I18nText, IPermissionResolver, ListMembersParams, ListMembersResponse, ListRolesParams, MemberMutationData, MemberType, PERMISSION_RESOLVER_TOKEN, PermissionPoint, PermissionRequirement, PresetGroupDTO, RemoveMembersParams, RoleMemberDTO, SearchChatEntity, SearchParams, SearchResponse, SearchResult, SearchUserEntity, UpdateRoleParams, UserSimpleDTO } from '@lark-apaas/nestjs-authzpaas';
@@ -8,7 +8,8 @@ export * from '@lark-apaas/nestjs-mcp';
 import { NestExpressApplication } from '@nestjs/platform-express';
 import { PlatformHttpClient, RequestContextService, ObservableService } from '@lark-apaas/nestjs-common';
 export { AutoTrace } from '@lark-apaas/nestjs-common';
-export { DevToolsModule, DevToolsOptions, DevToolsV2Module, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
+import { DevToolsOptions, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
+export { DevToolsOptions, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
 import { Request, Response, NextFunction } from 'express';
 import * as _lark_apaas_file_service from '@lark-apaas/file-service';
 import { FileBody, UploadOptions, FileDownloadBuilder, SearchOptions } from '@lark-apaas/file-service';
@@ -106,11 +107,11 @@ declare class PlatformModule implements NestModule {
 }
 
 /**
- * 初始化应用的基础能力（中间件、过滤器、Swagger 等）。
+ * 初始化应用的基础能力（中间件、日志、开发态 OpenAPI 生成等）。
  *
  * @param app NestExpressApplication 实例
  * @param perms 配置项
- * @param perms.disableSwagger 是否禁用 Swagger（默认：false）
+ * @param perms.disableSwagger 是否禁用开发态 OpenAPI/客户端 SDK 自动生成（默认：false）
  * @param perms.bodyLimit 请求体大小限制，优先级：perms.bodyLimit > env.BODY_LIMIT > '1mb'
  */
 declare function configureApp(app: NestExpressApplication, perms?: {
@@ -186,6 +187,15 @@ declare class HtmlHotUpdateService implements OnModuleInit {
     private getAppID;
 }
 
+/** @deprecated Import from @lark-apaas/nestjs-openapi-devtools when generation is required. */
+declare class DevToolsModule {
+    static mount(app: INestApplication, opts?: DevToolsOptions): Promise<void>;
+}
+/** @deprecated Import from @lark-apaas/nestjs-openapi-devtools when generation is required. */
+declare class DevToolsV2Module {
+    static mount(app: INestApplication, opts?: DevToolsV2Options): Promise<void>;
+}
+
 interface CsrfTokenOptions {
     cookieKey?: string;
     cookieMaxAge?: number;
@@ -449,4 +459,4 @@ declare function safeEscape(s: string): string;
  */
 declare function safeEscapeDeep<T>(value: T): T;
 
-export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, FileService, HtmlHotUpdateModule, HtmlHotUpdateService, type PlatformHttpClientOptions, PlatformHttpClientService, PlatformModule, type PlatformModuleOptions, StaticModule, UserContextMiddleware, ViewContextMiddleware, configureApp, createLegacyPathRedirectMiddleware, createPublicAssetsMiddleware, safeEscape, safeEscapeDeep, safeStringParse, safeStringify };
+export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, DevToolsModule, DevToolsV2Module, FileService, HtmlHotUpdateModule, HtmlHotUpdateService, type PlatformHttpClientOptions, PlatformHttpClientService, PlatformModule, type PlatformModuleOptions, StaticModule, UserContextMiddleware, ViewContextMiddleware, configureApp, createLegacyPathRedirectMiddleware, createPublicAssetsMiddleware, safeEscape, safeEscapeDeep, safeStringParse, safeStringify };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { NestModule, DynamicModule, MiddlewareConsumer, OnModuleInit, NestMiddleware } from '@nestjs/common';
+import { NestModule, DynamicModule, MiddlewareConsumer, OnModuleInit, INestApplication, NestMiddleware } from '@nestjs/common';
 import { HttpClientConfig, PlatformPluginOptions, HttpClient } from '@lark-apaas/http-client';
 import { AuthZPaasModuleOptions } from '@lark-apaas/nestjs-authzpaas';
 export { AddMembersParams, AuthZPaasModule, AuthorizationSDK, Can, CanRole, ChatSimpleDTO, CommonParam, CreateRoleParams, CreateRoleResponse, DepartmentDTO, DepartmentEntity, DepartmentSimpleDTO, FilterParams, ForceRoleDTO, I18nText, IPermissionResolver, ListMembersParams, ListMembersResponse, ListRolesParams, MemberMutationData, MemberType, PERMISSION_RESOLVER_TOKEN, PermissionPoint, PermissionRequirement, PresetGroupDTO, RemoveMembersParams, RoleMemberDTO, SearchChatEntity, SearchParams, SearchResponse, SearchResult, SearchUserEntity, UpdateRoleParams, UserSimpleDTO } from '@lark-apaas/nestjs-authzpaas';
@@ -8,7 +8,8 @@ export * from '@lark-apaas/nestjs-mcp';
 import { NestExpressApplication } from '@nestjs/platform-express';
 import { PlatformHttpClient, RequestContextService, ObservableService } from '@lark-apaas/nestjs-common';
 export { AutoTrace } from '@lark-apaas/nestjs-common';
-export { DevToolsModule, DevToolsOptions, DevToolsV2Module, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
+import { DevToolsOptions, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
+export { DevToolsOptions, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
 import { Request, Response, NextFunction } from 'express';
 import * as _lark_apaas_file_service from '@lark-apaas/file-service';
 import { FileBody, UploadOptions, FileDownloadBuilder, SearchOptions } from '@lark-apaas/file-service';
@@ -106,11 +107,11 @@ declare class PlatformModule implements NestModule {
 }
 
 /**
- * 初始化应用的基础能力（中间件、过滤器、Swagger 等）。
+ * 初始化应用的基础能力（中间件、日志、开发态 OpenAPI 生成等）。
  *
  * @param app NestExpressApplication 实例
  * @param perms 配置项
- * @param perms.disableSwagger 是否禁用 Swagger（默认：false）
+ * @param perms.disableSwagger 是否禁用开发态 OpenAPI/客户端 SDK 自动生成（默认：false）
  * @param perms.bodyLimit 请求体大小限制，优先级：perms.bodyLimit > env.BODY_LIMIT > '1mb'
  */
 declare function configureApp(app: NestExpressApplication, perms?: {
@@ -186,6 +187,15 @@ declare class HtmlHotUpdateService implements OnModuleInit {
     private getAppID;
 }
 
+/** @deprecated Import from @lark-apaas/nestjs-openapi-devtools when generation is required. */
+declare class DevToolsModule {
+    static mount(app: INestApplication, opts?: DevToolsOptions): Promise<void>;
+}
+/** @deprecated Import from @lark-apaas/nestjs-openapi-devtools when generation is required. */
+declare class DevToolsV2Module {
+    static mount(app: INestApplication, opts?: DevToolsV2Options): Promise<void>;
+}
+
 interface CsrfTokenOptions {
     cookieKey?: string;
     cookieMaxAge?: number;
@@ -449,4 +459,4 @@ declare function safeEscape(s: string): string;
  */
 declare function safeEscapeDeep<T>(value: T): T;
 
-export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, FileService, HtmlHotUpdateModule, HtmlHotUpdateService, type PlatformHttpClientOptions, PlatformHttpClientService, PlatformModule, type PlatformModuleOptions, StaticModule, UserContextMiddleware, ViewContextMiddleware, configureApp, createLegacyPathRedirectMiddleware, createPublicAssetsMiddleware, safeEscape, safeEscapeDeep, safeStringParse, safeStringify };
+export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, DevToolsModule, DevToolsV2Module, FileService, HtmlHotUpdateModule, HtmlHotUpdateService, type PlatformHttpClientOptions, PlatformHttpClientService, PlatformModule, type PlatformModuleOptions, StaticModule, UserContextMiddleware, ViewContextMiddleware, configureApp, createLegacyPathRedirectMiddleware, createPublicAssetsMiddleware, safeEscape, safeEscapeDeep, safeStringParse, safeStringify };

package/dist/index.js

@@ -36574,7 +36574,30 @@ PlatformModule = _ts_decorate16([
 var import_express = __toESM(require_express2(), 1);
 import { AppLogger as AppLogger3 } from "@lark-apaas/nestjs-logger";
 import cookieParser from "cookie-parser";
-import { DevToolsV2Module } from "@lark-apaas/nestjs-openapi-devtools";
+
+// src/compat/devtools.ts
+import { createRequire } from "module";
+function loadTools() {
+  const requireTools = createRequire(typeof __filename === "string" ? __filename : import.meta.url);
+  return requireTools("@lark-apaas/nestjs-openapi-devtools");
+}
+__name(loadTools, "loadTools");
+var DevToolsModule = class {
+  static {
+    __name(this, "DevToolsModule");
+  }
+  static async mount(app, opts = {}) {
+    return loadTools().DevToolsModule.mount(app, opts);
+  }
+};
+var DevToolsV2Module = class {
+  static {
+    __name(this, "DevToolsV2Module");
+  }
+  static async mount(app, opts = {}) {
+    return loadTools().DevToolsV2Module.mount(app, opts);
+  }
+};
 
 // src/middlewares/legacy-path-redirect/index.ts
 var LEGACY_ROUTE_PATTERNS = [
@@ -36787,7 +36810,6 @@ async function configureApp(app, perms = defaultPerms) {
         basePath: process.env.CLIENT_BASE_PATH,
         docsPath: "/api_docs"
       });
-      console.log("App Started Successfully.");
     } catch (err) {
       console.error("[OpenAPI] OpenAPI \u751F\u6210\u5931\u8D25:", err);
     }
@@ -36797,7 +36819,6 @@ async function configureApp(app, perms = defaultPerms) {
 __name(configureApp, "configureApp");
 
 // src/index.ts
-import { DevToolsModule, DevToolsV2Module as DevToolsV2Module2 } from "@lark-apaas/nestjs-openapi-devtools";
 export * from "@lark-apaas/nestjs-authnpaas";
 export * from "@lark-apaas/nestjs-capability";
 export * from "@lark-apaas/nestjs-datapaas";
@@ -36816,7 +36837,7 @@ export {
   CsrfMiddleware,
   CsrfTokenMiddleware,
   DevToolsModule,
-  DevToolsV2Module2 as DevToolsV2Module,
+  DevToolsV2Module,
   FileService,
   HtmlHotUpdateModule,
   HtmlHotUpdateService,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-nestjs-core",
-  "version": "1.1.70",
+  "version": "1.1.71",
   "description": "FullStack Nestjs Core",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,18 +39,18 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@lark-apaas/cache-service": "^0.1.3",
+    "@lark-apaas/cache-service": "^0.1.4",
     "@lark-apaas/file-service": "^0.1.2",
     "@lark-apaas/http-client": "^0.1.9",
     "@lark-apaas/nestjs-authnpaas": "^1.0.9",
     "@lark-apaas/nestjs-authzpaas": "^0.1.16",
     "@lark-apaas/nestjs-capability": "^0.1.14",
     "@lark-apaas/nestjs-common": "^0.1.9",
-    "@lark-apaas/nestjs-datapaas": "^1.0.23",
+    "@lark-apaas/nestjs-datapaas": "^1.0.24",
     "@lark-apaas/nestjs-http-forwarder": "^0.1.4",
-    "@lark-apaas/nestjs-logger": "^1.0.19",
+    "@lark-apaas/nestjs-logger": "^1.0.20",
     "@lark-apaas/nestjs-mcp": "^0.1.2",
-    "@lark-apaas/nestjs-observable": "^0.0.13",
+    "@lark-apaas/nestjs-observable": "^0.0.14",
     "@lark-apaas/nestjs-openapi-devtools": "^1.0.10",
     "@lark-apaas/nestjs-trigger": "^0.0.3",
     "@nestjs/axios": "^4.0.1",