FixedTokenInterceptor

概述

FixedTokenInterceptor 是 TioBoot 框架提供的一个内置 HTTP 请求拦截器，主要用于实现基于固定令牌的身份验证机制。该拦截器会检查 HTTP 请求头中的 authorization 字段，确保其值与预先配置的令牌一致，从而实现对 API 访问的安全控制。

应用场景

• 简单的 API 访问控制
• 微服务间内部通信认证
• 临时性访问令牌验证
• 开发环境下的简易认证方案

配置步骤

1. 配置认证令牌

在应用的配置文件 app.properties 中添加令牌配置：

# 认证令牌配置
app.auth.token=123456

2. 创建应用配置类

创建一个实现 BootConfiguration 接口的配置类，用于初始化拦截器：

package nexus.io.kit.config;

import nexus.io.context.BootConfiguration;
import nexus.io.kit.handler.PingHandler;
import nexus.io.tio.boot.http.interceptor.HttpInteceptorConfigure;
import nexus.io.tio.boot.http.interceptor.HttpInterceptorModel;
import nexus.io.tio.boot.satoken.FixedTokenInterceptor;
import nexus.io.tio.boot.server.TioBootServer;
import nexus.io.tio.http.server.intf.HttpRequestInterceptor;
import nexus.io.tio.http.server.router.HttpRequestRouter;
import nexus.io.tio.utils.environment.EnvUtils;

@AConfiguration
public class AppConfig implements BootConfiguration {

  @Override
  public void config() {
    // 初始化基本路由
    initBasicRoutes();
    
    // 配置令牌拦截器
    configureTokenInterceptor();
  }

  private void initBasicRoutes() {
    TioBootServer server = TioBootServer.me();
    HttpRequestRouter router = server.getRequestRouter();
    if (router != null) {
      PingHandler pingHandler = new PingHandler();
      router.add("/ping", pingHandler::ping);
    }
  }

  private void configureTokenInterceptor() {
    // 从环境变量获取令牌
    String authToken = EnvUtils.get("app.auth.token");
    
    // 创建令牌拦截器实例
    HttpRequestInterceptor tokenInterceptor = new FixedTokenInterceptor(authToken);
    
    // 配置拦截规则
    HttpInterceptorModel model = new HttpInterceptorModel();
    model.setInterceptor(tokenInterceptor);
    
    // 拦截所有路由
    model.addBlockUrl("/**");
    
    // 设置例外路由
    model.addAllowUrls("/", "/ping");
    
    // 创建拦截器配置
    HttpInteceptorConfigure interceptorConfig = new HttpInteceptorConfigure();
    interceptorConfig.add(model);
    
    // 应用到服务器
    TioBootServer.me().setHttpInteceptorConfigure(interceptorConfig);
  }
}

拦截器工作原理

1. 请求拦截：当 HTTP 请求到达时，拦截器会检查请求是否匹配配置的拦截路径
2. 令牌验证：对于需要拦截的请求，检查 Authorization 请求头
3. 结果处理：
   • 令牌有效：请求继续处理
   • 令牌无效：返回 401 未授权响应
   • 无令牌：返回 401 未授权响应

路由配置说明

方法	描述	示例
addBlockUrl	添加需要拦截的路由	/** 拦截所有路由
addAllowUrls	添加例外路由	/ping 不拦截 ping 接口

客户端请求示例

成功请求

curl --location --request GET 'http://localhost/api/protected' \
--header 'Authorization: 123456'

失败请求

curl --location --request GET 'http://localhost/api/protected' \
--header 'Authorization: wrong-token'

响应示例：

{
  "code": 401,
  "msg": "Unauthorized",
  "data": null
}

常见问题解答

Q: 为什么我的请求没有被拦截？ A: 请检查：

1. 拦截器是否正确配置并注册到服务器
2. 请求路径是否匹配拦截规则
3. 是否配置了例外路由

Q: 如何获取当前使用的令牌？ A: 令牌值来自环境变量 app.auth.token，可以通过 EnvUtils.get("app.auth.token") 获取

Q: 能否配置多个令牌？ A: 当前版本仅支持单一固定令牌，如需多令牌支持，可以考虑自定义拦截器实现

总结

FixedTokenInterceptor 提供了一种简单有效的方式来实现 API 的基础认证。虽然适合开发环境和小型应用，但对于复杂的生产环境，建议考虑更全面的安全解决方案。通过合理配置拦截规则，可以灵活控制应用的访问权限，保护关键 API 不被未授权访问。