chore: initialize qiming workspace repository
This commit is contained in:
Codex
@@ -0,0 +1,269 @@
|
||||
# LogHttpClientAdapter 使用说明
|
||||
|
||||
## 概述
|
||||
|
||||
`LogHttpClientAdapter` 是一个用于与 Rust 日志服务进行 HTTP 通信的客户端适配器。它提供了与 Rust 工程接口一一对应的 HTTP 请求方法，支持智能体日志的新增、批量新增和搜索功能。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- **健康检查**：检查 Rust 服务的健康状态
|
||||
- **就绪检查**：检查 Rust 服务是否就绪
|
||||
- **日志新增**：支持单个和批量新增智能体日志
|
||||
- **日志搜索**：支持条件查询、分页和排序
|
||||
- **异步支持**：所有方法都提供异步和同步两个版本
|
||||
- **配置化**：通过配置文件管理连接参数
|
||||
- **配置验证**：启动时验证必需配置，缺失时抛出异常
|
||||
|
||||
## 配置说明
|
||||
|
||||
在主配置文件（如 `application-dev.yml`）中添加以下配置：
|
||||
|
||||
```yaml
|
||||
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. 依赖注入
|
||||
|
||||
```java
|
||||
@Service
|
||||
public class LogService {
|
||||
|
||||
@Autowired
|
||||
private LogHttpClientAdapter logHttpClientAdapter;
|
||||
|
||||
// ... 业务方法
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 健康检查
|
||||
|
||||
```java
|
||||
// 异步方式
|
||||
CompletableFuture<Boolean> healthFuture = logHttpClientAdapter.healthCheck();
|
||||
Boolean isHealthy = healthFuture.get();
|
||||
|
||||
// 同步方式（不推荐在高并发场景使用）
|
||||
Boolean isHealthy = logHttpClientAdapter.healthCheck().join();
|
||||
```
|
||||
|
||||
### 3. 新增单个日志
|
||||
|
||||
```java
|
||||
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. 批量新增日志
|
||||
|
||||
```java
|
||||
List<AgentLogEntry> logEntries = Arrays.asList(
|
||||
AgentLogEntry.builder()...build(),
|
||||
AgentLogEntry.builder()...build()
|
||||
);
|
||||
|
||||
// 异步方式
|
||||
CompletableFuture<Boolean> result = logHttpClientAdapter.batchAddAgentLogs(logEntries);
|
||||
|
||||
// 同步方式
|
||||
boolean success = logHttpClientAdapter.batchAddAgentLogsSync(logEntries);
|
||||
```
|
||||
|
||||
### 5. 搜索日志
|
||||
|
||||
```java
|
||||
// 构建搜索条件
|
||||
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 块处理异常：
|
||||
|
||||
```java
|
||||
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. 配置正确的服务地址
|
||||
|
||||
```bash
|
||||
# 运行特定测试类
|
||||
mvn test -Dtest=LogHttpClientAdapterTest
|
||||
|
||||
# 运行所有测试
|
||||
mvn test
|
||||
```
|
||||
|
||||
## 配置示例
|
||||
|
||||
### 开发环境配置
|
||||
```yaml
|
||||
log-module:
|
||||
log:
|
||||
rust-service:
|
||||
base-url: http://localhost:8098
|
||||
|
||||
log:
|
||||
level:
|
||||
com.xspaceagi.domain.service.LogHttpClientAdapter: DEBUG
|
||||
```
|
||||
|
||||
### 生产环境配置
|
||||
```yaml
|
||||
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
|
||||
```
|
||||
Reference in New Issue
Block a user