全局异常处理器

Tio-Boot 提供了 TioBootExceptionHandler 接口，用于对全局异常进行统一处理。通过使用全局异常处理器，您可以在应用程序中捕获并处理所有未处理的异常，从而提高系统的健壮性和可维护性。

在 Tio-Boot 中使用全局异常处理器

以下是如何在 Tio-Boot 应用程序中使用全局异常处理器的详细步骤和说明。

1. 创建自定义异常处理器

首先，您需要创建一个自定义的异常处理器类，实现 TioBootExceptionHandler 接口，并覆盖 handler 方法。在 handler 方法中，您可以定义发生异常时的处理逻辑，例如记录日志、返回特定的响应信息等。

import java.io.PrintWriter;
import java.io.StringWriter;
import java.util.Map;

import com.litongjava.tio.boot.exception.TioBootExceptionHandler;
import com.litongjava.tio.http.common.HttpRequest;
import com.litongjava.tio.utils.resp.RespVo;

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class GlobalExceptionHandler implements TioBootExceptionHandler {

  @Override
  public RespVo handler(HttpRequest request, Throwable e) {
    StringBuffer requestURL = request.getRequestURL();
    Map<String, String> headers = request.getHeaders();
    String bodyString = request.getBodyString();

    // 获取完整的堆栈跟踪信息
    StringWriter sw = new StringWriter();
    PrintWriter pw = new PrintWriter(sw);
    e.printStackTrace(pw);
    String stackTrace = sw.toString();

    log.error("请求URL: {}, 请求头: {}, 请求体: {}, 异常堆栈: {}", requestURL.toString(), headers, bodyString, stackTrace);

    // 返回自定义的错误响应
    return RespVo.fail(e.getMessage());
  }
}

在上述示例中，GlobalExceptionHandler 类实现了 TioBootExceptionHandler 接口，并在 handler 方法中：

  • 获取了请求的 URL、请求头和请求体。
  • 捕获了异常的完整堆栈跟踪信息。
  • 记录了异常信息，方便调试和追踪问题。
  • 返回了一个自定义的错误响应 RespVo 给客户端。

2. 配置 TioBootServer 使用自定义异常处理器

接下来，需要在 TioBootServer 的配置类中设置自定义的异常处理器。通过在配置类中创建一个初始化方法，并使用 TioBootServer.me().setExceptionHandler(exceptionHandler) 来完成。

import com.litongjava.jfinal.aop.annotation.AConfiguration;
import com.litongjava.jfinal.aop.annotation.AInitialization;
import com.litongjava.tio.boot.server.TioBootServer;

@AConfiguration
public class TioBootServerConfiguration {

  @AInitialization
  public void config() {
    TioBootServer.me().setExceptionHandler(new GlobalExceptionHandler());
  }
}

在这个配置类中：

  • @AConfiguration 注解表示这是一个配置类。
  • @AInitialization 注解标记的方法 config 会在服务器启动时执行。
  • 在 config 方法中，通过 TioBootServer.me().setExceptionHandler(new GlobalExceptionHandler()) 设置了自定义的异常处理器。

3. 触发异常

为了测试异常处理器是否正常工作，可以创建一个 Controller 类，其中包含故意触发异常的方法。

import com.litongjava.tio.http.server.annotation.RequestPath;

@RequestPath("/exception")
public class ExceptionController {

  @RequestPath
  public Integer index() {
    return (0 / 0); // 故意触发除数为0的异常
  }
}

在这个示例中：

  • ExceptionController 类映射了 /exception 路径。
  • index 方法中执行了 0 / 0，故意触发 ArithmeticException 异常。

4. 运行应用程序

创建主应用程序类，启动 Tio-Boot 服务器。

import com.litongjava.jfinal.aop.annotation.AComponentScan;
import com.litongjava.tio.boot.TioApplication;

@AComponentScan
public class ExceptionApp {
  public static void main(String[] args) {
    long start = System.currentTimeMillis();
    TioApplication.run(ExceptionApp.class, args);
    long end = System.currentTimeMillis();
    System.out.println("启动耗时：" + (end - start) + "ms");
  }
}

在这个示例中：

  • @AComponentScan 注解用于扫描组件。
  • ExceptionApp 类的 main 方法调用 TioApplication.run 启动服务器。

5. 测试异常处理

启动应用程序后，可以通过浏览器或其他 HTTP 客户端访问 http://localhost/exception，触发异常。这将执行 ExceptionController 的 index 方法，导致除数为零的异常。然后，异常将被 GlobalExceptionHandler 捕获并处理。

通过查看应用程序的日志输出，可以看到由 GlobalExceptionHandler 记录的异常信息，表明全局异常处理器正常工作。

示例日志输出：

2024-02-04 10:12:36.683 [tio-group-3] INFO  c.l.t.w.h.h.GlobalExceptionHadler.handler:27 - /exception,{sec-fetch-mode=navigate, sec-fetch-site=none, accept-language=en-US,en;q=0.9,zh-CN;q=0.8,zh;q=0.7, cookie=PHPSESSID=45ab823cf4424734b764d8888b77130e, sec-fetch-user=?1, accept=text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7, sec-ch-ua="Not A(Brand";v="99", "Google Chrome";v="121", "Chromium";v="121", sec-ch-ua-mobile=?0, sec-ch-ua-platform="Windows", host=localhost, upgrade-insecure-requests=1, connection=keep-alive, cache-control=max-age=0, accept-encoding=gzip, deflate, br, user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36, sec-fetch-dest=document},null,java.lang.ArithmeticException: / by zero
	at com.litongjava.tio.web.hello.controller.ExceptionController.index(ExceptionController.java:9)
	at com.litongjava.tio.web.hello.controller.ExceptionControllerMethodAccess.invoke(Unknown Source)
	at com.esotericsoftware.reflectasm.MethodAccess.invoke(MethodAccess.java:39)
	at com.litongjava.tio.boot.http.handler.HandlerDispatcher.executeAction(HandlerDispatcher.java:73)
	at com.litongjava.tio.boot.http.handler.DefaultHttpRequestHandlerDispather.processDynamic(DefaultHttpRequestHandlerDispather.java:374)
	at com.litongjava.tio.boot.http.handler.DefaultHttpRequestHandlerDispather.handler(DefaultHttpRequestHandlerDispather.java:305)
	at com.litongjava.tio.http.server.HttpServerAioHandler.handler(HttpServerAioHandler.java:94)
	at com.litongjava.tio.boot.server.TioBootServerHandler.handler(TioBootServerHandler.java:140)
	at com.litongjava.tio.core.task.HandlerRunnable.handler(HandlerRunnable.java:67)
	at com.litongjava.tio.core.task.DecodeRunnable.handler(DecodeRunnable.java:55)
	at com.litongjava.tio.core.task.DecodeRunnable.decode(DecodeRunnable.java:205)
	at com.litongjava.tio.core.ReadCompletionHandler.completed(ReadCompletionHandler.java:83)
	at com.litongjava.tio.core.ReadCompletionHandler.completed(ReadCompletionHandler.java:21)
	at sun.nio.ch.Invoker.invokeUnchecked(Invoker.java:126)
	at sun.nio.ch.Invoker$2.run(Invoker.java:218)
	at sun.nio.ch.AsynchronousChannelGroupImpl$1.run(AsynchronousChannelGroupImpl.java:112)
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1142)
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:617)
	at java.lang.Thread.run(Thread.java:745)

通过上述步骤，可以在 Tio-Boot 应用程序中有效地管理和记录异常，保持代码的整洁和易于维护。

6. 测试源码

完整的测试源码可在 GitHub 上获取：

https://github.com/litongjava/java-ee-tio-boot-study/tree/main/tio-boot-latest-study/tio-boot-web-exception-handler-demo01open in new window

扩展：将异常信息保存到数据库

除了记录日志，您还可以在自定义全局异常处理器中将异常信息保存到数据库，或者发送到微信群等其他通知渠道。

1. 创建数据表

首先，在数据库中创建一个用于存储异常信息的表。例如：

DROP TABLE IF EXISTS tio_boot_admin_system_exception;
CREATE TABLE tio_boot_admin_system_exception (
  id BIGINT NOT NULL,
  exception TEXT NOT NULL,
  status SMALLINT NOT NULL DEFAULT 0,
  remark VARCHAR(255) NOT NULL DEFAULT '',
  creator VARCHAR(64) DEFAULT '',
  create_time TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updater VARCHAR(64) DEFAULT '',
  update_time TIMESTAMP WITHOUT TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
  deleted SMALLINT NOT NULL DEFAULT 0,
  tenant_id BIGINT NOT NULL DEFAULT 0,
  PRIMARY KEY (id)
);

该表包含了异常信息、创建时间、状态等字段，便于后续的查询和管理。

2. 修改异常处理器，保存异常到数据库

在自定义的异常处理器中，增加将异常信息保存到数据库的逻辑。例如：

import java.io.PrintWriter;
import java.io.StringWriter;
import java.util.Date;
import java.util.Map;

import com.litongjava.db.activerecord.Db;
import com.litongjava.db.activerecord.Record;
import com.litongjava.tio.boot.constatns.TioBootConfigKeys;
import com.litongjava.tio.boot.exception.TioBootExceptionHandler;
import com.litongjava.tio.http.common.HttpRequest;
import com.litongjava.tio.http.common.utils.HttpIpUtils;
import com.litongjava.tio.utils.environment.EnvUtils;
import com.litongjava.tio.utils.network.IpUtils;
import com.litongjava.tio.utils.notification.AlarmUtils;
import com.litongjava.tio.utils.notification.NotifactionWarmModel;
import com.litongjava.tio.utils.resp.RespVo;
import com.litongjava.tio.utils.snowflake.SnowflakeIdUtils;
import com.litongjava.tio.utils.thread.TioThreadUtils;

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class GlobalExceptionHandler implements TioBootExceptionHandler {

  @Override
  public RespVo handler(HttpRequest request, Throwable e) {
    String requestId = request.getChannelContext().getId();

    String requestLine = request.getRequestLine().toString();
    String host = request.getHost();
    Map<String, String> headers = request.getHeaders();
    String bodyString = request.getBodyString();

    String realIp = HttpIpUtils.getRealIp(request);

    // 获取完整的堆栈跟踪信息
    StringWriter sw = new StringWriter();
    PrintWriter pw = new PrintWriter(sw);
    e.printStackTrace(pw);
    String stackTrace = sw.toString();

    log.error("请求ID: {}, 主机: {}, 请求行: {}, 请求头: {}, 请求体: {}, 异常堆栈: {}", requestId, host, requestLine, headers, bodyString, stackTrace);

    // 构建异常信息模型
    NotifactionWarmModel model = new NotifactionWarmModel();
    String localIp = IpUtils.getLocalIp();
    model.setAppGroupName("default group");
    model.setAppName(EnvUtils.get(TioBootConfigKeys.APP_NAME));
    model.setWarningName("GlobalExceptionHandler");
    model.setLevel("普通级别");
    String env = EnvUtils.env();
    model.setDeviceName(localIp);
    model.setTime(new Date());
    String content = "环境: " + env + ", 请求ID: " + requestId + ", 用户IP: " + realIp + ", 访问 " + host + "，请求行: " + requestLine + "\n异常信息: " + stackTrace;
    model.setContent(content);

    // 异步保存异常信息到数据库，并发送告警
    if (!EnvUtils.isDev()) {
      TioThreadUtils.submit(() -> {
        // 生成唯一ID
        long id = SnowflakeIdUtils.id();
        // 保存到数据库
        Db.save("tio_boot_admin_system_exception", Record.by("id", id).set("exception", stackTrace));
        // 发送告警通知（如微信、邮件等）
        AlarmUtils.sendWarm(model);
      });
    }

    // 返回自定义的错误响应
    return RespVo.fail(e.getMessage());
  }
}

在上述代码中：

  • 获取了请求和异常的详细信息。
  • 使用 SnowflakeIdUtils 生成唯一的异常记录 ID。
  • 使用 Db.save 方法将异常信息保存到数据库的 tio_boot_admin_system_exception 表中。
  • 使用 AlarmUtils.sendWarm 方法发送告警通知，可以集成微信、邮件等通知渠道。
  • 使用 TioThreadUtils.submit 方法将保存和通知操作放入异步线程，避免阻塞主线程。
  • 通过 EnvUtils.isDev() 判断当前环境，避免在开发环境中执行数据库保存和发送通知的操作。

总结

通过自定义全局异常处理器，您可以：

  • 统一管理应用程序中的异常处理逻辑。
  • 记录详细的异常信息，便于调试和问题追踪。
  • 将异常信息持久化到数据库，方便后续的查询和统计分析。
  • 集成告警通知机制，在异常发生时及时通知相关人员。

以上方法可以提高应用程序的健壮性，增强系统的异常监控和管理能力。