@lark-apaas/fullstack-nestjs-core 1.1.22-beta.0 → 1.1.22-beta.10

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { NestModule, DynamicModule, MiddlewareConsumer, NestMiddleware } from '@nestjs/common';
-import { HttpClientConfig, PlatformPluginOptions } from '@lark-apaas/http-client';
+import { HttpClientConfig, PlatformPluginOptions, HttpClient } from '@lark-apaas/http-client';
 import { NestExpressApplication } from '@nestjs/platform-express';
 export { DevToolsModule, DevToolsOptions, DevToolsV2Module, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
 import { Request, Response, NextFunction } from 'express';
@@ -89,11 +89,40 @@ declare class PlatformModule implements NestModule {
  * @param app NestExpressApplication 实例
  * @param perms 配置项
  * @param perms.disableSwagger 是否禁用 Swagger（默认：false）
+ * @param perms.bodyLimit 请求体大小限制，优先级：perms.bodyLimit > env.BODY_LIMIT > '1mb'
  */
 declare function configureApp(app: NestExpressApplication, perms?: {
     disableSwagger?: boolean;
+    bodyLimit?: string;
 }): Promise<void>;
 
+/**
+ * Static Module
+ *
+ * Provides serving of static files from the shared/static directory.
+ * This module is automatically imported by PlatformModule in PRODUCTION mode only.
+ *
+ * Architecture:
+ * - Development: Vite/Rspack dev server middleware handles /static/* requests
+ *   (faster response, HMR support)
+ * - Production: NestJS StaticController handles /static/* requests
+ *   (proper caching, ETag support)
+ *
+ * Features:
+ * - Serves files at GET /static/* route
+ * - Security protection against path traversal
+ * - Proper MIME type detection
+ * - ETag-based cache validation
+ * - Streaming response for efficient file delivery
+ *
+ * Usage:
+ * 1. Place static files in shared/static/ directory
+ * 2. Import files in frontend: import x from '@shared/static/path'
+ * 3. Access files at {basePath}/static/{path}
+ */
+declare class StaticModule {
+}
+
 interface CsrfTokenOptions {
     cookieKey?: string;
     cookieMaxAge?: number;
@@ -169,4 +198,144 @@ declare class FileService {
     private _getFileMetadata;
 }
 
-export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, FileService, type PlatformHttpClientOptions, PlatformModule, type PlatformModuleOptions, UserContextMiddleware, ViewContextMiddleware, configureApp };
+/**
+ * 平台 HttpClient 服务
+ *
+ * 提供两种使用方式：
+ * 1. 全局实例：通过 `instance` 或 `PLATFORM_HTTP_CLIENT` 注入，适用于 95% 的场景
+ * 2. 独立实例：通过 `create()` 创建，适用于需要自定义拦截器或配置的场景
+ *
+ * @example
+ * 基本使用（推荐）
+ * ```typescript
+ * @Injectable()
+ * export class UserService {
+ *   constructor(
+ *     @Inject(PLATFORM_HTTP_CLIENT) private http: SafeHttpClient
+ *   ) {}
+ *
+ *   async getUser() {
+ *     return this.http.get('/user');
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * 需要自定义拦截器（高级场景）
+ * ```typescript
+ * @Injectable()
+ * export class FileService {
+ *   private fileClient: HttpClient;
+ *
+ *   constructor(private platformHttp: PlatformHttpClientService) {
+ *     this.fileClient = this.platformHttp.create({
+ *       config: { timeout: 60000 }
+ *     });
+ *
+ *     this.fileClient.interceptors.request.use((config) => {
+ *       console.log('File upload starting...');
+ *       return config;
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare class PlatformHttpClientService {
+    private readonly requestContext;
+    private readonly client;
+    private readonly protectedClient;
+    private readonly logger;
+    constructor(requestContext: RequestContextService);
+    /**
+     * 获取受保护的 HttpClient 实例（推荐）
+     *
+     * 该实例不暴露 interceptors，防止业务代码修改全局拦截器
+     *
+     * @returns 受保护的 HttpClient 实例
+     */
+    get instance(): PlatformHttpClient;
+    /**
+     * 获取原始 HttpClient 实例（危险）
+     *
+     * ⚠️ 警告：该实例允许修改拦截器，会影响所有使用全局实例的地方
+     *
+     * 仅用于特殊场景，不应该暴露给业务代码
+     * 如果需要自定义拦截器，请使用 `create()` 方法创建独立实例
+     *
+     * @internal
+     * @returns 原始 HttpClient 实例
+     */
+    get rawInstance(): HttpClient;
+    /**
+     * 创建一个新的独立 HttpClient 实例
+     *
+     * 适用于需要自定义拦截器或配置的场景
+     * 创建的实例完全独立，不会影响全局实例
+     *
+     * @param options - 配置选项（会与全局配置合并）
+     * @returns 完整的 HttpClient 实例（允许修改拦截器）
+     *
+     * @example
+     * ```typescript
+     * @Injectable()
+     * export class FileService {
+     *   private fileClient: HttpClient;
+     *
+     *   constructor(private platformHttp: PlatformHttpClientService) {
+     *     // 创建超时 60 秒的独立实例
+     *     this.fileClient = this.platformHttp.create({
+     *       config: { timeout: 60000 }
+     *     });
+     *
+     *     // 为这个实例注册拦截器（不影响全局实例）
+     *     this.fileClient.interceptors.request.use((config) => {
+     *       console.log('File upload starting...');
+     *       return config;
+     *     });
+     *   }
+     *
+     *   async uploadFile(file: Buffer) {
+     *     return this.fileClient.post('/file/upload', file);
+     *   }
+     * }
+     * ```
+     */
+    create(options?: PlatformHttpClientOptions): HttpClient;
+    /**
+     * 创建一个带全局拦截器的独立 HttpClient 实例
+     *
+     * 与 `create()` 类似，但会自动注册全局拦截器（日志、x-tt-env 透传等）
+     * 适用于需要保留平台标准行为，同时又需要添加自定义拦截器的场景
+     *
+     * @param options - 配置选项（会与全局配置合并）
+     * @returns 完整的 HttpClient 实例（带全局拦截器，允许添加更多拦截器）
+     *
+     * @example
+     * ```typescript
+     * const client = this.platformHttp.createWithGlobalInterceptors();
+     * // 客户端已包含日志和 x-tt-env 拦截器
+     * // 可以继续添加自定义拦截器
+     * client.interceptors.request.use((config) => {
+     *   config.headers['x-custom'] = 'value';
+     *   return config;
+     * });
+     * ```
+     */
+    createWithGlobalInterceptors(options?: PlatformHttpClientOptions): HttpClient;
+    /**
+     * 注册全局拦截器（用于单例实例）
+     */
+    private registerGlobalInterceptors;
+    /**
+     * 为指定的 HttpClient 实例注册标准拦截器
+     *
+     * 包含：
+     * - 请求日志记录
+     * - x-tt-env header 透传
+     * - 响应日志记录
+     * - 错误日志记录
+     */
+    private registerInterceptorsForClient;
+}
+
+export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, FileService, type PlatformHttpClientOptions, PlatformHttpClientService, PlatformModule, type PlatformModuleOptions, StaticModule, UserContextMiddleware, ViewContextMiddleware, configureApp };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { NestModule, DynamicModule, MiddlewareConsumer, NestMiddleware } from '@nestjs/common';
-import { HttpClientConfig, PlatformPluginOptions } from '@lark-apaas/http-client';
+import { HttpClientConfig, PlatformPluginOptions, HttpClient } from '@lark-apaas/http-client';
 import { NestExpressApplication } from '@nestjs/platform-express';
 export { DevToolsModule, DevToolsOptions, DevToolsV2Module, DevToolsV2Options } from '@lark-apaas/nestjs-openapi-devtools';
 import { Request, Response, NextFunction } from 'express';
@@ -89,11 +89,40 @@ declare class PlatformModule implements NestModule {
  * @param app NestExpressApplication 实例
  * @param perms 配置项
  * @param perms.disableSwagger 是否禁用 Swagger（默认：false）
+ * @param perms.bodyLimit 请求体大小限制，优先级：perms.bodyLimit > env.BODY_LIMIT > '1mb'
  */
 declare function configureApp(app: NestExpressApplication, perms?: {
     disableSwagger?: boolean;
+    bodyLimit?: string;
 }): Promise<void>;
 
+/**
+ * Static Module
+ *
+ * Provides serving of static files from the shared/static directory.
+ * This module is automatically imported by PlatformModule in PRODUCTION mode only.
+ *
+ * Architecture:
+ * - Development: Vite/Rspack dev server middleware handles /static/* requests
+ *   (faster response, HMR support)
+ * - Production: NestJS StaticController handles /static/* requests
+ *   (proper caching, ETag support)
+ *
+ * Features:
+ * - Serves files at GET /static/* route
+ * - Security protection against path traversal
+ * - Proper MIME type detection
+ * - ETag-based cache validation
+ * - Streaming response for efficient file delivery
+ *
+ * Usage:
+ * 1. Place static files in shared/static/ directory
+ * 2. Import files in frontend: import x from '@shared/static/path'
+ * 3. Access files at {basePath}/static/{path}
+ */
+declare class StaticModule {
+}
+
 interface CsrfTokenOptions {
     cookieKey?: string;
     cookieMaxAge?: number;
@@ -169,4 +198,144 @@ declare class FileService {
     private _getFileMetadata;
 }
 
-export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, FileService, type PlatformHttpClientOptions, PlatformModule, type PlatformModuleOptions, UserContextMiddleware, ViewContextMiddleware, configureApp };
+/**
+ * 平台 HttpClient 服务
+ *
+ * 提供两种使用方式：
+ * 1. 全局实例：通过 `instance` 或 `PLATFORM_HTTP_CLIENT` 注入，适用于 95% 的场景
+ * 2. 独立实例：通过 `create()` 创建，适用于需要自定义拦截器或配置的场景
+ *
+ * @example
+ * 基本使用（推荐）
+ * ```typescript
+ * @Injectable()
+ * export class UserService {
+ *   constructor(
+ *     @Inject(PLATFORM_HTTP_CLIENT) private http: SafeHttpClient
+ *   ) {}
+ *
+ *   async getUser() {
+ *     return this.http.get('/user');
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * 需要自定义拦截器（高级场景）
+ * ```typescript
+ * @Injectable()
+ * export class FileService {
+ *   private fileClient: HttpClient;
+ *
+ *   constructor(private platformHttp: PlatformHttpClientService) {
+ *     this.fileClient = this.platformHttp.create({
+ *       config: { timeout: 60000 }
+ *     });
+ *
+ *     this.fileClient.interceptors.request.use((config) => {
+ *       console.log('File upload starting...');
+ *       return config;
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare class PlatformHttpClientService {
+    private readonly requestContext;
+    private readonly client;
+    private readonly protectedClient;
+    private readonly logger;
+    constructor(requestContext: RequestContextService);
+    /**
+     * 获取受保护的 HttpClient 实例（推荐）
+     *
+     * 该实例不暴露 interceptors，防止业务代码修改全局拦截器
+     *
+     * @returns 受保护的 HttpClient 实例
+     */
+    get instance(): PlatformHttpClient;
+    /**
+     * 获取原始 HttpClient 实例（危险）
+     *
+     * ⚠️ 警告：该实例允许修改拦截器，会影响所有使用全局实例的地方
+     *
+     * 仅用于特殊场景，不应该暴露给业务代码
+     * 如果需要自定义拦截器，请使用 `create()` 方法创建独立实例
+     *
+     * @internal
+     * @returns 原始 HttpClient 实例
+     */
+    get rawInstance(): HttpClient;
+    /**
+     * 创建一个新的独立 HttpClient 实例
+     *
+     * 适用于需要自定义拦截器或配置的场景
+     * 创建的实例完全独立，不会影响全局实例
+     *
+     * @param options - 配置选项（会与全局配置合并）
+     * @returns 完整的 HttpClient 实例（允许修改拦截器）
+     *
+     * @example
+     * ```typescript
+     * @Injectable()
+     * export class FileService {
+     *   private fileClient: HttpClient;
+     *
+     *   constructor(private platformHttp: PlatformHttpClientService) {
+     *     // 创建超时 60 秒的独立实例
+     *     this.fileClient = this.platformHttp.create({
+     *       config: { timeout: 60000 }
+     *     });
+     *
+     *     // 为这个实例注册拦截器（不影响全局实例）
+     *     this.fileClient.interceptors.request.use((config) => {
+     *       console.log('File upload starting...');
+     *       return config;
+     *     });
+     *   }
+     *
+     *   async uploadFile(file: Buffer) {
+     *     return this.fileClient.post('/file/upload', file);
+     *   }
+     * }
+     * ```
+     */
+    create(options?: PlatformHttpClientOptions): HttpClient;
+    /**
+     * 创建一个带全局拦截器的独立 HttpClient 实例
+     *
+     * 与 `create()` 类似，但会自动注册全局拦截器（日志、x-tt-env 透传等）
+     * 适用于需要保留平台标准行为，同时又需要添加自定义拦截器的场景
+     *
+     * @param options - 配置选项（会与全局配置合并）
+     * @returns 完整的 HttpClient 实例（带全局拦截器，允许添加更多拦截器）
+     *
+     * @example
+     * ```typescript
+     * const client = this.platformHttp.createWithGlobalInterceptors();
+     * // 客户端已包含日志和 x-tt-env 拦截器
+     * // 可以继续添加自定义拦截器
+     * client.interceptors.request.use((config) => {
+     *   config.headers['x-custom'] = 'value';
+     *   return config;
+     * });
+     * ```
+     */
+    createWithGlobalInterceptors(options?: PlatformHttpClientOptions): HttpClient;
+    /**
+     * 注册全局拦截器（用于单例实例）
+     */
+    private registerGlobalInterceptors;
+    /**
+     * 为指定的 HttpClient 实例注册标准拦截器
+     *
+     * 包含：
+     * - 请求日志记录
+     * - x-tt-env header 透传
+     * - 响应日志记录
+     * - 错误日志记录
+     */
+    private registerInterceptorsForClient;
+}
+
+export { type ApiNotFoundResponse, CsrfMiddleware, CsrfTokenMiddleware, FileService, type PlatformHttpClientOptions, PlatformHttpClientService, PlatformModule, type PlatformModuleOptions, StaticModule, UserContextMiddleware, ViewContextMiddleware, configureApp };