dromara/Sa-Token · error · NotWebContextException

非 web 上下文无法获取 HttpServletRequest

Error message

非 web 上下文无法获取 HttpServletRequest

What it means

Error "非 web 上下文无法获取 HttpServletRequest" thrown in dromara/Sa-Token.

Source

Thrown at sa-token-starter/sa-token-spring-boot-webmvc-v3v4-common/src/main/java/cn/dev33/satoken/spring/SpringMVCUtil.java:42

/**
 * SpringMVC 相关操作工具类，快速获取当前会话的 HttpServletRequest、HttpServletResponse 对象
 *
 * @author click33
 * @since 1.34.0
 */
public class SpringMVCUtil {
	
	private SpringMVCUtil() {
	}
	
	/**
	 * 获取当前会话的 request 
	 * @return request
	 */
	public static HttpServletRequest getRequest() {
		ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
		if(servletRequestAttributes == null) {
			throw new NotWebContextException("非 web 上下文无法获取 HttpServletRequest");
		}
		return servletRequestAttributes.getRequest();
	}
	
	/**
	 * 获取当前会话的 response
	 * @return response
	 */
	public static HttpServletResponse getResponse() {
		ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
		if(servletRequestAttributes == null) {
			throw new NotWebContextException("非 web 上下文无法获取 HttpServletRequest");
		}
		return servletRequestAttributes.getResponse();
	}

	/**
	 * 判断当前是否处于 Web 上下文中  

View on GitHub (pinned to ac2c7f6e94)

Solutions

1. 仅在 Web 请求线程（如 Controller、拦截器）中调用 SpringMVCUtil.getRequest()，不要在定时任务、异步线程、启动初始化等非 Web 上下文中调用。
2. 调用前先使用 SpringMVCUtil.isWeb() 判断当前是否处于 Web 上下文，非 Web 环境改用其他方式获取请求信息。
3. 如果需要在异步线程中访问 request，请在 Web 线程中提前取出所需数据再传入异步任务。

When it happens

Trigger: Thrown at sa-token-starter/sa-token-spring-boot-webmvc-v3v4-common/src/main/java/cn/dev33/satoken/spring/SpringMVCUtil.java:42 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of dromara/Sa-Token@ac2c7f6e94 (2026-08-14). Data as JSON: /api/errors/0534ec41c9763e24. Report an issue: GitHub.