Controller拦截器

• 概述
• 接口定义
• 配置步骤
• 示例代码
  • 1. 自定义拦截器
  • 2. 在应用配置中注册
• 执行流程
• 注意事项

概述

ControllerInterceptor 是 Tio-Boot 内置的拦截器，用于在控制器的 Action 方法执行前后进行统一处理。通过实现 ControllerInterceptor 接口，可以在请求进入业务方法前进行预处理，如权限校验、参数校验、日志记录等；在业务方法执行后对返回结果进行统一包装或后置处理。

---

接口定义

public interface ControllerInterceptor {
    /**
     * 在 Action 方法执行前触发
     * @param request 当前 HttpRequest 对象
     * @param actionMethod 即将执行的控制器方法
     * @return 如果返回非 null 的 HttpResponse，将直接返回该响应，中断后续方法执行
     */
    HttpResponse before(HttpRequest request, Method actionMethod);

    /**
     * 在 Action 方法执行后触发
     * @param request 当前 HttpRequest 对象
     * @param targetController 控制器实例
     * @param actionMethod 执行的控制器方法
     * @param actionReturnValue 方法执行结果
     * @return Action返回的最终结果，通常可对 actionReturnValue 进行二次加工
     */
    Object after(HttpRequest request, Object targetController, Method actionMethod, Object actionReturnValue);
}

---

配置步骤

1. 实现自定义拦截器：创建一个类，实现 ControllerInterceptor 接口。
2. 注册拦截器：在 BootConfiguration 实现类中，通过 TioBootServer.me().setControllerInterceptor(...) 将自定义拦截器注册到 Tio-Boot。

---

示例代码

1. 自定义拦截器

package nexus.io.linux.interceptor;

import java.lang.reflect.Method;
import nexus.io.tio.boot.http.controller.ControllerInterceptor;
import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.http.common.HttpResponse;

public class MyControllerInterceptor implements ControllerInterceptor {

    @Override
    public HttpResponse before(HttpRequest request, Method actionMethod) {
        // 预处理逻辑，例如：权限校验
        if (!hasPermission(request)) {
            // 返回自定义错误响应，终止后续方法执行
            return HttpResponse.error(403, "无权限访问");
        }
        // 返回 null 则继续执行 Action 方法
        return null;
    }

    @Override
    public Object after(HttpRequest request, Object targetController, Method actionMethod, Object actionReturnValue) {
        // 后置处理逻辑，例如：统一包装返回结果
        return wrapResponse(actionReturnValue);
    }

    private boolean hasPermission(HttpRequest request) {
        // TODO: 实现权限校验逻辑
        return true;
    }

    private Object wrapResponse(Object data) {
        // TODO: 实现统一响应封装
        return new ApiResponse<>(0, "success", data);
    }
}

2. 在应用配置中注册

package nexus.io.linux.config;

import nexus.io.context.BootConfiguration;
import nexus.io.linux.interceptor.MyControllerInterceptor;
import nexus.io.tio.boot.server.TioBootServer;

public class AppConfig implements BootConfiguration {

    @Override
    public void config() {
        // 注册自定义的 ControllerInterceptor
        TioBootServer.me().setControllerInterceptor(new MyControllerInterceptor());
    }
}

---

执行流程

1. 客户端发起 HTTP 请求。
2. Tio-Boot 在路由解析到对应控制器方法前，调用 before 方法。
3. 如果 before 返回非 null 的 HttpResponse，框架将直接将其作为响应返回，中断后续执行。
4. 如果 before 返回 null，则执行对应的控制器业务方法。
5. 业务方法执行完毕后，调用 after 方法进行后置处理。
6. 最终将 after 方法的返回值序列化为 HTTP 响应体，返回给客户端。

---

注意事项

• 在 before 方法中返回非 null 响应时，将跳过控制器方法的执行。
• after 方法返回的结果可以是任意类型，框架会自动序列化为 JSON 或其它约定的格式。
• 自定义拦截器实例为单例，需注意线程安全，避免在方法中使用非线程安全的成员变量。
• 避免在拦截器中执行过于耗时的操作，以免影响整体请求性能。