qiming/qiming-backend/app-platform-modules/app-platform-log/app-platform-log-domain

LogHttpClientAdapter 使用说明

概述

LogHttpClientAdapter 是一个用于与 Rust 日志服务进行 HTTP 通信的客户端适配器。它提供了与 Rust 工程接口一一对应的 HTTP 请求方法，支持智能体日志的新增、批量新增和搜索功能。

功能特性

• 健康检查：检查 Rust 服务的健康状态
• 就绪检查：检查 Rust 服务是否就绪
• 日志新增：支持单个和批量新增智能体日志
• 日志搜索：支持条件查询、分页和排序
• 异步支持：所有方法都提供异步和同步两个版本
• 配置化：通过配置文件管理连接参数
• 配置验证：启动时验证必需配置，缺失时抛出异常

配置说明

在主配置文件（如 application-dev.yml）中添加以下配置：

log-module:
  log:
    rust-service:
      # Rust 日志服务的基础 URL（必填）
      base-url: http://localhost:8098
      # 连接超时时间（秒），默认 10
      connect-timeout-seconds: 10
      # 写入超时时间（秒），默认 30
      write-timeout-seconds: 30
      # 读取超时时间（秒），默认 30
      read-timeout-seconds: 30
      # 是否启用连接池，默认 true
      enable-connection-pool: true
      # 最大空闲连接数，默认 5
      max-idle-connections: 5
      # 连接保持存活时间（分钟），默认 5
      keep-alive-duration-minutes: 5

# 日志级别配置（复用现有的 log.level 配置）
log:
  level:
    com.xspaceagi.domain.service.LogHttpClientAdapter: DEBUG

注意：base-url 是必填配置项，如果未配置或为空，应用启动时会抛出异常。

使用示例

1. 依赖注入

@Service
public class LogService {
    
    @Autowired
    private LogHttpClientAdapter logHttpClientAdapter;
    
    // ... 业务方法
}

2. 健康检查

// 异步方式
CompletableFuture<Boolean> healthFuture = logHttpClientAdapter.healthCheck();
Boolean isHealthy = healthFuture.get();

// 同步方式（不推荐在高并发场景使用）
Boolean isHealthy = logHttpClientAdapter.healthCheck().join();

3. 新增单个日志

AgentLogEntry logEntry = AgentLogEntry.builder()
    .requestId("req_001")
    .conversationId("session_001")
    .userUid("user_123")
    .tenantId("tenant_001")
    .userInput("用户输入内容")
    .output("系统输出内容")
    .inputToken(50)
    .outputToken(100)
    .requestStartTime(Instant.now().minusSeconds(5))
    .requestEndTime(Instant.now())
    .elapsedTimeMs(5000L)
    .status("success")
    .build();

// 异步方式
CompletableFuture<Boolean> result = logHttpClientAdapter.addAgentLog(logEntry);

// 同步方式
boolean success = logHttpClientAdapter.addAgentLogSync(logEntry);

4. 批量新增日志

List<AgentLogEntry> logEntries = Arrays.asList(
    AgentLogEntry.builder()...build(),
    AgentLogEntry.builder()...build()
);

// 异步方式
CompletableFuture<Boolean> result = logHttpClientAdapter.batchAddAgentLogs(logEntries);

// 同步方式
boolean success = logHttpClientAdapter.batchAddAgentLogsSync(logEntries);

5. 搜索日志

// 构建搜索条件
AgentLogSearchParams searchParams = AgentLogSearchParams.builder()
    .tenantId("tenant_001")
    .userUid("user_123")
    .userInput("搜索关键词")
    .startTime(Instant.now().minus(Duration.ofDays(1)))
    .endTime(Instant.now())
    .build();

// 构建搜索请求
AgentLogSearchRequest searchRequest = AgentLogSearchRequest.builder()
    .queryFilter(searchParams)
    .current(1L)
    .pageSize(20L)
    .orders(Arrays.asList(
        AgentLogSearchRequest.OrderBy.builder()
            .column("request_start_time")
            .asc(false)
            .build()
    ))
    .build();

// 异步搜索
CompletableFuture<AgentLogSearchResult> future = logHttpClientAdapter.searchAgentLogs(searchRequest);
AgentLogSearchResult result = future.get();

// 同步搜索
AgentLogSearchResult result = logHttpClientAdapter.searchAgentLogsSync(searchRequest);

// 处理搜索结果
System.out.println("总记录数: " + result.getTotal());
System.out.println("当前页: " + result.getCurrent());
System.out.println("每页大小: " + result.getSize());
result.getRecords().forEach(log -> {
    System.out.println("日志ID: " + log.getRequestId());
    System.out.println("用户输入: " + log.getUserInput());
});

模型类说明

AgentLogEntry

智能体日志条目，包含以下主要字段：

• requestId: 请求ID（必填）
• conversationId: 会话ID（必填）
• userUid: 用户UID（必填）
• tenantId: 租户ID（必填）
• spaceId: 空间ID（可选）
• userInput: 用户输入内容
• output: 系统输出内容
• inputToken/outputToken: Token 数量
• requestStartTime/requestEndTime: 请求时间
• elapsedTimeMs: 耗时（毫秒）
• nodeType/nodeName/status: 节点信息

AgentLogSearchParams

搜索参数，支持多条件组合查询：

• 基础过滤：requestId, conversationId, userUid, tenantId, spaceId
• 全文搜索：userInput, output
• 时间范围：startTime, endTime

AgentLogSearchRequest

搜索请求包装类：

• queryFilter: 查询条件
• current: 当前页码
• pageSize: 每页大小
• orders: 排序条件列表

AgentLogSearchResult

搜索结果：

• records: 日志记录列表
• total: 总记录数
• current: 当前页
• size: 每页大小
• elapsedTimeMs: 查询耗时

错误处理

配置验证

客户端适配器在启动时会验证配置：

• 如果 base-url 未配置或为空，会抛出 IllegalArgumentException
• 错误信息会记录到日志中

运行时异常

客户端适配器已经内置了基本的错误处理：

• 网络异常会被记录并返回 false 或抛出异常
• HTTP 错误状态码会被记录并处理
• JSON 序列化/反序列化错误会被捕获

在业务代码中建议使用 try-catch 块处理异常：

try {
    AgentLogSearchResult result = logHttpClientAdapter.searchAgentLogsSync(searchRequest);
    // 处理搜索结果
} catch (Exception e) {
    log.error("搜索日志失败", e);
    // 处理错误情况
}

注意事项

1. 必填配置：log-module.log.rust-service.base-url 是必填配置，不能为空
2. 服务依赖：确保 Rust 日志服务正在运行并可访问
3. 线程安全：LogHttpClientAdapter 是线程安全的，可以在多线程环境中使用
4. 资源管理：应用关闭时会自动清理 HTTP 客户端资源
5. 配置优化：根据实际网络环境调整超时时间和连接池参数
6. 日志级别：通过 log.level 配置控制日志输出级别

测试

运行单元测试前确保：

1. Rust 服务正在运行
2. 配置正确的服务地址

# 运行特定测试类
mvn test -Dtest=LogHttpClientAdapterTest

# 运行所有测试
mvn test

配置示例

开发环境配置

log-module:
  log:
    rust-service:
      base-url: http://localhost:8098
      
log:
  level:
    com.xspaceagi.domain.service.LogHttpClientAdapter: DEBUG

生产环境配置

log-module:
  log:
    rust-service:
      base-url: http://rust-log-service:8098
      connect-timeout-seconds: 5
      write-timeout-seconds: 60
      read-timeout-seconds: 60
      max-idle-connections: 10
      
log:
  level:
    com.xspaceagi.domain.service.LogHttpClientAdapter: INFO