Tio Boot Docs

拦截器

[[topc]]

一、概述

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

二、核心类说明

1. `HttpInterceptorModel`

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

名称 name：拦截器标识。
放行列表 allowedUrls：一组明确允许的 URL 模式。
拦截列表 blockedUrls：一组需要拦截的 URL 模式。
拦截器实例 interceptor：实现 HttpRequestInterceptor 接口的处理逻辑。

常用方法：

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

// 添加单个/多个放行 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 com.litongjava.annotation.AConfiguration;
import com.litongjava.annotation.Initialization;
import com.litongjava.tio.boot.http.interceptor.HttpInteceptorConfigure;
import com.litongjava.tio.boot.http.interceptor.HttpInterceptorModel;
import com.litongjava.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 com.litongjava.demo.interceptor;

import com.litongjava.tio.http.common.HttpRequest;
import com.litongjava.tio.http.common.HttpResponse;
import com.litongjava.tio.http.common.RequestLine;
import com.litongjava.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，则直接返回该响应，不再执行后续拦截器与业务逻辑。
通配符规则
- /api/**：匹配 /api 及其所有子路径。
- /static/*：仅匹配一级子路径，如 /static/logo.png。

六、最佳实践

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

七、总结

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