全局异常处理器

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

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

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

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

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

package com.litongjava.tio.boot.admin.handler;

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

import com.litongjava.constants.ServerConfigKeys;
import com.litongjava.model.body.RespBodyVo;
import com.litongjava.tio.boot.agent.NotificationSender;
import com.litongjava.tio.boot.exception.TioBootExceptionHandler;
import com.litongjava.tio.boot.http.TioRequestContext;
import com.litongjava.tio.boot.server.TioBootServer;
import com.litongjava.tio.core.ChannelContext;
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.NotifactionWarmModel;
import com.litongjava.tio.websocket.common.WebSocketRequest;

import lombok.extern.slf4j.Slf4j;

@Slf4j
public class GlobalExceptionHadler implements TioBootExceptionHandler {

  @Override
  public RespBodyVo 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.info("requestId,{},{},{},{},{}", requestId, host, requestLine, headers, bodyString, stackTrace);
    NotifactionWarmModel model = new NotifactionWarmModel();

    String localIp = IpUtils.getLocalIp();
    model.setAppEnv(EnvUtils.env());
    model.setAppGroupName("tio-boot");
    model.setAppName(EnvUtils.get(ServerConfigKeys.APP_NAME));
    model.setWarningName("GlobalExceptionHadler");
    model.setLevel("LeveL 1");

    model.setDeviceName(localIp);
    model.setTime(new Date());
    model.setRequestId(requestId);
    model.setUserIp(realIp);
    model.setUserId(TioRequestContext.getUserIdString());
    model.setHost(host);
    model.setRequestLine(requestLine);
    model.setRequestBody(bodyString);
    model.setStackTrace(stackTrace);
    model.setContent("unknow error");

    if (!EnvUtils.isDev()) {
      NotificationSender notificationSender = TioBootServer.me().getNotificationSender();
      if (notificationSender != null) {
        notificationSender.send(model);
      }
    }

    return RespBodyVo.fail(e.getMessage());
  }

  @Override
  public Object wsTextHandler(WebSocketRequest webSokcetRequest, String text, ChannelContext channelContext, HttpRequest httpRequest, Throwable e) {
    return null;
  }

  @Override
  public Object wsBytesHandler(WebSocketRequest webSokcetRequest, byte[] bytes, ChannelContext channelContext, HttpRequest httpRequest, Throwable e) {
    return null;
  }
}

MyNotificationSender.java

import java.io.IOException;

import com.litongjava.tio.boot.agent.NotificationSender;
import com.litongjava.tio.utils.environment.EnvUtils;
import com.litongjava.tio.utils.notification.LarksuiteNotificationUtils;
import com.litongjava.tio.utils.notification.NotifactionWarmModel;
import com.litongjava.tio.utils.thread.TioThreadUtils;

import lombok.extern.slf4j.Slf4j;
import okhttp3.Response;

@Slf4j
public class MyNotificationSender implements NotificationSender {
  @Override
  public boolean send(NotifactionWarmModel model) {
    TioThreadUtils.submit(() -> {
      try (Response response = LarksuiteNotificationUtils.sendWarm(EnvUtils.get("warm.notification.webhook.url"), model)) {
        if (!response.isSuccessful()) {
          try {
            log.info("Faild to push :{}", response.body().string());
          } catch (IOException e1) {
            e1.printStackTrace();
          }
        }
      }
    });
    return true;
  }
}

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

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

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;
import com.litongjava.tio.boot.admin.handler.GlobalExceptionHadler;

@AConfiguration
public class TioBootServerConfiguration {

  @Initialization
  public void config() {
    TioBootServer server = TioBootServer.me();
    server.setExceptionHandler(new GlobalExceptionHadler());
    server.setNotificationSender(new MyNotificationSender());
  }
}

在这个配置类中：

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

3. 触发异常

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

import com.litongjava.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.GlobalExceptionHadler 上报数据示例

- Alarm Time : 2025-02-23 23:27:56
- App Env : dev
- App Group Name : tio-boot
- App Name : tio-boot
- Alarm Name : GlobalExceptionHadler
- Alarm Level : 普通级别
- Alarm Device : 172.27.96.1
- User Ip : 0:0:0:0:0:0:0:1
- User Id : 0
- Request Id : 1893956013658279936
- Host : localhost
- Request Line : POST /api/v1/chat/ask HTTP/1.1
- Request Body : {
    "chat_id": "483654906678661120",
    "messages": [
        {
            "role": "user",fff
            "content": "hi"
        }
    ],
    "model": "deepseek-ai/DeepSeek-V3",
    "provider": "siliconflow",
    "type": "general",
    "stream": true,
    "file_ids": [
        "483583407344754688",
        "483587022490324992"
    ]
}
- Stack Trace : com.alibaba.fastjson2.JSONException: illegal input
, offset 103, character
, line 6, column 1, fastjson-version 2.0.53
{
    "chat_id": "483654906678661120",
    "messages": [
        {
            "role": "user",fff
            "content": "hi"
        }
    ],
    "model": "deepseek-ai/DeepSeek-V3",
    "provider": "siliconflow",
    "type": "general",
    "stream": true,
    "file_ids": [
        "483583407344754688",
        "483587022490324992"
    ]
}
	at com.alibaba.fastjson2.JSONReader.readObject(JSONReader.java:2347)
	at com.alibaba.fastjson2.JSONReader.readArray(JSONReader.java:2579)
	at com.alibaba.fastjson2.JSONReader.read(JSONReader.java:2102)
	at com.alibaba.fastjson2.JSON.parseObject(JSON.java:348)
	at com.litongjava.tio.utils.json.FastJson2Utils.parseObject(FastJson2Utils.java:48)
	at com.litongjava.llm.handler.ApiChatAskHandler.send(ApiChatAskHandler.java:31)
	at com.litongjava.tio.boot.http.handler.internal.TioBootHttpRequestDispatcher.handler(TioBootHttpRequestDispatcher.java:327)
	at com.litongjava.tio.http.server.HttpServerAioHandler.handler(HttpServerAioHandler.java:82)
	at com.litongjava.tio.boot.server.TioBootServerHandler.handler(TioBootServerHandler.java:177)
	at com.litongjava.tio.core.task.HandlePacketTask.handle(HandlePacketTask.java:71)
	at com.litongjava.tio.core.task.DecodeTask.decode(DecodeTask.java:144)
	at com.litongjava.tio.core.ReadCompletionHandler.completed(ReadCompletionHandler.java:77)
	at com.litongjava.tio.core.ReadCompletionHandler.completed(ReadCompletionHandler.java:24)
	at java.base/sun.nio.ch.Invoker.invokeUnchecked(Invoker.java:129)
	at java.base/sun.nio.ch.Invoker.invokeUnchecked(Invoker.java:284)
	at java.base/sun.nio.ch.WindowsAsynchronousSocketChannelImpl$ReadTask.completed(WindowsAsynchronousSocketChannelImpl.java:586)
	at java.base/sun.nio.ch.Iocp$EventHandlerTask.run(Iocp.java:387)
	at java.base/sun.nio.ch.AsynchronousChannelGroupImpl$1.run(AsynchronousChannelGroupImpl.java:113)
	at java.base/java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144)
	at java.base/java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642)
	at java.base/java.lang.Thread.run(Thread.java:1583)

- Alarm Content :
unknow error

7. 测试源码

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

https://github.com/litongjava/java-ee-tio-boot-study/tree/main/tio-boot-latest-study/tio-boot-web-exception-handler-demo01

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

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

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.Row;
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.RespBodyVo;
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 RespBodyVo 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", Row.by("id", id).set("exception", stackTrace));
        // 发送告警通知（如微信、邮件等）
        AlarmUtils.sendWarm(model);
      });
    }

    // 返回自定义的错误响应
    return RespBodyVo.fail(e.getMessage());
  }
  @Override
  public Object wsTextHandler(WebSocketRequest webSokcetRequest, String text, ChannelContext channelContext, HttpRequest httpRequest, Throwable e) {
    handler(httpRequest, e);
    return null;
  }

  @Override
  public Object wsBytesHandler(WebSocketRequest webSokcetRequest, byte[] bytes, ChannelContext channelContext, HttpRequest httpRequest, Throwable e) {
    handler(httpRequest, e);
    return null;
  }
}

在上述代码中：

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

总结

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

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

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