@lark-apaas/fullstack-nestjs-core 1.1.22-beta.5 → 1.1.23-alpha.0

package/dist/index.cjs

@@ -39,6 +39,7 @@ __export(index_exports, {
   DevToolsModule: () => import_nestjs_openapi_devtools2.DevToolsModule,
   DevToolsV2Module: () => import_nestjs_openapi_devtools2.DevToolsV2Module,
   FileService: () => FileService,
+  PlatformHttpClientService: () => PlatformHttpClientService,
   PlatformModule: () => PlatformModule,
   UserContextMiddleware: () => UserContextMiddleware,
   ViewContextMiddleware: () => ViewContextMiddleware,
@@ -759,10 +760,47 @@ var PlatformHttpClientService = class _PlatformHttpClientService {
     });
   }
   /**
-  * 注册全局拦截器
+  * 创建一个带全局拦截器的独立 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) {
+    const client = this.create(options);
+    this.registerInterceptorsForClient(client);
+    return client;
+  }
+  /**
+  * 注册全局拦截器（用于单例实例）
   */
   registerGlobalInterceptors() {
-    this.client.interceptors.request.use((config) => {
+    this.registerInterceptorsForClient(this.client);
+  }
+  /**
+  * 为指定的 HttpClient 实例注册标准拦截器
+  *
+  * 包含：
+  * - 请求日志记录
+  * - x-tt-env header 透传
+  * - 响应日志记录
+  * - 错误日志记录
+  */
+  registerInterceptorsForClient(client) {
+    client.interceptors.request.use((config) => {
       this.logger.debug(`Server SDK HTTP Request: ${config.method?.toUpperCase()} ${config.url}`);
       const ttEnv = this.requestContext.get("ttEnv");
       if (ttEnv) {
@@ -776,7 +814,7 @@ var PlatformHttpClientService = class _PlatformHttpClientService {
       this.logger.error("Server SDK HTTP Request Error", error, "HttpService");
       return Promise.reject(error);
     });
-    this.client.interceptors.response.use((response) => {
+    client.interceptors.response.use((response) => {
       this.logger.debug(`Server SDK HTTP Response: ${response.status} ${response.url}`);
       return response;
     }, (error) => {
@@ -1290,6 +1328,15 @@ var PlatformModule = class _PlatformModule {
             PlatformHttpClientService
           ]
         },
+        {
+          provide: import_nestjs_common5.HTTP_CLIENT_FACTORY,
+          useFactory: /* @__PURE__ */ __name((svc) => ({
+            create: /* @__PURE__ */ __name((options2) => svc.createWithGlobalInterceptors(options2), "create")
+          }), "useFactory"),
+          inject: [
+            PlatformHttpClientService
+          ]
+        },
         HttpInterceptorService,
         {
           provide: import_core2.APP_INTERCEPTOR,
@@ -1303,6 +1350,8 @@ var PlatformModule = class _PlatformModule {
         import_nestjs_common5.CommonModule,
         import_nestjs_common5.OBSERVABLE_SERVICE,
         import_nestjs_common6.PLATFORM_HTTP_CLIENT,
+        import_nestjs_common5.HTTP_CLIENT_FACTORY,
+        PlatformHttpClientService,
         import_nestjs_capability.CapabilityModule,
         FileService
       ]
@@ -1386,6 +1435,7 @@ var import_nestjs_authzpaas2 = require("@lark-apaas/nestjs-authzpaas");
   DevToolsModule,
   DevToolsV2Module,
   FileService,
+  PlatformHttpClientService,
   PlatformModule,
   UserContextMiddleware,
   ViewContextMiddleware,

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';
@@ -169,4 +169,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, 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';
@@ -169,4 +169,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, UserContextMiddleware, ViewContextMiddleware, configureApp };

package/dist/index.js

@@ -4,7 +4,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 // src/modules/platform/module.ts
 import { Global, Module, ValidationPipe } from "@nestjs/common";
 import { APP_INTERCEPTOR, APP_PIPE } from "@nestjs/core";
-import { CommonModule, OBSERVABLE_SERVICE as OBSERVABLE_SERVICE2 } from "@lark-apaas/nestjs-common";
+import { CommonModule, OBSERVABLE_SERVICE as OBSERVABLE_SERVICE2, HTTP_CLIENT_FACTORY } from "@lark-apaas/nestjs-common";
 import { ConfigModule, ConfigService } from "@nestjs/config";
 import { NestjsObservableModule as ObservableModule, Observable, ObservableTraceMiddleware, TraceInterceptor } from "@lark-apaas/nestjs-observable";
 import { HttpModule } from "@nestjs/axios";
@@ -714,10 +714,47 @@ var PlatformHttpClientService = class _PlatformHttpClientService {
     });
   }
   /**
-  * 注册全局拦截器
+  * 创建一个带全局拦截器的独立 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) {
+    const client = this.create(options);
+    this.registerInterceptorsForClient(client);
+    return client;
+  }
+  /**
+  * 注册全局拦截器（用于单例实例）
   */
   registerGlobalInterceptors() {
-    this.client.interceptors.request.use((config) => {
+    this.registerInterceptorsForClient(this.client);
+  }
+  /**
+  * 为指定的 HttpClient 实例注册标准拦截器
+  *
+  * 包含：
+  * - 请求日志记录
+  * - x-tt-env header 透传
+  * - 响应日志记录
+  * - 错误日志记录
+  */
+  registerInterceptorsForClient(client) {
+    client.interceptors.request.use((config) => {
       this.logger.debug(`Server SDK HTTP Request: ${config.method?.toUpperCase()} ${config.url}`);
       const ttEnv = this.requestContext.get("ttEnv");
       if (ttEnv) {
@@ -731,7 +768,7 @@ var PlatformHttpClientService = class _PlatformHttpClientService {
       this.logger.error("Server SDK HTTP Request Error", error, "HttpService");
       return Promise.reject(error);
     });
-    this.client.interceptors.response.use((response) => {
+    client.interceptors.response.use((response) => {
       this.logger.debug(`Server SDK HTTP Response: ${response.status} ${response.url}`);
       return response;
     }, (error) => {
@@ -1245,6 +1282,15 @@ var PlatformModule = class _PlatformModule {
             PlatformHttpClientService
           ]
         },
+        {
+          provide: HTTP_CLIENT_FACTORY,
+          useFactory: /* @__PURE__ */ __name((svc) => ({
+            create: /* @__PURE__ */ __name((options2) => svc.createWithGlobalInterceptors(options2), "create")
+          }), "useFactory"),
+          inject: [
+            PlatformHttpClientService
+          ]
+        },
         HttpInterceptorService,
         {
           provide: APP_INTERCEPTOR,
@@ -1258,6 +1304,8 @@ var PlatformModule = class _PlatformModule {
         CommonModule,
         OBSERVABLE_SERVICE2,
         PLATFORM_HTTP_CLIENT3,
+        HTTP_CLIENT_FACTORY,
+        PlatformHttpClientService,
         CapabilityModule,
         FileService
       ]
@@ -1340,6 +1388,7 @@ export {
   DevToolsModule,
   DevToolsV2Module2 as DevToolsV2Module,
   FileService,
+  PlatformHttpClientService,
   PlatformModule,
   UserContextMiddleware,
   ViewContextMiddleware,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-nestjs-core",
-  "version": "1.1.22-beta.5",
+  "version": "1.1.23-alpha.0",
   "description": "FullStack Nestjs Core",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,12 +42,12 @@
     "@lark-apaas/file-service": "^0.1.1",
     "@lark-apaas/http-client": "^0.1.2",
     "@lark-apaas/nestjs-authnpaas": "^1.0.2",
-    "@lark-apaas/nestjs-authzpaas": "^0.1.1",
-    "@lark-apaas/nestjs-capability": "^0.1.4-beta.4",
-    "@lark-apaas/nestjs-common": "^0.1.3",
-    "@lark-apaas/nestjs-datapaas": "^1.0.9",
-    "@lark-apaas/nestjs-logger": "^1.0.9",
-    "@lark-apaas/nestjs-observable": "^0.0.4",
+    "@lark-apaas/nestjs-authzpaas": "^0.1.2-alpha.0",
+    "@lark-apaas/nestjs-capability": "^0.1.5-alpha.0",
+    "@lark-apaas/nestjs-common": "^0.1.4-alpha.0",
+    "@lark-apaas/nestjs-datapaas": "^1.0.10-alpha.0",
+    "@lark-apaas/nestjs-logger": "^1.0.10-alpha.0",
+    "@lark-apaas/nestjs-observable": "^0.0.5-alpha.0",
     "@lark-apaas/nestjs-openapi-devtools": "^1.0.9",
     "@lark-apaas/nestjs-trigger": "^0.0.2",
     "@nestjs/axios": "^4.0.1",