# trace-log

**Repository Path**: silzhan/trace-log

## Basic Information

- **Project Name**: trace-log
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-29
- **Last Updated**: 2025-06-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TraceLog 使用说明

## 概述

TraceLog 是一个基于 AOP 的方法调用追踪功能，可以自动记录方法的请求参数、响应结果、执行时间等信息，并支持从JSON请求体中提取特定的业务字段。

## 功能特性

- 自动生成唯一的 traceId
- 记录请求参数和响应结果
- 记录方法执行时间
- 支持异常信息记录
- 异步发送追踪数据
- 可配置是否记录请求/响应/异常
- 使用BeanUtil反射方式自动提取业务字段（支持驼峰命名和蛇形命名）
- 自动过滤HttpServletRequest参数，避免序列化问题

## 使用方法

### 1. 基本使用

在需要追踪的方法上添加 `@TraceLog` 注解：

```java
import com.dhpay.frontend.infra.conf.TraceLog;

@TraceLog("查询用户信息")
@GetMapping("/user/{id}")
public Map<String, Object> getUserInfo(@PathVariable String id) {
    // 方法实现
    return result;
}
```

### 2. 高级配置

```java
@TraceLog(
    value = "敏感操作",           // 操作描述
    logRequest = true,           // 是否记录请求参数（默认true）
    logResponse = false,         // 是否记录响应结果（默认true）
    logException = true          // 是否记录异常信息（默认true）
)
@PostMapping("/sensitive")
public Map<String, Object> sensitiveOperation(@RequestBody Map<String, Object> request) {
    // 方法实现
    return result;
}
```

### 3. 业务字段提取

系统会自动从JSON请求体中提取以下业务字段：

- `transOrderId` / `trans_order_id` - 交易订单ID
- `merchantOrderId` / `merchant_order_id` - 商户订单ID
- `orderNo` / `order_no` - 订单号
- `remark` - 备注
- `remark1` - 备注1
- `remark2` - 备注2
- `remark3` - 备注3
- `invoiceId` / `invoice_id` - 发票ID

支持驼峰命名和蛇形命名两种格式。

### 4. 参数过滤

系统会自动过滤以下类型的参数，避免序列化问题：
- `HttpServletRequest` - HTTP请求对象
- `HttpServletResponse` - HTTP响应对象
- `MultipartFile` - 文件上传对象

## 追踪数据字段

TraceLogDto 包含以下字段：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | String | 唯一ID |
| traceId | String | 唯一追踪ID |
| requestParam | String | 请求参数（JSON格式，已过滤HttpServletRequest） |
| responseParam | String | 响应结果（JSON格式） |
| httpStatusCode | int | HTTP状态码 |
| url | String | 请求URL |
| method | String | 方法名 |
| timestamp | long | 请求开始时间戳 |
| endTimestamp | long | 响应结束时间戳 |
| duration | long | 执行耗时（毫秒） |
| errorMsg | String | 异常信息 |
| header | String | 请求头信息 |
| opType | String | 操作类型描述 |
| transOrderId | String | 交易订单ID（自动提取） |
| merchantOrderId | String | 商户订单ID（自动提取） |
| orderNo | String | 订单号（自动提取） |
| remark | String | 备注（自动提取） |
| remark1 | String | 备注1（自动提取） |
| remark2 | String | 备注2（自动提取） |
| remark3 | String | 备注3（自动提取） |
| invoiceId | String | 发票ID（自动提取） |

## 配置说明

### 1. 启用 AOP

确保项目中已启用 AOP 功能，在配置类中添加：

```java
@EnableAspectJAutoProxy
@Configuration
public class AopConfig {
    // 配置内容
}
```

### 2. 配置追踪服务地址

在 `application.properties` 中配置：

```properties
# 追踪服务地址
trace.log.url=http://trace-service/api/trace
```

## 使用示例

### 示例1：基本接口追踪

```java
import com.dhpay.frontend.infra.conf.TraceLog;

@TraceLog("支付接口")
@PostMapping("/pay")
public PayResult pay(@RequestBody PayRequest request) {
    // 支付逻辑
    return payService.process(request);
}
```

### 示例2：包含HttpServletRequest的接口

```java
@TraceLog("用户信息查询")
@GetMapping("/user/info")
public Map<String, Object> getUserInfo(@RequestParam String userId, 
                                      HttpServletRequest request) {
    // HttpServletRequest参数会被自动过滤，不会出现在requestParam中
    // 但业务字段提取仍然会正常工作
    
    return Map.of("status", "success", "userId", userId);
}
```

### 示例3：业务字段提取 - 驼峰命名

```java
@TraceLog("支付订单创建")
@PostMapping("/payment/create")
public Map<String, Object> createPaymentOrder(@RequestBody Map<String, Object> request) {
    // 请求体示例：
    // {
    //   "transOrderId": "TXN123456",
    //   "merchantOrderId": "MERCH789",
    //   "orderNo": "ORD001",
    //   "remark": "测试订单",
    //   "remark1": "备注1",
    //   "remark2": "备注2",
    //   "remark3": "备注3",
    //   "invoiceId": "INV001"
    // }
    
    return Map.of("status", "success");
}
```

### 示例4：业务字段提取 - 蛇形命名

```java
@TraceLog("支付订单查询")
@PostMapping("/payment/query")
public Map<String, Object> queryPaymentOrder(@RequestBody Map<String, Object> request) {
    // 请求体示例：
    // {
    //   "trans_order_id": "TXN123456",
    //   "merchant_order_id": "MERCH789",
    //   "order_no": "ORD001",
    //   "remark": "测试订单",
    //   "remark1": "备注1",
    //   "remark2": "备注2",
    //   "remark3": "备注3",
    //   "invoice_id": "INV001"
    // }
    
    return Map.of("status", "success");
}
```

### 示例5：混合命名示例

```java
@TraceLog("发票处理")
@PostMapping("/invoice/process")
public Map<String, Object> processInvoice(@RequestBody Map<String, Object> request) {
    // 请求体示例：
    // {
    //   "transOrderId": "TXN123456",
    //   "merchant_order_id": "MERCH789",
    //   "orderNo": "ORD001",
    //   "remark": "测试订单",
    //   "remark1": "备注1",
    //   "remark2": "备注2",
    //   "remark3": "备注3",
    //   "invoice_id": "INV001"
    // }
    
    return Map.of("status", "success");
}
```

### 示例6：只记录请求的敏感接口

```java
@TraceLog(value = "用户登录", logResponse = false)
@PostMapping("/login")
public LoginResult login(@RequestBody LoginRequest request) {
    // 登录逻辑
    return loginService.authenticate(request);
}
```

### 示例7：异常处理

```java
@TraceLog("文件上传")
@PostMapping("/upload")
public UploadResult upload(@RequestParam("file") MultipartFile file) {
    try {
        return fileService.upload(file);
    } catch (Exception e) {
        // 异常会被自动记录
        throw e;
    }
}
```

## 文件位置

- 注解定义：`com.dhpay.frontend.infra.conf.TraceLog`
- AOP拦截器：`com.dhpay.frontend.infra.conf.TraceLogAspect`
- 示例代码：`com.dhpay.frontend.web.action.example.TraceLogExampleController`

## 异常处理机制

当方法抛出异常时，AOP拦截器会自动捕获并记录异常信息，包括：
- 异常消息
- HTTP状态码（500）
- 异常发生时间
- 执行耗时

异常信息会被异步发送到追踪系统，不会影响主业务流程。

## 业务字段提取机制

### 1. BeanUtil反射方式

系统使用Hutool的BeanUtil进行反射操作，提供以下优势：
- 自动类型转换
- 性能优化
- 容错处理
- 支持复杂对象结构

### 2. 提取策略

1. **直接复制**：首先尝试使用`BeanUtil.copyProperties()`直接复制属性
2. **Map转换**：如果直接复制失败，将对象转换为Map后处理
3. **命名兼容**：支持驼峰命名和蛇形命名两种格式
4. **容错处理**：单个字段提取失败不影响其他字段

### 3. 命名支持

支持两种命名格式：
- 驼峰命名：`transOrderId`, `merchantOrderId`, `orderNo`
- 蛇形命名：`trans_order_id`, `merchant_order_id`, `order_no`

### 4. 提取逻辑

- 优先尝试驼峰命名
- 如果驼峰命名不存在，尝试蛇形命名
- 支持混合使用两种命名格式
- 自动跳过null值和无法解析的参数
- 使用反射动态设置属性值

### 5. 性能优化

- 找到业务字段后立即停止搜索
- 使用BeanUtil进行高效的属性复制
- 异常处理不影响主业务流程
- 异步处理避免性能影响

## 参数过滤机制

### 1. 自动过滤

系统会自动过滤以下类型的参数，避免序列化问题：
- `HttpServletRequest` - HTTP请求对象
- `HttpServletResponse` - HTTP响应对象
- `MultipartFile` - 文件上传对象

### 2. 过滤策略

1. **类型检查**：检查参数是否为需要过滤的类型
2. **数组重构**：创建新的参数数组，排除过滤类型
3. **序列化优化**：只序列化有效的业务参数
4. **业务字段提取**：仍然从所有参数中提取业务字段

### 3. 优势

- 避免序列化异常
- 减少日志数据量
- 提高性能
- 保护敏感信息

## 注意事项

1. **性能影响**：追踪功能会异步执行，不会影响主业务流程的性能
2. **数据安全**：敏感信息（如密码）建议设置 `logResponse = false`
3. **异常处理**：异常信息会被自动记录，无需手动处理
4. **序列化**：请求和响应参数会通过 FastJson 序列化为 JSON 格式
5. **字段提取**：业务字段提取失败不会影响正常的追踪功能
6. **反射性能**：BeanUtil反射方式性能优于手动逐个提取
7. **参数过滤**：HttpServletRequest等参数会被自动过滤，避免序列化问题

## 扩展功能

如需扩展功能，可以：

1. 修改 `TraceLogDto` 添加更多字段
2. 在 `TraceLogAspect` 中添加自定义逻辑
3. 修改 `TrackGateway` 中的发送逻辑
4. 添加数据库持久化功能
5. 扩展业务字段提取逻辑
6. 自定义字段映射规则
7. 扩展参数过滤规则