# 接口报错日志记录功能说明

## 📋 功能概述

本项目已实现统一的接口报错日志记录功能，可以自动拦截并记录所有Controller层接口的异常信息。

## 🎯 核心组件

### 1. ControllerLogAspect（AOP切面）
**位置**: `cn.com.goldenwater.dcproj.aspect.ControllerLogAspect`

**功能**:
- ✅ 自动拦截所有Controller包的请求
- ✅ 记录完整的请求信息（URL、方法、参数、IP等）
- ✅ 记录响应结果和耗时
- ✅ 捕获并记录所有异常详情
- ✅ 性能监控（超过3秒的请求会记录警告）

**记录的详细信息**:
```
- 请求URL
- 请求方法（GET/POST等）
- 类名.方法名
- IP地址（支持代理获取真实IP）
- 用户ID（从请求头获取）
- User-Agent
- 请求参数
- 响应结果
- 耗时（毫秒）
```

### 2. GlobalExceptionHandler（全局异常处理器）
**位置**: `cn.com.goldenwater.dcproj.intercepter.GlobalExceptionHandler`

**功能**:
- ✅ 统一处理所有类型的异常
- ✅ 记录详细的错误上下文信息
- ✅ 返回友好的错误提示

**处理的异常类型**:
- `MethodArgumentTypeMismatchException` - 参数类型不匹配
- `TypeMismatchException` - 类型转换异常
- `MissingServletRequestParameterException` - 缺少必要参数
- `BaseException` - 业务异常
- `NoHandlerFoundException` - 请求路径不存在
- `CheckException` - 校验异常
- `HttpRequestMethodNotSupportedException` - 请求方法不支持
- `Exception` - 其他所有异常（兜底处理）

## 📁 日志文件

### 日志输出位置

根据 `log4j.properties` 配置，日志会输出到以下文件：

1. **主日志文件**: `./logs/dc-po.log`
   - 记录所有INFO级别的日志
   - 包含正常的请求日志和系统运行日志

2. **通用错误日志**: `./logs/dc-po-error.log`
   - 记录所有ERROR级别的日志
   - 包含系统各个层面的错误

3. **接口错误专用日志**: `./logs/interface-error.log` ⭐
   - **专门记录接口调用的错误**
   - 包含最详细的错误上下文信息
   - 便于快速定位接口问题

### 日志格式

```
%d [%t] %-5p [%c] - %m%n
```

示例：
```
2026-05-29 10:30:45 [http-nio-9002-exec-1] ERROR [ERROR_LOGGER] - 
========== 全局异常捕获 ==========
异常时间: 2026-05-29T10:30:45.123
异常类型: 系统异常
请求URL: /dc/pageoffice/hcbg/word/12345
请求方法: GET
查询字符串: 无
IP地址: 192.168.1.100
用户ID: user001
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)...
请求参数: 无
异常类名: java.lang.NullPointerException
异常消息: Cannot invoke method on null object
====================================
```

## 🔍 日志级别说明

| 级别 | 用途 | 示例 |
|------|------|------|
| INFO | 正常请求流程 | 接口调用开始/结束、响应结果 |
| WARN | 警告信息 | 接口响应缓慢（>3秒） |
| ERROR | 错误信息 | 所有异常、系统故障 |
| DEBUG | 调试信息 | 详细参数、中间过程 |

## 💡 使用示例

### 正常请求日志
```
========== 接口请求开始 ==========
请求URL: /dc/pageoffice/hcbg/show
请求方法: GET
类名.方法名: cn.com.goldenwater.dcproj.controller.dc.DcPageOfficeReportController.showIndex
IP地址: 192.168.1.100
请求参数: [adCode=350000]
响应结果: null
耗时: 125ms
========== 接口请求结束 ==========
```

### 异常请求日志
```
========== 接口异常详情 ==========
异常时间: 2026-05-29T10:30:45.123
请求URL: /dc/pageoffice/hcbg/word/12345
请求方法: GET
类名.方法名: cn.com.goldenwater.dcproj.controller.dc.DcPageOfficeReportController.showWord
IP地址: 192.168.1.100
用户ID: user001
User-Agent: Mozilla/5.0...
请求参数: []
耗时: 2345ms
异常类型: java.lang.RuntimeException
异常消息: 数据库连接失败
====================================
```

## ⚙️ 配置说明

### log4j.properties 关键配置

```properties
# 专门的接口错误日志记录器
log4j.logger.ERROR_LOGGER=ERROR, ERROR_FILE
log4j.additivity.ERROR_LOGGER=false

# 错误日志文件配置
log4j.appender.ERROR_FILE = org.apache.log4j.DailyRollingFileAppender
log4j.appender.ERROR_FILE.File = ./logs/interface-error.log
log4j.appender.ERROR_FILE.DatePattern='.'yyyy-MM-dd'.log'
log4j.appender.ERROR_FILE.Append = true
log4j.appender.ERROR_FILE.Threshold = ERROR
```

### 自定义配置

如果需要调整性能警告阈值（默认3秒），修改 `ControllerLogAspect.java`：

```java
// 如果耗时超过3秒，记录警告日志
if (duration > 3000) {  // 修改这里的数值
    logger.warn("【性能警告】接口响应缓慢 - URL: {}, 耗时: {}ms", uri, duration);
}
```

## 🎨 特性亮点

### 1. 双重日志记录
- 使用专门的 `ERROR_LOGGER` 记录到独立文件
- 同时用普通logger记录，方便快速查看

### 2. 完整的上下文信息
- 请求URL、方法、参数
- 用户信息（persId）
- 客户端信息（IP、User-Agent）
- 异常堆栈跟踪

### 3. 性能监控
- 自动记录每个接口的耗时
- 超过阈值的请求会记录警告日志
- 便于发现性能瓶颈

### 4. 真实IP获取
支持多种代理场景下的真实IP获取：
- X-Forwarded-For
- X-Real-IP
- Proxy-Client-IP
- WL-Proxy-Client-IP

### 5. 防止日志爆炸
- 日志记录本身有异常保护
- 避免因为日志记录导致系统崩溃

## 🔧 维护建议

### 1. 定期清理日志
日志文件按天滚动，建议保留最近30天的日志：
```bash
# Linux/Mac
find ./logs -name "interface-error.log.*" -mtime +30 -delete

# Windows PowerShell
Get-ChildItem .\logs\interface-error.log.* | Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } | Remove-Item
```

### 2. 监控日志文件大小
如果日志文件过大，可以考虑：
- 调整日志级别（将INFO改为WARN）
- 增加日志清理频率
- 使用日志分析工具（如ELK）

### 3. 常见问题排查

**问题1**: 没有生成日志文件
- 检查 `./logs` 目录是否存在
- 检查应用是否有写入权限
- 检查log4j配置是否正确加载

**问题2**: 日志内容不完整
- 检查是否使用了正确的Logger
- 确认日志级别设置
- 查看控制台是否有错误信息

**问题3**: 性能影响
- AOP切面会有轻微的性能开销（通常<1ms）
- 如果担心性能，可以将INFO日志改为DEBUG级别
- 生产环境建议关闭DEBUG日志

## 📊 日志分析

### 快速查看最近的错误
```bash
# Linux/Mac
tail -n 100 ./logs/interface-error.log

# Windows
Get-Content .\logs\interface-error.log -Tail 100
```

### 统计错误数量
```bash
# Linux/Mac
grep -c "全局异常捕获" ./logs/interface-error.log.2026-05-29.log

# Windows PowerShell
Select-String -Path .\logs\interface-error.log.2026-05-29.log -Pattern "全局异常捕获" | Measure-Object | Select-Object -ExpandProperty Count
```

### 查找特定接口的错误
```bash
# Linux/Mac
grep "/dc/pageoffice/hcbg/word" ./logs/interface-error.log

# Windows PowerShell
Select-String -Path .\logs\interface-error.log -Pattern "/dc/pageoffice/hcbg/word"
```

## 🚀 最佳实践

1. **开发环境**: 保持DEBUG级别，便于调试
2. **测试环境**: 使用INFO级别，记录完整流程
3. **生产环境**: 使用WARN级别，只记录重要信息
4. **定期检查**: 每周检查一次错误日志，及时发现潜在问题
5. **告警机制**: 对关键错误设置告警（可集成钉钉、企业微信等）

## 📞 技术支持

如有问题，请联系技术团队或查看详细代码注释。

---
**更新日期**: 2026-05-29  
**版本**: v1.0