Home Esplora Aiuto
Accedi
lql
/
ducha-pageoffice
1
0
Forka 0
File Problemi 0 Pull Requests 0 Wiki
Albero (Tree): 14e8398e24
Rami (Branch) Tag
ducha-pageoffic...
/
docs
/
接口报错日志说明.md

接口报错日志说明.md 7.4 KB
Cronologia Originale

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

📋 功能概述

本项目已实现统一的接口报错日志记录功能，可以自动拦截并记录所有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 关键配置

# 专门的接口错误日志记录器
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：

// 如果耗时超过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天的日志：

# 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日志

📊 日志分析

快速查看最近的错误

# Linux/Mac
tail -n 100 ./logs/interface-error.log

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

统计错误数量

# 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

查找特定接口的错误

# 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