@lark-apaas/fullstack-nestjs-core 1.1.4 → 1.1.6-alpha.0

package/README.md

@@ -5,6 +5,7 @@ FullStack NestJS Core 是一个为 NestJS 全栈应用提供核心功能的工
 ## 特性
 
 - **平台模块**: 一站式集成 Config、Logger、Database、Auth 等核心功能
+- **HTTP 客户端**: 自动集成 @nestjs/axios，提供 HTTP 请求能力，自动打印请求日志
 - **CSRF 保护**: 提供完整的 CSRF Token 生成和验证机制
 - **用户上下文**: 自动从请求头中提取并注入用户上下文信息
 - **视图上下文**: 将用户信息和 CSRF Token 注入到模板渲染上下文
@@ -53,6 +54,7 @@ export class AppModule {}
 `PlatformModule` 自动集成：
 - ✅ ConfigModule (环境变量配置)
 - ✅ LoggerModule (日志系统)
+- ✅ HttpModule (HTTP 客户端，自动打印请求日志)
 - ✅ DataPaasModule (数据库连接)
 - ✅ AuthNPaasModule (认证系统)
 - ✅ UserContextMiddleware (用户上下文)
@@ -237,6 +239,169 @@ await DevToolsModule.mount(app, {
 });
 ```
 
+## HTTP 客户端
+
+PlatformModule 自动集成了 `@nestjs/axios`，提供开箱即用的 HTTP 请求能力。
+
+### 特性
+
+- ✅ **自动集成**: 导入 PlatformModule 后即可直接使用，无需额外配置
+- ✅ **自动日志**: 所有 HTTP 请求和响应自动打印到日志系统
+- ✅ **标准 API**: 完全遵循 @nestjs/axios 的标准用法
+- ✅ **默认配置**: 自动设置 5 秒超时和最多 5 次重定向
+
+### 基础使用
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { HttpService } from '@nestjs/axios';
+import { firstValueFrom } from 'rxjs';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+@Injectable()
+export class UserService {
+  constructor(private readonly httpService: HttpService) {}
+
+  async getUserById(id: string): Promise<User> {
+    const { data } = await firstValueFrom(
+      this.httpService.get<User>(`https://api.example.com/users/${id}`)
+    );
+    return data;
+  }
+
+  async createUser(userData: Partial<User>): Promise<User> {
+    const { data } = await firstValueFrom(
+      this.httpService.post<User>('https://api.example.com/users', userData)
+    );
+    return data;
+  }
+
+  async updateUser(id: string, userData: Partial<User>): Promise<User> {
+    const { data } = await firstValueFrom(
+      this.httpService.put<User>(`https://api.example.com/users/${id}`, userData)
+    );
+    return data;
+  }
+
+  async deleteUser(id: string): Promise<void> {
+    await firstValueFrom(
+      this.httpService.delete(`https://api.example.com/users/${id}`)
+    );
+  }
+}
+```
+
+### 带配置的请求
+
+```typescript
+async getUserWithHeaders(id: string) {
+  const { data } = await firstValueFrom(
+    this.httpService.get(`https://api.example.com/users/${id}`, {
+      headers: {
+        'Authorization': 'Bearer token',
+        'X-Custom-Header': 'value',
+      },
+      params: {
+        include: 'profile',
+      },
+      timeout: 10000, // 10秒超时
+    })
+  );
+  return data;
+}
+```
+
+### 自动日志输出
+
+所有 HTTP 请求会自动打印到日志系统：
+
+```
+[HttpService] HTTP Request {
+  method: 'GET',
+  url: 'https://api.example.com/users/123',
+  headers: { ... },
+  params: { include: 'profile' },
+  data: undefined
+}
+
+[HttpService] HTTP Response {
+  method: 'GET',
+  url: 'https://api.example.com/users/123',
+  status: 200,
+  statusText: 'OK',
+  data: { id: '123', name: 'John', email: 'john@example.com' }
+}
+```
+
+错误请求也会自动记录：
+
+```
+[HttpService] HTTP Response Error {
+  method: 'GET',
+  url: 'https://api.example.com/users/999',
+  status: 404,
+  statusText: 'Not Found',
+  data: { message: 'User not found' },
+  message: 'Request failed with status code 404'
+}
+```
+
+### 高级用法
+
+#### 直接访问 Axios 实例
+
+```typescript
+constructor(private readonly httpService: HttpService) {
+  // 访问底层的 axios 实例
+  const axiosInstance = this.httpService.axiosRef;
+
+  // 添加自定义拦截器
+  axiosInstance.interceptors.request.use((config) => {
+    config.headers['X-Custom'] = 'my-value';
+    return config;
+  });
+}
+```
+
+#### 使用 RxJS 操作符
+
+```typescript
+import { map, catchError } from 'rxjs/operators';
+import { of } from 'rxjs';
+
+async getUsers() {
+  return this.httpService.get<User[]>('https://api.example.com/users').pipe(
+    map(response => response.data),
+    catchError(error => {
+      console.error('Error fetching users:', error);
+      return of([]);
+    })
+  );
+}
+```
+
+### 默认配置
+
+PlatformModule 注册 HttpModule 时使用以下默认配置：
+
+```typescript
+HttpModule.register({
+  timeout: 5000,      // 5 秒超时
+  maxRedirects: 5,    // 最多 5 次重定向
+})
+```
+
+### 注意事项
+
+1. **记得使用 firstValueFrom**: @nestjs/axios 返回的是 Observable，需要转换为 Promise
+2. **记得解构 data**: 响应数据在 `response.data` 中
+3. **类型安全**: 使用泛型指定响应数据类型 `httpService.get<User>(...)`
+
 ## 中间件
 
 ### CsrfTokenMiddleware