请求拦截器

拦截器概述

在基于 Tio-Boot 的 HTTP 应用中，拦截器（Interceptor）是一种在请求到达业务处理器之前或响应返回客户端之后，对请求/响应进行预处理和后处理的机制。合理地使用拦截器，可用于集中化地处理以下场景：

请求校验：验证 HTTP 请求是否合法，拦截恶意或缺少关键信息的请求
鉴权与权限控制：检查请求的认证信息或用户权限
日志记录：统一记录请求与响应的元数据
性能监控：统计方法执行时间或请求耗时
限流与防刷：对频繁请求或异常请求进行限流或封禁

支持的Interceptor

在 tio-boot 中，内置了连个个常用拦截器：

HttpRequestValidationInterceptor
HttpRequestInterceptor

在正常请求流程下，一个请求通常会按下面的顺序依次经过这些拦截器，然后才进入业务处理。

一、请求整体执行流程说明

1. HttpRequestValidationInterceptor（请求校验拦截器）

生效范围：所有请求
主要作用：在请求进入业务逻辑之前，先做基础合法性校验。
常见校验内容：
- 请求头是否完整
- 是否携带必需的请求头（例如 version）

这一层主要是“挡住不合规请求”，不涉及用户身份。

2. HttpRequestInterceptor（通用业务拦截器）

生效范围：仅对配置中指定的请求路径生效
主要作用：
- 校验当前请求是否携带 userId
- 校验该 userId 是否存在于数据库中

这一层才是真正意义上的“登录态校验”，但不是所有接口都会走到这里。

3. Handler / Controller 层业务处理

背景说明：某些接口设计为既支持登录访问，也支持未登录访问。
因此：即使前面已经有拦截器，在 Controller 或 Handler 中，仍然需要根据业务需要，判断当前请求是否存在 userId。

示例代码：

String userIdString = TioRequestContext.getUserIdString();
if (userIdString == null) {
    httpResponse.setStatus(401);
    return httpResponse;
}

这种判断通常用于：
接口对登录态“可选”
或同一个接口在不同场景下权限要求不同

普通拦截器(HttpRequestInterceptor)

一、概述

在 Tio‑Boot 中，HTTP 拦截器（Interceptor）可用于对进出的请求进行统一控制，例如：权限校验、日志记录、限流等。通过配置拦截器模型（HttpInterceptorModel），您可以灵活地指定哪些 URL 应被拦截（blockedUrls），哪些 URL 应被放行（allowedUrls），从而实现精细化的请求管理。

二、核心类说明

1. `HttpInterceptorModel`

拦截器的配置模型，包含：

名称 name：拦截器标识。
放行列表 allowedUrls：一组明确允许的 URL 模式。
拦截列表 blockedUrls：一组需要拦截的 URL 模式。
setAlloweStaticFile: 是否放行静态文件,默认为false
拦截器实例 interceptor：实现 HttpRequestInterceptor 接口的处理逻辑。

常用方法：

// 设置名称
HttpInterceptorModel model = new HttpInterceptorModel();
model.setName("exampleInterceptor");

// 放行静态文件
model.setAlloweStaticFile(true);
// 添加单个/多个放行 URL
model.addAllowUrl("/admin/login");
model.addAllowUrls("/public/**", "/status");

// 添加单个/多个拦截 URL
model.addBlockUrl("/admin/**");
model.addAllowUrls("/api/private/**", "/secure/*");

// 绑定拦截器实现
model.setInterceptor(new YourCustomInterceptor());

注意
同一路径不能同时出现在 allowedUrls 和 blockedUrls 中。
支持通配符：/** 匹配所有子路径，/* 匹配一级子路径。

2. `HttpInteceptorConfigure`

拦截器配置管理器，用于集中管理所有拦截器模型。

HttpInteceptorConfigure configure = new HttpInteceptorConfigure();
configure.add(model);      // 添加拦截器
configure.remove("name");  // 按名称移除拦截器
List<HttpInterceptorModel> list = configure.getInteceptors(); // 获取所有模型

3. `DefaultHttpRequestInterceptorDispatcher`

执行链中的调度器，负责遍历所有 HttpInterceptorModel，并在请求处理前后调用相应的拦截器方法。

doBeforeHandler：在业务处理前执行。
- 若返回非 null 的 HttpResponse，则后续业务和拦截器链将被短路。
doAfterHandler：在业务处理后执行。

三、在 TioBootServer 中注册拦截器

在启动类或配置类中，通过 TioBootServer 将自定义的拦截器配置注入到服务器：

import nexus.io.annotation.AConfiguration;
import nexus.io.annotation.Initialization;
import nexus.io.tio.boot.http.interceptor.HttpInteceptorConfigure;
import nexus.io.tio.boot.http.interceptor.HttpInterceptorModel;
import nexus.io.tio.boot.server.TioBootServer;

@AConfiguration
public class InterceptorConfiguration {

  @Initialization
  public void init() {
    // 1. 构建一个全局拦截器模型
    HttpInterceptorModel global = new HttpInterceptorModel()
        .setName("globalInterceptor")
        .addBlockUrl("/**")         // 拦截所有路径
        .addAllowedUrl("/health")     // 放行健康检查接口
        .setInterceptor(new GlobalInterceptor());

    // 2. 创建配置管理器并添加模型
    HttpInteceptorConfigure config = new HttpInteceptorConfigure();
    config.addInterceptor(global);

    // 3. 注入到 TioBootServer
    TioBootServer.me().setHttpInteceptorConfigure(config);
  }
}

四、自定义拦截器示例

自定义拦截器需实现 HttpRequestInterceptor 接口，示例中将请求日志打印到控制台：

package nexus.io.demo.interceptor;

import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.http.common.HttpResponse;
import nexus.io.tio.http.common.RequestLine;
import nexus.io.tio.http.server.intf.HttpRequestInterceptor;
import lombok.extern.slf4j.Slf4j;

@Slf4j
public class GlobalInterceptor implements HttpRequestInterceptor {

  @Override
  public HttpResponse doBeforeHandler(
      HttpRequest request,
      RequestLine requestLine,
      HttpResponse originalResponse) throws Exception
  {
    log.info("[Before] {} {}", requestLine.getMethod(), requestLine.getPath());
    // 返回 null 表示继续执行后续拦截器和业务处理
    return null;
  }

  @Override
  public void doAfterHandler(
      HttpRequest request,
      RequestLine requestLine,
      HttpResponse response,
      long costMillis) throws Exception
  {
    log.info("[After] {} {} -> {} ({} ms)",
             requestLine.getMethod(),
             requestLine.getPath(),
             response.getStatus(),
             costMillis);
  }
}

五、URL 匹配与执行逻辑

匹配顺序
DefaultHttpRequestInterceptorDispatcher 会依次遍历所有已注册的 HttpInterceptorModel。
拦截判定
- 若请求 URL 与某个模型的 blockedUrls 任一模式匹配，且不在该模型的 allowedUrls 中，则视为需拦截。
- 在 doBeforeHandler 中若返回非空 HttpResponse，则直接返回该响应，不再执行后续拦截器与业务逻辑。这一点很重要,和其它web框架不同,如果想要后续的拦截器和业务逻辑执行,务必返回null
通配符规则
- /api/**：匹配 /api 及其所有子路径。
- /static/*：仅匹配一级子路径，如 /static/logo.png。

六、最佳实践

分层注册：可根据业务模块，将拦截器按职责拆分成多个模型，如认证、授权、日志、限流等，按需组合。
精确放行：尽量将 allowedUrls 配置得更精细，例如放行静态资源、健康检查、登录回调等。
性能考量：拦截器链中的执行逻辑应尽量轻量，避免阻塞或耗时操作；如需复杂处理，可异步执行或交由专用服务。
单元测试：对自定义拦截器逻辑编写单元测试，验证不同 URL 下的拦截与放行行为。

七、总结

通过以上配置，您可以在 Tio‑Boot 应用中轻松地管理 HTTP 请求的拦截与放行，实现统一的安全、限流、监控等功能。拦截器模型与调度器解耦，配置灵活且可扩展。实践中可结合业务需求，定制多层拦截策略，进一步提升系统的健壮性与可维护性。

请求校验拦截器实现(HttpRequestValidationInterceptor)

本章将重点介绍如何在 Tio-Boot 中编写和配置“请求校验拦截器”（HttpRequestValidationInterceptor），实现对缺失必填 Header 的拦截、封禁高频“无头”请求的功能，并演示如何在启动配置类中注册该拦截器。

1. 设计思路

无头请求判定：当请求缺少关键 Header（例如 from）时，认为该请求不合法。
计数与阈值：统计同一 IP 的“无头请求”次数，超过设定阈值（如 10 次）后，将该 IP 加入黑名单（可扩展为持久化到 Redis 或防火墙规则）。
返回响应：对于每一次无头请求，都返回 HTTP 403 并主动关闭连接。

2. 自定义拦截拦截器校验逻辑

import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.atomic.AtomicInteger;

import nexus.io.tio.http.common.HttpRequest;
import nexus.io.tio.http.common.HttpResponse;
import nexus.io.tio.http.common.RequestLine;
import nexus.io.tio.http.server.intf.HttpRequestInterceptor;

/**
 * 应用级请求校验拦截器
 * 1. 检查请求是否包含必要 Header
 * 2. 累计无头请求次数，超过阈值则封禁 IP
 */
public class AppRequestValidationInterceptor implements HttpRequestInterceptor {

  // 存储每个 IP 的无头请求计数
  private final ConcurrentMap<String, AtomicInteger> badCount = new ConcurrentHashMap<>();
  private static final int MAX_BAD = 10;

  @Override
  public HttpResponse doBeforeHandler(HttpRequest request, RequestLine requestLine, HttpResponse httpResponse) throws Exception {
    String from = request.getHeader("from");
    String clientIp = request.channelContext.getClientNode().getIp();

    // 如果缺少 from Header，则视为无头请求
    if (from == null) {
      // 累加计数
      int count = badCount.computeIfAbsent(clientIp, k -> new AtomicInteger()).incrementAndGet();

      // 返回 403，主动关闭连接
      httpResponse.setStatus(403);
      httpResponse.setHeader("Connection", "close");
      httpResponse.setKeepConnection(false);

      // 超过阈值，执行封禁逻辑
      if (count >= MAX_BAD) {
        blockIp(clientIp);
      }
      return httpResponse;
    } else {
      //必须返回null,让请求继续向后执行
      return null;
    }

  }

  /**
   * 封禁 IP（可根据实际需求扩展为：加入 Redis、更新防火墙规则等）
   */
  private void blockIp(String ip) {
    // TODO: 将 IP 持久化到黑名单，比如 Redis 或防火墙规则
  }

  @Override
  public void doAfterHandler(HttpRequest request, RequestLine requestLine, HttpResponse response, long cost) {
    // 后置处理：目前无操作
  }
}

3. 在 Tio-Boot 中配置与使用

为了使上述拦截器生效，需要在应用启动配置类中注册它。Tio-Boot 提供了通过注解和初始化方法来完成这一操作的能力。

import nexus.io.annotation.AConfiguration;
import nexus.io.annotation.Initialization;
import nexus.io.tio.boot.server.TioBootServer;
@AConfiguration
public class InterceptorConfiguration {

  /**
   * 应用初始化时注册请求校验拦截器
   */
  @Initialization
  public void config() {
    // 获取 Tio-Boot 服务器单例
    TioBootServer server = TioBootServer.me();

    // 创建并注册自定义拦截器
    AppRequestValidationInterceptor validationInterceptor = new AppRequestValidationInterceptor();
    server.setHttpRequestValidationInterceptor(validationInterceptor);
  }
}

说明：
@AConfiguration 标记该类为配置类，需被框架扫描。
@Initialization 标记的方法在应用启动时被调用。
TioBootServer.me() 返回 TioBootServer 单例，setHttpRequestValidationInterceptor(...) 用于替换默认的请求校验拦截器。

4.拓展与优化

黑名单持久化
- 将被封禁的 IP 写入 Redis、数据库或防火墙规则，重启后依然生效；
- 定期清理过期或临时封禁 IP。
动态阈值与告警
- 根据应用运行时负载或安全策略动态调整 MAX_BAD；
- 当某个 IP 次数激增时，可触发告警通知运维人员。
白名单机制
- 对某些受信任的 IP 段或内网地址跳过校验。
多维度安全校验
- 除了 Header 校验，还可结合签名校验、令牌校验或验证码等手段；
- 对请求频率、请求体大小、URL 路径等进行限流或过滤。

请求头校验：确保请求头中包含必要参数（如 version）。
身份认证：通过请求头中的 token 校验用户是否合法。
用户上下文管理：在请求的生命周期中安全、统一地传递用户 ID。
权限隔离：支持部分接口无需登录即可访问，其他接口则需要合法用户身份。

为此，Tio-Boot 提供了 UserTokenInterceptor 内置拦截器，它们配合使用可以满足上述需求。

目标

统一 Token 验证逻辑：支持系统管理员 Token 和普通用户 Token 的验证。
透明的用户上下文传递：通过拦截器将 userId 注入到 TioRequestContext，在 Controller 中直接获取。
可配置化：允许定义无需拦截的 URL（如登录、注册、验证码接口），同时灵活扩展 Token 验证逻辑。
安全性：对非法请求（无 Token 或 Token 校验失败）统一拦截，返回 401 Unauthorized。

拦截器职责分工

UserTokenInterceptor
- 负责 拦截请求并进行用户校验。
- 默认拦截所有 URL (/**)，但支持配置 白名单 URL，如登录、注册、验证码、静态资源等接口。
- 如果请求未携带有效 Token，则阻止请求继续下发。

最佳实践实例

1. 定义白名单 URL

public interface TioBootAdminUrls {
  String[] ALLLOW_URLS = {
    "", "/",
    "/api/event/add",
    "/register/*", "/api/login/account", "/api/login/outLogin",
    "/api/v1/login", "/api/v1/register", "/api/v1/user/referesh",
    "/api/v1/sendVerification", "/api/v1/sendVerificationCode", "/api/v1/verify",
    "/verification/email", "/api/v1/user/resetPassword", "/api/v1/anonymous/create",
    "/api/v1/google/login", "/api/v1/user/refresh",
    "/table/json/tio_boot_admin_system_article/get/*",
    "/table/json/tio_boot_admin_system_docx/get/*",
    "/table/json/tio_boot_admin_system_pdf/get/*"
  };
}

2. 自定义 Token 验证逻辑

package nexus.io.tio.boot.admin.services;

import java.util.function.Predicate;

import nexus.io.tio.boot.admin.costants.AppConstant;
import nexus.io.tio.boot.http.TioRequestContext;
import nexus.io.tio.utils.environment.EnvUtils;
import nexus.io.tio.utils.jwt.JwtUtils;

public class TioBootAdminTokenPredicate implements Predicate<String> {

  @Override
  public boolean test(String token) {
    String adminToken = EnvUtils.get(AppConstant.ADMIN_TOKEN);
    //system token
    if (adminToken != null && adminToken.equals(token)) {
      TioRequestContext.setUserId(0L);
      return true;
    }

    // user and admin token
    String key = EnvUtils.getStr(AppConstant.ADMIN_SECRET_KEY);
    boolean verify = JwtUtils.verify(key, token);
    if (verify) {
      String userId = JwtUtils.parseUserIdString(token);
      TioRequestContext.setUserId(userId);
      return true;
    }
    return false;
  }

  public Long parseUserIdLong(String token) {
    String key = EnvUtils.getStr(AppConstant.ADMIN_SECRET_KEY);
    boolean verify = JwtUtils.verify(key, token);
    if (verify) {
      return JwtUtils.parseUserIdLong(token);
    }
    return null;
  }
}

3. 配置拦截器

package nexus.io.tio.boot.admin.config;

import nexus.io.tio.boot.admin.costants.TioBootAdminUrls;
import nexus.io.tio.boot.admin.services.TioBootAdminTokenPredicate;
import nexus.io.tio.boot.http.interceptor.HttpInteceptorConfigure;
import nexus.io.tio.boot.http.interceptor.HttpInterceptorModel;
import nexus.io.tio.boot.server.TioBootServer;
import nexus.io.tio.boot.token.TokenPredicate;
import nexus.io.tio.boot.token.UserTokenInterceptor;

public class TioAdminInterceptorConfiguration {

  private String[] permitUrls;
  private boolean alloweStaticFile = true;
  private TokenPredicate validateTokenLogic;

  public TioAdminInterceptorConfiguration() {
  }

  public TioAdminInterceptorConfiguration(String[] permitUrls) {
    this.permitUrls = permitUrls;
  }

  public TioAdminInterceptorConfiguration(String[] permitUrls, TokenPredicate validateTokenLogic) {
    this.permitUrls = permitUrls;
    this.validateTokenLogic = validateTokenLogic;
  }

  public TioAdminInterceptorConfiguration(String[] permitUrls, boolean b) {
    this.permitUrls = permitUrls;
    this.alloweStaticFile = b;
  }

  public void config() {
    // token验证逻辑
    if (validateTokenLogic == null) {
      validateTokenLogic = new TioBootAdminTokenPredicate();
    }

    UserTokenInterceptor userTokenInterceptor = new UserTokenInterceptor(validateTokenLogic);
    HttpInterceptorModel model = new HttpInterceptorModel();
    model.setInterceptor(userTokenInterceptor);
    // 拦截所有路由
    model.addBlockUrl("/**");

    // 添加不拦截的路由
    model.addAllowUrls(TioBootAdminUrls.ALLLOW_URLS);

    if (permitUrls != null) {
      model.addAllowUrls(permitUrls);
    }
    model.setAlloweStaticFile(alloweStaticFile);

    HttpInteceptorConfigure inteceptorConfigure = new HttpInteceptorConfigure();
    inteceptorConfigure.add(model);
    // 将拦截器配置添加到 Tio 服务器
    TioBootServer.me().setHttpInteceptorConfigure(inteceptorConfigure);
  }
}

Controller 层的使用

在 Controller 或 Handler 中，可以直接通过 TioRequestContext 获取用户 ID：

String userIdString = TioRequestContext.getUserIdString();
if (userIdString == null) {
    httpResponse.setStatus(401);
    return httpResponse;
}
// 根据 userId 执行业务逻辑

⚠️ 注意：部分接口既允许匿名访问，也允许带用户 ID 的访问，需要开发者在 Controller 中做进一步的判断。

总结

通过 UserTokenInterceptor 的配合使用，Tio-Boot 提供了一套灵活、安全的 Token 验证与用户上下文管理机制，其优势包括：

支持管理员和普通用户的双重 Token 验证。
请求拦截与 Token 验证解耦，职责清晰。
可配置白名单 URL，满足开放接口需求。
在 Controller 中使用简单，提升开发效率。

这套机制既能保证系统的安全性，又为开发者提供了灵活的配置和扩展能力。

JWT 的签名、到期时间和无效输入处理约定，见 JWT 签发与校验。