全局过滤器

组件简述

之前的章节中，我们学习了“根据拦截器实现路由拦截鉴权”，其实在大多数web框架中，使用过滤器可以实现同样的功能，本章我们就利用Sa-Token全局过滤器来实现路由拦截器鉴权。

首先我们先梳理清楚一个问题，既然拦截器已经可以实现路由鉴权，为什么还要用过滤器再实现一遍呢？简而言之：

相比于拦截器，过滤器更加底层，执行时机更靠前，有利于防渗透扫描。
过滤器可以拦截静态资源，方便我们做一些权限控制。
部分Web框架根本就没有提供拦截器功能，但几乎所有的Web框架都会提供过滤器机制。

但是过滤器也有一些缺点，比如：

由于太过底层，导致无法率先拿到HandlerMethod对象，无法据此添加一些额外功能。
由于拦截的太全面了，导致我们需要对很多特殊路由(如/favicon.ico)做一些额外处理。
在Spring中，过滤器中抛出的异常无法进入全局@ExceptionHandler，我们必须额外编写代码进行异常处理。

Sa-Token同时提供过滤器和拦截器机制，不是为了让谁替代谁，而是为了让大家根据自己的实际业务合理选择，拥有更多的发挥空间。

在 SpringBoot 中注册过滤器

同拦截器一样，为了避免不必要的性能浪费，Sa-Token全局过滤器默认处于关闭状态，若要使用过滤器组件，首先你需要注册它到项目中：

/**
 * [Sa-Token 权限认证] 配置类 
 */
@Configuration
public class SaTokenConfigure {
	
	/**
	 * 注册 [Sa-Token全局过滤器] 
	 */
	@Bean
	public SaServletFilter getSaServletFilter() {
        return new SaServletFilter()
		
        		// 指定 拦截路由 与 放行路由
        		.addInclude("/**").addExclude("/favicon.ico")    /* 排除掉 /favicon.ico */
				
        		// 认证函数: 每次请求执行 
        		.setAuth(obj -> {
					System.out.println("---------- 进入Sa-Token全局认证 -----------");
					
					// 登录认证 -- 拦截所有路由，并排除/user/doLogin 用于开放登录 
					SaRouter.match("/**", "/user/doLogin", () -> StpUtil.checkLogin());
					
					// 更多拦截处理方式，请参考“路由拦截式鉴权”章节 */
        		})
				
        		// 异常处理函数：每次认证函数发生异常时执行此函数 
        		.setError(e -> {
					System.out.println("---------- 进入Sa-Token异常处理 -----------");
        			return SaResult.error(e.getMessage());
        		})
				
        		// 前置函数：在每次认证函数之前执行（BeforeAuth 不受 includeList 与 excludeList 的限制，所有请求都会进入）
        		.setBeforeAuth(r -> {
        			// ---------- 设置一些安全响应头 ----------
        			SaHolder.getResponse()
        			// 服务器名称 
        			.setServer("sa-server")
        			// 是否可以在iframe显示视图： DENY=不可以 | SAMEORIGIN=同域下可以 | ALLOW-FROM uri=指定域名下可以 
        			.setHeader("X-Frame-Options", "SAMEORIGIN")
        			// 是否启用浏览器默认XSS防护： 0=禁用 | 1=启用 | 1; mode=block 启用, 并在检查到XSS攻击时，停止渲染页面 
        			.setHeader("X-XSS-Protection", "1; mode=block")
        			// 禁用浏览器内容嗅探 
        			.setHeader("X-Content-Type-Options", "nosniff")
        			;
        		})
        		;
	}
	
}

注意事项：

在[认证函数]里，你可以写和拦截器里一致的代码，进行路由匹配鉴权，参考：路由拦截鉴权。
由于过滤器中抛出的异常不进入全局异常处理，所以你必须提供[异常处理函数]来处理[认证函数]里抛出的异常。
在[异常处理函数]里的返回值，将作为字符串输出到前端，如果需要定制化返回数据，请注意其中的格式转换。

改写 setError 函数的响应格式示例：

.setError(e -> {
	// 设置响应头
	SaHolder.getResponse().setHeader("Content-Type", "application/json;charset=UTF-8");
	// 使用封装的 JSON 工具类转换数据格式 
	return JSONUtil.toJsonStr( SaResult.error(e.getMessage()) );
})

JSON 工具类可参考：Hutool-Json

自定义过滤器执行顺序

SaServletFilter 默认执行顺序为 -100，如果你要自定义过滤器的执行顺序，可以使用 FilterRegistrationBean 注册，参考：

/**
 * 注册 [Sa-Token 全局过滤器]
 */
@Bean
public FilterRegistrationBean<SaServletFilter> getSaServletFilter() {
	FilterRegistrationBean<SaServletFilter> frBean = new FilterRegistrationBean<>();
	frBean.setFilter(
			new SaServletFilter()
				.addInclude("/**")
				.setAuth(obj -> {
					// ....
				})
				// 等等，其它代码 ... 
	);
	frBean.setOrder(100);  // 更改顺序为 -101
	return frBean;
}

在 SpringBoot 中， Order 值越小，执行时机越靠前。

在 WebFlux 中注册过滤器

Spring WebFlux中不提供拦截器机制，因此若你的项目需要路由鉴权功能，过滤器是你唯一的选择，在Spring WebFlux注册过滤器的流程与上述流程几乎完全一致，除了您需要将过滤器名称由SaServletFilter更换为SaReactorFilter以外，其它所有步骤均可参考以上示例。

/**
 * [Sa-Token 权限认证] 配置类 
 */
@Configuration
public class SaTokenConfigure {
		
	/**
	 * 注册 [Sa-Token全局过滤器] 
	 */
	@Bean
	public SaReactorFilter getSaReactorFilter() {
		return new SaReactorFilter()
			// 其它代码... 
		;
	}
	
}

本章代码示例：Sa-Token 全局过滤器 —— [ com.pj.satoken.SaTokenConfigure.java ]

5.8 KiB Raw Blame History Unescape Escape