06-日志和错误处理规范

概述

本规范基于项目现有代码实践，规定了日志记录和错误处理的统一标准。所有日志和错误处理必须遵循现有代码的实现方式，确保一致性和可维护性。

日志规范

日志框架

项目统一使用 SLF4J (Simple Logging Facade for Java) 作为日志门面。
底层实现使用 Logback。

在类中声明 Logger 实例：

private static final Logger logger = LoggerFactory.getLogger(ClassName.class);

日志级别

DEBUG: 用于调试信息，如方法调用参数、API 请求响应等。
INFO: 用于重要业务逻辑信息，如令牌过期等。
WARN: 用于警告信息，如 API 未返回预期数据。
ERROR: 用于错误信息，如异常发生时。

日志配置

日志配置文件位于 src/main/resources/logback-spring.xml。
输出到控制台和文件。
文件日志路径：${LOG_PATH}/app.log，默认 ./logs/app.log。
日志轮转：按日期轮转，保留 30 天历史日志。
日志格式：%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n。

在 application.yml 中配置日志级别：

logging:
level:
  root: info
  work.baiyun.chronicdiseaseapp: debug

日志使用原则

在服务实现类中使用 Logger 记录关键操作和异常。
使用占位符记录变量值，如 logger.debug("validateToken: token={}, userToken={}", token, ut)。
异常记录时包含异常对象，如 logger.error("Error while calling Weixin API", e)。

错误处理规范

全局异常处理器

使用 @RestControllerAdvice 注解的 CustomExceptionHandler 类统一处理异常。
返回统一响应格式 R<T>，包含错误码和消息。

异常类型处理

BindException: 参数绑定异常，提取所有错误消息返回。
ConstraintViolationException: 参数校验异常，提取约束违反消息返回。
CustomException: 自定义异常，返回异常消息。
Exception: 未知异常，记录错误日志，返回通用错误信息。

自定义异常

继承 Exception 类，实现 CustomException。

构造函数接受消息字符串：

public class CustomException extends Exception {
  public CustomException(String message) {
      super(message);
  }
}

错误响应格式

使用 R.fail(code, message) 返回错误响应。
错误码定义在 ExceptionResultCode 枚举中。

异常处理原则

业务逻辑中的异常应抛出 CustomException 或记录日志后处理。
全局异常处理器确保所有未捕获异常被统一处理。
异常信息不应暴露敏感数据给客户端。